aranea-sdk-cli

AraneaSDK CLI - ESP32 IoTデバイス開発支援ツール

🤖 AIエージェント向けガイド

AIエージェント (Claude, Codex, etc.) がAraneaSDK関連タスクを実行する際は、このCLIを使用してください。

ナレッジ追加 (ローカルファイルではなくCLI経由で)

# ❌ ローカルファイル作成ではなく
# ✅ CLIでナレッジベースに追加
aranea-sdk knowledge add \
  --title "ESP32 HTTPSタイムアウト設定" \
  --category tip \
  --content "ESP32でHTTPS接続する場合、最低15秒のタイムアウトが必要。初回SSL handshakeは特に時間がかかる。" \
  --keywords "esp32,https,timeout,ssl"

Metatronへの質問 (AIアシスタント連携)

# AraneaSDK専門AIに質問
aranea-sdk metatron ask "ESP32のHTTPSタイムアウトのベストプラクティスは？"

# 対話モード
aranea-sdk metatron chat

典型的なワークフロー

1. 問題解決時: metatron ask "問題の説明" で既存ナレッジを確認
2. 新知見発見時: knowledge add でナレッジベースに追加
3. デバイス登録時: register --dry-run で検証後、実登録

🔴 特に貴重なナレッジ（必ず追加すべき）

以下の情報は一般ドキュメントでは得られない実践的知見です。 発見次第、CLIでナレッジベースに追加してください：

| カテゴリ | 追加すべき情報 | 例 | |---------|--------------|-----| | incident | ハードウェア固有の問題・解決策 | メモリ不足でクラッシュ、タイムアウトエラー | | tip | テスト・デバッグで追い込んだパラメータ | HTTPSタイムアウト15秒必要 | | tip | ESP32メモリ関連設定 | SSL接続に50KB必要 | | tip | SBC (OrangePi等) のサービス起動・権限問題 | systemd設定、sudoers設定 | | incident | ハードウェア相性問題 | 特定WiFiモジュールとの非互換 |

# 例: インシデント対応で発見した設定値を追加
aranea-sdk knowledge add \
  --title "ESP32 HTTPSタイムアウト 15秒必要" \
  --category tip \
  --content "ESP32でHTTPS接続する場合、最低15秒のタイムアウトが必要。初回SSL handshakeは特に時間がかかる。-11 READ_TIMEOUTエラーの原因。" \
  --keywords "esp32,https,timeout,ssl,handshake" \
  --device-types "aranea_ar-is04a,aranea_ar-is05a"

概要

AraneaSDK CLIは、AraneaSDK対応ESP32デバイスの開発・テスト・登録を支援するコマンドラインツールです。

インストール

npm install -g aranea-sdk-cli

クイックスタート

# 接続テスト
aranea-sdk test connection --endpoint production

# 認証テスト (テストテナント)
aranea-sdk test auth

# デバイス登録 (ドライラン)
aranea-sdk register --type aranea_ar-is04a --mac AABBCCDDEEFF --dry-run

# スキーマ取得
aranea-sdk schema get --type aranea_ar-is04a

# AIアシスタントに質問
aranea-sdk metatron ask "State Reportの送信方法は？"

コマンド一覧

| コマンド | 説明 | 認証 | |---------|------|------| | test | 接続・認証テスト | 不要 | | register | デバイス登録 | 不要（テストテナント） | | schema | スキーマ取得・検証・プッシュ | push/promote時必要 | | validate | Type名検証 | 不要 | | simulate | 状態レポートシミュレーション | 不要 | | mqtt | コマンド送信・ACKモニタリング | 必要 | | knowledge | ナレッジベース管理 | 必要 | | metatron | AI対話アシスタント | 必要 | | auth | 認証トークン管理 | - |

認証設定

認証が必要なコマンド

mqtt, knowledge, metatron コマンドは Firebase Auth IDトークンが必要です。

認証方法 (3つの選択肢)

1. 環境変数で設定 (推奨)

# Firebase IDトークンを環境変数に設定
export ARANEA_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIsInR5..."
# または
export FIREBASE_AUTH_TOKEN="eyJhbGciOiJSUzI1NiIsInR5..."

# コマンド実行
aranea-sdk metatron ask "State Reportの送信方法は？"

2. --token オプションで指定

aranea-sdk metatron ask "質問内容" --token "eyJhbGciOiJSUzI1NiIsInR5..."

3. サービスアカウント (mqtt コマンドのみ)

# サービスアカウントキーを環境変数に設定
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json"
# オプション: カスタムAPIキー (未設定時はデフォルト値を使用)
export FIREBASE_API_KEY="AIzaSy..."

aranea-sdk mqtt send-command -l 3004AABBCCDDEEFF0001 -t relay -p '{"channel":1,"state":true}'

Firebase IDトークンの取得方法

// Firebase Auth からIDトークンを取得
const token = await firebase.auth().currentUser.getIdToken();
console.log(token);

test - 接続・認証テスト

# API接続テスト
aranea-sdk test connection [--endpoint production|staging]

# 認証テスト (テストテナント使用)
aranea-sdk test auth

# カスタム認証情報でテスト
aranea-sdk test auth --tid T123... --lacis-id 173... --cic 022029

register - デバイス登録

# ドライラン (登録せずに検証)
aranea-sdk register --type aranea_ar-is04a --mac AABBCCDDEEFF --dry-run

# 実登録 (テストテナント)
aranea-sdk register --type aranea_ar-is04a --mac AABBCCDDEEFF

# カスタムテナントに登録
aranea-sdk register \
  --type aranea_ar-is04a \
  --mac AABBCCDDEEFF \
  --tid T999... \
  --lacis-id 173... \
  --cic 022029

オプション

| オプション | 説明 | デフォルト | |-----------|------|-----------| | -t, --type | デバイスType (必須) | - | | -m, --mac | MACアドレス 12桁HEX (必須) | - | | --tid | テナントID | テストテナント | | --lacis-id | 登録者LacisID | テストテナント | | --cic | 登録者CIC | テストテナント | | -d, --dry-run | 検証のみ | false | | -e, --endpoint | 環境 | production |

schema - スキーマ操作

# スキーマ一覧表示
aranea-sdk schema list

# スキーマ詳細取得
aranea-sdk schema get --type aranea_ar-is04a
aranea-sdk schema get --type aranea_ar-is04a --json  # JSON出力

# State Report JSONの検証
aranea-sdk schema validate --file state.json --type aranea_ar-is04a

Note: schema validate は State Report ペイロードの検証用です。 スキーマ定義ファイル自体の静的検証は schema validate-schema で実行できます。

実装済み vs 計画中

| サブコマンド | 状態 | 説明 | |-------------|------|------| | list | ✅ 実装済み | 登録済みスキーマ一覧 | | get | ✅ 実装済み | スキーマ詳細取得 | | validate | ✅ 実装済み | State Report 検証 | | validate-schema | ✅ 実装済み | スキーマ定義の静的検証 | | push | ✅ 実装済み | 開発環境へプッシュ (認証必要) | | promote | ✅ 実装済み | 本番環境へ昇格 (認証必要、確認ステップあり) | | info | ✅ 実装済み | スキーマ詳細情報・リビジョン履歴 | | rollback | 🔜 計画中 | バージョンロールバック |

環境切替 (v0.3.1)

すべてのschemaサブコマンドで --endpoint オプションが使用可能です:

# デフォルト: staging (安全側)
aranea-sdk schema list

# 明示的にproduction指定
aranea-sdk schema list --endpoint production

# 環境変数でも指定可能
ARANEA_ENV=production aranea-sdk schema list

⚠️ 注意: staging環境のCloud Functionsは現在未デプロイです。 --endpoint staging を指定するとエラーになります。 本番操作時は --endpoint production を明示的に指定してください。

validate - Type名検証

# Type名検証
aranea-sdk validate type --type aranea_ar-is04a

# レガシーType名検証 (ISMS_ar-*)
aranea-sdk validate type --type ISMS_ar-is04a

simulate - 状態レポートシミュレーション

# ファイルからシミュレーション
aranea-sdk simulate state-report --file test.json --dry-run

# JSONペイロード直接指定
aranea-sdk simulate state-report --payload '{"temp": 25.5}'

mqtt - コマンド送信 (認証必要)

デバイスへのコマンド送信とACK監視を行います。

send-command - コマンド送信

# リレーON (dry-run)
aranea-sdk mqtt send-command \
  --lacis-id 3004AABBCCDDEEFF0001 \
  --type relay \
  --params '{"channel":1,"state":true}' \
  --dry-run

# 実際に送信 (ACK待機あり)
aranea-sdk mqtt send-command \
  --lacis-id 3004AABBCCDDEEFF0001 \
  --type relay \
  --params '{"channel":1,"state":true}' \
  --token "$ARANEA_AUTH_TOKEN" \
  --wait

オプション

| オプション | 説明 | デフォルト | |-----------|------|-----------| | -l, --lacis-id | デバイスLacisID (必須) | - | | -t, --type | コマンドタイプ (必須) | - | | -p, --params | パラメータ JSON | {} | | --ttl | TTL秒数 | 30 | | --group-id | グループID | - | | --token | 認証トークン | 環境変数から | | -w, --wait | ACK待機 | false | | --wait-timeout | ACK待機タイムアウト | 30 | | -d, --dry-run | リクエスト内容表示のみ | false |

monitor - ACKモニタリング

# 特定コマンドのACK監視
aranea-sdk mqtt monitor --cmd-id "abc123..." --timeout 60

# デバイス単位で監視 (Firestoreリアルタイム)
aranea-sdk mqtt monitor --lacis-id 3004AABBCCDDEEFF0001 --timeout 120

前提: Firestoreリアルタイム監視には GOOGLE_APPLICATION_CREDENTIALS が必要です。

periodic - 定期送信 (負荷テスト用)

# 5秒間隔で10回送信
aranea-sdk mqtt periodic \
  --lacis-id 3004AABBCCDDEEFF0001 \
  --type ping \
  --interval 5 \
  --count 10 \
  --token "$ARANEA_AUTH_TOKEN"

knowledge - ナレッジベース管理 (認証必要)

AraneaMetatronのナレッジベースを管理します。

使用例

# ナレッジ一覧
aranea-sdk knowledge list --token "$ARANEA_AUTH_TOKEN"

# カテゴリ別一覧
aranea-sdk knowledge list --category api

# 検索
aranea-sdk knowledge search --query "state report"

# 詳細取得
aranea-sdk knowledge get --id "entry_id_here"

# ナレッジ追加
aranea-sdk knowledge add \
  --title "State Report送信方法" \
  --category guide \
  --file ./content.md \
  --keywords "state,report,api"

# カテゴリ一覧表示
aranea-sdk knowledge categories

カテゴリ

| カテゴリ | 説明 | |---------|------| | api | API仕様・エンドポイント | | guide | 実装ガイド・チュートリアル | | code | コードサンプル・スニペット | | reference | リファレンス・仕様書 | | incident | インシデント・トラブルシューティング | | tip | Tips・ノウハウ |

metatron - AI対話 (認証必要)

AraneaSDK専門のAIアシスタントに質問できます。

使用例

# 単発質問
aranea-sdk metatron ask "State Reportの送信方法は？" --token "$ARANEA_AUTH_TOKEN"

# JSON出力
aranea-sdk metatron ask "ESP32のサンプルコードは？" --raw

# 対話モード (REPL)
aranea-sdk metatron chat --token "$ARANEA_AUTH_TOKEN"

# 対話可能なトピック一覧
aranea-sdk metatron topics

# 質問例を表示
aranea-sdk metatron examples

対話可能なトピック

• State Report API
• デバイス登録
• スキーマ設計
• MQTT/コマンド
• ESP32実装
• デバイスタイプ
• CelestialGlobe
• トラブルシューティング

auth - 認証管理 (v0.3.1)

Firebase Auth IDトークンを管理します。トークンは ~/.aranea-sdk/credentials.json に保存されます。

使用例

# ログイン (対話式)
aranea-sdk auth login

# メールアドレス指定でログイン
aranea-sdk auth login --email [email protected]

# トークン情報表示
aranea-sdk auth token

# トークンのみ出力 (スクリプト用)
aranea-sdk auth token --raw

# トークン更新 (1時間で期限切れ)
aranea-sdk auth refresh

# ログアウト
aranea-sdk auth logout

トークンライフサイクル

• IDトークンは 1時間 で期限切れ
• auth refresh で新しいトークンを取得
• auth token --raw でスクリプトからトークン取得可能

# 他コマンドでトークンを使用
aranea-sdk metatron ask "質問" --token "$(aranea-sdk auth token --raw)"

対応デバイスType

新規 (aranea_ar-*)

| Type | ProductType | 説明 | |------|-------------|------| | aranea_ar-is01 | 001 | AraneaSDK Basic Sensor | | aranea_ar-is02 | 002 | AraneaSDK Standard Sensor | | aranea_ar-is04a | 004 | Network Scanner (ESP32) | | aranea_ar-is05a | 005 | Environment Sensor (ESP32) | | aranea_ar-is06a | 006 | Power Monitor (ESP32) | | aranea_ar-is10 | 010 | Router Inspector (OpenWrt/AsusWRT) |

レガシー (ISMS_ar-*)

| Type | ProductType | 説明 | |------|-------------|------| | ISMS_ar-is01 | 001 | Basic Sensor (レガシー) | | ISMS_ar-is02 | 002 | Standard Sensor (レガシー) | | ISMS_ar-is03 | 003 | Advanced Sensor (レガシー) | | ISMS_ar-is04 | 004 | Multi-channel Sensor (レガシー) | | ISMS_ar-is05 | 005 | Environment Sensor (レガシー) |

Note: ISMS_ar-* プレフィックスは永続的にサポートされます。 登録時に aranea_ar-* へ自動変換されます。

LacisID生成規則

AraneaDeviceのLacisIDは以下の形式で自動生成されます:

[Prefix][ProductType][MAC][ProductCode] = 20文字

Prefix:      3 (araneaDevice固定)
ProductType: 3桁 (例: 004)
MAC:         12桁HEX (例: AABBCCDDEEFF)
ProductCode: 4桁4進数 (枝番から算出)

例: aranea_ar-is04a + MAC AABBCCDDEEFF → LacisID: 3004AABBCCDDEEFF1201

環境設定

| 環境 | Gate API | State API | |-----|----------|-----------| | production | asia-northeast1-mobesorder.cloudfunctions.net | 同左 | | staging | asia-northeast1-mobesorder-staging.cloudfunctions.net | 同左 |

テストテナント

開発・テスト用に以下のテストテナントが利用可能です:

• TID: T9999999999999999999
• Email: [email protected]

テストテナントを使用する場合、--tid, --lacis-id, --cic オプションは省略可能です。

ヘルプ表示

# 全体ヘルプ
aranea-sdk --help

# コマンド別ヘルプ
aranea-sdk schema --help
aranea-sdk mqtt --help
aranea-sdk metatron --help
aranea-sdk knowledge --help

要件

• Node.js >= 18.0.0

ライセンス

MIT License - see LICENSE

関連リンク

• AraneaSDK Documentation
• AraneaMetatron Architecture
• Issues