NEEOドライバとmeta（メタ）
meta（jac459/meta）は、active/フォルダからJSON デバイスファイルを読み込み、それぞれをローカルのNEEO Brainに登録されるNEEO SDKドライバに変換するNode.jsエンジンです。デバイスをJSONで記述するだけで、JavaScriptを書く必要はありません（小さなDYNAMIK式を除く）。
言語: ドキュメントは日本語で記述されていますが、JSONキー、エンジンキーワード、ボタン名、ログ文字列はここに記載された英語のまま正確に使用してください。
スコープ: 買収前のNEEO SDK、ローカルのBrain、metaのみを対象とします。Control4関連のマテリアルやNEEOクラウド（シャットダウン済み）は無視してください。
基本ルール（必読）
- JSONキーやコマンドタイプを勝手に作らないでください。 リファレンスにない機能が必要な場合は、その旨を伝え、代替案（
references/companion-services.mdにあるNode-RED + MQTT、小規模なローカルRESTブリッジ、cliコマンド、隠しボタンチェーン）を提案してください。 - 純粋なJSON: コメント、末尾のカンマは禁止。ダブルクォートを使用。
python3 -m json.tool file.jsonとpython3 scripts/check_driver.py file.jsonで検証してください。 - コマンドタイプは大文字小文字を区別します:
http-get、http-rest、http-post、http-get-soap、static、cli、repl、webSocket、socketIO、jsontcp、mqtt、wol、mDNS、android。 versionは 表示コンポーネントを追加するたびに更新してください。Brainはコンポーネントを追加するだけです。名前の変更や削除には、NEEOアプリでデバイスを削除して再追加する必要があります（レシピとショートカットも再作成）。インストール済みデバイスではバージョンアップだけでは不十分な場合があります。Brainを確認してください（references/debugging.md）。- ラベル、スイッチ、スライダー、イメージ、センサーの名前（キー）は英数字のみ 使用可能です。スペースや記号があるとセンサーリンクが壊れ（Brainで
"sensor": null）、そのコンポーネントをショートカットに使うとリモートが同期時にクラッシュします。表示されるlabelテキストは自由です。ボタン名にはスペースを含められますが、+やアクセント記号は避けてください（DISNEY PLUS、ラベルDisney+）。 - ラベルにバインドされた変数に
""を書き込まないでください: meta v1.2.0では、ラベルがテキストから""に戻るとmetaが停止します。代わりに" "（または読みやすいフォールバック）を書き込んでください。ラベル変数も初期値は" "にしておく習慣をつけてください。 - ラベルに渡すすべての外部テキストをサニタイズしてください:
"→'、\→/、制御文字→スペース、$→＄（全角）。ドライバ内およびソース側で行ってください。 - リスナーはセッションごとに一度だけ起動します。
ListenerOnガードと、すべての可視コントロールに配線された隠し__LISTENボタンを通じて制御してください。POWER ONだけに頼ったり、mqttリスナーで__CLEANUPを呼び出したりしないでください（references/listeners-and-state.md）。 - ポーリングよりもイベントを優先（
webSocket、socketIO、mqtt）。ポーリングする場合はpooltimeは3000以上に設定してください。 $Resultは常に文字列で、失敗時は"undefined"になります。JSON.parseの前には必ずガードを入れてください。ボタンはスカラー（ok）、ディレクトリアクションのフィーダーは["ok"]を返します。- 変数名: 別の変数の接頭辞になる名前は使用しないでください。
$Varに文字が続くと別の変数として解釈されます。 - セキュリティ:
DYNAMIKとcliはメタホスト上でコードを実行します。共有するドライバに秘密情報をハードコードしないでください。metaをroot/adminで実行しないでください。 - 元に戻せない変更には同意が必要: 可視コンポーネントの追加（例：
DIGIT 0-9）はデバイスを再インストールしないと元に戻せません。事前に確認してください。 - 成果物の区別: metaドライバはJSONオブジェクト（
{で始まり、名前に-flowを含まず、active/に配置）。Node-REDフローはJSONリスト（[で始まり、常に*-flow.jsonという名前で、Node-REDにインポート）。 templateでは、dynamicnameとdynamicidは必須。dynamicidは安定していること（DHCPのIPではなくMACアドレスやハードウェアID）。
ワークフロー
- 必要な情報を収集（一度に最大3つの質問）: 正確なデバイスモデル；その制御プロトコルまたはAPI（HTTP/REST、WebSocket、raw TCP、MQTT、IRのみ、Android TV...）；固定IPかどうかと安定したID（MAC）；制御するものと表示する状態；metaのバージョンと実行環境（Pi with pm2、Docker...）；MQTTブローカーとNode-REDが利用可能かどうか。公式APIドキュメントがあればそれを探してください。
- NEEOタイプ（
references/driver-anatomy.md、セクション「types and recognized buttons」）とディスカバリーパターン（references/discovery.md）を選択：静的単一デバイス、ユーザー入力IP、mDNS、またはハブ。 assets/のスケルトンから開始:skeleton-static.json（固定アドレスの1デバイス）またはskeleton-register-ip.json（ユーザーがIPを入力）。references/patterns.mdから実績のあるパターンを再利用。- ロジックの配置場所を決定: シンプルなHTTPまたはWebSocketデバイス：すべてドライバ内。バイナリまたはステートフルなプロトコル（raw TCP、永続セッション、ペアリング、バースティな状態）：間にコンパニオンサービスを置き、高速なHTTPコマンドと、保持されたMQTTメッセージとしてプッシュされる状態を使用（
references/companion-services.md）。 - 納品前にチェック:
python3 -m json.tool driver.jsonその後python3 scripts/check_driver.py driver.json（名前、空のラベル値、タイプ、バージョン、ガード、ポーリング...）- リスナーがあるドライバでは
node scripts/simulate_guard.js driver.json（セッションをまたいだ__INITIALISE/__CLEANUPのカウント） - 複雑な
DYNAMIK式はNodeで実際の置換ルールを使って評価（references/logic-and-commands.md） references/pitfalls.mdを再読。
- 次の順序で成果物を納品: サマリー（デバイス、プロトコル、NEEOタイプ、ディスカバリーパターン、対応/非対応項目）；検証済みの完全なJSONファイルと明示的なファイル名；デプロイ手順（
active/へコピー、meta再起動、NEEOアプリでデバイス追加、レシピの可視性とショートカット作成）；テスト計画（試すボタン、期待される結果、確認するログ行）；実機で検証していない仮定；次のイテレーション。複数ファイルのプロジェクト（ドライバ＋フロー＋サービス）：操作順序、各成果物のバージョンマーカーとインストールされているバージョンの確認方法。常に実機でテストされていないことを明記。
リファレンスマップ（タスクに必要なものだけ読む）
| ファイル | 読むタイミング |
|---|---|
references/meta-engine.md | アーキテクチャ、インストール、フォルダ、再起動、ログレベル、metaが公開するMQTTトピック、Docker/NASホスティング、既知のmeta v1.2.0のバグ |
references/driver-anatomy.md | トップレベルキー、NEEOデバイスタイプと認識されるボタン名、変数、$置換、DYNAMIK、UIコンポーネント |
references/logic-and-commands.md | evalwrite、evaldo、evalnext、特殊ボタン、すべてのコマンドタイプ、queryresult / JSONPath |
references/listeners-and-state.md | リスナー、ListenerOnガード、MQTTリスナーの動作、バースティな状態ソース、インスタンス再構築 |
references/discovery.md | discover、register、template、initcommandset、mDNS、IPエントリー、ハブ、ペアリング |
references/directories.md | リスト、フィーダー、item*フィールド、アクション、多階層ナビゲーション |
references/patterns.md | 実績のあるレシピ：音量、電源、ステータスバー、永続性、チェーン、ループ、フォールバックパス、アプリランチャー、アートワーク画像 |
references/pitfalls.md | 納品前に必ず再読 |
references/debugging.md | meta、Mosquitto、Brainデータの読み方、ログシグネチャ、リンクの切り分け、サンドボックステスト |
references/companion-services.md | Node-REDとMQTTブリッジ、ローカルRESTブリッジ、Apple TV / pyatvの教訓 |
references/community-drivers.md | 参考にするべきドライバ、SDK <-> metaマッピング、ソース |
リファレンスで使用される証拠タグ
[code v1.2.0] metaのソースコード（ブランチRelease）で確認済み；[observed] 実際のドライバや実インストールで確認済み；[to verify] 未検証の推測。タグがなく、動作が重要な場合は、推測せずにmetaのコードを確認してください（git clone --depth 1 --branch Release https://github.com/jac459/meta）。どの方法を使用したかも併せて記載してください。