如何对接智能空调指令发射器以实现HTTP接口远程发送指令_解决方案

CATALOG

芯步的智能空调遥控器通过红外信号控制空调，开放HTTP接口供开发者调用。以下是完整的对接方案，涵盖接口协议、签名算法、指令格式和状态确认机制。

1. 产品概述与对接价值

芯步智能空调遥控器是一款支持红外信号控制的物联网硬件设备。它能够兼容市面上超过90%的红外遥控空调机型，支持远程开关机、模式切换（制冷/制热/送风/除湿）、温度调节、风力调节等全功能控制。

对接价值：通过该设备的开放HTTP接口，开发者可将传统红外空调无缝接入现有的Web系统、APP、小程序或SaaS平台，实现能源管理、智能场景联动（如与温湿度传感器联动）、集中控制（酒店/办公楼多空调管理）等场景应用。

2. API接口架构

芯步开放平台采用标准的HTTP协议进行指令下发，同时提供异步消息推送机制用于获取设备执行结果。

2.1 核心接口地址

POST http(s)://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

AppID：平台生成的应用唯一标识，在控制台获取
sign：接口签名，用于身份验证
ts：Unix时间戳（秒），防止重放攻击

2.2 签名算法

签名生成分为两步：

先将AppSecret进行MD5加密得到 secret_md5
将 secret_md5 与时间戳 ts 拼接后再次进行MD5加密

secret_md5 = md5(AppSecret)
sign = md5(secret_md5 + ts)

参数说明

AppSecret：开发者密钥，与控制台AppID配对使用
ts：当前Unix时间戳（秒），需与请求中的ts参数保持一致

2.3 请求参数

请求Body支持JSON或Form格式，推荐使用JSON：

参数	类型	必填	说明
device	string	是	设备唯一ID（硬件外壳或控制台可见）
order	object	是	指令内容，JSON对象

3. 空调控制指令集

空调设备的控制指令与普通通断器不同，需要指定完整的空调运行参数。根据空调产品的功能定义，order对象支持以下字段：

指令字段	说明	可选值
power	开关机	1（开机），0（关机）
mode	运行模式	1（制冷），2（制热），3（送风），4（除湿），5（自动）
temp	设定温度	16-30（摄氏度），具体范围取决于空调型号
wind	风力档位	0（自动），1（低风），2（中风），3（高风）
swing	扫风模式	0（关闭扫风），1（上下摆风），2（左右摆风），3（上下左右）

3.1 请求示例

示例1：开启制冷模式，设定24℃，中风

示例2：关机

示例3：调节温度（保持其他状态不变）

3.2 批量控制

如需同时控制多台空调，device参数支持使用逗号或竖线分隔多个设备ID，单次最多支持100台

device=820720,820721,820722

批量控制时，所有设备将执行相同的指令。若需对不同设备下发不同指令，需分多次调用。

4. 获取设备执行结果（异步消息推送）

接口返回 code:200仅表示平台已接收指令并下发至设备，不代表空调已成功执行。要确认空调实际是否响应，需通过平台的消息推送机制获取执行结果。

4.1 配置推送地址

登录芯步控制台 → 物联网控制台 → 设置消息推送URL（HTTP端点）或选择MQTT方式接收。

4.2 推送消息格式

当设备执行指令后，平台会向配置的URL推送如下格式的JSON：

mid：对应下发指令的消息ID，可用于关联请求与响应
data：设备实际执行后的状态变更内容

4.3 状态确认集成

在业务系统中推荐采用以下模式确保指令可靠执行：

调用控制接口时，在order中携带 extra 字段（如订单号、请求ID）
平台推送执行结果时，extra 原样返回，用于关联匹配
设置超时机制：若未在规定时间内收到推送，判定为超时，可重试或告警

5. 完整对接流程

步骤1：注册账号并获取凭证

访问芯步官网注册账号，登录后在控制台创建工作台，获取AppID和AppSecret。

步骤2：设备配网

有两种方式为设备配置WiFi：

方式一：电脑控制台配网

进入物联网控制台 → 网络配置
添加现场WiFi名称和密码（必须是2.4G频段）
为设备配置此网络：点击已添加的网络，选择“为设备配置此网络”，按页面提示将手机热点改为指定名称和密码，设备自动连接

方式二：小程序配网

搜索“芯步小程序”并登录
选择工作台 → 添加现场WiFi
按提示设置手机热点完成配网

步骤3：获取设备ID

配网成功后，设备列表中将显示已添加的设备及其唯一ID，复制保存待用。

步骤4：接口联调

使用获取的AppID、AppSecret和设备ID进行接口调用测试，确认能够正常控制空调。

步骤5：配置消息推送

在控制台设置消息接收URL，测试异步推送是否正常到达。

6. 多设备管理

6.1 使用设备分组

当需要管理大量空调时，使用分组控制接口，避免逐个下发

POST http(s)://api.thingboot.com/{AppID}/group/control/?sign={sign}&ts={ts}

请求参数：

6.2 设备命名规范

在控制台为设备配置有业务意义的名称（如“会议室A-空调”），或在自己的业务系统中维护设备ID到业务实体的映射关系。

7. 常见问题和需要注意的点

问题	解决方案
设备收不到指令	设备需保持在线，检查WiFi是否为2.4G频段；确认设备已成功配网且指示灯常亮
空调无响应	确认空调红外接收头无遮挡；验证指令参数是否超出空调支持范围（如温度设置过低）
签名验证失败	检查时间戳是否为Unix秒级时间戳；确认AppSecret是否正确；验证MD5计算流程
异步推送未收到	检查推送URL是否公网可达（非localhost）；确认服务器返回HTTP 200状态码
批量控制部分失败	接口返回504表示部分设备不存在或无权限；先通过设备列表接口校验每个device的有效性