dot-device-openapi

Dot Device OpenAPI と MCP

ユーザーが Dot. デバイスを操作したい場合は、このスキルを使用します。

• デバイスの一覧表示、またはデバイス ID の検索
• デバイスのステータス確認
• デバイス設定の読み取りまたは更新
• 次のコンテンツへの切り替え
• Text API コンテンツの送信
• Image API コンテンツの送信
• 設計済みの Canvas API ペイロードの送信
• デバイス上のループタスクまたは固定タスクの一覧表示

カスタム Canvas カード、ダッシュボード、または windowData レイアウトの設計をユーザーが希望する場合は、まず dot-canvas-designer を使用します。その後、デバイスへの送信をユーザーが希望した場合に限り、ここに戻ります。

製品の振り分け

Read Pico または Rand/0 の連携を選ぶ場合や、ユーザーがハードウェアリソースについて質問した場合は、products.md を読んでください。Read Pico の開発では公式ファームウェアリポジトリを使用し、Rand/0 Display Mode ではローカル画像プロトコルを使用します。これらの経路では Dot クラウドの認証情報を要求したり、送信スクリプトを使用したりしないでください。以下の要件は、サポート対象の Dot クラウド API デバイスに適用されます。

ローカル MCP

互換性のあるエージェントは、HTTP リクエストを組み立てる代わりに、ローカルの dot-mcp stdio サーバーを使用できます。このサーバーは、以下の固定 Dot ツールのみを公開し、任意の HTTP アクセスは公開しません。

• 読み取り専用：dot_list_devices、dot_get_device_status、dot_get_device_settings、dot_list_timezones、dot_list_tasks、dot_validate_canvas
• デバイスを変更：dot_update_device_settings、dot_switch_next_content、dot_send_text、dot_send_image、dot_send_canvas

サーバーは MCP プロセス環境から DOT_API_KEY を読み取ります。ツール引数としてキーを受け取ることも、保存することも、ログに記録することもありません。デバイスを変更するリクエストは、自動再試行なしで一度だけ送信されます。

pipx install git+https://github.com/MindReset/dot_skill.git でローカルサーバーをインストールし、dot-mcp で実行するか、uvx --from git+https://github.com/MindReset/dot_skill.git dot-mcp を使用します。プラットフォームごとの設定例は docs/mcp-configs.md にあります。

要件

• ベース URL：https://dot.mindreset.tech
• 認証：Authorization: Bearer dot_app_<api_key>
• API キーの取得元：ユーザーに尋ねるか、ローカル環境から DOT_API_KEY を読み取ります。
• デバイス ID の取得元：ユーザーに尋ねるか、デバイス一覧を取得するか、ユーザーが提示した ID を使用します。
• レート制限：毎秒 10 リクエストです。

成功した POST 制御エンドポイント（next、text、image、canvas）は、トップレベルに message フィールドを持つ JSON オブジェクトを返します。従来の { code, message, result } ラッパーは想定しないでください。

ワークフロー

1. 有効な API キーとデバイス ID を確認します。
2. Text API、Image API、または Canvas API に書き込む場合は、対応するコンテンツが Dot. App Content Studio の選択したループまたは固定リストにすでに追加されていることを確認します。固定コンテンツには taskType: "fixed" を使用します。taskType を省略すると、ループリストが選択されます。同じリストを取得して taskKey を確認します。
3. エンドポイントを選択します。
   • テキスト表示：POST /api/authV2/open/device/:deviceId/text
   • 画像表示：POST /api/authV2/open/device/:deviceId/image
   • Canvas 表示：POST /api/authV2/open/device/:deviceId/canvas
   • デバイスのステータス：GET /api/authV2/open/device/:deviceId/status
   • デバイス設定：GET /api/authV2/open/device/:deviceId/settings
   • デバイス設定の更新：POST /api/authV2/open/device/:deviceId/settings
   • タイムゾーン一覧：GET /api/authV2/open/timezones
   • デバイス一覧：GET /api/authV2/open/devices
   • 次のコンテンツ：POST /api/authV2/open/device/:deviceId/next
   • タスク一覧：GET /api/authV2/open/device/:deviceId/:taskType/list
4. POST リクエストには必ず Content-Type: application/json を含めます。

スクリプト

ローカルで実行するには、scripts/ 内のスクリプトを使用します。

• list_devices.py
• get_device_status.py
• get_device_settings.py
• update_device_settings.py
• list_tasks.py
• switch_next.py
• send_text.py
• send_image.py
• send_canvas.py

テキスト、画像、Canvas のヘルパースクリプトは、デバイスのタスクリストに表示されるユーザー向けのタスク名を指定する --task-alias をサポートしています。

固定コンテンツを更新するには、--task-type fixed を使用します。Canvas の --payload では、--task-type を省略するとファイルの taskType が保持され、明示的に指定するとその値で上書きされます。どちらにも taskType が含まれない場合、API のデフォルトは loop です。

リクエストに関する注意事項

Text API のパラメーターには、taskType、refreshNow、taskKey、taskAlias、title、message、signature、icon、link、styles があります。

Image API のパラメーターには、taskType、refreshNow、taskKey、taskAlias、image、link、border、ditherType、ditherKernel があります。

Canvas API の送信パラメーターには、taskType、refreshNow、taskKey、taskAlias、data、windowData、layoutFull、link、border があります。dot-canvas-designer を使用して windowData を作成または編集します。対象リストは、data の外側にあるトップレベルの taskType で指定します。

3 つのコンテンツ API すべてにおいて、taskKey は taskType 内でのみ一致する API 項目を選択します。他のリストは検索されません。taskKey を指定しない場合、そのリスト内で最初に一致する API 項目が更新されます。固定コンテンツの更新では、設定済みの時刻が保持され、項目がすでに表示されている場合も含め、次回のスケジュールされた更新時に表示されます。固定コンテンツでは refreshNow は無視されます。固定コンテンツがすぐに表示されると約束したり、それを強制するために別途、次のコンテンツへの切り替えコマンドを実行したりしないでください。

デバイス設定のパラメーターには、alias、location、timezone、interval、sleep があります。タイムゾーンには、GET /api/authV2/open/timezones が返すキーのいずれかを指定する必要があります。インターバルは分単位の整数倍で指定し、43,200,000 ms（12 時間）を超えることはできません。最小値はモデルごとに異なります。Quote/0 と Quote/1 は、どちらの電源モードでも 60,000 ms です。Rand/0 は外部電源使用時に 900,000 ms、バッテリー使用時に 3,600,000 ms です。ZenMeasure M401 は外部電源使用時に 60,000 ms、バッテリー使用時に 1,800,000 ms です。これらの制限は自動切り替えに適用され、手動更新には適用されません。バッテリー使用時のインターバルは、自動ウェイクとコンテンツ更新のタイミングを制御します。sleep.start と sleep.end は、デバイスのタイムゾーンにおけるローカル時刻を HH:mm 形式で指定します。終了時刻が開始時刻より早い場合、終了時刻は翌日を意味します。

Text API、Image API、Canvas API では、ユーザーがタスクリストに人が読めるタスク名を表示したい場合、トップレベルの taskAlias を使用します。既存のタスク名を維持するには、taskAlias を省略します。名前を消去したいとユーザーが明示した場合に限り、taskAlias: "" または taskAlias: null を送信します。Canvas の data 内に taskAlias を入れないでください。

参考資料

• references/authentication.md
• references/api_reference.md
• OpenAPI スキーマ：../../openapi/dot-openapi.yaml