obniz
Version:
obniz sdk for javascript
215 lines (156 loc) • 8.33 kB
Markdown
# obniz connection
obnizクラスはobnizをjavascriptの中で抽象化したクラスです。
idを指定してインスタンス化することで通信内容を意識せずにobnizやobnizに繋がれた部品の操作ができるようになります。
## basics
obnizはidをもとにインスタンス化します。
HTMLの場合はscriptタグで読み込むだけでObnizクラスが利用できます。nodejsの場合はnpmでインストールした後に、
```javascript
var Obniz = require('obniz');
```
このようにクラスを取得できます。
そして、接続して利用したいobnizのidを与えてインスタンス化します。
```javascript
var obniz = new Obniz('1234-5678');
```
２台以上のobnizを使いたい場合は
```javascript
var obnizA = new Obniz('1234-5678');
var obnizB = new Obniz('0000-0000');
```
のように記載することになります。
インスタンス化した段階で[obniz Websocket API](https://obniz.io/doc/about_obniz_api)を使いobnizとの接続を行います。
接続が完了するとonconnectが呼ばれます。また、oncloseは切断時に呼ばれます。
標準で自動接続が行われますので、切断が起きても、継続的に接続を試みます。
```javascript
var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {
}
obniz.onclose = async function() {
}
```
ioのon,offなどは接続することで操作できるようになりますので、onconnectの中でobnizに対して行いたいことを記載します。
```javascript
var obniz = new Obniz('1234-5678');
obniz.onconnect = async function() {
obniz.io0.output(true);
}
```
インスタンス化するときのオプションもありますので、下のそれぞれの関数リファレンスを御覧ください。
## new Obniz('obniz id', { options })
obnizインスタンス化します。
obniz idに半角文字列でobnizの番号を入力します。ハイフン(-)はあってもなくても大丈夫です。数値では認識できません。
```javascript
new Obniz('1234-5678') // OK
new Obniz('12345678') // OK
new Obniz(12345678) // Can't accept
```
また、obnizにアクセストークンを設定しているobnizの場合は以下のようにオプションで指定します。
```javascript
new Obniz('1234-5678', {access_token: 'your token here'})
```
obniz idとして正しくないと判断された場合は接続は行われません。nodejsの場合はエラーとなります。
ブラウザ上で実行している場合はpromptが表示されます。そこでidを入れることでそのobnizに接続することが可能です。
これは正しくない形式の場合にのみ表示されます。正しくても存在しないobniz idを入れた場合には表示されません。
idが正しければ、クラウドに接続を行い、接続が完了するとonconnectが呼ばれます。
ただし、obnizとobniz.jsを利用している端末が同一LAN内にある可能性が高い場合、obniz.jsは同時にobnizと直接Websocket接続を行おうとします。これをlocal connectといいます。
local connectできた場合はほとんどのコマンドで、クラウドを経由せずにobnizを操作可能です。ただし、local connectしていてもクラウドとの接続は切断されません。
また、クラウドとの接続が切断されるとlocal connectも切断されます。
onconnectが呼ばれるタイミングは、クラウドにつながったとしてもlocal_connectが利用できるかどうかによって変わってきます。できるだけlocal_connect経由になるように接続を少しまちます。
以下のような流れとなります。
obnizをインスタンス化するときの第二引数はオプションです。
そのoptionで以下の設定が指定できます。
name | type | default | description
--- | --- | --- | ---
binary | `boolean` | true | APIの通信ではjsonでなく圧縮形式が使えますが、それのon-offとなります。falseにした場合local_connectは利用できません。
local_connect | `boolean` | true | obniz.js はクラウドAPI経由でobnizとつないだあとに可能であればobnizと直接接続しようとします。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に接続する場合は指定してください。
reset_obniz_on_ws_disconnection | `boolean` | true | 同一のobnizに対してのwebsocket接続が0本になった時にクラウド側がobnizをリセットするかどうか
## connect()
optionのauto_connectをfalseにしている場合に利用できます。connectを呼ぶことでobnizとの接続を試みます。
```javascript
var obniz = new Obniz('1234-5678', { auto_connect: false });
obniz.connect();
obniz.onconnect = async function() {
obniz.io0.output(true);
}
```
## [await]connectWait({timeout})
接続を試し，接続するまで待ちます．
```javascript
var obniz = new Obniz('1234-5678');
await obniz.connectWait(); //waiting for connection
obniz.io0.output(true);
obniz.close();
```
timeout[秒]を指定すれば，時間内に接続できなかった場合はfalseが返ります
```javascript
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を返します
```javascript
var obniz = new Obniz('1234-5678',{auto_connect: false});
var connected = await obniz.connectWait(); //try once
if(connected){
obniz.io0.output(true);
obniz.close();
}
```
## close()
現在の接続を切断します。
auto_connectがfalseになっていないと、また自動的に再接続されます。
```javascript
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();
}
```
## connectionState
obnizとの現在の接続状態を接続状態を表す文字列が入っています。
以下の4状態のうちどれかになります。
state | type
--- | ---
`'closed'` | 接続していない
`'connecting'` | 接続中
`'connected'` | 接続が完了した
`'closing'` | 切断中
```javascript
var obniz = new Obniz('1234-5678');
console.log(obniz.connectionState) // => === "connecting"
obniz.onconnect = async function() {
console.log(obniz.connectionState) // => === "connected"
}
```
## debugprint
通信でやりとりされるjsonを出力したり、接続状態などのobniz.js内のログがconsole.logに出力されます。
```javascript
var obniz = new Obniz('1234-5678');
obniz.debugprint = true
obniz.onconnect = async function() {
obniz.io0.output(true);
}
```
## resetOnDisconnect(reset)
オプションである `reset_obniz_on_ws_disconnection` の設定をあとから変更する場合に使う関数です。
obniz.jsでは標準でtrueなので、obnizクラウドは同一obnizへのwebsocket接続が0本になったところでobnizに対してリセットを行います。
リセットするので、出力されている電圧などももとに戻り、pwmなども全て停止します。
この関数でそれを無効にし、リセットしないようにできます。
この設定はobnizがオンラインである限り有効となります。
```Javascript
// Example
obniz.resetOnDisconnect(false);
```