设备数据点

概述

设备数据点定义设备如何读取或写入物理信号。每个数据点映射到 Modbus 寄存器，存储可选的工程转换参数，并在底层硬件支持时可以进行控制（开/关/正转/反转）。

基础路径: /api/v2/projects/{project_id}/devices/{device_id}/points/
缓存: 数据点列表/详情端点缓存响应 5 分钟，并在添加、更新或删除数据点时自动刷新。

端点摘要

方法	路径	用途	备注
GET	`/projects/{project_id}/devices/{device_id}/points/`	列出设备的数据点	已缓存；按 `slave_id`、`address`、`data_index` 排序
GET	`/projects/{project_id}/devices/{device_id}/points/{id}/`	获取单个数据点	包括派生元数据（`the_type_detail` 等）
POST	`/projects/{project_id}/devices/{device_id}/points/`	创建数据点	验证 `(slave_id, address, data_index)` 的唯一性
PATCH	`/projects/{project_id}/devices/{device_id}/points/{id}/`	更新数据点	允许部分更新
DELETE	`/projects/{project_id}/devices/{device_id}/points/{id}/`	删除数据点	删除后自动刷新缓存
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/on/`	打开	向设备下发开指令，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/off/`	关闭	向设备下发关指令，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/forward/`	正转	向设备下发正转指令，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/antiport/`	反转	向设备下发反转指令，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/stop/`	停止	向设备下发停止指令，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/set-content/`	设置显示内容	适用于 LED、数码管等显示设备，返回命令令牌
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/set-alarm-level/`	设置告警等级	等级范围 0~5，返回命令令牌
GET	`/projects/{project_id}/devices/{device_id}/points/{id}/current-data/`	实时快照	从低延迟缓存读取最新数据
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/set-threshold/`	配置阈值	设置 `min_value`/`max_value`，超限时触发告警
GET	`/projects/{project_id}/devices/{device_id}/points/threshold-points/`	已配置阈值的数据点	仅返回设置了任一阈值的数据点
GET	`/projects/{project_id}/devices/{device_id}/points/options/`	获取配置选项	返回可用的 Modbus 类型、数据类型和数据点类型
POST	`/projects/{project_id}/devices/{device_id}/points/{id}/duplicate/`	复制数据点	创建具有自动递增 `data_index` 的同级数据点
GET	`/api/v2/data/{point_agri_id}/`	历史数据	通过数据点 `agri_id` 直接查询历史数据

数据点模型

每个数据点包含以下主要字段：

字段	类型	说明
`id`	integer	数据点主键
`agri_id`	string	完整标识符，格式 `{device_agri_id}-{slave_id}-{address}{data_index}`
`device_id`	integer	所属设备 ID
`name`	string	数据点名称
`slave_id`	integer	Modbus 从站 ID
`address`	integer	寄存器地址
`data_index`	integer	多寄存器读取时的偏移量（0~9）
`the_type`	integer	数据点类型 ID
`the_type_detail`	object	数据点类型详细信息（名称、单位、图标）
`modbus_type`	string	`holding`、`input`、`coil`、`discrete` 之一
`data_type`	string	`int16`、`uint16`、`int32`、`float` 等
`data_endian`	string	字节序（`ABCD`、`DCBA`、`BADC`、`CDAB`）
`data_scale`	float	缩放系数，最终值 = 原始值 × data_scale + data_delta
`data_delta`	float	偏移量，最终值 = 原始值 × data_scale + data_delta
`min_value`	float	告警最小值（可选）
`max_value`	float	告警最大值（可选）
`enabled`	boolean	是否启用
`info`	string	备注（可选）

列出数据点

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

响应示例：

json

[
  {
    "id": 12,
    "agri_id": "d-1000-abcd-1-00",
    "device_id": 5,
    "name": "入口温度",
    "slave_id": 1,
    "address": 0,
    "data_index": 0,
    "the_type": 1,
    "the_type_detail": {
      "the_type": 1,
      "name": "温度",
      "unit": "℃",
      "icon_url": "https://cloud.yengear.com/media/icon/temp.png",
      "is_shared": true
    },
    "modbus_type": "holding",
    "data_type": "int16",
    "data_endian": "ABCD",
    "data_scale": 0.1,
    "data_delta": 0.0,
    "min_value": null,
    "max_value": null,
    "enabled": true,
    "info": null
  }
]

获取数据点

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

返回与列表条目相同的结构，包括 min_value/max_value（如已配置）。

创建数据点

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>
Content-Type: application/json

{
  "name": "入口温度",
  "slave_id": 1,
  "address": 0,
  "data_index": 0,
  "the_type": 1,
  "modbus_type": "holding",
  "data_type": "int16",
  "data_endian": "ABCD",
  "data_scale": 0.1,
  "info": "入口温度传感器"
}

请求字段

字段	类型	必填	说明
`slave_id`	integer	是	Modbus 从站 ID
`address`	integer	是	寄存器地址
`data_index`	integer	是	多寄存器读取的偏移量
`the_type`	integer	是	数据点类型 ID
`modbus_type`	string	是	`holding`、`input`、`coil`、`discrete`
`data_type`	string	是	`int16`、`uint16`、`int32`、`float` 等
`data_endian`	string	是	字节序（`ABCD`、`DCBA`、`BADC`、`CDAB`）
`name`	string	否	数据点名称
`data_scale`	float	否	缩放系数，默认为 `1`
`data_delta`	float	否	偏移量，默认为 `0`
`enabled`	boolean	否	默认为 `true`
`info`	string	否	备注

返回创建的数据点记录。重复的 (slave_id, address, data_index) 组合将被拒绝，返回 400。

注意：设备的 BaseDevice.property & 0x20 必须为真，否则返回 DEVICE_NOT_EDITABLE 错误。

更新数据点

http

PATCH /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>
Content-Type: application/json

{
  "data_scale": 0.01,
  "info": "已更新缩放比例"
}

支持部分更新，仅传入需要修改的字段即可。

删除数据点

http

DELETE /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

成功返回 204 No Content。

复制数据点

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/duplicate/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

复制数据点，自动在名称后附加 _N，并对相同 (slave_id, address) 的 data_index 自动递增。返回 201 及新数据点数据。

控制操作

开关或执行器类数据点支持以下控制指令，需要 operator 或更高权限：

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/on/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

操作	端点	说明
打开	`POST /on/`	向设备下发开指令
关闭	`POST /off/`	向设备下发关指令
正转	`POST /forward/`	电机正向旋转
反转	`POST /antiport/`	电机反向旋转
停止	`POST /stop/`	停止当前操作

所有控制操作的响应结构相同：

json

{
  "success": true,
  "message": "操作成功",
  "token": "cmd_xxxxxxxxxxxxxxxx"
}

token 可用于关联命令执行状态。

设置显示内容

适用于 LED、数码管等显示设备：

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-content/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>
Content-Type: application/json

{
  "content": "Hello"
}

字段	类型	必填	说明
`content`	string	是	要显示的文本内容

设置告警等级

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-alarm-level/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>
Content-Type: application/json

{
  "level": 2
}

字段	类型	必填	说明
`level`	integer	是	告警等级，范围 0~5

实时快照

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/current-data/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

从低延迟缓存（Cloudflare D1）读取数据点最新数据。若暂无数据则返回空对象，不会返回 404。

响应示例：

json

{
  "agri_id": "d-1000-abcd-1-00",
  "value": 24.5,
  "the_type": 1,
  "unit": "℃",
  "updated_at": 1704758400
}

获取配置选项

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/options/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

返回创建数据点时可用的配置选项：

json

{
  "modbus_type_choices": [
    {"value": "holding", "label": "保持寄存器"},
    {"value": "input", "label": "输入寄存器"},
    {"value": "coil", "label": "线圈"},
    {"value": "discrete", "label": "离散输入"}
  ],
  "data_type_choices": [
    {"value": "int16", "label": "16 位整数"},
    {"value": "uint16", "label": "16 位无符号整数"},
    {"value": "int32", "label": "32 位整数"},
    {"value": "float", "label": "浮点数"}
  ],
  "data_endian_choices": [
    {"value": "ABCD", "label": "大端序"},
    {"value": "DCBA", "label": "小端序"},
    {"value": "BADC", "label": "中端序"},
    {"value": "CDAB", "label": "中端序"}
  ],
  "point_types": [
    {"the_type": 1, "name": "温度", "unit": "℃", "is_shared": true},
    {"the_type": 2, "name": "湿度", "unit": "%RH", "is_shared": true},
    {"the_type": 200, "name": "开关", "unit": "", "is_shared": true}
  ]
}

阈值管理

设置阈值

http

POST /api/v2/projects/{project_id}/devices/{device_id}/points/{id}/set-threshold/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>
Content-Type: application/json

{
  "min_value": 5.0,
  "max_value": 35.0
}

字段	类型	必填	说明
`min_value`	float	否	下限值，超出时触发告警
`max_value`	float	否	上限值，超出时触发告警

min_value 和 max_value 均为可选，但若两者同时提供，min_value 必须小于 max_value。

查询已配置阈值的数据点

http

GET /api/v2/projects/{project_id}/devices/{device_id}/points/threshold-points/
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

仅返回设置了任一阈值的数据点列表。

按 agri_id 查询历史数据

http

GET /api/v2/data/{point_agri_id}/?page=1&page_size=50&min_timestamp=1704758400
Authorization: Bearer <token>
X-Organization-Slug: <org-slug>

查询参数

参数	类型	默认值	说明
`page`	integer	1	页码
`page_size`	integer	50	每页数量
`min_timestamp`	integer	-	最小时间戳（Unix 秒），过滤起始时间

响应示例：

json

{
  "count": 100,
  "next": "?page=2&page_size=50",
  "previous": null,
  "results": [
    { "agri_id": "d-1000-abcd-1-00", "v": 24.2, "t": 1704758400 }
  ]
}

错误代码

状态码	错误代码	说明
400	`DUPLICATE_POINT`	`(slave_id, address, data_index)` 组合已存在
400	`DEVICE_NOT_EDITABLE`	设备不支持自定义数据点配置
400	`INVALID_THRESHOLD`	`min_value`/`max_value` 参数无效
401	`UNAUTHORIZED`	Token 缺失或无效
403	`FORBIDDEN`	权限不足
404	`POINT_NOT_FOUND`	数据点不存在或不属于当前组织
500	`COMMAND_FAILED`	下发控制指令失败

使用说明

硬件支持: 设备的 BaseDevice.property & 0x20 为真时才支持自定义数据点。不支持编辑的设备，创建/更新/删除操作均返回 DEVICE_NOT_EDITABLE。
命令令牌: 控制操作返回的 token 可用于关联设备的执行状态反馈。
实时数据 vs 历史数据: current-data 从低延迟缓存读取，历史 API 从持久存储分页读取，两者之间可能存在细微差异。
agri_id 格式: agri_id = {device_agri_id}-{slave_id}-{address}{data_index}，其中 address 和 data_index 不带前导零。
缓存刷新: 创建、更新、删除数据点后缓存自动刷新；控制操作不影响缓存。

设备数据点 ​

概述 ​

端点摘要 ​

数据点模型 ​

列出数据点 ​

获取数据点 ​

创建数据点 ​

更新数据点 ​

删除数据点 ​

复制数据点 ​

控制操作 ​

设置显示内容 ​

设置告警等级 ​

实时快照 ​

获取配置选项 ​

阈值管理 ​

设置阈值 ​

查询已配置阈值的数据点 ​

按 agri_id 查询历史数据 ​

错误代码 ​

使用说明 ​

设备数据点

概述

端点摘要

数据点模型

列出数据点

获取数据点

创建数据点

更新数据点

删除数据点

复制数据点

控制操作

设置显示内容

设置告警等级

实时快照

获取配置选项

阈值管理

设置阈值

查询已配置阈值的数据点

按 agri_id 查询历史数据

错误代码

使用说明