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 显示模式使用本地图像协议。对于这些路径，请勿索取 Dot 云凭据，也不要使用发送脚本。以下要求适用于受支持的 Dot 云 API 设备。

本地 MCP

兼容的 Agent 可以使用本地 dot-mcp stdio 服务，而无需构造 HTTP 请求。它仅公开以下固定 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。

对于这三种内容 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。切勿将 taskAlias 放入 Canvas data 中。

参考资料

• references/authentication.md
• references/api_reference.md
• OpenAPI 架构：../../openapi/dot-openapi.yaml