❗ このプロジェクトは現在アルファ版です。
opnizとはM5StackデバイスをNode.js（JavaScript / TypeScript）からobnizライクに実装できるオープンソースフレームワークです。
Node.js SDKおよびArduinoライブラリがあり、WebSocketで相互通信を行います。
しくみとしてはM5StackデバイスおよびNode.js SDK間にてJSON形式のRPCメッセージをやりとりし、相互に定義されたメソッドを呼び合います。
本リポジトリはM5Stackデバイス共通ライブラリであるM5Unified向けのopniz Arduinoライブラリ リポジトリとなります。
Node.js SDKからのRPCリクエストを処理するハンドラーと、ESP32デバイスからのRPCイベントを発火するエミッターを実装したデバイスクラスを提供します。
Arduino IDEおよびPlatformIOに対応しています。
- M5Stack BASIC
- M5Stack Core2
- M5StickC
- M5ATOM Matrix
- M5ATOM Lite
- M5ATOM Echo
- M5ATOM U
- M5ATOMS3
- M5ATOMS3 Lite
- M5Stamp Pico
- M5Stamp S3
- その他ESP32、ESP32-PICO-D4、ESP32-S3デバイス
opniz CLIを使用する方法と、Arduinoを使用する方法があります。
opniz CLIでのインストール
opniz CLIとはopniz Arduino LibraryのBasicスケッチをコマンドから簡単に書き込めるCLIツールです。
npmにリリースされているので、以下のnpm installコマンドでインストールできます。
npm install -g opniz-cliopniz CLIインストール後に以下のコマンドを実行するとBasicスケッチをデバイスへ書き込みます。
デバイスのシリアルポートやWi-FiのSSID/パスワードといった情報が必要ですが、対話モードで動的に選択肢を取得し表示してくれます。
opniz upload
Arduinoライブラリマネージャーにはリリースしていないため、GitHubリポジトリよりZIPをダウンロードのうえ、Arduino IDEにて「.ZIP形式のライブラリをインストール...」を選択しダウンロードしたZIPをライブラリへ追加してください。
「Code」ボタンを押すと表示されるメニューより「Download ZIP」を選択しダウンロードします。
Arduinoのメニューより「スケッチ」→「ライブラリをインクルード」→「.ZIP形式のライブラリをインストール...」と選択し、ダウンロードしたZIPを選択します。
ArduinoJson、WebSockets、M5Unified、FastLEDライブラリが別途必要となります。
以下のコードはOpniz::M5Unifiedクラスを使用した最小限のコードです。
Arduino IDEメニューの「スケッチ例」→「opniz」→「Basic」にあるコードと同等です。
opnizインスタンスの生成、Wi-Fi接続、Node.js SDKへの接続、そしてloop関数内のopniz->loop()にてNode.js SDKからのRPCリクエストの待ち受け・ハンドリングと、デバイスへ実装されているRPCイベントの発火を行っています。
LED制御やボタンイベントはOpniz::M5Unifiedクラスにて実装されているので、このコードをデバイスへ書き込むだけでNode.js SDKから制御可能となります。
ssid、passwordをお使いのWi-Fiのものに、address、portをそれぞれNode.js SDKを実行する端末のものに書き換え、デバイスにスケッチを書き込んでみてください。
opniz Node.js SDKと連携可能になります。
// 内蔵フルカラーLEDを使用する場合は対応するデバイスのdefineを有効化
// #define M5ATOM_LED_ENABLE
// #define M5ATOMS3_LITE_LED_ENABLE
// #define M5STAMP_S3_LED_ENABLE
// #define M5STAMP_PICO_LED_ENABLE
#include <OpnizM5Unified.h>
#include <lib/WiFiConnector.h>
const char* ssid = "<SSID>"; // WiFiのSSIDに書き換え
const char* password = "<PASSWORD>"; // WiFiのパスワードに書き換え
WiFiConnector wifiConnector(ssid, password); // WiFi接続ヘルパーインスタンス生成
const char* address = "192.168.0.1"; // Node.js SDKを実行する端末のIPアドレスを指定
const uint16_t port = 3000; // Node.js SDKを実行する端末のポート番号を指定
Opniz::M5Unified* opniz = new Opniz::M5Unified(address, port); // opnizインスタンス生成
void setup() {
initM5(); // M5デバイス初期化
wifiConnector.setTimeoutCallback([]() { esp_restart(); }); // WiFi接続タイムアウト時にリブート
wifiConnector.connect(); // WiFi接続
Serial.printf("opniz server address: %s\nopniz server port: %u\n\n", opniz->getAddress(), opniz->getPort()); // Node.js SDK接続情報を表示
opniz->connect(); // Node.js SDKへ接続
}
void loop() {
opniz->loop(); // opnizメインループ
wifiConnector.watch(); // WiFi接続監視
}実装を追加して独自に拡張できます。
ハンドラーやエミッターの追加はexamples/AddHandler/AddHandler.ino（以下のコード）が参考になると思います。
このコードではEsp32クラスをもとにM5ATOMのLED制御ハンドラーとボタンイベントエミッターを拡張し追加しています。
// 内蔵フルカラーLEDを使用する場合は対応するデバイスのdefineを有効化
#define M5ATOM_LED_ENABLE
// #define M5ATOMS3_LITE_LED_ENABLE
// #define M5STAMP_S3_LED_ENABLE
// #define M5STAMP_PICO_LED_ENABLE
#include <OpnizM5Unified.h>
#include <lib/WiFiConnector.h>
const char* ssid = "<SSID>"; // WiFiのSSIDに書き換え
const char* password = "<PASSWORD>"; // WiFiのパスワードに書き換え
WiFiConnector wifiConnector(ssid, password); // WiFi接続ヘルパーインスタンス生成
const char* address = "192.168.0.1"; // Node.js SDKを実行する端末のIPアドレスを指定
const uint16_t port = 3000; // Node.js SDKを実行する端末のポート番号を指定
Opniz::Esp32* opniz = new Opniz::Esp32(address, port); // M5UnifiedクラスではなくEsp32クラスでopnizインスタンス生成
// 独自ハンドラーを作成
class FillpixHandler : public BaseHandler {
public:
String name() override { return "_led.fillpix(CRGB):void"; }; // Node.js側から受け取るRPC methodを指定
String procedure(JsonArray params) override { // nameメソッドと一致するRPCを受信したときに実行する処理を記述
CRGB Color = int2crgb(params[0]);
led.fillpix(Color);
return "true"; // 特に戻り値がなければ文字列でtrueを返す
}
};
// 独自エミッターを作成
class ButtonEmitter : public BaseEmitter {
public:
boolean canEmit() override { // true/falseを返却する処理を記述
M5.update();
return M5.BtnA.wasClicked();
};
String emit() override { // canEmitの結果がtrueなら実行される
std::vector<String> parameters;
parameters.emplace_back("BtnA"); // RPCリクエストのパラメーターを指定
return createRpcRequest("_M5.Btn.wasClicked(void):bool", parameters); // RPC methodを指定し、RPCリクエストを送信
};
};
void setup() {
M5.begin(); // M5デバイス初期化
initLed(); // LED初期化
wifiConnector.setTimeoutCallback([]() { esp_restart(); }); // WiFi接続タイムアウト時にリブート
wifiConnector.connect(); // WiFi接続
opniz->addHandler({ new FillpixHandler }); // 独自ハンドラーを登録
opniz->addEmitter({ new ButtonEmitter }); // 独自エミッターを登録
Serial.printf("opniz server address: %s\nopniz server port: %u\n\n", opniz->getAddress(), opniz->getPort()); // Node.js SDK接続情報を表示
opniz->connect(); // Node.js SDKへ接続
}
void loop() {
opniz->loop(); // opnizメインループ
wifiConnector.watch(); // WiFi接続監視
}opniz Arduinoライブラリでは以下の通信プロトコルを実装しています。
デフォルトではWebSocket (Client)が使用されます。
- WebSocket (Client)
- TCP (Server/Client同居)
opniz Node.js SDKでは以下の通信プロトコルを実装しています。
デフォルトではWebSocket (Server)が使用されます。
- WebSocket (Server)
- WebSocket (Client)
- TCP (Server/Client同居)
使用するプロトコルによりopnizのコンストラクタパラメータが変わってきます。
| プロトコル | コンストラクタパラメータ | パラメータ内容 |
|---|---|---|
| WebSocket (Client) | Opniz::M5Unified(address, port, id) |
address: 接続先のopnizのIPアドレスまたはhostnameを指定しますport: 接続先のopnizのWebSocket Serverポート番号を指定しますid: opniz Serverを経由してopniz Node.js SDKと接続する場合に、opniz Node.js SDKで指定したidと同じ値を指定します（省略可） |
| TCP (Server/Client同居) | Opniz::M5Unified(address, port, protocol) |
address: 接続先のopnizのIPアドレスを指定しますport: 接続先のopnizのTCP Serverポート番号を指定しますprotocol: Protocol::TCPを指定します（文字列ではありません。enumを用意しています） |
- opniz SDK for Node.js
- opnizデバイスをNode.jsから遠隔制御するためのSDK
- opniz CLI
- opniz Arduino LibraryのBasicスケッチをコマンドから簡単に書き込めるCLIツール
- opniz Server
- opniz Node.js SDKやopnizデバイスからのJSON RPCメッセージを中継するWebSocketサーバ