pypixelcolor 详细使用教程 (LED 像素屏控制)

前言

两年前入手了一块32x32的LED像素屏，到手后只能用官方的ipixel color手机APP控制，想折腾点自动化显示自定义文字动画的玩法，搜遍了全网资料都没找到靠谱的代码控制方案，折腾几次无果，这块屏就被我塞柜子里吃灰了。

前阵子心血来潮，抱着试试看的心态问了问AI，没想到真挖到了pypixelcolor这个宝藏库！研究了一番发现，不管是命令行快速调试，还是写Python脚本实现复杂逻辑，都能轻松拿捏这块像素屏。

为了让和我一样的玩家少走弯路，我把自己踩过的坑整理好的操作步骤全写在这儿了，从环境搭建到自动化轮播脚本，手把手带你玩转LED像素屏的代码控制！

官方资源

GitHub 仓库: https://github.com/lucagoc/pypixelcolor
官方文档: https://lucagoc.github.io/pypixelcolor/

⚠️ 黄金三原则 (开始前必读)

断开手机APP：蓝牙设备一次只能被一个主机连接。开始前，必须彻底关闭手机上的官方APP，或者直接关闭手机蓝牙，否则电脑永远也连不上。
颜色格式要纯净：所有颜色参数都使用不带 # 号的十六进制字符串。例如，红色是 FF0000，不是 #FF0000。
准备好设备地址：你的设备 MAC 地址是 23:44:90:FE:4A:79，下文将一直使用它。

1. 环境安装

打开电脑的终端 (Windows 上的 CMD 或 PowerShell，macOS/Linux 上的 Terminal)，输入以下命令安装：

pip install pypixelcolor
```*(这会安装 pypixelcolor 及其所有依赖，占用约 50-80MB 空间)*

---

## 2. 命令行 (CLI) 快速入门 (已修正语法)
命令行适合快速测试和执行单个指令，无需写代码。**注意：所有可选参数都使用 `key=value` 格式，等号两边没有空格。**

### 扫描设备
首先，确认你的电脑能找到灯板。
```bash
pypixelcolor --scan

开关机 (Power Control)

# 关机 (屏幕熄灭， 功耗0.2瓦左右)
pypixelcolor -a 23:44:90:FE:4A:79 -c set_power off

# 开机 (点亮屏幕，功耗3瓦左右)
pypixelcolor -a 23:44:90:FE:4A:79 -c set_power on

设置时钟 (Clock Mode)

style 参数范围为 0 到 8。

# 切换到样式 4 的时钟
pypixelcolor -a 23:44:90:FE:4A:79 -c set_clock_mode 4

带参数的时钟设置：

# 设置样式2，并关闭日期显示
pypixelcolor -a 23:44:90:FE:4A:79 -c set_clock_mode 2 show_date=false

发送文字 (Send Text)

这是之前出错的地方，以下是正确语法：

# 发送静态的绿色文字 "Hello"
pypixelcolor -a 23:44:90:FE:4A:79 -c send_text "Hello" color=00FF00

# 发送滚动的紫色文字，并设置速度
pypixelcolor -a 23:44:90:FE:4A:79 -c send_text "It Works!" color=FF00FF animation=1 speed=90

发送图片 (Send Image)

你需要先准备一张 32x32 像素的图片 (如 icon.png)。

# 将图片 icon.png 发送到灯板
pypixelcolor -a 23:44:90:FE:4A:79 -c send_image icon.png

3. Python 脚本编程 (实现自动化)

通过编写 .py 脚本，你可以实现复杂的逻辑，如自动轮播、根据数据改变显示等。(Python 脚本的函数调用方式不受命令行语法影响，是正确的)。

基础连接模板

所有 Python 控制都基于这个模板。

import pypixelcolor
import time

# 你的设备地址
ADDRESS = "23:44:90:FE:4A:79"

# 创建一个设备客户端
device = pypixelcolor.Client(ADDRESS)

try:
    print(f"正在连接 {ADDRESS} ...")
    device.connect()
    print("✅ 连接成功！")
    
    # ------------------------------------
    # 在这里添加你的具体控制代码
    # 示例: 让灯板亮一下
    print("正在开机...")
    device.set_power(True) # True 代表 on
    time.sleep(2) # 等待2秒
    # ------------------------------------
    
except Exception as e:
    print(f"❌ 发生错误: {e}")
finally:
    # 确保程序结束时能断开连接
    device.disconnect()
    print("👋 已断开连接")

场景 A: 详细设置时钟

set_clock_mode 函数会自动同步你电脑的当前时间。

# --- 放在基础模板的控制代码区 ---
print("正在设置时钟模式...")
device.set_clock_mode(
    style=4,          # 样式 ID (0-8)
    show_date=True,   # 显示日期
    format_24=True    # 使用24小时制
)

场景 B: 详细发送文字

send_text 函数支持多种参数，可以实现酷炫的文字效果。

# --- 放在基础模板的控制代码区 ---
print("正在发送高级文字效果...")
device.send_text(
    text="Python Rocks!",
    color="FFFF00",      # 黄色 (不带#)
    bg_color="0000FF",   # 蓝色背景
    speed=90,            # 滚动速度 (0-100)
    animation=1,         # 1=向左滚动, 0=静态
    rainbow_mode=0       # 0=关闭彩虹特效
)

4. 终极自动化脚本：时钟与文字轮播

这个脚本完美实现了你 “5秒时钟，2秒文字” 的需求，并且加入了自动重连机制，非常稳定，适合长期运行（例如在树莓派上）。

新建文件 auto_loop.py:

import pypixelcolor
import time

ADDRESS = "23:44:90:FE:4A:79"

def main_loop(device):
    """主循环，负责轮播显示"""
    print("✅ 连接成功！按 Ctrl+C 停止轮播。")
    time.sleep(1) # 刚连上缓冲一下

    while True:
        # --- 阶段 1: 显示时钟 ---
        print("🕒 显示时钟 (Style 4)，持续5秒...")
        try:
            device.set_clock_mode(style=4)
        except Exception as e:
            print(f"⚠️ 时钟指令未收到确认 (可忽略): {e}")
        time.sleep(5)

        # --- 阶段 2: 显示文字 ---
        print("🔤 显示文字，持续3秒...")
        try:
            device.send_text("Hello", color="FF00FF", animation=1)
        except Exception as e:
            print(f"⚠️ 文字指令未收到确认 (可忽略): {e}")
        time.sleep(3) # 文字滚动需要多一点时间

def run_controller():
    """带重连机制的控制器"""
    while True:
        device = pypixelcolor.Client(ADDRESS)
        try:
            device.connect()
            main_loop(device) # 进入主循环
        except KeyboardInterrupt:
            print("\n🛑 用户手动停止")
            break
        except Exception as e:
            print(f"❌ 连接断开或发生错误: {e}")
        finally:
            device.disconnect()
            print("👋 已断开连接")
        
        print("🔄 5秒后尝试重连...")
        time.sleep(5)

if __name__ == "__main__":
    run_controller()
```**如何运行:**
1.  保存代码为 `auto_loop.py`。
2.  在终端运行 `python auto_loop.py`。
3.  按 `Ctrl+C` 停止。

---

## 5. 常见问题排查 (Troubleshooting)

| 错误信息/现象 | 原因分析 | 解决方案 |
| :--- | :--- | :--- |
| `Found 0 devices` | 灯板已被手机APP占用。 | **关闭手机蓝牙**，或者在手机APP后台管理中彻底杀死它。 |
| `no ack from device` | 指令发送太快，设备来不及响应。 | 在Python代码的指令之间加入 `time.sleep(1)`，或者直接忽略这个报错（指令通常已生效）。 |
| `unrecognized arguments` | 命令行可选参数格式错误。 | 必须使用 `key=value` 格式，例如 `color=FF0000`，而不是 `--color FF0000`。 |
| 灯板卡在开机动画 | 设备未被成功“唤醒”。 | 先发送一个简单的指令，如 `set_power on` 或发送一个字，打破默认循环。 |
| `WinRT` 或 `Bleak` 相关报错 | Windows 蓝牙服务不稳定。 | 重启电脑蓝牙；拔插灯板电源；重启电脑。 |