控制设备

这是全文档唯一会驱动现场物理设备的接口

调用本接口会真实打开/关闭温室里的天窗、遮阳幕、风机、湿帘、灌溉阀门。误操作可能造成作物受损、机械损坏、人员受伤。

生产接入前请务必：

先在测试设备上验证全部位串与地址
在业务系统里加二次确认（人工确认后再下发）
加操作审计日志（谁、什么时候、动了哪台设备的哪个地址、值是多少）
评估失败重试策略（不要盲目重发）

接口说明

向指定设备的指定 address（控制地址） 下发一个 value（控制值），驱动对应的执行机构动作。

平台将指令下发到设备，返回成功仅代表指令已被受理，不代表设备已完成动作。要确认执行结果，请用读取地址值回读。

请求地址

text

POST https://mqtt.iot.auto-control.com.cn/api/set-value

请求方法

POST

必须用 POST

即使后端实现里也存在 GET /api/set-value（语义是「获取设定值」）， 下发控制一律使用 POST /api/set-value。不要用 GET 触发控制动作。

请求头

请求头	值	必填
`Content-Type`	`application/json`	是
`Authorization`	`Bearer <token>`	是

请求参数

请求体为 JSON：

参数名	类型	必填	说明	示例
`address`	Int \| String	是	控制地址，取值见 address 控制地址全量表	`3417`
`value`	String	是	控制值位串，含义随地址而变（见下）	`"10010"`
`deviceCode`	String	是	目标设备编码	`2022070314150044`

请求体示例

json

{
  "address": 3417,
  "value": "10010",
  "deviceCode": "2022070314150044"
}

接口文档对这三行的注释分别是：address = 「右向天窗，地址参考下表格」、 value = 「10010 开 10001 关」、deviceCode = 「设备 code，输入实际设备 code」。

address 的类型

示例里 address 是数字（3417），而读取地址值接口里 address 是 字符串。为兼容起见，建议在客户端统一按字符串处理，由服务端容忍两种形态。

控制值（`value`）语义

value 是位串，不同类设备的取值含义不同。以下表格照录接口文档。

通用控制值速查

控制值	含义	适用设备
`1010`	手动开	环流风扇、紫外消毒、微雾加湿、co2 补气、加湿除湿、热风机、加热热风机、微雾降温
`1001`	手动关	同上
`1100`	自动	同上
`10010`	手动开	天窗类、遮阳幕类、指定位置类设备
`10001`	手动关	同上
`11000`	自动	同上
`10100`	指定位置模式	同上
`11111111`	轮灌方式	灌溉计划类
`00000100` 等	停止电机转动	电机类（见 address 表）

天窗 / 遮阳幕类（含「指定位置」）

text

10010  手动开
10001  手动关
11000  自动
10100  指定位置   ← 必须先发这一条，再发 0-100 的开度值

指定位置类设备是「两步操作」

接口文档对这类地址的说明是：0-100（<地址> 需要先设置为 10100）。

即：

第一步：向该地址下发 10100，把设备切到「指定位置」模式
第二步：向该地址下发开度值（0~100）

直接下发开度值不会生效。每个「指定位置」地址对应的模式地址见 address 控制地址全量表。

风机湿帘（组合控制）

接口文档对「风机湿帘」地址给出的取值：

控制值	含义
`11110`	全开
`11100`	1、2、3 级风扇开，湿帘关
`11000`	1、2 级风扇开，3 级风扇关，湿帘关
`10000`	1 级风扇开，2、3 级风扇关，湿帘关
`00000`	全关

位串方向

以 11110 为例，五位分别对应「一级风机 / 二级风机 / 三级风机 / 湿帘 / …」。文档未明确写出每一位的对应关系，请结合读取控制参数的 deviceTypeNumber（16=一级风机、17=二级风机、18=三级风机、19=湿帘）现场核对。

灌溉计划

控制值	含义
`1010`	手动开
`1001`	手动关
`1100`	自动
`11111111`	采用轮灌方式

补光灯

控制值	含义
`1010`	手动开
`1001`	手动关
`1100`	自动

补光灯有前置指令

文档说明：「1010 手动开，控制补光灯前，先执行该指令」。

请求示例

curl

bash

# 注意：这会真实驱动设备
curl -X POST 'https://mqtt.iot.auto-control.com.cn/api/set-value' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer <token>" \
  -d '{"address": 3417, "value": "10010", "deviceCode": "2022070314150044"}'

HTTP 报文

http

POST /api/set-value HTTP/1.1
Host: mqtt.iot.auto-control.com.cn
Content-Type: application/json
Authorization: Bearer <token>

{
  "address": 3417,
  "value": "10010",
  "deviceCode": "2022070314150044"
}

Python（含回读校验）

python

import time
import requests

RT_HOST = "https://mqtt.iot.auto-control.com.cn"


def set_value(token: str, device_code: str, address, value: str, timeout: int = 30) -> dict:
    """下发控制指令。返回原始返回体。"""
    resp = requests.post(
        f"{RT_HOST}/api/set-value",
        json={"address": address, "value": value, "deviceCode": device_code},
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {token}",
        },
        timeout=timeout,
    )
    body = resp.json()
    if body.get("code") != 200:
        raise RuntimeError(
            f"下发失败: code={body.get('code')} message={body.get('message')}"
            f" requestId={body.get('requestId')}"
        )
    return body


def set_and_verify(token: str, device_code: str, address, value: str,
                   expect: str, wait_sec: float = 3.0) -> bool:
    """下发并回读校验。expect 为期望回读到的值。"""
    print(f"下发 address={address} value={value} → {device_code}")
    set_value(token, device_code, address, value)

    time.sleep(wait_sec)   # 给设备机械动作留时间

    read_back = requests.get(
        f"{RT_HOST}/api/get-value",
        params={"deviceCode": device_code, "address": str(address), "flush": 1},
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,
    ).json().get("data", {}).get(str(address))

    ok = read_back == expect
    print(f"回读值={read_back} 期望={expect} → {'✅ 一致' if ok else '❌ 不一致，请检查设备'}")
    return ok


if __name__ == "__main__":
    # ⚠️ 请替换为测试设备！
    set_and_verify("<你的 token>", "2022070314150044", 3417, "10010", "10010")

Java

java

public JsonNode setValue(String token, String deviceCode, int address, String value)
        throws Exception {
    String payload = MAPPER.writeValueAsString(Map.of(
            "address", address,
            "value", value,
            "deviceCode", deviceCode));

    HttpRequest req = HttpRequest.newBuilder()
            .uri(URI.create("https://mqtt.iot.auto-control.com.cn/api/set-value"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer " + token)
            .timeout(Duration.ofSeconds(30))
            .POST(HttpRequest.BodyPublishers.ofString(payload))
            .build();

    HttpResponse<String> resp = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());

    JsonNode body = MAPPER.readTree(resp.body());
    if (body.path("code").asInt() != 200) {
        throw new IllegalStateException("下发失败: " + resp.body());
    }
    return body;
}

返回字段

字段名	类型	说明
`address`	String	本次操作的地址
`deviceCode`	String	本次操作的设备编码
`value`	String	本次下发的值

平台的返回字段表比较简略

接口文档在本节末尾给出的字段表只有 address / deviceCode / value 三行， 没有给出返回体的完整示例，也没有像其他接口那样带 code / message。

从平台的统一约定看，返回体应当包含 code / message / data（data 内含上述三字段）。 请以实际返回为准。

注意事项

调用前的检查清单

[ ] 目标 deviceCode 是测试设备（联调阶段）
[ ] address 已在 address 全量表中核对，且与设备类型匹配
[ ] value 的位串含义已核对（10010 开 / 10001 关 / 11000 自动 / 10100 指定位置）
[ ] 指定位置类设备已先发 10100 切模式
[ ] 补光灯已先发 1010 前置指令
[ ] 设备在线（先查在线状态）
[ ] 已记录操作审计日志（操作人、时间、参数）

正确的调用顺序

text

① 查在线状态  GET  /api/mqtt-client-status?deviceCode=xxx
      ↓ 在线（status=1）
② 读当前值    GET  /api/get-value?deviceCode=xxx&address=3417&flush=1
      ↓ 确认当前状态，避免重复动作
③ 下发指令    POST /api/set-value   {address, value, deviceCode}
      ↓ 返回 code=200
④ 回读确认    GET  /api/get-value?deviceCode=xxx&address=3417&flush=1
      ↓ 值符合预期 ⇒ 成功
      ↓ 不符合 ⇒ 记录 requestId，检查设备，告警（不要盲目重发）

接口不保证幂等

平台暂未说明任何幂等机制。网络超时后重试会导致指令重复下发。建议：

超时设为 30 秒以上
超时后先回读状态再决定是否重试
重试次数上限设为 1 次

文档明确写着「谨慎调用」

接口文档对本接口的注释接口文档是：

⚠️ ⚠️ 地址映射：设置的时候，先通过 /api/get-value 获取对应地址的值…… 该接口为控制接口，谨慎调用

这是文档唯一一处风险提示，请照做。

关于不在文档中的地址

文档末尾提到：

更多参数设置可通过访问 web 界面，通过开发者模式（F12），实际操作获得对应的地址以及……

即：存在本文档未收录的控制地址。需要时请通过浏览器开发者工具观察平台页面实际操作时发出的请求，获取 address 与 value。 这属于未文档化的用法，请与运营方确认后再用于生产。

下一步

→ address 控制地址全量表：查地址与位串取值
→ 读取地址值：下发后回读
→ 错误码：控制指令未生效的排查

控制设备 ​

接口说明 ​

请求地址 ​

请求方法 ​

请求头 ​

请求参数 ​

控制值（value）语义 ​

通用控制值速查 ​

天窗 / 遮阳幕类（含「指定位置」） ​

风机湿帘（组合控制） ​

灌溉计划 ​

补光灯 ​

请求示例 ​

curl ​

HTTP 报文 ​

Python（含回读校验） ​

Java ​

返回字段 ​

注意事项 ​

下一步 ​

控制设备

接口说明

请求地址

请求方法

请求头

请求参数

控制值（`value`）语义

通用控制值速查

天窗 / 遮阳幕类（含「指定位置」）

风机湿帘（组合控制）

灌溉计划

补光灯

请求示例

curl

HTTP 报文

Python（含回读校验）

Java

返回字段

注意事项

下一步