デバイスへの接続

SDKでの接続

SDKを利用して接続するにはSDKのインストールが必要です。obnizはobniz.jsというJavaScript向けSDKを利用します。Nodejsの場合は

npm install obniz

として、JavaScriptやTypescriptの中でrequire/importにより取り込みます

var Obniz = require('obniz');

ブラウザの場合はunpkg.comより各バージョンを取り込むことができます。

<script src="https://unpkg.com/obniz@latest/obniz.js"></script>

obniz IDを指定して接続

以下のようにIDを使うことでデバイスの代わりになるインスタンスを作成できます。接続は自動で開始されて、成功するとonconnectに指定した関数が、切断でoncloseに指定した関数が呼ばれます。

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

}
obniz.onclose = async function() {

}

部品の操作やioの操作など、デバイスに対する操作は接続した後でのみ行えるため、onconnect後に操作するように指定します。

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

oncloseは切断後に呼び出される関数です。そのため「デバイスとの接続が切れたのでモーターをOFFにする」という処理は既に接続が切れているのでoncloseにプログラムで書くことはできません。詳しくはこのページの「切断」をご覧ください。

アクセストークン

デバイスにアクセストークンを設定している場合は以下のようにオプションで指定します。

new Obniz('1234-5678', {access_token: 'your token here'})
自動プロンプト

ブラウザ上で実行している場合にobniz idとして正しくない場合は自動的にpromptが表示されます。そこでidを入れることでそのデバイスに接続することが可能です。
これはidとして正しくない形式の場合にのみ表示されます。正しくても存在しないobniz idを入れた場合には表示されません。

登録済みデバイス

obniz.jsではデバイスに初めて接続するときにハードウェア情報を取得し、ioがいくつあるのか、bleはあるのか、内蔵センサーはあるのかなどを元にobnizインスタンスを構成します。

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

この他に事前にobniz.jsに登録されているデバイスの場合はペリフェラルや内蔵センサーのための関数が用意されているものを利用できます。利用可能なものは以下のobnizクラスのリファレンスより見つけられます。
https://obniz.github.io/obniz/obnizjs/classes/obnizcore.obniz.html

obnizBoardはもちろん、他にもM5StickCなどが事前登録されています。
https://obniz.github.io/obniz/obnizjs/classes/obnizcore.hardware.m5stickc.html
以下のように記載することで利用できます。引数はnew Obniz()と同じです。

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

これにより内部に登録されているbuttonや赤外線LEDも登録済みの状態で利用できます。

ローカルコネクト

デバイスとobniz.jsを利用している端末が同一LAN内にある可能性が高い場合、obniz.jsは同時にデバイスと直接Websocket接続を行おうとします。これをlocal connectといいます。
local connectできた場合はほとんどのコマンドがクラウドを経由せずにやりとりされます。ただし、local connectしていてもクラウドとの接続は切断されません。
また、クラウドとの接続が切断されるとlocal connectも切断されます。

onconnectが呼ばれるタイミングは、クラウドにつながったとしてもlocal_connectが利用できるかどうかによって変わってきます。できるだけlocal_connect経由になるように接続を少しまちます。
以下のような流れとなります。

複数プログラムからの接続

1つのデバイスは複数のobniz.jsからの同時websocket接続を受け付けます。(同時接続数制限はあります) つまり、クラウドとスマートフォンからの同時操作ができるため、片方では電圧を監視しながら片方ではグラフ化するといった動作が可能です。

同時接続の場合すべてのコマンドはデバイスへ届き、デバイスからのデータは全ての接続元に届きます。

ローカルコネクトが存在する場合

ただしある1つのobniz.jsからデバイスにlocal connectが張られているときにはデバイスはローカルコネクト側にのみデータを送るため他のobniz.jsはデータを送ることはできても受け取ることができません。

全てのobniz.jsでデータを受け取れるようにうするには、すべてのobniz.jsにおいて local_connect: false を設定することでlocal connectしないようにする必要があります。

切断

デバイスがインターネットから切断されたり、意図的にclose()関数を呼ぶことで通信は切断され、oncloseに指定した関数が呼ばれます。

切断後はデバイスに指示を送ることができませんが、デバイスとクラウドが自動的にリセット処理を行うようになっています。

デバイスがWi-Fiなどから切断された場合

デバイスの電源は正常なのに、ネットワークから切断されるとデバイスは自動的に「リセット」を行い、IOなどすべての状態が電源投入後と同じ状態に戻ります。その場合にリセットを行うのをやめさせてIOなどの状態を最後のまま維持する(highのioはそのままhigh)には接続後に以下のように設定しておくことで、デバイスはIOなどの状態を維持します。

obniz.keepWorkingAtOffline(true);

obniz.jsなどクラウドとの接続が切断された場合

デバイス自体は正常にクラウドと通信しているのに、プログラムを動かしているブラウザを閉じたりnodejsのプログラムを止めた場合はobnizクラウドがデバイスに対してリセットを指示します。

ただし、複数接続された状態で、まだ他のプログラムから接続がある場合はリセットは送信されません。

この設定は接続時オプションでオフにすることが可能です。オフにした場合はプログラムを終了したとしてもデバイスのIOなどは最後の状態のまま維持されます。

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

obnizOS version and obniz.js version

obnizクラウドは接続してきたobniz.jsと接続先のobnizOSのバージョンを比較します。
sdkのメジャー番号がOSのそれよりも低い場合(例 obniz.js is 2.0.0 and obnizOS is 3.0.0) にはobniz cloudが接続時に警告を送ります。互換性がない部分があるためです。その場合はobniz.jsのアップデートが必要です。