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.
- 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
Install the SDK from npm (or your preferred package manager):
$ npm i obniz-dock obniz
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();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.
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 saveWhile running, the app continuously coordinates with obniz devices, monitoring newly added or removed devices and scaling workers up or down automatically.
Sample code lives in ./examples.
The lifecycle diagram is shown below.