Webmo JavaScript Client Library "webmo.js"ドキュメント

Last Modified: 2016/6/16 Cidre Interaction Design Inc.

基本的な使い方

簡単なサンプルコード

　以下にwebmo.jsが提供するWebmo制御のためのオブジェクトであるWebmo.ws(後述)を用いて， Webmoに接続し，毎秒360度の速度で2秒間回転させるサンプルコードを示します． 
  <html>
  <body>
    <!-- ライブラリ読み込み -->
    <script src="https://cdn.rawgit.com/cidreixd/webmo-library-javascript/master/dist/webmo.min.js"></script>
    <!-- 2秒間回す -->
    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します

        // ブラウザがWebmoに接続したら呼ばれる関数
        webmo.onopen = function () {
            webmo.rotate(360) // 360[度/秒]で回転する
            //2秒後に停止する
            setTimeout(function () {
                webmo.stop()
            }, 2000)
        }
    </script>
  </body>
  </html>

ライブラリのロード

　"Webmo.js"のロード方法は大きく分けて2種類存在します．
  1. CDNよりロードして使用する
  2. Webmo本体よりロードして使用する
　本ドキュメント内のサンプルコードは基本的に1.のCDNよりロードする方法で記述されています． この方法の利点としては常に最新版のWebmo.jsを利用できることが挙げられます．
　しかし，インターネットに接続していない環境でWebmoを使用したい場合には1.は使用することができません． その場合は，2.のWebmo本体よりWebmo.jsをロードする方法を使用します．以下に2.のサンプルコードを示します． 
    <html>
    <body>
      <!-- ライブラリ読み込み (Webmo本体のWebmo.jsを使用)-->
      <script src="http://webmo.local/javascripts/webmo.js"></script>
      <!-- 2秒間回す -->
      <script type="text/javascript">
          //Webmo.wsのインスタンス化
          var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します

          // ブラウザがWebmoに接続したら呼ばれる関数
          webmo.onopen = function () {
              webmo.rotate(360) // 360[度/秒]で回転する
              //2秒後に停止する
              setTimeout(function () {
                  webmo.stop()
              }, 2000)
          }
      </script>
    </body>
    </html>

Webmo.wsとWebmo.http

　webmo.jsにより提供されるWebmo制御のためのオブジェクトは以下の2つが存在します． 　どちらを用いる場合でも，提供される関数は同じものです．
　HTTPによる通信を行うWebmo.httpではXMLHttpRequestを使用している関係で，Webmo.httpを使用している HTMLファイルがHTTPサーバによって送信されたものでない場合， 例えばローカルに置いたHTMLファイルをブラウザで開いた場合には使用できません．
　加えてHTTPによる通信ではコマンド発行のたびにWebmoとブラウザとの間の接続を確立するため， 多少のオーバヘッドが存在してしまいます．一方で，WebSocketによる通信では最初に一度接続を確立すると， その接続を使用し続けるため，オーバヘッドが少なくなります．これらの理由から，頻繁に通信を行うような用途や，ローカルに置いたHTMLから操作をしたい場合には WebSocketによる通信を行うWebmo.wsを使うことをおすすめします．
　WebSocketによる通信は上に書いたように，最初に接続を確立する必要があるため，Webmoに対して 具体的な操作を行う前に，Webmoへの接続が確立していることを保証する必要があります． 上記サンプルコードの"webmo.onopen"に指定された関数がブラウザとWebmoとの間の接続が確立した際に 自動で呼び出されるようになっています．
　一方で，Webmo.httpを用いる場合は毎回接続を確立するため，このような接続の確立を待つような処理は必要ないため， 下記のように記述できます．そのため，シンプルさではWebmo.httpが若干優れます． 
  <html>
  <body>
    <!-- ライブラリ読み込み -->
    <script src="https://cdn.rawgit.com/cidreixd/webmo-library-javascript/master/dist/webmo.min.js"></script>
    <!-- 2秒間回す -->
    <script type="text/javascript">
        //Webmo.httpのインスタンス化
        var webmo = new Webmo.http("webmo.local");// 引数にはホスト名を指定します

        //webmo.onopenは不要
        webmo.rotate(360) // 360[度/秒]で回転する
        //2秒後に停止する
        setTimeout(function () {
            webmo.stop()
        }, 2000)
    </script>
  </body>
  </html>

Webmo.jsが提供する関数

　以下に示す関数のうち，"Webmo."という接頭辞が付いているものはコンストラクタになります．

Webmo.ws()

WebSocketによるWebmoコントロール用インスタンスの生成

  • 引数：hostname:接続先Webmoのホスト名
  • 返り値：Webmoコントロール用のインスタンス
　Webmo.ws(hostname)はWebSocketによるWebmoコントロール用のインスタンスを生成します．引数hostname には接続先のWebmoのホスト名を指定します．
　Bonjourによる名前解決が可能である場合には，Webmoの設定画面の"Webmoの名前を変える"で 設定した名称の後ろに".local"を付加した名称がホスト名として利用できます.
　Webmo.wsとWebmo.httpで触れたように，WebSocketでの接続では 接続が確立したことを保証する必要があるため，この関数によるインスタンス化の後に"(インスタンス名).onopen" に指定した関数が呼び出されるまでその他の操作を行う関数が使用できないことに注意してください．

サンプル

      <script type="text/javascript">
          //Webmo.wsのインスタンス化
          var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
          // ブラウザがWebmoに接続したら呼ばれる関数
          webmo.onopen = function () {
              //この関数の内部，あるいはこの関数が呼び出された後の操作のみが有効となります
              webmo.rotate(360) // 360[度/秒]で回転する
          }
      </script>

Webmo.http()

HTTPによるWebmoコントロール用インスタンスの生成

  • 引数：hostname:接続先Webmoのホスト名
  • 返り値：Webmoコントロール用のインスタンス
　Webmo.http(hostname)はHTTPによるWebmoコントロール用のインスタンスを生成します．引数hostname には接続先のWebmoのホスト名を指定します．
　Bonjourによる名前解決が可能である場合には，Webmoの設定画面の"Webmoの名前を変える"で 設定した名称の後ろに".local"を付加した名称がホスト名として利用できます.
　Webmo.wsとWebmo.httpで触れたように，Webmo.httpでは 各種関数を呼び出すごとにWebmoとの接続を確立させるため，接続の確立まで待機をする必要がありません． そのため，Webmo.wsと異なり"(インスタンス名).onopen"を使用する必要はありません．

サンプル

    <script type="text/javascript">
        //Webmo.httpのインスタンス化
        var webmo = new Webmo.http("webmo.local");// 引数にはホスト名を指定します
        //webmo.onopenは不要
        webmo.rotate(360) // 360[度/秒]で回転する
    </script>

rotate()

Webmoを回転させる

  • 引数：speed:回転速度[度/秒]（speed < 0：逆転，speed > 0 : 正転，speed = 0：停止）
  • 返り値：なし
　rotate(speed)はWebmoを引数speedに指定された速度で回転させる関数です．単位は[度/秒]です． speedに負の値を指定すると，正の値を指定した場合と逆方向に回転します．
　過熱による保護機能の動作等の場合を除き，rotate()を実行した場合は後述するstop()などの関数を実行するまで Webmoは回転し続けます．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
            webmo.rotate(360) // 360[度/秒]で回転する
        }
    </script>

rotateTo()

Webmoを指定角度まで回転させる

  • 引数1：degree:回転角度[度]
  • 引数2：absRange:目標角度の許容量[度]
  • 引数3：speed:回転速度[度/秒]（speed < 0：逆転，speed > 0 : 正転，speed = 0：停止）
  • 返り値：なし
　rotateTo(degree,absRange,speed)はWebmoを引数speedに指定された速度で回転させ， degreeが指す位置まで回転させる関数です．引数speedの単位は[度/秒]， 引数degreeの単位は[度]で，ここで指定する角度はWebmoに内蔵されているセンサが指す回転角度です． rotate()と同様に，speedに負の値を指定すると，正の値を指定した場合と逆方向に回転します．
　第2引数であるabsRangeは目標角度の許容量を示す引数で，第1引数が指す角度から見て前後absRange[度]の範囲に 到達した時点で回転を停止するという実装になっています．第3引数であるspeedの速度によっては，absRangeの 値が小さい場合に停止できず，目標位置を通りすぎてしまう場合があります．そのような場合は stop()などの関数で停止をする必要があります．
　目標位置を通りすぎてしまう場合，absRangeの値を大きくするという方法の他に， speedを小さい値とすることでも改善する場合があります．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
          webmo.rotateTo(270,5,90) //90［度/秒]で回転し，270±5[度]の位置まで移動
        }
    </script>

rotateBy()

Webmoを指定角度分だけ回転させる

  • 引数1：diff:回転角度[度]
  • 引数2：speed:回転速度[度/秒]
  • 返り値：なし
　rotateBy(diff,speed)はWebmoを引数speedに指定された速度で， diff[度]だけ回転させる関数です．引数speedの単位は[度/秒]， 引数diffの単位は[度]となります．
rotate()と同様に，speedに負の値を指定すると，正の値を指定した場合と逆方向に回転しますが， diffとspeedの双方が負の値である場合は，これらの値の両方が正の値であった時と同じ方向に回転します．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
          webmo.rotateBy(270,90) //90［度/秒]で回転し，現在位置から270[度]動かす
        }
    </script>

stop()

Webmoを停止させる

  • 引数1：smooth(デフォルト値:false):停止時に徐々に減速させるかどうか(true:徐々に減速する/false:即時に速度を0にする)
  • 引数2：lock(デフォルト値:false):停止後にモータに通電し位置を保持するかどうか(true:保持する/false:保持しない)
  • 返り値：なし
　stop(smooth,lock)はWebmoを停止させる関数です．
　引数smoothはこの関数により停止が実行される際に，徐々に減速を行い，なめらかに停止を行うかどうかを指定できます．
　引数lockはこの関数により停止が実行され，モータの回転速度が0[度/秒]になった後もモータに通電し続け，位置の保持を行うかどうかを 指定するものです．
　例えば，軸に対して回転する方向に何らかの外力が加わっている場合，位置の保持を行わない場合にはその外力により モータが回転してしまいます．ただし，位置の保持は消費電力が高く，本体の温度上昇につながりますので，最低限に留めることをおすすめします．
　この関数の2つの引数にはデフォルト値が設定されています．引数を指定せずstop()を実行した場合には，即時に速度が0となり，停止後は モータには通電されない状態となります．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
          webmo.rotate(90) //90［度/秒]で回転する
          setTimeout(function () {//2秒後に実行
              webmo.stop(true,false)//徐々に減速して停止し，停止後は位置の保持を行わない
          }, 2000)
        }
    </script>

stopHard()

Webmoを急停止させる

  • 引数：なし
  • 返り値：なし
　stopHard()はWebmoを停止させる関数です．
　stopHard()はstop()関数をstop(false,false)として呼び出したものと等価です． すなわち，stopHard()を実行するとWebmoの回転速度は即時に0[度/秒]となり，停止後は位置の保持が行われません．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
          webmo.rotate(90) //90［度/秒]で回転する
          setTimeout(function () {//2秒後に実行
              webmo.stopHard()//即時に速度を0[度/秒]にして停止し，停止後は位置の保持を行わない
          }, 2000)
        }
    </script>

stopSoft()

Webmoをなめらかに停止させる

  • 引数：なし
  • 返り値：なし
　stopSoft()はWebmoをなめらかに停止させる関数です．
　stopSoft()はstop()関数をstop(true,false)として呼び出したものと等価です． すなわち，stopSoft()を実行するとWebmoは徐々に減速した後停止し，停止後は位置の保持が行われません．

サンプル

    <script type="text/javascript">
        //Webmo.wsのインスタンス化
        var webmo = new Webmo.ws("webmo.local");// 引数にはホスト名を指定します
        webmo.onopen = function () {
          webmo.rotate(90) //90［度/秒]で回転する
          setTimeout(function () {//2秒後に実行
            webmo.stopSoft()//なめらかに減速して停止し，停止後は位置の保持を行わない
          }, 2000)
        }
    </script>

その他参考資料

HTTP REST API リファレンス

Webmo HTTP REST API リファレンス： WebmoのHTTP REST APIのリファレンスです．Webmo.httpはこのREST APIを操作する関数群として実装されています．
(c)Cidre Interaction Design Inc.