Connect by using SDK

Install JavaScript SDK obniz.js for connect and use a device. For Node.js

npm install obniz

And require/import it from your js/typescript.

var Obniz = require('obniz');

For Browser, include from

<script src=""></script>

Specify obniz ID

Instantiate an obniz device with obniz id. Connection will be established automatically. onconnect will be called whenc success. onclose will be called when disconnected from a device.

var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {

obniz.onclose = async function() {


Operations like turning on/off an io becomes possible only after connection is established, so any operations you want device to undertake must be written in onconnect

Operations written in onclose function never delivered to a device because connection is already lost. So you can’t turn off a moving motor when disconnected. See more at Disconnection

var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {

Specify access token when you configured on obniz Cloud device console.

new Obniz('1234-5678', {access_token: 'your token here'})
Automatic Prompt

If obniz id is incorrect, connection will never be established. In nodejs, an error occurs.
In HTML, obniz.js shows a prompt message. The user can put in a correct obniz id into it.
It shows up only when the format is invalid. If you specify obniz id which doesn’t exist, this would never be shown.

Pre-configured Device

We recommend you to use pre configured device classes.
obniz.js will get device information like how many io it has when first connection established.

new obniz = new Obniz("1234-5678")
obniz.io0 => undefined
obniz.onconnect = async function() {
  obniz.io0 => exist if device has io0

obniz Board and M5StickC and other official devices are pre configured in obniz.js. You can find from here.

And below is M5StickC pre configured class reference.
You can instantiate it like below method. Params are same as “new Obinz()”

new obniz = new Obniz.M5StickC("1234-5678")

By using it, peripherals and internal sensors are pre configured.

Local Connect

When obniz Board and the device running obniz.js is expected to be in the same network, obniz.js will try to establish a direct Websocket connection to obniz Board. This is called “local connect”. When local connect is avaiable, obniz Board can be controlled with almost all commands without having to go through the cloud. However, the connection to the cloud never gets disconnected even when using local connect.
But when cloud connection gets closed, the local connect also gets closed.

The timing onconnect() gets called depends on the availability of local connect.
obniz.js will wait a little to establish connection via local connect as much as possible.
See the flow below.

Multiple Connection

One device can accept multiple connection until it’s limit. So one cloud software and one smartphone software can control one device at once.

When local connect exist

But If one of obniz.js established a connection to a device, then target device will send datas only via local connect. So other connected obniz.js only can send datas and never receive datas from a device.

If you’d like to receive, you need to specify local_connect: false at all of obniz.js to disable local connect.


When device is disconnected from the internet or calling close() will cause disconnection. Then onclose will be called.

Operations can’t be delivered after disconnection, device or cloud will automatically reset the state.

When device disconnected from the internet.

By default, device resets after disconnection from the cloud.
It means the output value and pwm and other kind of states will all stop at that point.
But the below function with the argument true can nullify that default setting and change it to “do not reset when offline”.
This configuration remains as long as obniz Board is on.


When obniz.js is disconnected from the cloud.

When program is ended, obniz.js connection to the cloud will be closed. Device is still connected to the cloud, then cloud will indicate reset to a device.

But another connection is still exist for same device, obniz cloud never reset the target.

This setting can be changed by providing below option. So device can keep IO state when your program finished.

var obniz = new Obniz("1234-5678", {reset_obniz_on_ws_disconnection: false})

obnizOS version and obniz.js version

obniz cloud compare your obniz.js version and target device obnizOS version.
If your js sdk major number is below from OS version (eg obniz.js is 2.0.0 and obnizOS is 3.0.0) then obniz cloud will alert when connection established.
It will work somehow but some functions looses compatibility.