API トークンの発行

コンソール画面にアクセスして「新規トークン発行」ボタンを押します。API トークンが発行されたことを確認したら「起動」ボタンを押します。

コントローラの操作方法

API サーバーからの通知がコントローラの下部に表示されます。同じメッセージを連続して複数回受信した場合はその回数が括弧内に表示されます。起動中のコントローラに対応する API トークンはアドレスバーで確認できます。コントローラには操作ボタンが 8 つあります。タップ操作するとボタンに応じたメッセージがデバイスに 1 回通知されます。長押しすると 0.5 秒間隔で継続的に通知されます。

コントローラのボタン番号

右側の無印ボタンと左側の矢印ボタンには、それぞれ↑←→↓の順に連番が割り当てられています。

Arduino の接続方法

SDK で提供される C/C++ ライブラリを利用します。WiFi モジュール ESP-WROOM-02 を介してインターネットに接続します。

Raspberry Pi の接続方法

ご使用の言語に応じて、以下の GitHub ページをご参照ください。

以下は Python で接続したときの様子

その他のデバイス

WebSocket クライアントが存在すれば利用可能です。各デバイスでサポートされているプログラミング言語で記述されたクライアントアプリケーションを Qoosky API サーバーに接続して、token をキーに含む JSON 文字列で API トークンを送信してください。

{"token":"XXXX-XXXX-XXXX-XXXX"}

エンドポイント

ws://api.qoosky.dev/v1/websocket-relay-server/actuator/ws
wss://api.qoosky.dev/v1/websocket-relay-server/actuator/ws

補足情報 (通常は不要な情報です)

以下の内容は Qoosky Cloud Controller の一般利用のためには不要な情報です。高度な設定を行いたい場合にご参照ください。サーバーアプリケーションのソースコードは GitHub で公開されています。類似アプリケーションを開発する際などにご活用ください。

サーバー構成

API 利用時のイメージがつかみやすくなるため、簡略化したサーバー構成を記載します。

  • 前述の利用手順で「起動」ボタンを押すと Web ブラウザに JavaScript アプリケーションがダウンロードされます (図1-3)
  • ダウンロードが完了すると自動的に API サーバーとの WebSocket コネクションを確立します (図4-5)
  • Arduino や Raspberry Pi 等のデバイスに API トークンを設定して API サーバーとの WebSocket コネクションを確立します (図6-7)
  • API サーバーは提供された API トークンに応じて適切な Web ブラウザとデバイスの組を識別します。
  • API サーバーに通知されたメッセージは対応する相手に双方向にプロキシされてリアルタイムに通知されます (図4,6)。

タイムアウト時間

ペアリングされていない状態では API サーバーからデバイスに自動で Ping メッセージが定期的に送信されるためデバイスが API サーバーから切断されることはありませんが、サーバーリソースは有限なため、ペアリング後にメッセージのやり取りが 90 秒間なされない組のコネクションはサーバーによって切断されます。ペアリングしているにも関わらずメッセージのやり取りが 90 秒間なされないことが想定される用途の場合、これを回避するためには Ping/Pong 用途の空のメッセージを 1 分に一回送信してください。

ネットワーク障害への対策

タイムアウト時間とは関係ありませんが、切断時に Raspberry Pi 等のデバイスが自動で API サーバーに再接続する処理を実装しておけば、何らかのネットワーク障害で一定期間切断された後であっても、再度スマートフォンや PC でコントローラを起動したときに常にペアリングできる状態になるため安心です。

平文通信 (ws) と SSL 通信 (wss) の使い分け

自宅に設置されたロボットを操作する場合など、通常のネットワーク環境においては平文通信で問題ありませんが、プロキシが存在するネットワーク環境においては SSL 通信が必須となる場合があります。

ルート証明書

SSL 通信時に api.qoosky.dev のサーバー証明書を署名した認証局のルート証明書が必要な場合は websocket_clients からダウンロードしてください。