舞蹈室灯光管理：怎样把12路远程照明控制模块接入到项目中_解决方案

CATALOG

一、概述

舞蹈室的灯光管理直接影响教学氛围和舞蹈效果。传统方案中，排练不同舞种时需要手动切换多路灯光，调光台操作复杂，无法实现排练流程自动化。芯步智能照明控制器12路通过开放HTTP接口，可无缝接入您的舞蹈室管理系统，实现12路独立照明回路的远程分控、第一种场景键切换和定时控制。

核心能力

12路独立分控：单台控制器可管理舞蹈室内所有照明回路
开放HTTP API：适用于任何支持HTTP请求的编程语言，10分钟完成对接
超低延迟：命令下发到设备响应80-120ms，灯光切换实时流畅
私有化部署：支持局域网运行，数据安全可控
无网关设计：WiFi直连，可设定5组WiFi自动切换

舞蹈室12路照明分配方案

回路编号	控制对象	典型负载	场景用途
回路1	主舞台面光	LED平板灯	排练照明主光源
回路2	舞台顶光	LED PAR灯	顶部氛围照明
回路3	侧光左	LED洗墙灯	左侧舞蹈区域
回路4	侧光右	LED洗墙灯	右侧舞蹈区域
回路5	背光	LED灯带	背景烘托
回路6	地脚光	LED地插灯	地面效果照明
回路7	色光灯组	RGB灯带	氛围变色
回路8	镜前灯	LED灯管	更衣区/镜前
回路9	观众席照明	筒灯	观摩区域
回路10	应急照明	应急灯	安全备用
回路11	氛围灯1	装饰灯	不同舞种氛围
回路12	氛围灯2	装饰灯	不同舞种氛围

二、核心产品选型

2.1 智能照明控制器12路16A

芯步智能照明控制器12路（型号：UNI-KZQ-ZM-12-16A）专为舞蹈室、剧场等专业灯光场景设计。

特性	参数
控制路数	12路独立分控
额定电流	16A / 路（MAX）
工作电压	DC 5V 2A（直流）
负载功率	阻性≤3500W/路，感性≤500W/路
无线连接	WiFi 2.4GHz
控制接口	HTTP API
私有化部署	支持局域网直连
产品尺寸	宽210mm × 长99mm × 厚62.8mm

数据来源：

2.2 产品核心优势

芯步智能照明控制器开放HTTP接口，适用于任何支持HTTP请求的编程语言。接口简单、清晰、友好，仅需在接口携带签名以及设备ID，即可向设备下发命令。支持接入任何形式的软件项目：Web、APP/小程序、窗体软件以及SaaS/低代码等平台。

设备核心优势

私有化部署：支持自建消息服务器，可运行在纯局域网环境
无网关设计：设备使用WiFi 2.4G无线网络，采用WiFi直接方式，无需网关支持
多网络备份：可设定5组WiFi网络，优先连接信号最强的进行连接
超低延迟：命令下发到设备响应80-120ms，灯光切换实时流畅

2.3 负载容量说明

请注意设备的负载容量限制

单路阻性负载最大3500W，感性负载最大500W
全接通时总负载受限于电源适配器规格

⚠️ 选型提示：舞蹈室常用的LED灯具属于阻性负载，12路全开时需确保总功率不超过12×3500W的理论值，实际受电源适配器限制。如需控制大功率常规灯具，选择AC 85-265V供电版本。

三、整体架构

3.1 系统架构图

┌─────────────────────────────────────────────────────────────────┐
│                    舞蹈室管理系统 / 中控平台                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐               │
│  │  场景编排   │  │  一键切换   │  │  定时任务   │               │
│  └─────────────┘  └─────────────┘  └─────────────┘               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ HTTP API调用（携带签名）
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                     芯步云平台 / 私有化服务器                  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ WiFi 2.4GHz
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│               智能照明控制器12路（配电箱内安装）                   │
│  ┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐                           │
│  │1 │2 │3 │4 │5 │6 │7 │8 │9 │10│11│12│                           │
│  └──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘                           │
│   面光 顶光 侧光 侧光 背光 地脚 色光 镜前 观众 应急 氛围 氛围       │
└─────────────────────────────────────────────────────────────────┘

3.2 集成工作流程

业务触发：教师切换舞种模式、定时任务到达、或管理员远程操作
签名计算：生成MD5签名，发起一个HTTP请求
指令下发：向API发送POST请求
设备执行：控制器执行指定回路通断控制

四、API接口接入详解

4.1 接口地址与签名计算

请求地址

https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

参数说明

参数	说明	示例
{AppId}	应用ID（控制台获取）	`qtyVWcgeMq`
{ts}	当前Unix时间戳（秒）	`1747212640`
{sign}	签名	`c484eb97...`

签名计算公式

sign = md5( md5(AppSecret) + ts )

将开发者密码（AppSecret）进行一次MD5
将这个结果拼接上时间戳ts
对整个拼接后的字符串再做一次MD5

签名计算示例

4.2 核心命令详解

4.2.1 单路独立控制

4.2.2 批量控制（场景切换）

批量控制可同时控制任意组合的回路，适用于一键切换不同舞种灯光场景：

说明：relay为回路编号数组，power为1（开）或0（关）

4.2.3 先断后通（灯光复位/重启）

适用于灯光设备异常时的远程复位：

先断开回路1，5秒后自动接通

4.2.4 携带业务标识

在一些业务场景，需要在命令里携带订单号等特征信息。可在order中增加一个字段extra，在消息推送中会原样返回此特征信息

*extra只支持32位以内的大小写英文字母和数字（a-zA-Z0-9）*

4.3 多语言代码示例

Python

import requests
import time
import hashlib
from typing import List, Dict

class DanceStudioLightController:
    """舞蹈室灯光控制器"""
    
    # 舞种场景预设
    SCENES = {
        "ballet": {
            "name": "芭蕾舞",
            "relays": [1, 2, 5],
            "desc": "基本光+顶光+背光"
        },
        "modern": {
            "name": "现代舞",
            "relays": [3, 4, 7, 11],
            "desc": "侧光+色光+氛围"
        },
        "latin": {
            "name": "拉丁舞",
            "relays": [1, 6, 7, 12],
            "desc": "面光+地脚+色光"
        },
        "rehearsal": {
            "name": "排练模式",
            "relays": [1, 2, 3, 4],
            "desc": "面光+顶光+侧光"
        },
        "performance": {
            "name": "演出模式",
            "relays": [1, 2, 3, 4, 5, 6, 7],
            "desc": "全面板"
        },
        "cleanup": {
            "name": "清场照明",
            "relays": [1, 8],
            "desc": "面光+镜前灯"
        }
    }
    
    def __init__(self, app_id: str, app_secret: str, device_id: str):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"
    
    def _generate_sign(self, ts: int) -> str:
        """生成签名: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, order: dict) -> dict:
        """发送命令到设备"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {"device": self.device_id, "order": order}
        
        response = requests.post(url, json=payload, timeout=5)
        return response.json()
    
    # ========== 基础控制 ==========
    def control_single(self, relay: int, on: bool, extra: str = None) -> dict:
        """控制单路灯光"""
        order = {f"power{relay}": "1" if on else "0"}
        if extra:
            order["extra"] = extra
        return self._send_command(order)
    
    def batch_control(self, relays: List[int], on: bool, extra: str = None) -> dict:
        """批量控制多个回路"""
        order = {
            "batch": {
                "relay": relays,
                "power": "1" if on else "0"
            }
        }
        if extra:
            order["extra"] = extra
        return self._send_command(order)
    
    # ========== 场景控制 ==========
    def set_scene(self, scene_name: str) -> dict:
        """一键切换舞种灯光场景"""
        scene = self.SCENES.get(scene_name.lower())
        if not scene:
            return {"error": f"未找到场景: {scene_name}"}
        
        # 首先关闭所有回路
        relays_all = list(range(1, 13))
        self.batch_control(relays_all, False, extra=f"SCENE_{scene_name.upper()}_PRE")
        
        # 开启目标场景的回路
        result = self.batch_control(scene["relays"], True, extra=f"SCENE_{scene_name.upper()}_ON")
        
        print(f"已切换至{scene['name']}模式:{scene['desc']}")
        return result
    
    def all_on(self) -> dict:
        """全开所有12路照明"""
        relays = list(range(1, 13))
        return self.batch_control(relays, True, extra="ALL_ON")
    
    def all_off(self) -> dict:
        """全关所有12路照明"""
        relays = list(range(1, 13))
        return self.batch_control(relays, False, extra="ALL_OFF")
    
    # ========== 特定舞种快捷方法 ==========
    def ballet_mode(self) -> dict:
        """芭蕾舞模式"""
        return self.set_scene("ballet")
    
    def modern_mode(self) -> dict:
        """现代舞模式"""
        return self.set_scene("modern")
    
    def latin_mode(self) -> dict:
        """拉丁舞模式"""
        return self.set_scene("latin")
    
    def rehearsal_mode(self) -> dict:
        """排练模式"""
        return self.set_scene("rehearsal")
    
    # ========== 设备复位 ==========
    def reset_relay(self, relay: int, interval_ms: int = 5000) -> dict:
        """远程复位指定回路"""
        order = {"reset": {"relay": [relay], "interval": interval_ms}}
        return self._send_command(order)

# 使用示例
controller = DanceStudioLightController("your_app_id", "your_app_secret", "dance_studio_01")

# 一键切换芭蕾舞灯光
controller.ballet_mode()

# 一键切换现代舞灯光
controller.modern_mode()

# 排练结束后全关
controller.all_off()

# 单独控制面光（回路1）
controller.control_single(1, True, extra="TEACHER_OVERRIDE")

JavaScript/Node.js

const crypto = require('crypto');
const axios = require('axios');

class DanceStudioLightController {
    constructor(appId, appSecret, deviceId) {
        this.appId = appId;
        this.appSecret = appSecret;
        this.deviceId = deviceId;
        this.baseUrl = `https://api.thingboot.com/${appId}/device/control/`;
        
        // 舞种场景预设
        this.scenes = {
            ballet: { relays: [1, 2, 5], name: '芭蕾舞' },
            modern: { relays: [3, 4, 7, 11], name: '现代舞' },
            latin: { relays: [1, 6, 7, 12], name: '拉丁舞' },
            rehearsal: { relays: [1, 2, 3, 4], name: '排练模式' }
        };
    }
    
    _generateSign(ts) {
        const md5Secret = crypto.createHash('md5').update(this.appSecret).digest('hex');
        const signStr = md5Secret + ts;
        return crypto.createHash('md5').update(signStr).digest('hex');
    }
    
    async sendCommand(order) {
        const ts = Math.floor(Date.now() / 1000);
        const sign = this._generateSign(ts);
        const url = `${this.baseUrl}?sign=${sign}&ts=${ts}`;
        
        const payload = { device: this.deviceId, order };
        const response = await axios.post(url, payload);
        return response.data;
    }
    
    async batchControl(relays, powerOn) {
        const order = {
            batch: { relay: relays, power: powerOn ? '1' : '0' }
        };
        return this.sendCommand(order);
    }
    
    async setScene(sceneName) {
        const scene = this.scenes[sceneName];
        if (!scene) return;
        
        // 先关闭所有回路
        await this.batchControl([1,2,3,4,5,6,7,8,9,10,11,12], false);
        // 再开启场景回路
        return this.batchControl(scene.relays, true);
    }
    
    async allOff() {
        return this.batchControl([1,2,3,4,5,6,7,8,9,10,11,12], false);
    }
}

Shell（curl）- 快速测试

五、舞蹈室场景实战

5.1 第一种场景：舞种预设一键切换

需求：舞蹈老师在教学不同舞种时，能够一键切换对应的灯光场景。

联动实现

5.2 第二种场景：课程时段自动切换

需求：根据课表时间自动切换灯光场景，无需人工干预。

5.3 第三种场景：舞蹈动作配合灯光变化

需求：舞蹈表演中，灯光需要配合舞蹈动作节奏变化。通过接入音频分析或触发信号，实现灯光与舞蹈同步。

5.4 场景四：远程运维与故障排查

需求：管理员远程检查灯光设备状态，发现异常回路时进行远程复位。

5.5 场景五：节能模式自动调度

需求：无人时段自动进入节能模式，仅保留必要照明。

六、私有化部署方案

舞蹈室可能部署在校内局域网环境，芯步控制器支持纯局域网运行。

部署模式对比

特性	公有云模式	私有化模式
设备联网	WiFi连接互联网	连接校内WiFi
API地址	`api.thingboot.com`	自建服务器IP
数据流向	经过芯步云端	内网直连，数据不出校园
网络依赖	需要互联网	仅需局域网
适用场景	快速接入	学校、培训机构内网部署

私有化配置要点

设备支持配置5组WiFi网络，自动连接信号最强的网络
需自建HTTP服务，所有API调用在内网完成
支持自建消息服务器，接收设备状态回调

七、设备安装部署指南

7.1 安装要求

项目	要求
安装方式	标准配电箱安装（DIN导轨安装）
工作电压	DC 5V 2A（直流）
单路负载	阻性≤3500W，感性≤500W
网络要求	WiFi 2.4GHz信号覆盖良好
外壳材质	塑料

数据来源：

7.2 回路分配

回路	推荐用途	注意事项
1-2	面光/主光	排练和演出的主要光源
3-4	侧光	舞蹈动作强调区域
5-6	背光/地脚光	增加舞台层次感
7	色光	营造不同舞种氛围
8-9	镜前灯/观众席	辅助区域照明
10	应急照明	安全备用
11-12	氛围灯	装饰及特殊效果

7.3 安装注意事项

负载限制：LED灯具属于阻性负载，注意单路功率不超过3500W
WiFi信号：金属配电箱可能屏蔽信号，测试后固定安装
电源适配器：设备使用DC 5V 2A供电，确保电源稳定
散热空间：控制器安装在通风位置，避免过热

八、常见问题与排障

问题	可能原因	解决方案
设备不在线	WiFi信号被屏蔽	检查2.4GHz WiFi覆盖，设备支持5组WiFi自动切换
某回路无法控制	负载超限/硬件故障	检查该路负载是否超过3500W
批量控制部分失败	设备离线	200仅表示平台接收，需确认设备在线状态
切换场景延迟高	网络波动	私有化部署可降至80-120ms
命令执行无效果	设备离线/参数错误	通过消息推送确认设备是否成功执行命令

九、总结

本方案基于芯步智能照明控制器12路，实现了舞蹈室灯光的场景化、自动化管理

能力	实现的方式是
12路独立分控	每路设备独立API控制通断
舞种场景预设	批量控制命令一键切换
课表自动切换	定时任务自动执行场景
远程运维	远程复位故障回路
节能模式	定时自动进入低功耗模式
批量管理	单条命令控制多回路

集成核心步骤

获取AppID/AppSecret，实现MD5签名算法
根据舞蹈室需求规划12路回路分配
预设不同舞种的灯光场景（芭蕾、现代、拉丁等）
开发HTTP调用模块，封装场景切换函数
可选：配置定时任务实现自动场景切换

方案优势

✅ 12路独立：单设备覆盖舞蹈室所有照明需求
✅ 接口统一：标准HTTP API，10分钟完成对接
✅ 场景丰富：支持批量控制，一键切换舞种灯光
✅ 超低延迟：80-120ms响应，灯光切换流畅
✅ 部署灵活：WiFi直连无需网关，支持私有化部署
✅ 负载能力强：单路最大3500W，满足专业灯光需求

如需详细的产品手册和API文档，请访问查阅或联系技术支持团队获取。