EasyWebSocket ライブラリの使い方解説

前回の記事ではArduino core for ESP8266 の自作ライブラリ、EasyWebSocket のインストールや設定方法を紹介しました。
今回はそのプログラミング方法を紹介したいと思います。

ライブラリをバージョンアップしました。
現在 BETA 1.3 です。
こちらのページで紹介してます。再接続しやすくなり、更に使いやすくなりました。
以下、古い記事ですのでご了承ください。
2016/2/20

その前にちょっとした課題点があります。
これにはSPIFFSファイルシステムを使っていますが、５つのHTMLテキストファイルと、ユーザーが書き込んだSSIDやパスワードなどの文字列をマージして読み出しているので、コネクション確立に少々時間がかかってしまいます。
ユーザーがHTMLを改変しないのであれば、ライブラリ内にHTMLも含んだ方が良いかもしれません。インストールがちょっと手間というのもあり、SPIFFSファイルシステムは別の方法で使った方が良いかもしれません。幸い、ESP-WROOM-02には膨大なSRAMがあるので、ライブラリにHTMLを組み込んでも問題ないような気がします。ユーザーは編集しにくいですが、より簡単に早く実行できますからね。この辺は次期バージョンアップで対応したいと思います。

では、プログラミング方法を解説していきます。
ちなみに、このライブラリ作成初心者の私が作成したので、いろいろと問題が有るかも知れません。動作を補償するものではありませんのでご了承ください。あくまでベータのベータ版です。

１．EasyWebSocketライブラリの概要

EasyWebSocketライブラリはGitHubの　こちら　にあります。

これはブラウザのボタンやスライダー、テキスト表示に特化したライブラリです。

みなさんも既にご存知かと思いますが、GitHub に公開してある ESP8266 Community Forum にある Arduino core for ESP8266 ライブラリを使用していて、それをincludeしています。

ご自分のアクセスポイント（ルーター）のSSIDとパスワード、ESP-WROOM-02 ( ESP8266 )のローカルＩＰアドレスを入力するだけで、WebSocketハンドシェイク（コネクション確立）が可能です。

ブラウザへ送信するHTML文のヘッダやBODY要素まではライブラリ内、およびサンプルスケッチEasyWebSocket_Testフォルダの中のdataフォルダにある５つのHTMLテキストファイルを連結（マージ）して出力します。これには前回の記事で述べたSPIFFSファイルシステムを使用して、予めWROOM(ESP8266)のフラッシュメモリにアップロードしておく必要があります。これをしないと動作しませんのでご注意ください。
ということで、ユーザーはArduinoスケッチ内ではBODY要素内のHTMLタグをString型の文字列で記入するだけでＯＫです。
しかも、そのHTMLタグ内のボタンやスライダー、テキスト表示タグをライブラリ化していますので、HTML文が良く分からない方にもある程度簡単にプログラムが組めるようにしてみました。

HTMLタグとESP-WROOM-02からのデータはテキスト文字列をＩＤとして関連付けています。
このＩＤ文字列でどのボタンが押されたかなどを振り分けることができます。

WROOMからPingを送信して、ブラウザからPongを受信し、Pongが無いとWROOMからコネクション切断します。
その数秒後に再コネクション可能です。

ネットワークやスマートフォンの性能によっては、スライダーなどの連続データ送信によって通信切断が起きる場合があります。
その場合、スマートフォンからの間引き送信によって、不意の通信切断を防ぐことができます。
ただ、その場合、操作の追従性は悪くなります。

２．クラスおよびプログラミング使用方法

前回の記事でもあげましたが、今回も一応サンプルスケッチを記載しておきます。
これをご覧いただきながら解説していきます。

ライブラリをバージョンアップしました。
現在 BETA 1.3 です。
こちらのページで紹介してます。再接続しやすくなり、更に使いやすくなりました。
2016/2/20

【ソースコード】 (※無保証　※PCの場合、ダブルクリックすればコード全体を選択できます)

まずはライブラリのそれぞれのクラスの使い方を説明します。

５～７行目ではルーターのSSID、パスワード、WROOMのローカルＩＰアドレスを入力します。
const char* というポインタで宣言しなければなりません。

１５行目ではブラウザへ送信するHTML文字列を宣言してます。
HTTPレスポンスヘッダ、HTML内のJavaScriptのWebSocket設定などのヘッダなどは、事前にSPIFFSファイルシステムアップローダーでフラッシュメモリにアップした５つのファイルを読み込んでライブラリから出力していますので、ユーザーは＜ｂｏｄｙ＞要素内のHTMLだけ作ればＯＫです。それが２９～５７行目になります。
これはグローバル変数領域でString文字列を宣言します。なぜならば、コネクション切断されて再接続するときにこの文字列が再び必要になるからです。

17行目では、ブラウザ表示サイズを定義していて、62行目のクラスで使用します。

13行目：
EasyWebSocket ews;

ews がクラス名です。これは任意に設定可能です。この宣言はグローバル変数領域で宣言してください。

29行目；
ews.EWS_Body_style(“文字色”, “背景色”);

ews. が先ほど宣言したクラス名です。
これはHTMLの＜ｂｏｄｙ＞要素のタグをライブラリ化しただけです。つまり、String型のbodyタグを返します。
ですから、ブラウザ表示全体の文字色、背景色を決めます。

34行目：
ews.EWS_Receive_Text(“ID文字列”,”文字の大きさ”,”文字色”);

これはWROOMからのデータをブラウザが受信したテキストを表示するためのHTMLタグ文字列を返します。
これは実はネーミング間違えてしまいました。勘違いしてWROOMが受信するデータと思っちゃいますね。次期バージョンアップで変更したいと思います。失礼しました・・・。
ID文字列では、WROOMから送られて来るデータのID文字列と一致すれば、その文字列をブラウザに表示します。89行目でWROOMから送信するデータのID文字列を”text”としています。
文字の大きさは 25px のように “px” をつけます。これはHTMLでは一般的ですね。
文字色は”RED”でもいいですが、”#FF0000″でもよいです。

37行目：
ews.EWS_OnOff_Button(“ID文字列”,ボタン幅,ボタン高さ,文字サイズ,”文字色”,”ボタン色”);

サンプルスケッチではBLUEとかありますが、ボタンの色ではありません。ID文字列です。この文字列がブラウザから送られてくるときに ‘|’ という文字を挟んでデータとマージして送られてきます。ONにすると100というデータ。OFFは0というデータを送ります。終端は ‘;’ というセミコロンです。
100|BLUE;
という感じの連結文字列で送られてきます。
それを94行目で受信して、’|’という文字で分割してデータを取り出すわけです。
色の指定方法は先ほど紹介したものと同じですが、サイズの数値は文字列ではなく、数値となっています。統一してなくてスイマセンm_ _m。次期バージョンアップで対応したいと思います。

38行目：
ews.EWS_Slider_BoxText(“ボックスID文字列”,ボックス幅,ボックス高さ,文字サイズ,”文字色”);

これは、ブラウザのスライダーを動かした場合にボックステキストに数値を0-100の間で表示するものです。
このID文字列はスライダーのID文字列と同じにしてください。

39行目：
ews.EWS_Touch_Slider(“ID文字列”, “ボックスID文字列”);

これはブラウザにスライダーを表示させ、スライダー値を0-100の間でWROOMへ送信します。
ボタンのデータ送信と同様、文字 ‘|’ で区切られたデータを送信して、終端は ‘;’ です。
87|BLUE;
という連結文字列をWROOMに送信します。
ID文字列でWROOM側でどのスライダーが操作されたかを判断します。
ボックスID文字列で38行目のボックステキストの数値と連動します。
因みに、これはマウスでは動作しません。タッチパネル専用です。

56行目：
ews.EWS_Close_Button(“表示文字”,ボタン幅,ボタン高さ,文字サイズ);

これは、ブラウザ側のボタンでWebSocket通信を切断するものです。これはIDは不要で、単独使用です。
これを押すとcloseコマンドがWROOMに送信されます。

60行目：
ews.AP_Connect(ssid, password);

これはWROOMの電源を立ち上げたら、ルーターに接続するクラスです。

62行目：
ews.EWS_HandShake(LocalIPaddress, view_scale, s_rate, html_str);

これはブラウザとWebSocketのハンドシェイク（コネクション確立）させるためのクラスです。
ここでブラウザからのGETリクエストにHTTPレスポンスヘッダを返し、WebSocketスクリプトを含んだHTMLタグをブラウザに送信します。
view_scaleはHTMLの＜META＞タグに記述されます。つまり、全体の画面サイズを決めます。

重要なのが s_rate です。
ブラウザのスライダー値など、連続したデータをブラウザから送信する場合、ネットワークのトラフィックがオーバーフローする可能性があります。
この数値をゼロにするとデータの間引きはありません。
単位はミリセコンド(ms)です。
つまり、50にしたら 50ms の間、ブラウザからデータ送信しません。
そうすると、追従性が悪くなりますが、不意の通信切断を防ぐことができます。
スマートフォンが非力なＣＰＵやメモリだったりすると、これの値を大きくするといいと思います。
スマートフォンから送信している間、WROOMからもデータ送信しているわけですから、トラフィックにかなり影響される要素です。
この辺はまだ改善しなければいけないと思っていますが、どうしたらいいかまだ分からない状態です。解る方がいたら是非教えていただきたいですね。
ちなみに、この間引きプログラムはブラウザ側のJavaScriptで組んでいます。

89行目：
ews.EWS_String_DATA_SEND(str, “ID文字列”);

これは、WROOMからブラウザにデータを送信するクラスです。
strはString型で、最大127文字です。
ID文字列では34行目の
ews.EWS_Receive_Text(“text”,”25px”,”RED”);
というクラスでブラウザ側のHTMLタグのIDと関連付けています。そこに文字が表示されます。

94行目：
ews.EWS_Char_Receive(PingSendTime);

これはブラウザから送信されてくる文字列を受信して、マスク処理を外して実文字列を抽出する関数です。WebSocket通信ではこのマスク処理がキモです。
PingSendTimeではWROOMからミリセコンド単位でブラウザにPing送信する間隔を決めます。ここでは３秒間隔(3000ms)で設定してます。
Ping送信して、ブラウザからPongが返って来なければWROOM側で通信を切断するようにしてます。Ping送信の間隔が短すぎるとトラフィックに影響してきますので、十分長く取ってください。３秒くらいが適当かと思います。

97～104行目でブラウザからの文字列を実データとID文字列とを分割して、ＬＥＤをＰＷＭコントロールして調光しています。

108行目では通信切断されたときにブラウザのURL再入力で再接続できるようにハンドシェイククラスを持ってきています。

※以前のサンプルスケッチで、res_htmlという不要な引数を削除してますので、2行減っています(2015/12/2)

以上が、ライブラリのクラスの使用方法およびプログラミング方法です。

初めにも言いましたが、私はライブラリ作成初心者ですので、いろいろ不具合や誤り等があるかも知れません。
もし気付いたことがありましたらコメントやお問い合わせフォームでご連絡いただけると幸いです。

今後、このライブラリは予告なくバージョンアップやバグ修正しますのでご了承ください。
バージョンアップしたらこのブログやツィッターでご連絡させていただく予定です。

今回はここまでです。
なかなかこういう記事を書くのってホントに大変だということがしみじみ分かりました。
仕事から帰ったらパソコンに釘付けになってしまいます。
とても介護しながらは無理です・・・。
更新するのにもエライ労力と精神的ダメージを受けるもんですね。
こりゃぁ、何か良い方法を考えねばなりませんねぇ・・・。

ということで、まだまだプログラミング未熟者で、文章力も無く読みにくかったと思いますが、ここまでお読みいただきありがとうございます。
それではまた・・・。

最新記事ではWebSocketライブラリをさらにバージョンアップして、格段に使いやすくなりました。
現在BETA1.3です。
こちらのページをご覧ください。
2016/2/22

Amazon.co.jp 当ブログのおすすめ

スイッチサイエンス ESPr Developer 32 Type-C SSCI-063647

スイッチサイエンス

￥2,420（2025/03/31 10:26時点）

ZEROPLUS ロジックアナライザ LAP-C(16032)

ZEROPLUS

￥19,358（2025/03/31 20:05時点）

Excelでわかるディープラーニング超入門

技術評論社

￥2,068（2025/03/31 11:42時点）