obniz-dock

日本語はこちら

This framework helps you build self-hosted Node.js applications using obniz.

By running your program continuously with this SDK, you can control every device where the app is installed. When a device connects, an obnizjs instance is created automatically and your program starts handling the device.

Features

• Build local-network-only self-hosted apps with minimal setup
• Manage connections to each obniz device
• Pin and use any version of obnizjs
• First-class TypeScript support

Getting Started

Install SDK

Install the SDK from npm (or your preferred package manager):

$ npm i obniz-dock obniz

Use SDK

Prepare a Node.js program that controls your devices and import obniz-dock. You will create a subclass of the Worker class; one instance of this class is created per device. The App configuration describes the metadata for the app and how it scales.

The example below watches the built-in switch and polls an analog pin, logging whichever values are available for the connected board.

import Obniz from "obniz";
import {App, Worker} from "obniz-dock";

export class AppWorker extends Worker<typeof Obniz> {
	async onObnizConnect(obniz: Obniz) {
		console.log("on obniz connect");

		if (obniz.switch) {
			obniz.switch.onchange = (pressed) => {
				console.log("switch onchange", pressed);
			};
		}
	}

	async onObnizLoop(obniz: Obniz) {
		console.log("on obniz loop");
		const s = await this.getSomeAdPinValue(obniz);
		console.log(`[${new Date()}]Loop on ${obniz.id} / ${s}`);
		await obniz.wait(1000);
	}

	async getSomeAdPinValue(obniz: Obniz) {
		// for obniz board
		if ("ad0" in obniz) {
			return await obniz.ad0?.getWait();
		}

		// for esp32
		if ("ad32" in obniz) {
			return await (obniz.ad32 as any)?.getWait();
		}

		return null;
	}

	async onObnizClose(obniz: Obniz) {
		console.log("on obniz close");
	}
}

const app = new App({
    port: 8082,
	obnizClass: Obniz,
    workerClass: (obnizId, { requestInfo }) => AppWorker,
	onObnizDeviceConnected: (obnizId) => {
		console.log(`obniz connected: ${obnizId}`);
	},
	onObnizDeviceDisconnected: (obnizId) => {
		console.log(`obniz disconnected: ${obnizId}`);
	},

    shouldAllowConnectObnizDevice: async (obnizId, { modules, requestInfo }) => {
		console.log(`obniz auth: ${obnizId}`);
		await new Promise((resolve) => setTimeout(resolve, 1000));
		
		console.log(`obniz auth finished: ${obnizId}`);
        return true;
	},
});

app.start();

Options

You can configure the following options on the App.

| key | meaning | |:--------------------------|:-----------------------------------------------------------------------------------------------------------------------| | workerClass | Specifies the worker class that contains per-device logic. You can return different worker classes based on obnizId. | | obnizClass | Specifies the obniz class used by your workers. | | obnizOption | Passed as the second argument of new Obniz(). | | onObnizDeviceConnected | Callback invoked when an obniz device connects. | | onObnizDeviceDisconnected | Callback invoked when an obniz device disconnects. | | shouldAllowConnectObnizDevice | Callback invoked before onObnizDeviceConnected/Worker.onObnizConnect. return false to refuse the connection. |

See src/App.ts for additional optional parameters.

Deploy

Run this Node.js project on your server. The snippet below shows how to keep it alive with pm2.

$ npm install pm2 -g
$ pm2 startup ubuntu
$ pm2 start index.js
$ pm2 save

While running, the app continuously coordinates with obniz devices, monitoring newly added or removed devices and scaling workers up or down automatically.

Examples

Sample code lives in ./examples.

The lifecycle diagram is shown below.