# LED

**Repository Path**: mutudu0912/led

## Basic Information

- **Project Name**: LED
- **Description**: LED 灯带控制器
一款通过串口通信（USB OTG 或硬件 UART）控制 RGB/RGBW LED 灯带的 Android 应用。实现了 RCS-527A 全彩灯带控制器通信协议。
- **Primary Language**: Android
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Android, Kotlin

## README

# LED 灯带控制器

一款通过串口通信（USB OTG 或硬件 UART）控制 RGB/RGBW LED 灯带的 Android 应用。实现了 **RCS-527A** 全彩灯带控制器通信协议。

使用 Jetpack Compose + Kotlin 构建。

## 功能

- **双串口后端**：USB OTG（FTDI、CH340、CP210x 等）或直连硬件串口（`/dev/tty*`）
- **颜色控制**：预设颜色、自定义 RGB 滑块、全亮 / 灭灯
- **逐颗灯珠编辑**：颜色网格，支持点击或滑动多选、批量填充/清除
- **跑马灯效果**：自动滚动颜色，速度可调（50~2000ms），支持手动偏移
- **预设方案**：保存/加载/删除命名方案，支持开机自动加载
- **上电显示**：将当前颜色保存为控制器的开机显示图案
- **国际化**：中文 / 英文运行时切换，无需重启
- **配置持久化**：灯珠数量、跑马灯开关/偏移/速度退出后自动保存
- **实时通信日志**：监控串口收发数据

## 截图

![img.png](img.png)
![img_1.png](img_1.png)

## 硬件要求

| 项目 | 要求 |
|------|------|
| Android 系统 | Android 8.0 (API 26) 及以上 |
| USB OTG 模式 | 设备需支持 USB Host |
| 硬件串口 | 操作 `/dev/tty*` 文件可能需要 root 权限 |
| 串口芯片 | FTDI FT232R/FT232H/FT231X、Prolific PL2303、CH340/CH341、CP210x、CDC/ACM、STMicroelectronics、Silicon Labs、Microchip |

## 构建

```bash
# Debug APK
./gradlew assembleDebug

# Release APK
./gradlew assembleRelease

# 安装到连接的设备
./gradlew installDebug

# 运行单元测试
./gradlew testDebugUnitTest
```

用 Android Studio 打开项目根目录即可。

## 快速开始

1. 将 USB 串口适配器（或硬件串口）连接到 Android 设备
2. 将适配器的 TX/RX/GND 连接到 LED 控制器
3. 打开 APP — 会自动扫描串口并连接 LED 控制器
4. 连接成功（状态卡片变绿）后，即可使用颜色控制功能

### 串口模式

通过界面开关切换 **硬件串口** 和 **USB 串口**：

| 模式 | 工作原理 |
|------|----------|
| **硬件串口** | 直接读写 `/dev/ttyS*`、`/dev/ttyAS*` 等设备文件。使用 `stty` 配置波特率。自动探测时逐个发送查询指令（功能码 0x92），回复 "YES" 的设备即被确认为 LED 控制器。 |
| **USB 串口** | 使用 [usb-serial-for-android](https://github.com/mik3y/usb-serial-for-android) 库。需要 USB Host 功能。支持的芯片型号见 `res/xml/device_filter.xml`。 |

## 架构

```
MainActivity (Compose UI)
  ├── SerialPortManager        — USB 串口（usb-serial-for-android）
  ├── HardwareSerialPortManager — 直接读写 /dev/tty* 设备文件
  ├── LedController            — RCS-527A 协议指令构建器
  ├── LedCommand / LedProtocol — 协议常量、数据模型
  ├── SchemeManager            — 基于 JSON 的颜色方案持久化
  └── LanguageManager          — 国际化：中/英文运行时切换
```

**协议格式**：16 字节固定头 + 颜色数据 + 2 字节尾部。支持显示颜色（功能码 0x99）、查询设备信息（0x8F–0x94）、修改地址/波特率（0x95–0x97）、上电显示设置（0x9B–0x9C）。

完整协议文档见 `extracted_docs/` 目录。

## 国际化

在标题栏右侧点击 **English** 或 **中文** 即可实时切换语言，无需重启。

```kotlin
val langManager = remember { LanguageManager(context) }
val currentLang by langManager.language.collectAsState()
val s = remember(currentLang) { Strings.of(currentLang) }
// 使用 s.appTitle、s.autoScan 等代替硬编码文字
```

## 持久化

设置存储在 SharedPreferences：

| 文件 | 数据 |
|------|------|
| `led_prefs` | 语言偏好 |
| `config_prefs` | 灯珠数量 |
| `marquee_prefs` | 跑马灯开关、偏移量、速度 |

灯珠数量和跑马灯配置在 APP 重启后自动恢复。

## 兼容性

本应用适用于兼容 RCS-527A 协议的 LED 灯带控制器。已在 WS2812B 灯带、115200 波特率下测试通过。

## 许可证

[Apache 2.0](LICENSE) © 2026 mutudu