Language: Japanese, English (Google Translation)

RelayServer.js 概要

さまざまな WebSocket リレーサービスを使用して、CHIRIMEN デバイスを含むウェブアプリをインターネットを介して簡単に通信・連携可能にするライブラリです。

CHIRIMEN チュートリアル 受講者など初学者による利用を想定し、機能をシンプルに絞り他のライブラリや標準 API とも使い勝手を揃えることで、簡単に使えるよう設計しています。WebSocket リレーサービスはサービス毎に用語や API なども異なりますが、RelayServer.js を使えば同じ API でいつでも好みの WebSocket リレーサービスを切り替え・組み合わせて利用できます。

ためしてみる

Live Demo Source
Example1 GitHub

ライブラリ

構成

構成図

上の構成図で RelayServer.js の役割を示します。


使用方法

ライブラリを読み込む

<script src="https://chirimen.org/remote-connection/js/RelayServer.js"></script>

Note: scaledrone を使用するときには追加のライブラリ読み込みが必要です (後述)

初期化 Step1: リレーサービスインスタンスを取得する

var relay = RelayServer("achex", "chirimenSocket"); 

achex は利用したいサービス名、chirimenSocket はそのサービスを利用するためのトークン (Achex の場合は任意文字列) です。 ここでは Achex を利用する場合を例に挙げます (他のサービスでの利用については後述)。 先の図で示したように、トークンごとに別のスペース (メッセージ中継を行うグループ) が作られ、同一トークンに接続したクライアント間で通信が可能になります。

初期化 Step2: チャンネルを取得する

var channel = await relay.subscribe("chirimenLED");

chirimenLED はチャンネル名(任意の文字列)です。

subscribe() はリレーサーバと通信して登録を行う非同期関数です (通信に時間が掛かるため)。呼び出し前に await を付けるのを忘れないようにしてください。この初期化ステップは async を頭に付けた非同期関数内で実行するようにしましょう。

初期化Step3: メッセージ受信ハンドラを設定する

channel.onmessage = getMessage;

function getMessage(message){
    console.log(message.data);
}

onmessage に代入した関数(ハンドラ)の第一引数にメッセージオブジェクトが送られます。メッセージオブジェクトのdataプロパティにメッセージ本文が入っています。(上の例ではmessage.data) メッセージ本文は文字列もしくは任意のオブジェクトです。(次項参照)

初期化は以上で完了です。

メッセージの送信

一旦初期化が完了すれば、同じサービス、トークン、チャンネルに登録したウェブアプリ間でメッセージを送受信できます。 メッセージを送信するときは次のように send() に送信したいメッセージを渡します。

channel.send("Hello Remote Device");

メッセージとしてオブジェクトも受け付けられます。

channel.send({temperature:24, humidity:60});

サービスごとの利用方法

RelayServer.js では現在、Achex (Legacy Server), Scaledrone, WebSocket.IN に対応しています。いずれのサービスを利用する場合でも同じ API で使えるので、好みやサービスの利用制限などに応じて簡単に切り替えられます。

サービスごとに違いがあるのは、最初の RelayServer インスタンスの取得部分のみです。

var relay = RelayServer("serverName", "serviceToken");

注: scaledrone では別途専用ライブラリの読み込みも必要です

serverName

RelayServer の第一引数 serverName には以下のいずれかの文字列を指定してください:

serviceToken

RelayServer の第二引数 serviceToken にはリレーサーバとの接続時に利用するトークンを指定します。ここでいうトークンはリレーサーバに接続するユーザやクライアントを認証するために使われる乱数文字列で、その指定方法やトークンに該当するものの用語 (API Key や Channel ID) はサービスごとに異なります。

Achex (Legacy Server)

Achex (Legacy Server) の使い方は上記の例の通りです。

Achex (Legacy Server) では接続するユーザの認証を行っておらず、トークンとしては任意の文字列を指定できます。サービスへのアカウント登録手続きやトークンの発行手続きなどが不要であり事前準備なく容易に利用できる反面、ユーザの認証を行わないため、同じチャンネル名を指定すると人は誰でも何処からでもメッセージの送受信が出来てしまいます (第三者が送受信できては困る場合には使えない)。

WebSocket.IN

WebSocket.IN では、RelayServer.js における ServiceToken のことを、「API Key」と呼んでいます。

アカウントを作成し、API Key を取得してください:

Note: WebSocket.IN の仕様としては、チャンネル名には数値しか使えません。そこで RelayServer.js では relay.subscribe() に指定する任意の文字列をCRC16 を用いて数値に変換することで差異を吸収しています。

Scaledrone

Scaledrone では、RelayServer.js と用語定義が異なるので注意してください。

また、RelayServer.js の前に **scaledrone.com が配信している専用ライブラリも読み込む必要があります:

<script src='https://cdn.scaledrone.com/scaledrone-lite.min.js'></script>
<script src="https://chirimen.org/remote-connection/js/RelayServer.js"></script>

アカウントとチャンネルを作成し、トークン (Channel ID) を取得してください:


WebIDL

RelayServer.js の WebIDL (API 仕様を記述したもの) を以下に紹介します。

enum ServiceName { "achex", "websocketin" , "websocket.in" , "scaledrone" };

[Exposed=(Window)]
interface RelayServer {
  constructor(ServiceName serviceName, USVString serviceToken);
  Promise<Channel> subscribe(optional USVString channelName);
}

interface Channel {
  readonly attribute USVString serverName;
  attribute MessageHandler onmessage;
  void send(USVString or object );
};

callback interface MessageHandler {
  void handleMessage(RSMessage message);
};

interface  RSMessage {
  readonly attribute object data;
  readonly attribute USVString origin;
  readonly attribute USVString timeStamp;
}

Tests

Test1