obnizクラスはobniz BoardをJavaScriptの中で抽象化したクラスです。
idを指定してインスタンス化することで通信内容を意識せずにobniz Boardやobniz Boardに繋がれた部品の操作ができるようになります。
obniz idをもとにインスタンス化します。
HTMLの場合はscriptタグで読み込むだけでObnizクラスが利用できます。nodejsの場合はnpmでインストールした後に、
var Obniz = require('obniz');このようにクラスを取得できます。
そして、接続して利用したいobniz Boardのidを与えてインスタンス化します。
var obniz = new Obniz('1234-5678');２台以上のobniz Boardを使いたい場合は
var obnizA = new Obniz('1234-5678');
var obnizB = new Obniz('0000-0000');のように記載することになります。
インスタンス化した段階でobniz Websocket APIを使いobniz Boardとの接続を行います。
接続が完了するとonconnectが呼ばれます。また、oncloseは切断時に呼ばれます。
標準で自動接続が行われますので、切断が起きても、継続的に接続を試みます。
var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {
}
obniz.onclose = async function() {
}ioのon,offなどは接続することで操作できるようになりますので、onconnectの中でobniz Boardに対して行いたいことを記載します。
var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {
obniz.io0.output(true);
}インスタンス化するときのオプションもありますので、下のそれぞれの関数リファレンスを御覧ください。
obnizインスタンス化します。
obniz idに半角文字列でobniz Boardの番号を入力します。ハイフン(-)はあってもなくても大丈夫です。数値では認識できません。
new Obniz('1234-5678') // OK
new Obniz('12345678') // OK
new Obniz(12345678) // Can't acceptまた、obniz Boardにアクセストークンを設定している場合は以下のようにオプションで指定します。
new Obniz('1234-5678', {access_token: 'your token here'})obniz idとして正しくないと判断された場合は接続は行われません。nodejsの場合はエラーとなります。
ブラウザ上で実行している場合はpromptが表示されます。そこでidを入れることでそのobniz Boardに接続することが可能です。
これは正しくない形式の場合にのみ表示されます。正しくても存在しないobniz idを入れた場合には表示されません。
idが正しければ、クラウドに接続を行い、接続が完了するとonconnectが呼ばれます。
ただし、obniz Boardとobniz.jsを利用している端末が同一LAN内にある可能性が高い場合、obniz.jsは同時にobniz Boardと直接Websocket接続を行おうとします。これをlocal connectといいます。
local connectできた場合はほとんどのコマンドで、クラウドを経由せずにobniz Boardを操作可能です。ただし、local connectしていてもクラウドとの接続は切断されません。
また、クラウドとの接続が切断されるとlocal connectも切断されます。
onconnectが呼ばれるタイミングは、クラウドにつながったとしてもlocal_connectが利用できるかどうかによって変わってきます。できるだけlocal_connect経由になるように接続を少しまちます。
以下のような流れとなります。
インスタンス化するときの第二引数はオプションです。
そのoptionで以下の設定が指定できます。
| name | type | default | description |
|---|---|---|---|
| binary | boolean |
true | APIの通信ではjsonでなく圧縮形式が使えますが、それのon-offとなります。falseにした場合local_connectは利用できません。 |
| local_connect | boolean |
true | obniz.js はクラウドAPI経由でobniz Boardとつないだあとに可能であればobniz Boardと直接接続しようとします。falseにすることでそれを使わない設定にできます。binaryがfalseの場合はlocal_connectは自動的にfalseになります。 |
| debug_dom_id | string |
'obniz-debug' | HTMLではここで指定されたidを持つDOMにオンラインステータスなど各種情報が出力されます |
| auto_connect | boolean |
true | 標準でobniz.jsは自動的に接続を行い、切れても再接続を自動で行いますが、これによりoffにできます。自動接続は1秒間隔ではじまり、徐々に間隔が伸びるようになっています。 |
| access_token | string |
null | access_tokenが発行されているobniz Boardに接続する場合は指定してください。 |
| reset_obniz_on_ws_disconnection | boolean |
true | 同一のobniz Boardに対してのwebsocket接続が0本になった時にクラウド側がobniz Boardをリセットするかどうか |
obnizクラウドは接続してきたobniz.jsと接続先のobnizOSのバージョンを比較します。
js sdkのメジャー番号がOSのそれよりも低い場合(例 obniz.js is 2.0.0 and obnizOS is 3.0.0) にはobniz cloudが接続時に警告を送ります。
およそ機能するものの互換性がない部分があるため、obniz.jsのアップデートが必要です。
obniz Cloudは複数のobniz.jsからの同時websocket接続を受け付けます。
すべてのコマンドはデバイスへ届き、デバイスからのデータは全てのjsに届きます。
ただしある1つのobniz.jsからデバイスにlocal connectが張られているときにはデバイスはローカルコネクト側にのみデータを送るため他のobniz.jsはデータを送ることはできても受け取ることができません。
全てのobniz.jsでデータを受け取れるようにうするには、すべてのobniz.jsにおいて local_connect: false を設定することでlocal connectしないようにする必要があります。
optionのauto_connectをfalseにしている場合に利用できます。connectを呼ぶことでobniz Boardとの接続を試みます。
var obniz = new Obniz('1234-5678', { auto_connect: false });
obniz.connect();
obniz.onconnect = async function() {
obniz.io0.output(true);
}接続を試し，接続するまで待ちます．
var obniz = new Obniz('1234-5678');
await obniz.connectWait(); //waiting for connection
obniz.io0.output(true);
obniz.close();
timeout[秒]を指定すれば，時間内に接続できなかった場合はfalseが返ります
var obniz = new Obniz('1234-5678');
var connected = await obniz.connectWait({timeout:10}); //timeout 10sec
if(connected){
obniz.io0.output(true);
obniz.close();
}
auto_connectオプションがfalseの場合，一度だけ接続を試みて，つながらなかったらfalseを返します
var obniz = new Obniz('1234-5678',{auto_connect: false});
var connected = await obniz.connectWait(); //try once
if(connected){
obniz.io0.output(true);
obniz.close();
}現在の接続を切断します。
auto_connectがfalseになっていないと、また自動的に再接続されます。
var obniz = new Obniz('1234-5678', {
auto_connect: false,
reset_obniz_on_ws_disconnection: false
});
obniz.connect();
obniz.onconnect = async function() {
obniz.io0.output(true);
obniz.close();
}obniz Boardとの現在の接続状態を接続状態を表す文字列が入っています。
以下の4状態のうちどれかになります。
| state | type |
|---|---|
'closed' |
接続していない |
'connecting' |
接続中 |
'connected' |
接続が完了した |
'closing' |
切断中 |
var obniz = new Obniz('1234-5678');
console.log(obniz.connectionState) // => === "connecting"
obniz.onconnect = async function() {
console.log(obniz.connectionState) // => === "connected"
}通信でやりとりされるjsonを出力したり、接続状態などのobniz.js内のログがconsole.logに出力されます。
var obniz = new Obniz('1234-5678');
obniz.debugprint = true
obniz.onconnect = async function() {
obniz.io0.output(true);
}接続されたデバイスのハードウェア番号です
var obniz = new Obniz('1234-5678');
obniz.debugprint = true
obniz.onconnect = async function() {
console.log(obniz.hw) // ex. "obnizb1"
}接続されたデバイスにインストールされているOSのバージョンを取得します
var obniz = new Obniz('1234-5678');
obniz.debugprint = true
obniz.onconnect = async function() {
console.log(obniz.firmware_ver) // ex. "2.0.0"
}オプションである reset_obniz_on_ws_disconnection の設定をあとから変更する場合に使う関数です。
obniz.jsでは標準でtrueなので、obnizクラウドは同一obniz Boardへのwebsocket接続が0本になったところでobniz Boardに対してリセットを行います。
リセットするので、出力されている電圧などももとに戻り、pwmなども全て停止します。
この関数でそれを無効にし、リセットしないようにできます。
この設定はobniz Boardがオンラインである限り有効となります。
// Example
obniz.resetOnDisconnect(false);