怎么接入万能空调遥控器2以实现空调温度调节_解决方案

CATALOG

1. 产品概述与准备

1.1 产品能力简介

芯步智能空调遥控器2是一款通过红外信号控制空调的物联网设备，支持远程发送指令控制空调的开关机、模式切换、温度调节、风力调整等功能。该产品兼容市面上90%以上带红外遥控功能的空调，通过HTTP接口即可实现对设备的远程控制。

1.2 接入前准备

在开始对接前，请完成以下准备工作：

准备项	说明
注册账号	访问芯步官网完成账号注册
获取AppID/AppSecret	登录工作台，在“物联网控制台”→“开发设置”中获取开发者ID和密码
设备配网	为万能空调遥控器2接通电源，通过控制台或小程序完成WiFi配网（仅支持2.4G频段）
获取设备ID	配网成功后，在控制台的设备列表中查看设备ID（整型）

1.3 接口调用基础信息

协议类型：HTTP，支持任何可发起HTTP请求的编程语言
请求方式：POST
调试模式：开发阶段可在“开发设置”中开启调试模式，此时系统不校验sign和ts参数
生产环境：关闭调试模式后，需按规定计算签名并携带ts时间戳

2. 对接流程与技术实现

2.1 接口通用请求格式

万能空调遥控器2的HTTP接口采用统一的调用格式。基础请求结构如下：

请求地址

https://api.thingboot.com/ordercontrol

请求头（Headers）

参数名	类型	必填	说明
Content-Type	string	是	application/json
AppID	string	是	开发者在控制台获取的应用ID

请求体（Body）参数

参数名	类型	必填	说明
deviceId	int	是	设备的唯一标识ID
command	object	是	命令对象，具体结构见下文
sign	string	生产环境必填	签名值，用于身份验证
ts	int	生产环境必填	当前Unix时间戳（秒）

2.2 空调温度调节命令详解

调节空调温度的核心是构造正确的command对象。该对象需同时包含目标状态和温度值

命令结构示例

命令参数说明

参数	类型	可选值	说明
power	string	on / off	开关机状态
mode	string	cool / heat / auto / fan / dry	运行模式（制冷/制热/自动/送风/除湿）
temperature	int	16-30（视空调型号而定）	目标温度（摄氏度）
fanSpeed	string	auto / low / medium / high	风速档位

注意：部分空调对温度范围有不同限制，首次对接时通过设备详情页的“控制”卡片验证具体空调的能力范围。

2.3 签名计算方式（生产环境）

关闭调试模式后，需按以下规则计算sign签名：

签名算法

将所有请求参数（除sign外）按参数名ASCII码升序排序
将排序后的参数键值对拼接为字符串，格式：key1value1key2value2...
在拼接结果末尾追加AppSecret
对最终字符串进行MD5加密，得到32位小写签名

示例代码（Node.js）

示例代码（Python）

2.4 完整调用示例（使用cURL）

2.5 接口响应处理

成功响应示例

错误响应示例

常见错误码

错误码	说明	处理
0	成功	-
1001	设备不在线	检查设备网络状态和供电
1002	签名错误	重新计算sign，检查AppSecret
1003	命令不支持	确认command参数是否符合产品手册规范
1004	参数缺失	检查必填参数是否完整

3. 分步实现温度调节功能

3.1 基础封装类（JavaScript/TypeScript）

class AirConditionerController {
  constructor(appId, appSecret, baseUrl = 'https://api.thingboot.com') {
    this.appId = appId;
    this.appSecret = appSecret;
    this.baseUrl = baseUrl;
  }

// 签名生成方法
  #generateSign(params) {
    const sortedKeys = Object.keys(params).filter(k => k !== 'sign').sort();
    let signStr = '';
    sortedKeys.forEach(key => {
      const value = typeof params[key] === 'object' 
        ? JSON.stringify(params[key]) 
        : params[key];
      signStr += `${key}${value}`;
    });
    signStr += this.appSecret;
    return crypto.createHash('md5').update(signStr).digest('hex');
  }

// 发送控制命令
  async #sendCommand(deviceId, command) {
    const ts = Math.floor(Date.now() / 1000);
    const params = { deviceId, command, ts };
    const sign = this.#generateSign(params);
    
    const response = await fetch(`${this.baseUrl}/ordercontrol`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'AppID': this.appId
      },
      body: JSON.stringify({ ...params, sign })
    });
    
    return response.json();
  }

// 调节温度
  async setTemperature(deviceId, targetTemp, options = {}) {
    const defaultConfig = {
      power: 'on',
      mode: 'cool',
      fanSpeed: 'auto'
    };
    
    const command = {
      power: options.power || defaultConfig.power,
      mode: options.mode || defaultConfig.mode,
      temperature: targetTemp,
      fanSpeed: options.fanSpeed || defaultConfig.fanSpeed
    };
    
    return this.#sendCommand(deviceId, command);
  }

// 快速降温
  async quickCool(deviceId, targetTemp = 18) {
    return this.setTemperature(deviceId, targetTemp, { mode: 'cool', fanSpeed: 'high' });
  }

// 快速制热
  async quickHeat(deviceId, targetTemp = 26) {
    return this.setTemperature(deviceId, targetTemp, { mode: 'heat', fanSpeed: 'high' });
  }

// 关闭空调
  async turnOff(deviceId) {
    return this.#sendCommand(deviceId, { power: 'off' });
  }
}

// 使用示例
const controller = new AirConditionerController('YOUR_APP_ID', 'YOUR_APP_SECRET');
await controller.setTemperature(123456789, 24);

3.2 集成到应用程序的步骤

第一步：配网与设备注册

通过芯步小程序或控制台完成万能空调遥控器2的配网操作
确保设备指示灯停止闪烁，表示已成功连接WiFi
在控制台设备列表中记录设备ID

第二步：开发阶段测试

在“开发设置”中开启调试模式
使用Postman或类似工具直接发送请求，验证设备响应
通过设备详情页的“控制”卡片确认命令是否正确下发

第三步：生产环境部署

关闭调试模式
实现完整的签名计算逻辑
添加IP白名单（可选）
部署到正式环境

3.3 常见问题与处理

问题现象	可能原因	解决方案
设备无响应	WiFi连接不稳定	检查2.4G网络信号，重新配网
温度无法调节	命令格式错误	确认temperature参数在空调支持范围内
签名验证失败	AppSecret错误或排序问题	核对AppSecret，检查参数排序逻辑
控制延迟大	网络问题	考虑使用局域网控制方案（需单独配置）

4. 进阶功能与最佳实践

4.1 定时任务与场景联动

芯步平台支持通过接口创建定时任务，实现自动化温度调节。调用定时任务接口可将温度调节指令安排在指定时间执行。

4.2 局域网直连控制

对于对延迟敏感的场景，万能空调遥控器2支持局域网直连控制模式。需在网络配置中开启相关选项，并使用本地IP地址进行调用。

4.3 最佳实践

调用机制处理：在业务层记录命令发送状态，避免重复下发相同指令
状态同步：由于红外控制是单向的（设备不反馈实际温度），在应用中维护空调的目标温度状态
异常重试：当接口返回设备离线（1001）时，可设置合理的重试策略（如间隔5秒重试3次）
日志记录：记录每次命令下发的请求参数和响应结果，便于问题排查

5. 总结

通过芯步万能空调遥控器2的开放HTTP接口，开发者可以快速实现空调远程温度调节功能。整个接入流程包括：注册账号获取凭证 → 设备配网 → 构造控制命令 → 签名验证 → 下发指令。核心要点包括：

命令对象需同时携带开关、模式、温度等多维参数
生产环境必须实现完整的签名计算逻辑
开发阶段开启调试模式降低对接门槛
不同空调对温度/模式的支持可能存在差异，预先验证

按照本文档描述的步骤完成对接后，即可将空调控制能力集成到各类软件应用中，实现远程温度调节、定时任务、场景联动等智能化功能。