智能公寓客房控制：如何将1路照明触摸开关对接到自己的项目中_解决方案

CATALOG

一、解决概述

智能公寓客房控制的核心诉求是：入住自动通电、离店自动断电极、远程集中管理。传统公寓管理依赖人工处理入住/退房时电卡插拔，不仅效率低下，还容易出现“人走未断电”的能源浪费。

本方案利用芯步智能触摸墙壁开关1路的HTTP接口能力，将公寓客房的主照明和其他电器接入控制系统，通过与PMS系统联动，实现客房的智能化电源管理。

核心价值

零改造安装：标准86型底盒直接替换原有墙壁开关，无需重新布线
HTTP开放接口：任何编程语言均可对接，与PMS系统无缝集成
入住/退房联动：前台办理入住时自动通电，退房后自动断电
防误触锁房：离房模式下锁定开关状态，防止无关人员误操作

二、核心技术能力分析

2.1 产品规格

芯步智能触摸墙壁开关1路的核心参数如下

类别	特性说明
产品型号	UNI-KG-1 / 触摸版
安装方式	标准86型底盒安装，可直接平行替换原有开关
控制路数	1路独立输出
工作电压	100-240V AC（交流/市电）
额定电流	MAX 10A
负载功率	300-1200W（LED灯、节能灯等感性负载需控制在300W以内）
待机功耗	0.4W（断开）- 1.7W（接通/无负载）
产品尺寸	宽：86mm；长：86mm；厚：35mm
产品外壳	防火V0级PC + 钢化玻璃面板
无线连接	WiFi 2.4GHz，直连路由器，无需网关
控制协议	开放标准HTTP接口，支持私有化部署

2.2 核心命令表

根据芯步产品手册，1路开关支持以下核心命令

命令类型	JSON格式示例	功能说明（客房联动关键）
照明开启	`{"power1":1}`	开启照明
照明关闭	`{"power1":0}`	关闭照明
状态保持	`{"power1":{"keep":"1","revert":"5"}}`	锁定开启状态，用户手动关灯5秒后自动恢复
状态锁定关	`{"power1":{"keep":"0","revert":"5"}}`	锁定关闭状态，用户手动开灯5秒后自动关闭
先通后断	`{"point1":"3000"}`	开启后3秒自动关闭（临时照明）
先断后通	`{"reset1":"3000"}`	关闭后3秒自动恢复

⚠️ LED/节能灯负载注意事项：LED灯、节能灯属于感性负载，实际功率需按标称值×3~4倍估算，单路感性负载控制在300W以内。

2.3 API接口签名规则

芯步设备控制采用动态签名验证，接口适用于任何支持HTTP请求的编程语言

请求地址:https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}
请求方法:POST
Content-Type:application/json

签名算法:
md5_secret = md5(AppSecret)
sign = md5(md5_secret + ts)

参数说明:
- AppId:应用ID（控制台获取）
- AppSecret:应用密钥（控制台获取）
- ts:当前Unix时间戳（秒）

请求Body示例

多设备控制：支持同时向最多100台设备下发命令，设备ID用逗号分隔

⚠️ 重要说明：API返回code:200仅表示平台已接收指令，不代表设备执行成功。若设备离线，命令不会生效。

三、智能公寓客房集成方案

3.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                    智能公寓客房                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │     智能触摸墙壁开关1路（86型，替换原有开关）             │   │
│  │                      ↓                                  │   │
│  │              主照明/电器（受控设备）                      │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  联动触发:PMS系统事件                                          │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │  入住办理 → 自动通电（开灯）                              │   │
│  │  退房办理 → 自动断电（关灯）+ 锁定状态                   │   │
│  │  清洁模式 → 临时通电（20分钟后自动关灯）                  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP API
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      公寓PMS系统                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    客房控制模块                          │   │
│  │  - 入住时:开关控制（开灯）                              │   │
│  │  - 退房时:开关控制（关灯）+ 状态锁定                    │   │
│  │  - 清洁模式:定时开关                                    │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

3.2 硬件安装步骤

步骤1：开关选型与采购

选择智能触摸墙壁开关1路（钢化玻璃面板，符合公寓装修风格）
根据客房数量采购（预留10%备件）

步骤2：开关安装

由电工在客房内更换原有86型墙壁开关
接线方式与普通开关一致：火线(L)、零线(N)、灯控线(L1)
可选：安装时配置电容（根据灯具类型）

步骤3：网络配置

确保客房内WiFi信号覆盖（设备仅支持2.4G频段）
支持配置5组WiFi网络，自动连接信号最强的
通过芯步控制台完成配网

步骤4：获取凭证

登录
在「开发设置」中获取 AppId 和 AppSecret
记录每个开关的设备ID，建立客房-设备映射表

3.3 代码集成示例

以下提供Python、Java和PHP三种语言的完整对接示例。

Python实现（推荐用于后端服务）

import hashlib
import time
import requests
from typing import Dict, Optional, List
from flask import Flask, request, jsonify

app = Flask(__name__)

class ApartmentRoomController:
    """智能公寓客房开关控制类"""
    
    def __init__(self, app_id: str, app_secret: str):
        self.app_id = app_id
        self.app_secret = app_secret
        self.api_base = "https://api.thingboot.com"
    
    def _generate_sign(self, ts: int) -> str:
        """生成API签名:sign = md5(md5(AppSecret) + ts)"""
        md5_secret = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = md5_secret + str(ts)
        return hashlib.md5(sign_str.encode()).hexdigest()
    
    def _send_command(self, device_id: str, order: Dict) -> Optional[Dict]:
        """发送控制命令"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_base}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        
        payload = {"device": device_id, "order": order}
        try:
            response = requests.post(url, json=payload, timeout=5)
            return response.json()
        except Exception as e:
            print(f"命令发送失败: {e}")
            return None
    
    # ========== 基础控制 ==========
    def light_on(self, device_id: str) -> Optional[Dict]:
        """开启照明"""
        return self._send_command(device_id, {"power1": 1})
    
    def light_off(self, device_id: str) -> Optional[Dict]:
        """关闭照明"""
        return self._send_command(device_id, {"power1": 0})
    
    # ========== 状态保持（防误触）==========
    def lock_on(self, device_id: str, revert_seconds: int = 5) -> Optional[Dict]:
        """
        锁定照明为开启状态
        用户手动关灯后，revert_seconds秒后自动重新开灯
        适用场景:退房后空置房间，防止误操作
        """
        return self._send_command(device_id, {
            "power1": {"keep": "1", "revert": str(revert_seconds)}
        })
    
    def lock_off(self, device_id: str, revert_seconds: int = 5) -> Optional[Dict]:
        """
        锁定照明为关闭状态
        用户手动开灯后，revert_seconds秒后自动关灯
        适用场景:深夜时段，防止客人误开灯
        """
        return self._send_command(device_id, {
            "power1": {"keep": "0", "revert": str(revert_seconds)}
        })
    
    # ========== 定时控制 ==========
    def timed_on(self, device_id: str, duration_ms: int) -> Optional[Dict]:
        """
        临时开启:开启后定时自动关闭
        适用场景:保洁/维修人员临时照明
        """
        return self._send_command(device_id, {"point1": str(duration_ms)})
    
    # ========== 批量控制 ==========
    def batch_light_off(self, device_ids: List[str]) -> Dict:
        """批量关闭多个客房照明"""
        devices_str = ",".join(device_ids)
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.api_base}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
        
        payload = {"device": devices_str, "order": {"power1": 0}}
        try:
            response = requests.post(url, json=payload, timeout=10)
            return response.json()
        except Exception as e:
            print(f"批量控制失败: {e}")
            return {}
    
    def unlock_keep_state(self, device_id: str) -> Optional[Dict]:
        """解除状态保持，恢复正常控制"""
        return self._send_command(device_id, {"power1": {"keep": ""}})

# ========== 客房配置 ==========
# 客房号与设备ID映射表
ROOM_DEVICES = {
    "101": "1878",
    "102": "1879",
    "103": "1880",
    # ... 更多客房
}

controller = ApartmentRoomController("YOUR_APP_ID", "YOUR_APP_SECRET")

# ========== PMS联动接口 ==========

@app.route('/api/room/checkin', methods=['POST'])
def room_checkin():
    """
    入住办理:客房通电、开灯
    由PMS系统在办理入住时调用
    """
    data = request.get_json()
    room_number = data.get('room_number')
    
    device_id = ROOM_DEVICES.get(room_number)
    if not device_id:
        return jsonify({"code": 404, "message": f"客房{room_number}未配置设备"})
    
    # 1. 开启照明
    result = controller.light_on(device_id)
    
    # 2. 解除状态保持（如果之前被锁定）
    controller.unlock_keep_state(device_id)
    
    # 3. 记录操作日志
    log_action(room_number, "checkin", "light_on")
    
    return jsonify({
        "code": 200 if result else 500,
        "message": f"客房{room_number}已通电"
    })

@app.route('/api/room/checkout', methods=['POST'])
def room_checkout():
    """
    退房办理:客房断电、关灯、锁定状态
    由PMS系统在办理退房时调用
    """
    data = request.get_json()
    room_number = data.get('room_number')
    
    device_id = ROOM_DEVICES.get(room_number)
    if not device_id:
        return jsonify({"code": 404, "message": f"客房{room_number}未配置设备"})
    
    # 1. 关闭照明
    result = controller.light_off(device_id)
    
    # 2. 锁定为关闭状态（防止后续误操作）
    controller.lock_off(device_id, revert_seconds=5)
    
    # 3. 记录操作日志
    log_action(room_number, "checkout", "light_off")
    
    return jsonify({
        "code": 200 if result else 500,
        "message": f"客房{room_number}已断电"
    })

@app.route('/api/room/clean', methods=['POST'])
def room_clean():
    """
    清洁模式:临时开启照明，20分钟后自动关闭
    由保洁人员触发
    """
    data = request.get_json()
    room_number = data.get('room_number')
    duration_minutes = data.get('duration_minutes', 20)
    
    device_id = ROOM_DEVICES.get(room_number)
    if not device_id:
        return jsonify({"code": 404, "message": f"客房{room_number}未配置设备"})
    
    # 临时开启，指定时长后自动关闭
    duration_ms = duration_minutes * 60 * 1000
    result = controller.timed_on(device_id, duration_ms)
    
    return jsonify({
        "code": 200 if result else 500,
        "message": f"客房{room_number}照明已开启，{duration_minutes}分钟后自动关闭"
    })

@app.route('/api/rooms/all-off', methods=['POST'])
def all_rooms_off():
    """全楼批量关闭照明（深夜节能）"""
    all_device_ids = list(ROOM_DEVICES.values())
    result = controller.batch_light_off(all_device_ids)
    
    return jsonify({
        "code": 200,
        "message": f"已向{len(all_device_ids)}间客房发送断电指令"
    })

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

Java实现

import okhttp3.*;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;

public class ApartmentRoomController {
    private final String appId;
    private final String appSecret;
    private final OkHttpClient client;
    private static final String API_BASE = "https://api.thingboot.com";
    
    // 客房设备映射
    private final Map<String, String> roomDevices = new HashMap<>();
    
    public ApartmentRoomController(String appId, String appSecret) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.client = new OkHttpClient();
        
        // 初始化客房-设备映射
        roomDevices.put("101", "1878");
        roomDevices.put("102", "1879");
    }
    
    private String md5(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("MD5");
            byte[] digest = md.digest(input.getBytes());
            StringBuilder sb = new StringBuilder();
            for (byte b : digest) sb.append(String.format("x", b));
            return sb.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
    
    private String sendCommand(String deviceId, String orderJson) throws IOException {
        long ts = System.currentTimeMillis() / 1000;
        String md5Secret = md5(appSecret);
        String sign = md5(md5Secret + ts);
        String url = API_BASE + "/" + appId + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        String bodyJson = "{\"device\":\"" + deviceId + "\",\"order\":" + orderJson + "}";
        RequestBody body = RequestBody.create(bodyJson, MediaType.parse("application/json"));
        
        Request request = new Request.Builder().url(url).post(body).build();
        try (Response response = client.newCall(request).execute()) {
            return response.body() != null ? response.body().string() : null;
        }
    }
    
    // 开灯
    public void lightOn(String roomNumber) throws IOException {
        String deviceId = roomDevices.get(roomNumber);
        if (deviceId != null) {
            sendCommand(deviceId, "{\"power1\":1}");
            System.out.println("客房 " + roomNumber + " 照明已开启");
        }
    }
    
    // 关灯
    public void lightOff(String roomNumber) throws IOException {
        String deviceId = roomDevices.get(roomNumber);
        if (deviceId != null) {
            sendCommand(deviceId, "{\"power1\":0}");
            System.out.println("客房 " + roomNumber + " 照明已关闭");
        }
    }
    
    // 锁定状态（防误触）
    public void lockOff(String roomNumber, int revertSeconds) throws IOException {
        String deviceId = roomDevices.get(roomNumber);
        if (deviceId != null) {
            sendCommand(deviceId, "{\"power1\":{\"keep\":\"0\",\"revert\":\"" + revertSeconds + "\"}}");
            System.out.println("客房 " + roomNumber + " 照明已锁定为关闭状态");
        }
    }
    
    // 入住联动
    public void checkin(String roomNumber) throws IOException {
        lightOn(roomNumber);
    }
    
    // 退房联动
    public void checkout(String roomNumber) throws IOException {
        lightOff(roomNumber);
        lockOff(roomNumber, 5);
    }
}

PHP实现

<?php
class ApartmentRoomController {
    private $appId = 'YOUR_APP_ID';
    private $appSecret = 'YOUR_APP_SECRET';
    private $apiBase = 'https://api.thingboot.com';
    
    private $roomDevices = [
        '101' => '1878',
        '102' => '1879',
        '103' => '1880',
    ];
    
    private function generateSign($ts) {
        $md5Secret = md5($this->appSecret);
        return md5($md5Secret . $ts);
    }
    
    private function sendCommand($deviceId, $orderJson) {
        $ts = time();
        $sign = $this->generateSign($ts);
        $url = "{$this->apiBase}/{$this->appId}/device/control/?sign={$sign}&ts={$ts}";
        
        $payload = json_encode([
            "device" => $deviceId,
            "order" => json_decode($orderJson, true)
        ]);
        
        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 5);
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    // 入住通电
    public function checkin($roomNumber) {
        $deviceId = $this->roomDevices[$roomNumber] ?? null;
        if ($deviceId) {
            return $this->sendCommand($deviceId, '{"power1":1}');
        }
        return null;
    }
    
    // 退房断电
    public function checkout($roomNumber) {
        $deviceId = $this->roomDevices[$roomNumber] ?? null;
        if ($deviceId) {
            return $this->sendCommand($deviceId, '{"power1":0}');
        }
        return null;
    }
}

// 使用示例
$controller = new ApartmentRoomController();
$controller->checkin('101');   // 办理入住
// $controller->checkout('101'); // 办理退房
?>

四、典型应用场景

4.1 入住/退房自动联动

事件	触发条件	执行动作	说明
入住办理	PMS办理入住完成	开灯 + 解除状态锁定	客人进入房间时灯光已亮
退房办理	PMS办理退房完成	关灯 + 锁定为关闭状态	防止后续人员误操作
空置保护	客房空置超过30分钟	关灯 + 锁定关闭	节能并防止误开

4.2 状态保持（防误触）应用

场景：退房后的空置房间，防止保洁或其他人员误开灯。

4.3 保洁/维修临时照明

场景：保洁或维修人员需要临时照明进行作业，工作结束后自动关灯。

4.4 批量控制（全楼节能）

场景：深夜时段，系统自动关闭所有空置客房的照明。

五、集成步骤

步骤一：硬件采购与安装

根据客房数量采购智能触摸墙壁开关1路
由电工在客房内更换原有86型墙壁开关
确保接线正确（火线L、零线N、灯控线L1）

步骤二：平台配置

登录
在「开发设置」中获取 AppId 和 AppSecret
为每个开关配网，记录设备ID，建立客房-设备映射表

步骤三：后端集成

将上述ApartmentRoomController类集成到公寓PMS系统中
在入住/退房事件中调用相应方法
配置保洁模式等扩展功能

步骤四：部署测试

测试入住联动：入住办理后照明是否自动开启
测试退房联动：退房办理后照明是否自动关闭并锁定
测试状态保持功能：手动开关后是否正确恢复状态

六、总结

优势	说明
零布线改造	标准86型底盒直接替换原有开关，无需重新布线
PMS无缝集成	HTTP开放接口，10分钟完成与PMS系统的对接
状态保持	可锁定关键状态，防止客人退房后误开灯导致浪费
批量管理	单次API调用最多控制100间客房照明
临时照明模式	保洁/维修模式下自动延时关灯，提升运营效率
零网关部署	WiFi直连，无需购买额外网关设备
私有化部署	支持局域网运行，数据不出公寓管理系统

七、注意事项

负载限制 ⚠️：LED灯、节能灯属于感性负载，单路功率需控制在300W以内
WiFi信号：确保客房内WiFi信号良好（设备仅支持2.4G频段）
零火线确认：安装前确认开关底盒内有零线
API响应说明：返回code:200仅表示平台接收指令，不代表设备执行成功
专业安装：涉及强电操作，必须由持证电工按照安全规范安装

通过以上方案，你可以快速将芯步智能触摸墙壁开关1路集成到公寓客房管理系统中，实现入住自动通电、退房自动断电、夜间批量节能等核心功能，提升公寓运营效率和住客体验。如有疑问，可访问获取详细产品手册和技术支持。