

SDK for controlling [obniz enabled Devices](https://obniz.com/) using obniz websocket API from JavaScript.

It works on both browser and nodejs.

### Source
[GitHub](https://github.com/obniz/obniz/)


## Example

```typescript
import * as Obniz from 'obniz'

const obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
obniz.onconnect = async () => {

  obniz.display.print("hello!");
  obniz.switch.onchange = (state: string) => {
    console.log(state);
  }
  const servo = obniz.wired("ServoMotor", {gnd:0, vcc:1, signal:2});
  servo.angle(90);
}
```

### Example: Browser

```html
<html>
<head>
  <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
  <script src="https://unpkg.com/obniz/obniz.js"></script>
</head>
<body>

<input id="text">
<button id="send">send</button>

<script>
  var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
  obniz.onconnect = async function () {
    // embed parts
    obniz.display.print("hello!");
    obniz.switch.onchange = function(state) {
      $('body').css({
        "background-color" : (state == "push") ? "#F00" : "#FFF"
        });
    }

    // parts library
    var servo = obniz.wired("ServoMotor", {gnd:0, vcc:1, signal:2});
    servo.angle(90);
    
    // peripherals
    var uart = obniz.getFreeUart();
    uart.start({tx: 5, rx: 6, baud:9600});  
    
    $('#send').click(function () {
      uart.send($("#text").val());
    });

    obniz.io7.drive("5v")
    obniz.io7.output(true)
    obniz.io8.pull("3v");
    obniz.io8.drive("open-drain");
    obniz.io8.output(false);
  }
</script>
</body>
</html>
```

## API

| Category | Function/Property | Minimum Support OS | Class Reference |
|:-----|:--------|:---|:-----------------|
| Connection | [new Obniz()](./connection) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html#constructor) |
|  | [obniz.onconnect](./connection) | 1.0.0 | |
|  | [obniz.onclose](./connection) | 1.0.0 | |
|  | [obniz.autoConnect()](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.connect()](./connection) | 1.0.0 | |
|  | [obniz.close()](./connection) | 1.0.0 | |
|  | [obniz.onloop](./connection) | 1.0.0 | |
|  | [obniz.setLoopInterval()](./connection) | 1.0.0 | |
|  | [obniz.connected_network](./connected_network) | 1.0.0 | [obnizcore.Obniz#constructor](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html#constructor) |
|  | [obniz.pingWait()](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.keepWorkingAtOffline()](./connection) | 1.0.0 | |
|  | [obniz.resetOnDisconnect()](./connection) | 1.0.0 | |
|  | [obniz.boot_reason](./connection) | 7.0.0 | |
| Queue | [obniz.setClock()](./) | 7.0.0 | |
|  | [obniz.setQueueMode()](./) | 7.0.0 | |
|  | [obniz.deviceTimestamp](./) | 7.0.0 | |
| Debug | [obniz.debugprint](./) | 2.0.0 | |
| Hardware | [obniz.id](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.firmware_ver](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.version](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.reboot()](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.wait()](./) | 1.0.0 | [obnizcore.Obniz](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html) |
|  | [obniz.sleepMinutes()](./sleep) | 2.0.0 | |
|  | [obniz.sleepSeconds()](./sleep) | 2.0.0 | |
|  | [obniz.sleepIoTrigger()](./sleep) | 2.0.0 | |
| Components | [obniz.components.prepare()](./) | 7.0.0 | |
|  | [obniz.components.powerOnInterface()](./) | 7.0.0 | |
|  | [obniz.components.powerOffAllInterfaces()](./) | 7.0.0 | |
|  | [obniz.components.isRS232HavingTargetWait()](./) | 7.0.0 | |
|  | [obniz.components.startMonitoringPowerSupply()](./) | 7.0.0 | |
|  | [obniz.components.getPowerSupplyVoltageWait()](./) | 7.0.0 | |
|  | [obniz.components.setRelay()](./) | 7.0.0 | |
| Motion | [obniz.motion.start()](./) | 7.0.0 | |
|  | [obniz.motion.onAccelerationUpdate()](./) | 7.0.0 | |
|  | [obniz.motion.onRecognitionUpdate](./) | 7.0.0 | |
|  | [obniz.motion.onTemperatureUpdate()](./) | 7.0.0 | |
|  | [obniz.motion.getAccelerationWait()](./) | 7.0.0 | |
|  | [obniz.motion.getRecognitionWait()](./) | 7.0.0 | |
|  | [obniz.motion.getTemperatureWait()](./) | 7.0.0 | |
| Location | [obniz.location.start()](./) | 7.0.0 experimental | |
|  | [obniz.location.onupdate](./) | 7.0.0 experimental | |
| obnizCloud | [obniz.metadata](./metadata) |  | [obnizcore.Obniz#metadata](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html#metadata) |
|  | [obniz.onmessage](./messaging) |  | [obnizcore.Obniz#onmessage](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html#onmessage) |
| io | [obniz.ioX](./io) | 1.0.0 | [obnizcore.components.peripheralio](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralio.html) |
|    | [obniz.ioX.output()](./io) | 1.0.0 |  |
|    | [obniz.ioX.inputWait()](./io) | 1.0.0 |  |
|    | [obniz.ioX.input()](./io) | 1.0.0 |  |
|    | [obniz.ioX.pull()](./io) | 1.0.0 |  |
|    | [obniz.ioX.drive()](./io) | 1.0.0 |  |
|    | [obniz.ioX.end()](./io) | 1.0.0 |  |
| io.animation | [obniz.io.animation()](./io-animation) | 1.0.0 | [obnizcore.components.directive](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.directive.html) |
|  | [obniz.io.repeatWait()](./io-animation) | 1.0.0 | [obnizcore.components.directive](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.directive.html) |
| ad | [obniz.adX.start()](./ad) | 1.0.0 | [obnizcore.components.peripheralad](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralad.html) |
|  | [obniz.adX.getWait()](./ad) | 1.0.0 | [obnizcore.components.peripheralad](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralad.html) |
| pwm | [obniz.pwmX.start()](./pwm) | 1.0.0 | [obnizcore.components.peripheralpwm](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralpwm.html) |
|  | [obniz.pwmX.freq()](./pwm) | 1.0.0 | [obnizcore.components.peripheralpwm](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralpwm.html) |
|  | [obniz.pwmX.duty()](./pwm) | 1.0.0 | [obnizcore.components.peripheralpwm](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralpwm.html) |
|  | [obniz.pwmX.modulate()](./pwm) | 1.0.0 | [obnizcore.components.peripheralpwm](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralpwm.html) |
| uart | [obniz.uartX.start()](./uart) | 1.0.0 | [obnizcore.components.peripheraluart](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheraluart.html) |
|  | [obniz.uartX.send()](./uart) | 1.0.0 | [obnizcore.components.peripheraluart](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheraluart.html) |
|  | [obniz.uartX.setDE()](./uart) | 1.0.0 | [obnizcore.components.peripheraluart](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheraluart.html) |
|  | [obniz.uartX.onreceive](./uart) | 1.0.0 | [obnizcore.components.peripheraluart](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheraluart.html) |
| spi | [obniz.spiX.start()](./spi) | 1.0.0 | [obnizcore.components.peripheralspi](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralspi.html) |
|  | [obniz.spiX.write()](./spi) | 1.0.0 | [obnizcore.components.peripheralspi](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralspi.html) |
|  | [obniz.spiX.writeWait()](./spi) | 1.0.0 | [obnizcore.components.peripheralspi](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralspi.html) |
|  | [obniz.spiX.end()](./spi) | 1.0.0 | [obnizcore.components.peripheralspi](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralspi.html) |
| i2c | [obniz.i2cX.start()](./i2c) | 1.0.0 | [obnizcore.components.peripherali2c](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripherali2c.html) |
|  | [obniz.i2cX.write()](./i2c) | 1.0.0 | [obnizcore.components.peripherali2c](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripherali2c.html) |
|  | [obniz.i2cX.readWait()](./i2c) | 1.0.0 | [obnizcore.components.peripherali2c](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripherali2c.html) |
|  | [obniz.i2cX.onwritten](./i2c) | 1.0.0 | [obnizcore.components.peripherali2c](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripherali2c.html) |
| canbus | [obniz.canbusX.start()](./can) | 7.0.0 | [obnizcore.components.peripheralcanbus](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralcanbus.html) |
|  | [obniz.canbusX.send()](./can) | 7.0.0 | [obnizcore.components.peripheralcanbus](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralcanbus.html) |
|  | [obniz.canbusX.onreceive](./can) | 7.0.0 | [obnizcore.components.peripheralcanbus](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.peripheralcanbus.html) |
| ble | [obniz.ble ( See Details )](./ble)  | 1.0.0 | [obnizcore.components.ble.hci.obnizble](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.ble.hci.obnizble.html) |
| logicAnalyzer | [obniz.logicAnalyzer.start()](./logicanalyzer) | 1.0.0 | [obnizcore.components.logicanalyzer](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.logicanalyzer.html) |
|  | [obniz.logicAnalyzer.onmeasured](./logicanalyzer) | 1.0.0 | [obnizcore.components.logicanalyzer](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.logicanalyzer.html) |
| measure | [obniz.measure.echo()](./measurement) | 1.0.0 | [obnizcore.components.obnizmeasure](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.obnizmeasure.html) |
| display | [obniz.display ( See Details )](./display) | 1.0.0 | [obnizcore.components.display](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.display.html) |
| switch | [obniz.switch.getWait()](./switch) | 1.0.0 | [obnizcore.components.obnizswitch](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.obnizswitch.html) |
|  | [obniz.switch.onchange](./switch) | 1.0.0 | [obnizcore.components.obnizswitch](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.obnizswitch.html) |
| tcp | [obniz.tcp ( See Details )](./tcp) | - | [obnizcore.components.tcp](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.tcp.html) |
| wifi | [obniz.wifi.scanWait()](./wifi) | 2.0.0 | [obnizcore.components.wifi](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.wifi.html) |
| plugin | [obniz.plugin.send()](./plugin) | 2.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin.onreceive](./plugin) | 2.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin.onFrameStart](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin.onFrameEnd](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin.execLua()](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin.reloadLua()](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.plugin_name](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
| storage | [obniz.storage.save()](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.storage.savePluginLua()](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |
|  | [obniz.storage.readWait()](./plugin) | 7.0.0 | [obnizcore.components.plugin](https://obniz.github.io/obniz/obnizjs/classes/obnizcore.components.plugin.html) |



## Installation

### Browser
Add the following script tag to your html
```html
  <script src="https://unpkg.com/obniz/obniz.js"></script>
```
### Nodejs
Install obniz via npm
```shell
  npm install obniz
```
and import it to js file.
```javascript
  const Obniz = require('obniz');
```

## Connect

The details are on [Connection](./connection)

To use obniz, instantiate obniz with obniz id, and set onconnect callback function. It will be called when connected to obniz successfully.

```javascript
  var obniz = new Obniz("0000-0000");
  obniz.onconnect = async function () {

  }
```

You can use everything on obniz Device after connection succeeds.

```javascript
  var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
  obniz.onconnect = async function () {
    obniz.display.print("hello!");
    obniz.switch.onchange = function(state) {
      if (state === "push") {
        obniz.display.print("Button Pressed");
      }
    }
  }
  obniz.onloop = async function () {
    // called continuously
  }
  obniz.onclose = async function () {
    // called after connection lost
  }
```

and its io peripherals too can be used

```javascript
  var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
  obniz.onconnect = async function () {
    obniz.io0.drive("5v");
    obniz.io0.output(true)
    obniz.io1.pull("3v");
    obniz.io1.drive("open-drain");
    obniz.io1.output(false);
    obniz.io2.drive("3v");
    obniz.io2.output(true);

    obniz.ad3.start(function(voltage){
      console.log("changed to "+voltage+" v")
    });

    var pwm = obniz.getFreePwm();
    pwm.start({io: 4});
    pwm.freq(1000);
    pwm.duty(50);

    var uart = obniz.getFreeUart();
    uart.start({tx: 5, rx: 6, baud:9600});  
    uart.onreceive = function(data, text) {
      console.log(data);
    }
    uart.send("Hello");
  }
```

## Parts library
The parts library is embedded in obniz.js.
All parts and their details can be found there.

[obniz Parts Library](https://obniz.com/sdk/parts/)

To use the connected parts, instantiate the parts in onconnect callback function and use it. The function list can be found on [obniz Parts Library](https://obniz.com/sdk/parts/).

For example, LED is found here [https://obniz.com/sdk/parts/LED](https://obniz.com/sdk/parts/LED)
```javascript
  var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
  obniz.onconnect = async function () {
    var led = obniz.wired("LED", {anode:0, cathode:1});
    led.blink();
  }
```

HC-SR40(distance measure) [https://obniz.com/sdk/parts/HC-SR04](https://obniz.com/sdk/parts/HC-SR04)
```javascript
  var obniz = new Obniz("0000-0000");
  obniz.onconnect = async function () {
    var hcsr04 = obniz.wired("HC-SR04", {gnd:0, echo:1, trigger:2, vcc:3});
    hcsr04.unit("inch");
    hcsr04.measure(function( distance ){
      console.log("distance " + distance + " inch")
    })
  }
```

## Example: browser integrates hardware
Easy to integrate UI and hardware on html
```html
<input id="slider" type="range"  min="0" max="180" />

<script src="https://unpkg.com/obniz/obniz.js"></script>
<script>
var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
obniz.onconnect = async function () {
  var servo = obniz.wired("ServoMotor", {gnd:0, vcc:1, signal:2});
  $("#slider").on('input', function() {
    servo.angle($("#slider").val())
  });
}
</script>
```

## Example: integrate web services
Easy to integrate web services like Dropbox and Twitter and hardware.
```javascript
// save data from obniz to dropbox
var obniz = new Obniz("0000-0000", { access_token: 'xxxx' });
obniz.onconnect = async function () {
  var dbx = new Dropbox({ accessToken: '<YOUR ACCESS TOKEN HERE>' });
  var button = obniz.wired("Button",  {signal:0, gnd:1});
  button.onchange = function(pressed){
    if (pressed) {
  　　dbx.filesUpload({path: '/obniz.txt', contents: "[Button Pressed]\n" + new Date(), mode: 'overwrite' });
    }
  };
}
```

## Example: integrate two or more obniz
Two or more device integration.
```javascript
// control servomotor from potention meter which connected to another obniz.
var obnizA = new Obniz("0000-0000", { access_token: 'xxxx' });
obnizA.onconnect = async function () {
  var obnizB = new Obniz("0000-0001", { access_token: 'xxxx' });
  obnizB.onconnect = async function(){
    var meter = obnizA.wired("Potentiometer", 0, 1, 2);
    var servo = obnizB.wired("ServoMotor", 0, 1, 2);
    meter.onchange = function(position) {
      servo.angle(position * 180);
    }; 
  }
}
```

