wiz-light

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiz-Light Skill

TypeScript library for controlling Philips Wiz smart lights via UDP communication.

用于通过UDP通信控制Philips Wiz智能灯的TypeScript库。

Quick Start

快速开始

CRITICAL: Before controlling any light, ALWAYS ask the user for the IP address:

"What is the IP address of your Wiz light?" or "Where is your Wiz light located?" or "What IP does your Wiz light use?"

重要提示： 在控制任何灯光之前，务必向用户询问IP地址：

"你的Wiz灯的IP地址是什么？" 或 "你的Wiz灯位于哪里？" 或 "你的Wiz灯使用什么IP？"

For Ready-Made Scripts

使用现成脚本

IMPORTANT: Scripts MUST be run from the skill's directory. Do NOT run them from outside the skill folder.

bash

undefined

注意： 脚本必须从技能目录运行，不要从技能文件夹外运行。

bash

undefined

Navigate to the skill directory first

先导航到技能目录

cd wiz-light

Install dependencies

安装依赖

npm install

Turn light ON

打开灯光

node scripts/light-on.js 192.168.1.2

Turn light OFF

关闭灯光

node scripts/light-off.js 192.168.1.2

Set color with brightness

设置颜色和亮度

node scripts/light-color.js 192.168.1.2 38899 blue 80

Check status

检查状态

node scripts/light-status.js 192.168.1.2

undefined

node scripts/light-status.js 192.168.1.2

undefined

For Custom Scripts

使用自定义脚本

If creating custom light control scripts, I will automatically check for and set up your Node.js project if needed:

Ask for your Wiz light IP address
Check if you have a Node.js project (check for
```
package.json
```
)
If NO project exists, automatically:
- Initialize a new Node.js project in your current directory with
```
npm init -y
```
- Set
```
"type": "module"
```
  in package.json
- Install
```
wiz-light
```
  library
- (Optional) Install
```
node-cron
```
  if you need scheduling
Create your custom script in your current directory
Provide instructions to run it from your current directory

如果要创建自定义灯光控制脚本，我会自动检查并按需设置你的Node.js项目：

询问你的Wiz灯IP地址
检查你是否有Node.js项目（检查是否存在
```
package.json
```
）
如果没有项目，自动执行以下操作：
- 在你的当前目录中使用
```
npm init -y
```
  初始化新的Node.js项目
- 在package.json中设置
```
"type": "module"
```
- 安装
```
wiz-light
```
  库
- （可选）如果需要调度功能，安装
```
node-cron
```
在你的当前目录中创建自定义脚本
提供从当前目录运行脚本的说明

Using the Library

使用库

typescript

import { WizLight } from 'wiz-light';

// Create instance with IP and port (IP must be provided)
const wl = new WizLight('192.168.1.2', { port: 38899 });

// Turn light ON
await wl.setLightStatus(true);

// Turn light OFF
await wl.setLightStatus(false);

// Set properties
await wl.setLightProps({
  r: 0,
  g: 255,
  b: 0,
  c: 0,
  w: 100,
  dimming: 100
});

// Get current status
const status = await wl.getStatus();
console.log(status.result);

typescript

import { WizLight } from 'wiz-light';

// 使用IP和端口创建实例（必须提供IP）
const wl = new WizLight('192.168.1.2', { port: 38899 });

// 打开灯光
await wl.setLightStatus(true);

// 关闭灯光
await wl.setLightStatus(false);

// 设置属性
await wl.setLightProps({
  r: 0,
  g: 255,
  b: 0,
  c: 0,
  w: 100,
  dimming: 100
});

// 获取当前状态
const status = await wl.getStatus();
console.log(status.result);

Color Settings

颜色设置

IMPORTANT: When calling

setLightProps()

, both

(warm) and

(cool) MUST be provided with one set to 100 and the other set to 0:

Warm colors: Use
```
w: 100
```
and
```
c: 0
```
Cool colors: Use
```
c: 100
```
and
```
w: 0
```

This ensures only one channel is active for clear color representation.

重要提示： 调用

setLightProps()

时，

（暖光）和

（冷光）必须同时提供，且其中一个设为100，另一个设为0：

暖色调：使用
```
w: 100
```
和
```
c: 0
```
冷色调：使用
```
c: 100
```
和
```
w: 0
```

这样可以确保只有一个通道激活，呈现清晰的颜色。

Configuration Options

配置选项

typescript

const wl = new WizLight('192.168.1.2', {
  // Port number (default: 38899)
  port: 38899,

  // Time to wait before retrying in ms (default: 1000)
  statusCheckTimeout: 1000,

  // Number of retry attempts (default: 5)
  retryTimes: 5
});

typescript

const wl = new WizLight('192.168.1.2', {
  // 端口号（默认：38899）
  port: 38899,

  // 重试前等待时间（毫秒，默认：1000）
  statusCheckTimeout: 1000,

  // 重试次数（默认：5）
  retryTimes: 5
});

Scheduling Light Control

调度灯光控制

Use

node-cron

to schedule automatic light control. Use the library directly for scheduling - scripts are not suitable for scheduled tasks.

typescript

import { WizLight } from 'wiz-light';
import cron from 'node-cron';

const wl = new WizLight('192.168.1.2', { port: 38899 });

// Schedule light to turn ON every day at 6:00 AM
cron.schedule('0 6 * * *', async () => {
  await wl.setLightStatus(true);
});

// Schedule light to turn OFF every day at 10:00 PM
cron.schedule('0 22 * * *', async () => {
  await wl.setLightStatus(false);
});

See references/scheduling.md for complete scheduling examples including:

Daily routines
Weekday vs weekend schedules
Work hours automation
Color cycling
Multiple light control
Error handling and cleanup

使用

node-cron

调度自动灯光控制。请直接使用库进行调度 - 脚本不适合用于调度任务。

typescript

import { WizLight } from 'wiz-light';
import cron from 'node-cron';

const wl = new WizLight('192.168.1.2', { port: 38899 });

// 调度灯光每天早上6点打开
cron.schedule('0 6 * * *', async () => {
  await wl.setLightStatus(true);
});

// 调度灯光每天晚上10点关闭
cron.schedule('0 22 * * *', async () => {
  await wl.setLightStatus(false);
});

查看references/scheduling.md获取完整的调度示例，包括：

日常routine
工作日与周末差异化调度
工作时间自动化
颜色循环
多灯光控制
错误处理与清理

API Reference

API参考

See references/API.md for complete API documentation including all types and methods.

查看references/API.md获取完整的API文档，包括所有类型和方法。

Usage Examples

使用示例

See references/examples.md for common use cases and patterns.

查看references/examples.md获取常见用例和模式。

Ready-Made Scripts

现成脚本

The skill includes ready-made scripts for quick light control. When the user wants to perform a direct action, first ask for the IP address, then use these scripts.

该技能包含用于快速灯光控制的现成脚本。当用户想要执行直接操作时，先询问IP地址，然后使用这些脚本。

Available Scripts

可用脚本

```
scripts/light-on.js
```
- Turn light ON with specified color (default: white)
```
scripts/light-off.js
```
- Turn light OFF
```
scripts/light-color.js
```
- Set light to specific color
```
scripts/light-status.js
```
- Check current light status

```
scripts/light-on.js
```
- 打开灯光并设置指定颜色（默认：白色）
```
scripts/light-off.js
```
- 关闭灯光
```
scripts/light-color.js
```
- 将灯光设置为特定颜色
```
scripts/light-status.js
```
- 检查当前灯光状态

Running Scripts

运行脚本

IMPORTANT: Scripts MUST be run from the skill's directory. Do NOT run them from outside the skill folder.

bash

undefined

重要提示： 脚本必须从技能目录运行，不要从技能文件夹外运行。

bash

undefined

Navigate to the skill directory first

先导航到技能目录

cd wiz-light

Install dependencies

安装依赖

npm install

Turn on light with default white color

以默认白色打开灯光

node scripts/light-on.js 192.168.1.2

Turn on light with custom color and brightness

以自定义颜色和亮度打开灯光

node scripts/light-on.js 192.168.1.2 38899 red 100

Turn off light

关闭灯光

node scripts/light-off.js 192.168.1.2

Set specific color

设置特定颜色

node scripts/light-color.js 192.168.1.2 38899 blue 80

Check status

检查状态

node scripts/light-status.js 192.168.1.2


**CRITICAL:**
- IP address is REQUIRED for all scripts
- Port is optional (default: 38899)
- Scripts MUST be run from the skill's directory (where package.json and scripts folder are located)

node scripts/light-status.js 192.168.1.2


**关键提示：**
- 所有脚本都需要IP地址
- 端口为可选（默认：38899）
- 脚本必须从技能目录（包含package.json和scripts文件夹的位置）运行

When to Use Scripts vs. Writing Code

何时使用脚本 vs 编写代码

Use READY-MADE scripts for:

Simple, one-time light control actions
Quick color changes
Turning lights on/off
User wants immediate results without coding
Testing light control quickly

Use the LIBRARY for:

Complex automation and scheduling
Integrating with other systems
Repeated automated tasks
Building custom applications
Creating custom scripts with specific requirements

使用现成脚本的场景：

简单的一次性灯光控制操作
快速更改颜色
开关灯光
用户想要无需编码即可获得即时结果
快速测试灯光控制

使用库的场景：

复杂的自动化和调度
与其他系统集成
重复的自动化任务
构建自定义应用
创建具有特定需求的自定义脚本

Auto-Setup for New Projects

新项目自动设置

If creating custom light control scripts and don't have a Node.js project, I will automatically:

Check if you have a Node.js project (check for
```
package.json
```
)
If NO project exists:
- Initialize a new Node.js project in your current directory with
```
npm init -y
```
- Set
```
"type": "module"
```
  in package.json (for ES module imports)
- Install
```
wiz-light
```
  library
- (Optional) Install
```
node-cron
```
  if you need scheduling
Create your custom script in your current directory
Once set up, proceed with your script creation

如果要创建自定义灯光控制脚本但没有Node.js项目，我会自动执行以下操作：

检查你是否有Node.js项目（检查
```
package.json
```
是否存在）
如果没有项目：
- 在你的当前目录中使用
```
npm init -y
```
  初始化新的Node.js项目
- 在package.json中设置
```
"type": "module"
```
  （用于ES模块导入）
- 安装
```
wiz-light
```
  库
- （可选）如果需要调度功能，安装
```
node-cron
```
在你的当前目录中创建自定义脚本
设置完成后，继续脚本创建

Documentation

文档

references/API.md - Complete API documentation
references/examples.md - Common use cases
references/scheduling.md - Scheduling with node-cron

references/API.md - 完整的API文档
references/examples.md - 常见用例
references/scheduling.md - 使用node-cron进行调度