App implementation

Specific usage of obniz-app-sdk

  • Get the Hosted App token
  • Install the library
  • Write a program for a worker, which is a program for one obniz device
  • Create an App instance while specifying the worker

Get the token

Create a Hosted App in obnizCoud and acquire a token.
For more details about token acquisition, please refer to Creating a Hosted App.

Installing SDK

Create a nodejs project and install the sdk.

$ npm i obniz-app-sdk.

The worker program

A worker is an instance that is created for each obniz device.
Write the program to operate the device in this worker.

You inherit the worker to make your worker program.

class MyWorker extends Worker {

That's it for the minimal worker. To use it in practice, override onObnizConnect, onObnizLoop, and so on.

class MyWorker extends Worker {

  // Called only once when a connection to an obniz is made.
  // The obniz argument is the same as each obniz instance in obniz.js.
  async onObnizConnect(obniz){

    //BLE initialization and parts wired are done here
    await obniz.ble.initWait();

  // run repeatedly as long as it is connected to the device
  // pingWait() with the device all the time and loop as in obniz.onloop.
  // The argument obniz is the same as each obniz instance in obniz.js.
  async onObnizLoop(obniz){

      //do the actual processing here that we want to repeat
    const peripherals = await obniz.ble.scan.startAllWait(null, {
      duration : 10
    console.log(`founded beacons by obniz ${} length=${peripherals.length}`)


Start app

There are several parameters to create the app, but only four are required.

const app = new App({
  appToken: "<<< Here's the token >>>",
  workerClass: MyWorker,
  instanceType: AppInstanceType.Master,
  obnizClass: Obniz

Parameter Description
appToken Pass the Hosted App token.
workerClass Pass the worker class you created.
instanceType Specify Master/Slave to support scale. In this case, specify Master since there is only one instance. If you want to distribute the load across multiple servers, please refer to the load distribution section below.
obnizClass Pass the obniz instance of obniz.js you use.

Now let's run the program. It's up and running.

In the log, we can see that the app-sdk has started.

[2021-11-14T16:13:36.942] [DEBUG] obniz-app-sdk - ready id:master

However, no workers exist because there is no device with the app installed in this state. You can add the device by installing the app from obniz Cloud.

[2021-11-14T16:13:37.535] [DEBUG] obniz-app-sdk - all | added | updated | deleted
[2021-11-14T16:13:37.535] [DEBUG] obniz-app-sdk - 1 | 1 | 0 | 0
[2021-11-14T16:13:37.535] [DEBUG] obniz-app-sdk - synchronize sent to master idsCount=1
[2021-11-14T16:13:37.535] [INFO] obniz-app-sdk - New Worker Start id=8952-6555

The all:1 and add:1 part of this log shows that the app is newly installed on one device so that the total number of devices becomes one.

The next New Worker Start id=8952-6555 is the start log for the specific worker.

Let's try uninstalling the app from the device. You will see that the number of workers has changed in the same way.

As you can see, if you install the obniz Cloud app, it will automatically increase or decrease the number of workers and keep as many workers running as obniz devices with the app installed.

For more information about obniz-app-sdk, please refer to obniz-app-sdk documentation.

Note: About "Install"

In obniz, linking a Hosted App to a device is called "installing" the app on the device. By installing a Hosted App on a device, the logic defined in the Hosted App is applied to the data sent from the target device.

Be careful with the word "install." iOS apps write data directly to the iPhone device, but app data is not written to the obniz device. It is just a mapping between the device and the Hosted App on the obniz Cloud.

For more information about installation, please refer to Hosted App: Installation.