读取地址值

接口说明

按 address（控制地址） 精确读取某个控制参数当前的值。

如果说 读取控制参数 是「一次性拿到设备的全部状态」， 那么本接口就是「只拿我要的那一个」——做状态确认、下发后回读时用它。

返回的 data 是以 address 为 key 的对象：

{ "code": 200, "data": { "3112": "00010" }, "message": "SuccessCode" }

请求地址

GET https://mqtt.iot.auto-control.com.cn/api/get-value

请求方法

GET

请求参数

参数名	类型	必填	说明	示例
deviceCode	String	是	设备编码	0010202606040002
address	String	是	控制地址，取值见 address 控制地址全量表	3112
flush	Int	是	是否刷新缓存、向设备索要最新值。1 = 刷新，0 = 读缓存	1

flush 该传 0 还是 1

值	行为	实测耗时	适用场景
1	向设备索要最新值	~4~5 秒（设备在线时）	刚下发过控制指令后回读；页面刷新时取最新状态
0	读缓存	~150 毫秒	高频读取、对实时性要求不高的场景

flush=1 很慢，超时要设足够大

实测 flush=1 单地址耗时 4~5 秒（平台需要向设备发起一次通信并等待回应）。 请把该请求的超时设为 30 秒以上，不要用默认的 5~10 秒 —— 否则会大面积超时。

设备离线时，flush=1 会等到超时并返回 code: 504。

请求头

请求头	值	必填
Authorization	Bearer <token>	是

返回字段

字段名	类型	说明	示例
code	Int	状态码，200 为成功	200
data	Object | String	成功时是以 address 为 key 的对象；失败时是空字符串 ""	{ "3112": "00010" }
message	String	提示信息，成功时为 SuccessCode	SuccessCode

data 里的键可能不止 address 一个

多数设备只返回请求的那个地址：

{ "code": 200, "data": { "3112": "00010" }, "message": "SuccessCode" }

但部分设备会额外带 hex_value 与 origin_value：

{
  "code": 200,
  "data": { "3112": "00000", "hex_value": "00", "origin_value": "00000" },
  "message": "SuccessCode"
}

取值时请用 data[address] 精确取键，不要遍历 data 的所有键。

请求示例

curl

curl 'https://mqtt.iot.auto-control.com.cn/api/get-value?deviceCode=0010202606040002&address=3112&flush=1' \
  -H "Authorization: Bearer <token>"

HTTP 报文

GET /api/get-value?deviceCode=0010202606040002&address=3112&flush=1 HTTP/1.1
Host: mqtt.iot.auto-control.com.cn
Authorization: Bearer <token>

Python

import requests

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


def get_value(token: str, device_code: str, address: str, flush: int = 1) -> str:
    """读取某个 address 当前的值。flush=1 表示向设备索要最新值。"""
    resp = requests.get(
        f"{RT_HOST}/api/get-value",
        params={"deviceCode": device_code, "address": address, "flush": flush},
        headers={"Authorization": f"Bearer {token}"},
        timeout=30,          # ← flush=1 实测要 4~5 秒，别用短超时
    )
    body = resp.json()
    if body.get("code") != 200:
        # 常见：404「地址不存在」/ 504「数据缺失」/ 504「请求超时」
        raise RuntimeError(f"读取失败: {body.get('code')} {body.get('message')}")

    data = body.get("data")
    if not isinstance(data, dict) or address not in data:
        raise KeyError(f"返回体中没有 address={address}，实际返回: {data}")
    return data[address]


def decode_bits(value: str, names: list[str]) -> dict[str, bool]:
    """把位串解析为 {名称: 是否为 1}。
    ⚠️ 位序方向（从左还是从右数）需按现场操作核对，见下方注意事项。
    """
    bits = value.zfill(len(names))[::-1]     # 这里按「从右往左」解析
    return {name: bits[i] == "1" for i, name in enumerate(names)}

返回示例

成功

{
  "code": 200,
  "data": {
    "3112": "00010"
  },
  "message": "SuccessCode"
}

失败：地址不存在

{
  "code": 404,
  "data": "",
  "message": "地址:999999不存在，请通过/api/address配置"
}

失败：数据缺失（该地址在这台设备上没有数据）

{
  "code": 504,
  "data": "",
  "message": "数据缺失,address:3417 数据不存在 ,addressList:['3417'] ,valueList:[None]"
}

失败：请求超时（设备离线或响应慢）

{
  "code": 504,
  "data": "",
  "message": "请求超时，请点击右上角 '重新获取设定值'按钮，重新获取数据"
}

三种失败都返回 HTTP 200

必须判断返回体的 code。见 错误码。

注意事项

位序方向必须现场核对

以地址 3112（一级~三级风机 + 湿帘）为例，实测返回过 00010。 文档对位序的说明存在方向上的歧义。

可靠做法：

1. 在平台页面上操作一个设备（例如把一级风机切到「手动开」）
2. 同时调本接口读同一个地址，观察 status 的哪一位发生了变化
3. 用观测结果确定你所在环境的位序方向，并写成单元测试固化下来

不要凭猜测写死位序。

回读是判断控制是否生效的唯一可靠方式

下发控制指令返回成功只代表指令被平台受理，不代表设备已动作。正确流程：

下发控制 → 等 2~5 秒（给设备机械动作留时间）→ GET /api/get-value?flush=1 回读
        → 值符合预期 ⇒ 成功
        → 值不符合预期 ⇒ 检查设备在线状态，必要时告警，不要盲目重发

部分参数的读取有前置条件

例如「天窗指定位置」类地址，需要先切换到指定位置模式（下发 10100）才能读到有意义的开度值。 前置关系见 address 控制地址全量表。

批量读取请用另一个接口

需要读多个地址时，用 批量读控制参数 一次拉全， 不要循环调本接口 —— 每次调用都会向设备发起一次通信。

下一步

• → 批量读控制参数：一次读一批
• → 控制设备：下发控制指令
• → address 控制地址全量表：查地址取值