一、引言

二、技术背景

1. 鸿蒙分布式设备控制能力

• ​​设备发现与连接​​：自动发现同一局域网内的鸿蒙灯具设备（支持 Zigbee、Wi-Fi、蓝牙 Mesh 等协议），并建立低延迟的安全通信通道；
• ​​统一控制接口​​：通过 ​​分布式设备管理 API​​，将不同厂商的灯具硬件能力（如开关、亮度、色温）抽象为标准化的控制指令（如 turnOn()、setBrightness(50%)、setColorTemperature(3000K)）；
• ​​本地优先执行​​：优先通过本地网络直接控制灯具（避免云端延迟），仅在必要时依赖云端同步（如跨公网远程控制）。

2. 灯光控制的核心参数

• ​​开关（Power）​​：控制灯具的电源状态（开/关）；
• ​​亮度（Brightness）​​：调节灯光的明暗程度（通常为 0%~100%，对应 0~255 或 0~1000 流明）；
• ​​色温（Color Temperature）​​：调节灯光的色调（单位：开尔文 K，典型范围 2700K~6500K，其中 2700K~3500K 为暖黄光，4000K~5000K 为中性白光，6000K~6500K 为冷蓝光）。

三、应用使用场景

1. 家庭日常照明

• ​​场景描述​​：用户通过手机 APP 或智慧屏，远程控制客厅、卧室灯具的开关，并根据时间调节亮度（如夜间调暗）和色温（如睡前切换暖光）；
• ​​需求​​：低延迟（<200ms）、支持多房间灯具分组控制（如“全屋灯光”“卧室灯光”）。

2. 智能场景联动

• ​​场景描述​​：通过自动化规则（如“回家模式”触发玄关灯自动开+调至暖光，“观影模式”触发客厅灯自动关闭）；
• ​​需求​​：灯光控制与其他设备（如门锁、传感器）联动，支持条件触发（如“当门锁打开且时间为 18:00~22:00 时，打开客厅灯”）。

3. 酒店/公寓智能客控

• ​​场景描述​​：酒店客人通过房间内的平板或手机，调节床头灯、吊灯的亮度和色温，满足个性化需求；
• ​​需求​​：支持临时权限管理（如客人只能控制当前房间的灯具）、预设场景（如“阅读模式”“休息模式”）。

4. 工业/商业照明

• ​​场景描述​​：工厂车间通过调节工作区灯具的亮度和色温，优化员工视觉舒适度；商场通过统一控制店铺灯光营造氛围；
• ​​需求​​：支持批量控制（如“一楼所有灯具调至 50% 亮度”）、定时任务（如“每天 22:00 自动关闭非必要灯光”）。

四、不同场景下详细代码实现

场景 1：手机控制单盏鸿蒙灯具（基础版）

1.1 项目结构

LightControlApp/
├── entry/src/main/ets/pages/
│   ├── Index.ets          // 主页面（控制界面）
│   └── LightManager.ets   // 灯具控制逻辑（分布式设备通信）
├── entry/src/main/module.json5  // 模块配置（声明分布式能力）
└── build-profile.json5

1.2 分布式能力配置（module.json5）

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",  // 支持手机控制端
      "tablet"  // 可扩展平板控制端
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DEVICE_CONTROL",  // 分布式设备控制权限
        "reason": "$string:control_permission_reason"
      },
      {
        "name": "ohos.permission.NETWORK",  // 网络通信权限（用于设备发现）
        "reason": "$string:network_permission_reason"
      }
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ts",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:icon",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}

1.3 灯具控制逻辑（LightManager.ets）

// entry/src/main/ets/pages/LightManager.ets
import distributedDevice from '@ohos.distributed.device'; // 鸿蒙分布式设备管理模块
import lightControl from '@ohos.smart.device.light'; // 鸿蒙灯光控制专用模块（示例，实际需使用官方 SDK）

export class LightManager {
  private lightDeviceId: string = ''; // 目标灯具的设备 ID
  private isConnected: boolean = false; // 是否已连接到灯具

  // 初始化：发现并连接目标灯具
  async init(lightId: string) {
    try {
      // 1. 通过分布式设备管理 API 发现鸿蒙灯具（需灯具支持标准协议）
      const devices = await distributedDevice.getDevicesByType('light'); // 获取所有类型为 'light' 的设备
      const targetDevice = devices.find(device => device.deviceId === lightId || device.name.includes('客厅灯')); // 根据 ID 或名称匹配目标灯具
      if (!targetDevice) {
        console.error('未找到目标灯具！');
        return;
      }
      this.lightDeviceId = targetDevice.deviceId;

      // 2. 建立连接（鸿蒙会自动通过软总线建立低延迟通道）
      this.isConnected = await lightControl.connect(this.lightDeviceId);
      if (!this.isConnected) {
        console.error('灯具连接失败！');
      } else {
        console.log('✅ 已连接到灯具：', this.lightDeviceId);
      }
    } catch (error) {
      console.error('灯具初始化失败:', error);
    }
  }

  // 控制灯具开关
  async togglePower(isOn: boolean) {
    if (!this.isConnected) {
      console.warn('灯具未连接，无法控制！');
      return;
    }
    try {
      await lightControl.setPower(this.lightDeviceId, isOn); // isOn: true=开灯，false=关灯
      console.log('💡 灯具已', isOn ? '开启' : '关闭');
    } catch (error) {
      console.error('开关控制失败:', error);
    }
  }

  // 调节灯具亮度（0~100，对应 0%~100%）
  async setBrightness(brightness: number) {
    if (!this.isConnected) {
      console.warn('灯具未连接，无法控制！');
      return;
    }
    try {
      // 限制亮度范围（部分灯具可能只支持 1~100）
      const clampedBrightness = Math.max(1, Math.min(100, brightness));
      await lightControl.setBrightness(this.lightDeviceId, clampedBrightness);
      console.log('🔆 亮度已调节至：', clampedBrightness + '%');
    } catch (error) {
      console.error('亮度调节失败:', error);
    }
  }

  // 调节灯具色温（2700K~6500K，典型范围）
  async setColorTemperature(tempK: number) {
    if (!this.isConnected) {
      console.warn('灯具未连接，无法控制！');
      return;
    }
    try {
      // 限制色温范围（部分灯具可能只支持 2700~6500K）
      const clampedTemp = Math.max(2700, Math.min(6500, tempK));
      await lightControl.setColorTemperature(this.lightDeviceId, clampedTemp);
      console.log('🌡️ 色温已调节至：', clampedTemp + 'K');
    } catch (error) {
      console.error('色温调节失败:', error);
    }
  }

  // 释放连接（退出时调用）
  disconnect() {
    if (this.isConnected) {
      lightControl.disconnect(this.lightDeviceId);
      this.isConnected = false;
    }
  }
}

1.4 主页面（Index.ets）

// entry/src/main/ets/pages/Index.ets
import { LightManager } from './LightManager.ets';

@Entry
@Component
struct Index {
  @State private lightManager: LightManager = new LightManager();
  @State private isLightOn: boolean = false; // 当前灯光开关状态
  @State private brightness: number = 50; // 当前亮度（0~100）
  @State private colorTemp: number = 4000; // 当前色温（2700~6500K）
  @State private targetLightId: string = 'light_001'; // 目标灯具 ID（需与实际灯具匹配）

  aboutToAppear() {
    // 初始化连接（应用启动时自动连接目标灯具）
    this.lightManager.init(this.targetLightId).then(() => {
      // 连接成功后，获取灯具当前状态（可选，需灯具支持状态查询 API）
      this.loadLightStatus();
    });
  }

  // 加载灯具当前状态（模拟，实际需调用灯具的状态查询接口）
  private async loadLightStatus() {
    // 假设通过 lightControl.getPower/getBrightness/getColorTemperature 获取当前状态
    // 此处简化为默认值（实际项目需实现状态同步逻辑）
    this.isLightOn = false;
    this.brightness = 50;
    this.colorTemp = 4000;
  }

  // 开关控制
  private toggleLight() {
    this.isLightOn = !this.isLightOn;
    this.lightManager.togglePower(this.isLightOn);
  }

  // 亮度调节（通过滑块输入）
  private onBrightnessChange(value: number) {
    this.brightness = value;
    this.lightManager.setBrightness(value);
  }

  // 色温调节（通过滑块输入）
  private onColorTempChange(value: number) {
    this.colorTemp = value;
    this.lightManager.setColorTemperature(value);
  }

  build() {
    Column() {
      Text('鸿蒙灯光控制（开关/亮度/色温）')
        .fontSize(24)
        .fontWeight(FontWeight.Bold)
        .margin({ bottom: 30 });

      // 开关按钮
      Button(this.isLightOn ? '关闭灯光' : '开启灯光')
        .width('80%')
        .height(50)
        .backgroundColor(this.isLightOn ? '#ff4444' : '#4CAF50')
        .onClick(() => this.toggleLight())
        .margin({ bottom: 30 });

      // 亮度调节
      Column() {
        Text(`亮度：${this.brightness}%`)
          .fontSize(16)
          .alignSelf(ItemAlign.Start);
        Slider({
          value: this.brightness,
          min: 1,
          max: 100,
          step: 1
        })
          .width('100%')
          .onChange((value: number) => {
            this.onBrightnessChange(value);
          });
      }
      .width('80%')
      .margin({ bottom: 30 });

      // 色温调节
      Column() {
        Text(`色温：${this.colorTemp}K`)
          .fontSize(16)
          .alignSelf(ItemAlign.Start);
        Slider({
          value: this.colorTemp,
          min: 2700,
          max: 6500,
          step: 100
        })
          .width('100%')
          .onChange((value: number) => {
            this.onColorTempChange(value);
          });
      }
      .width('80%')
      .margin({ bottom: 30 });

      // 当前状态提示
      Text(this.isLightOn ? '🔆 灯光已开启' : '🌑 灯光已关闭')
        .fontSize(14)
        .fontColor(this.isLightOn ? '#4CAF50' : '#999');
    }
    .width('100%')
    .height('100%')
    .padding(20)
    .justifyContent(FlexAlign.Center);
  }

  aboutToDisappear() {
    // 退出时释放连接
    this.lightManager.disconnect();
  }
}

• 手机端启动应用后，自动连接目标鸿蒙灯具（需灯具与手机在同一局域网且支持标准协议）；
• 通过开关按钮控制灯光的开启/关闭，通过亮度滑块调节明暗（1%~100%），通过色温滑块调节色调（2700K~6500K）；
• 控制指令实时下发至灯具，灯光状态同步更新。

场景 2：多灯具分组控制（进阶版）

2.1 分组管理逻辑（新增 GroupManager.ets）

// entry/src/main/ets/pages/GroupManager.ets
import { LightManager } from './LightManager.ets';

export class GroupManager {
  private lightManagers: LightManager[] = []; // 组内的多个灯具控制器

  // 添加灯具到分组
  addLight(lightId: string) {
    const manager = new LightManager();
    manager.init(lightId); // 初始化每个灯具的连接
    this.lightManagers.push(manager);
  }

  // 控制整组灯具的开关
  async toggleGroupPower(isOn: boolean) {
    for (const manager of this.lightManagers) {
      if (manager['isConnected']) { // 实际需通过 manager 的状态判断
        await manager['togglePower'](isOn); // 调用单个灯具的开关方法
      }
    }
  }

  // 控制整组灯具的亮度
  async setGroupBrightness(brightness: number) {
    for (const manager of this.lightManagers) {
      if (manager['isConnected']) {
        await manager['setBrightness'](brightness);
      }
    }
  }

  // 控制整组灯具的色温
  async setGroupColorTemperature(tempK: number) {
    for (const manager of this.lightManagers) {
      if (manager['isConnected']) {
        await manager['setColorTemperature'](tempK);
      }
    }
  }
}

2.2 主页面集成分组控制（修改 Index.ets）

// 在 Index.ets 中引入 GroupManager 并绑定分组逻辑
@State private groupManager: GroupManager = new GroupManager();

aboutToAppear() {
  // 添加两个灯具到分组（示例：客厅灯 light_001 和卧室灯 light_002）
  this.groupManager.addLight('light_001');
  this.groupManager.addLight('light_002');
}

// 新增分组控制按钮（示例）
Button('全屋开灯')
  .onClick(() => this.groupManager.toggleGroupPower(true));

Button('全屋调暗至 30%')
  .onClick(() => this.groupManager.setGroupBrightness(30));

Button('全屋切换暖光（3000K）')
  .onClick(() => this.groupManager.setGroupColorTemperature(3000));

• 用户点击“全屋开灯”时，客厅灯和卧室灯同时开启；
• 调节“全屋调暗至 30%”时，所有灯具亮度统一降至 30%；
• 切换“全屋暖光”时，所有灯具色温统一调整为 3000K（暖黄光）。

五、原理解释

1. 鸿蒙灯光控制的核心流程

1. ​​设备发现与连接​​：
   • 手机通过鸿蒙 ​​分布式软总线​​ 自动扫描同一局域网内的鸿蒙灯具设备（需灯具支持标准协议，如鸿蒙智联认证）；
   • 使用 distributedDevice.getDevicesByType('light')API 获取灯具列表，并通过 lightControl.connect(lightId)建立低延迟连接。
2. ​​控制指令下发​​：
   • 用户通过 UI 操作（如点击开关按钮、滑动亮度滑块）触发控制逻辑；
   • 应用调用 lightControl.setPower()（开关）、setBrightness()（亮度）、setColorTemperature()（色温）等标准化 API，将指令通过分布式软总线传输至灯具。
3. ​​灯具响应​​：
   • 灯具接收到指令后，通过内置的鸿蒙协议栈解析控制参数（如亮度值、色温值），并调整 LED 驱动电路，实现实际的明暗和色调变化；
   • 部分高端灯具支持状态反馈（如当前亮度、色温），可通过 lightControl.getBrightness()等 API 同步回手机端显示。

2. 关键技术点

• ​​分布式软总线​​：提供低延迟（<100ms）、高可靠性的设备间通信通道，确保控制指令实时到达灯具；
• ​​标准化协议​​：鸿蒙定义了统一的灯光控制接口（如 setPower、setBrightness），屏蔽不同厂商灯具的硬件差异；
• ​​本地优先​​：优先通过本地网络（Wi-Fi 或蓝牙）直接控制灯具，避免云端中转带来的延迟（远程控制时才依赖云端）。

六、核心特性

七、原理流程图及原理解释

原理流程图（鸿蒙灯光控制）

+-----------------------+       +-----------------------+       +-----------------------+
|     手机（控制端）    |       |     鸿蒙灯具（被控端）|       |     分布式软总线      |
|  (Control Terminal)   |       |  (Light Device)       |       |  (Distributed SoftBus)|
+-----------------------+       +-----------------------+       +-----------------------+
          |                             |                             |
          |  1. 发现灯具设备          |                             |  4. 传输控制指令       |
          |-------------------------->|                             |-----------------------> |
          |  (getDevicesByType('light'))|                             |  (setPower/brightness) |
          |                             |  2. 建立连接             |                             |
          |                             |<--------------------------|                             |
          |                             |  3. 解析并执行指令       |                             |
          |                             |  (调整 LED 驱动电路)     |                             |
          |  5. 接收状态反馈（可选）  |                             |  6. 返回状态数据       |
          |<--------------------------|                             |<----------------------- |

原理解释

1. ​​设备发现​​：手机端通过鸿蒙分布式软总线扫描同一局域网内的灯具设备（需灯具注册为“light”类型），获取设备列表（如 light_001、light_002）；
2. ​​连接建立​​：手机与目标灯具（如 light_001）通过软总线建立低延迟连接（类似局域网内的点对点通信）；
3. ​​指令下发​​：用户操作（如点击开关）触发手机端调用 lightControl.setPower(true)，指令通过软总线传输至灯具；
4. ​​灯具执行​​：灯具接收到指令后，解析参数（如 true表示开灯），调整内部 LED 驱动电路的电流/电压，改变灯光的明暗或色调；
5. ​​状态反馈（可选）​​：部分灯具支持将当前状态（如亮度值、色温值）通过软总线回传至手机，用于 UI 实时更新。

八、环境准备

1. 开发环境

• ​​鸿蒙 SDK​​：需安装鸿蒙开发者工具（DevEco Studio），并配置 HarmonyOS 3.0 及以上版本的 SDK；
• ​​开发语言​​：eTS（基于 TypeScript 的鸿蒙声明式开发语言）；
• ​​设备​​：至少一台鸿蒙手机（如华为 P50、Mate 40 系列）和一盏鸿蒙认证灯具（如鸿蒙智联智能灯泡、吸顶灯）；
• ​​网络​​：手机与灯具需处于同一局域网（如连接同一 Wi-Fi）。

2. 权限配置

• ​​分布式设备控制权限​​：在 module.json5中声明 ohos.permission.DISTRIBUTED_DEVICE_CONTROL，用于调用灯具控制 API；
• ​​网络权限​​：声明 ohos.permission.NETWORK，用于设备发现和通信。

3. 灯具要求

• 必须为 ​​鸿蒙认证设备​​（支持鸿蒙分布式协议），或通过第三方协议（如 Zigbee、Wi-Fi）接入鸿蒙生态（需适配层转换）；
• 支持标准控制接口（如开关、亮度、色温调节），部分高端灯具还需支持状态反馈。

九、实际详细应用代码示例实现

完整项目代码（整合上述场景）

1. 主页面（Index.ets）

2. 灯具控制逻辑（LightManager.ets）

3. 分组控制逻辑（GroupManager.ets）

4. 模块配置（module.json5）

十、运行结果

1. 基础版表现

• 手机端成功连接灯具后，点击开关按钮，灯具立即响应开启/关闭；
• 拖动亮度滑块，灯具亮度实时变化（如从 30% 调至 80%）；
• 拖动色温滑块，灯具色调从冷蓝光（6500K）切换至暖黄光（2700K）。

2. 进阶版表现

• 点击“全屋开灯”按钮，客厅灯和卧室灯同时开启；
• 调节“全屋调暗至 30%”时，所有灯具亮度统一降低；
• 切换“全屋暖光”时，所有灯具色温同步调整为 3000K。

十一、测试步骤以及详细代码

1. 测试目标

• 设备连接是否成功（手机能否发现并连接灯具）；
• 开关控制是否实时生效；
• 亮度/色温调节是否平滑且无延迟；
• 分组控制是否同步所有灯具状态。

2. 测试步骤

步骤 1：启动应用

• 在手机上安装并运行应用，确保手机与灯具处于同一 Wi-Fi 网络。

步骤 2：验证设备连接

• 打开应用，观察控制台日志（通过 DevEco Studio 的 Log 工具）是否输出灯具发现信息（如 已连接到灯具：light_001）；
• 若未连接成功，检查灯具是否开机、是否支持鸿蒙协议、网络是否互通。

步骤 3：测试开关控制

• 点击“开启灯光”按钮，观察灯具是否立即点亮；点击“关闭灯光”按钮，确认灯具熄灭。

步骤 4：测试亮度/色温调节

• 拖动亮度滑块至 100%，观察灯具是否最亮；拖动至 1%，确认灯具最暗；
• 拖动色温滑块至 2700K，观察灯光是否变为暖黄光；拖动至 6500K，确认是否变为冷蓝光。

步骤 5：测试分组控制

• 点击“全屋开灯”按钮，确认所有分组灯具同时开启；
• 调节“全屋调暗至 30%”，检查所有灯具亮度是否统一降低。

十二、部署场景

1. 家庭智能家居

• 用户通过手机或智慧屏控制全屋灯光，实现“回家模式”（自动开灯+暖光）、“睡眠模式”（自动关灯/调暗）；