Back to Details

dot-device-openapi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Dot Device OpenAPI

Dot设备OpenAPI

Use this skill when the user wants to operate a Dot. device:
  • List devices or find a device ID
  • Check device status
  • Read or update device settings
  • Switch to the next content
  • Send Text API content
  • Send Image API content
  • Send an already-designed Canvas API payload
  • List loop or fixed tasks on a device
If the user asks to design a custom Canvas card, dashboard, or 
windowData
layout, use 
dot-canvas-designer
first, then return here only when the user wants to send it to a device.
当用户想要操作Dot.设备时使用此技能：
  • 列出设备或查找设备ID
  • 检查设备状态
  • 读取或更新设备设置
  • 切换到下一个内容
  • 发送Text API内容
  • 发送Image API内容
  • 发送已设计好的Canvas API负载
  • 列出设备上的循环任务或固定任务
如果用户要求设计自定义Canvas卡片、仪表盘或
windowData
布局，请先使用
dot-canvas-designer
，仅当用户想要将其发送到设备时再返回此技能。

Requirements

要求

  • Base URL: 
    https://dot.mindreset.tech
  • Authentication: 
    Authorization: Bearer dot_app_<api_key>
  • API key source: ask the user or read 
    DOT_API_KEY
    from the local environment.
  • Device ID source: ask the user, list devices, or use the ID the user provides.
  • Rate limit: 10 requests per second.
Successful POST control endpoints (
next
, 
text
, 
image
, 
canvas
) return a JSON object with a top-level 
message
field. Do not expect a legacy 
{ code, message, result }
wrapper.
  • 基础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 }
包装格式。

Workflow

工作流程

  1. Confirm a valid API key and device ID.
  2. For Text API, Image API, or Canvas API writes, ensure the matching content has already been added to the device loop task in Dot. App Content Studio.
  3. Pick the endpoint:
    • Text display: 
      POST /api/authV2/open/device/:deviceId/text
    • Image display: 
      POST /api/authV2/open/device/:deviceId/image
    • Canvas display: 
      POST /api/authV2/open/device/:deviceId/canvas
    • Device status: 
      GET /api/authV2/open/device/:deviceId/status
    • Device settings: 
      GET /api/authV2/open/device/:deviceId/settings
    • Update device settings: 
      POST /api/authV2/open/device/:deviceId/settings
    • Timezone list: 
      GET /api/authV2/open/timezones
    • Device list: 
      GET /api/authV2/open/devices
    • Next content: 
      POST /api/authV2/open/device/:deviceId/next
    • Task list: 
      GET /api/authV2/open/device/:deviceId/:taskType/list
  4. Always include 
    Content-Type: application/json
    for POST requests.
  1. 确认有效的API密钥和设备ID。
  2. 对于Text API、Image API或Canvas API写入操作，确保匹配的内容已添加到Dot.应用内容工作室中的设备循环任务中。
  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

脚本

Use the scripts in 
scripts/
for local execution:
  • 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
Text, image, and Canvas helper scripts support 
--task-alias
for the user-readable task name shown in the device task list.
使用
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
参数指定设备任务列表中显示的用户可读任务名称。

Request Notes

请求说明

For Text API, parameters include 
refreshNow
, 
taskKey
, 
taskAlias
, 
title
, 
message
, 
signature
, 
icon
, 
link
, and 
styles
.
For Image API, parameters include 
refreshNow
, 
taskKey
, 
taskAlias
, 
image
, 
link
, 
border
, 
ditherType
, and 
ditherKernel
.
For Canvas API sending, parameters include 
refreshNow
, 
taskKey
, 
taskAlias
, 
data
, 
windowData
, 
layoutFull
, 
link
, and 
border
. Build or revise 
windowData
with 
dot-canvas-designer
.
For device settings, parameters include 
alias
, 
location
, 
timezone
, 
interval
, and 
sleep
. Timezones must be one of the keys returned by 
GET /api/authV2/open/timezones
. Both 
interval.powerMs
and 
interval.batteryMs
must be 60,000-43,200,000 ms in whole-minute multiples. The battery interval controls automatic wake and content refresh timing. 
sleep.start
and 
sleep.end
use local 
HH:mm
time in the device timezone, and an end time earlier than start means the next day.
For Text API, Image API, and Canvas API, use top-level 
taskAlias
when the user wants a human-readable task-list name. Omit 
taskAlias
to keep the existing task name. Send 
taskAlias: ""
or 
taskAlias: null
only when the user explicitly wants to clear the name. Never put 
taskAlias
inside Canvas 
data
.
对于Text API，参数包括
refreshNow
、
taskKey
、
taskAlias
、
title
、
message
、
signature
、
icon
、
link
和
styles
。
对于Image API，参数包括
refreshNow
、
taskKey
、
taskAlias
、
image
、
link
、
border
、
ditherType
和
ditherKernel
。
对于Canvas API发送操作，参数包括
refreshNow
、
taskKey
、
taskAlias
、
data
、
windowData
、
layoutFull
、
link
和
border
。请使用
dot-canvas-designer
构建或修改
windowData
。
对于设备设置，参数包括
alias
、
location
、
timezone
、
interval
和
sleep
。时区必须是
GET /api/authV2/open/timezones
返回的键值之一。
interval.powerMs
和
interval.batteryMs
必须为60,000-43,200,000毫秒之间的整分钟倍数。电池间隔控制自动唤醒和内容刷新的时间。
sleep.start
和
sleep.end
使用设备时区的本地
HH:mm
时间，若结束时间早于开始时间则表示次日。
对于Text API、Image API和Canvas API，当用户需要人类可读的任务列表名称时，请使用顶级
taskAlias
参数。省略
taskAlias
将保留现有任务名称。仅当用户明确要求清除名称时，才发送
taskAlias: ""
或
taskAlias: null
。切勿将
taskAlias
放在Canvas的
data
内部。

References

参考资料

  • references/authentication.md
  • references/api_reference.md
  • OpenAPI schema: 
    ../../openapi/dot-openapi.yaml
  • references/authentication.md
  • references/api_reference.md
  • OpenAPI schema: 
    ../../openapi/dot-openapi.yaml
    ",