Added documents related to PM5.
This commit is contained in:
1 parent
32e2e414cd
commit
bcbe1afac0
14 files changed
+1339
-1
No files matched your search
@@ -0,0 +1,350 @@
|
||||
# RGB Controller Technical Manual
|
||||
|
||||
> This document is intended for host-side (Host) development and integration personnel. It describes the I2C communication interface, register model, and business behavior provided by this chip.
|
||||
> This document describes only the **externally visible interface and business logic**.
|
||||
|
||||
- Author: DXL
|
||||
- Document version: v1.0
|
||||
- Date: 2026-08-25
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This chip acts as an **I2C slave** and drives a chain of single-wire, daisy-chained RGB LEDs. The host sends LED color data and configuration commands to the chip over the I2C bus; the chip maintains a color buffer internally and automatically, continuously refreshes the data onto the LED strip.
|
||||
|
||||
Core capabilities:
|
||||
|
||||
| Capability | Description |
|
||||
|------|------|
|
||||
| Color setting | Set the RGB888 color value of each LED individually |
|
||||
| Index management | Supports setting a start index, automatic index increment, and index locking |
|
||||
| One-command lights off | Turn off all LEDs with a single command |
|
||||
| Controllable blink | Hardware-timed on/off flashing, freeing the host CPU |
|
||||
| Firmware version | Reads the firmware major/minor version for compatibility adaptation |
|
||||
|
||||
---
|
||||
|
||||
## 2. I2C Communication Interface
|
||||
|
||||
### 2.1 Slave Address
|
||||
|
||||
The chip supports selecting the slave address via the level state of an **address-select pin**:
|
||||
|
||||
| Address-select pin state | 7-bit slave address | Remarks |
|
||||
|----------------|--------------|------|
|
||||
| High level (tied to VCC) | `0x48` | Currently available |
|
||||
| Low level (tied to GND) | `0x49` | Currently available |
|
||||
| Tied to SCL | `0x68` | Reserved, not yet enabled |
|
||||
| Tied to SDA | `0x69` | Reserved, not yet enabled |
|
||||
|
||||
> Note: the address-select pin performs a level detection with debounce during the **power-on initialization phase**; a high level uses `0x48`, a low level uses `0x49`.
|
||||
> The two dynamic-detection schemes "tied to SCL / tied to SDA" in the table are currently reserved designs that are not yet enabled in the actual firmware — do not rely on them.
|
||||
|
||||
### 2.2 Register Addressing Method (Register Pointer)
|
||||
|
||||
The chip uses the "register pointer" addressing method: **before every operation, one byte of register address must be written first**. Once the chip remembers this address, subsequent reads and writes target that register.
|
||||
|
||||
- **Write operation**: when writing the data body, byte 1 is the register address, and the subsequent bytes are that register's data.
|
||||
- **Read operation**: you must **first perform a write operation** (writing only 1 byte of register address) to set the target register, then initiate the read operation.
|
||||
|
||||
> Key point: the register address is **retained across transactions**. The register address set by the previous write operation remains valid in subsequent read transactions until the next write operation writes a new register address.
|
||||
|
||||
### 2.3 Read/Write Operation Timing
|
||||
|
||||
**Write register:**
|
||||
|
||||
```
|
||||
START → 7-bit address + W(0) → ACK → [register address] → [data bytes…] → STOP
|
||||
```
|
||||
|
||||
**Read register:**
|
||||
|
||||
```
|
||||
Step 1 (set pointer): START → 7-bit address + W(0) → ACK → [register address] → STOP
|
||||
Step 2 (read data) : START → 7-bit address + R(1) → ACK → [data bytes…] → host NACK → STOP
|
||||
```
|
||||
|
||||
### 2.4 Recommended Communication Rate
|
||||
|
||||
It is recommended to use a communication clock rate of **around 10K**; an excessively high rate may cause communication failures.
|
||||
|
||||
### 2.5 Abnormal Acknowledge (NACK) Behavior
|
||||
|
||||
The chip replies NACK and terminates the current communication in the following cases:
|
||||
|
||||
| Case | Description |
|
||||
|------|------|
|
||||
| Address mismatch | The received 7-bit address differs from the configured slave address |
|
||||
| Reading an invalid address | A read operation is initiated when no register address has been set (default `0x00`) |
|
||||
| Reading a write-only register | Reading the lights-off register (`0x04`) |
|
||||
| Writing a read-only register | Writing the firmware version register (`0xFF`) |
|
||||
| Writing an invalid address | The register address is `0x00` |
|
||||
| Index out of range | The written index value ≥ the current valid LED count |
|
||||
|
||||
---
|
||||
|
||||
## 3. Register Map
|
||||
|
||||
### 3.1 Register Overview Table
|
||||
|
||||
| Address | Name | Access | Data Length | Description |
|
||||
|------|------|------|----------|------|
|
||||
| `0x00` | Invalid address | — | — | Power-on default address; not readable or writable |
|
||||
| `0x01` | Count register | Read / Write | 1 byte | Number of LEDs actually mounted on the hardware |
|
||||
| `0x02` | Index register | Read / Write | 1 byte | Index of the LED currently being operated on |
|
||||
| `0x03` | Data register | Read / Write | 3×N bytes | LED color value (RGB888) |
|
||||
| `0x04` | Lights-off register | Write-only | No data body | Turn off all LEDs |
|
||||
| `0x05` | Index lock register | Read / Write | 1 byte | Whether to lock the operation index |
|
||||
| `0x06` | Blink enable register | Read / Write | 1 byte | Whether to enable controllable blink |
|
||||
| `0x07` | Blink duration register | Read / Write | 2 bytes | On duration + off duration |
|
||||
| `0xFF` | Firmware version register | Read-only | 2 bytes | Major version + minor version |
|
||||
|
||||
### 3.2 Register Detailed Descriptions
|
||||
|
||||
#### 0x00 — Invalid Address (Reserved)
|
||||
|
||||
Power-on default value. No read operation can be performed at this address; writing this address causes NACK and terminates the communication.
|
||||
|
||||
#### 0x01 — Count Register (Read/Write)
|
||||
|
||||
Indicates the number of LEDs actually mounted on the current hardware.
|
||||
|
||||
- **Write**: writes 1 byte. If multiple bytes are written, the **last byte** takes effect. If the written value exceeds the chip's supported upper limit, it is **clamped** to the upper limit.
|
||||
- **Read**: returns the current valid LED count.
|
||||
- **Default**: the chip's supported upper-limit count after power-on.
|
||||
|
||||
#### 0x02 — Index Register (Read/Write)
|
||||
|
||||
Indicates the LED index to be operated on (starting from 0).
|
||||
|
||||
- **Write**: writes 1 byte. If multiple bytes are written, the last byte takes effect. If the written value ≥ the current valid LED count, it is an illegal operation; the chip replies NACK and terminates the communication.
|
||||
- **Read**: returns the current operation index.
|
||||
- **Side effect**: writing **triggers blink disable**.
|
||||
- **Constraint**: the legal index range is `0 ~ (valid count - 1)`.
|
||||
|
||||
#### 0x03 — Data Register (Read/Write)
|
||||
|
||||
LED color data. **Every 3 bytes is the RGB888 color value of one LED**, in the byte order **R, G, B**.
|
||||
|
||||
- **Write**: writes a multiple of 3 bytes consecutively. Each time 3 bytes (one complete LED) are written, the index auto-increments by 1 (unless locked, see `0x05`).
|
||||
- **Read**: reads consecutively; every 3 bytes returns one LED's R, G, B, and the index auto-increments by 1.
|
||||
- **Index wraparound**: when the index increments to the valid count, it resets to zero, enabling circular read/write of the buffer.
|
||||
- **Persistence**: the index does **not** reset to zero after communication ends; the next operation continues from the current index.
|
||||
- **Side effect**: both read and write **trigger blink disable**.
|
||||
|
||||
> Example: after setting count = 8 and index = 0, writing 24 bytes (8 LEDs) each time covers the entire LED strip.
|
||||
|
||||
#### 0x04 — Lights-off Register (Write-only)
|
||||
|
||||
Turns off all LEDs (all colors set to R0-G0-B0).
|
||||
|
||||
- **Write**: no data body required; writing triggers it.
|
||||
- **Read**: not supported; reading causes NACK.
|
||||
- **Deferred effect**: the lights-off action actually executes after the current I2C communication **ends (STOP)**.
|
||||
- **Side effect**: also disables blink.
|
||||
- **Note**: after writing, allow about **10ms** to ensure the lights-off completes; if the data or index register is written again during this period, the lights-off may fail (color disorder or some LEDs not properly turned off).
|
||||
|
||||
#### 0x05 — Index Lock Register (Read/Write)
|
||||
|
||||
Controls whether the index auto-increments when writing the data register.
|
||||
|
||||
- **Write**: writing `0` means unlocked (index auto-increments when writing data); writing a non-`0` value means locked (index does not increment when writing data).
|
||||
- **Read**: returns the current lock state (`0` / `1`).
|
||||
- **Purpose**: when locked, it is suitable for repeatedly writing data commands to **refresh a single LED** (index unchanged).
|
||||
- **Note**: locking affects only the index auto-increment of **write** operations; the index of **read** operations still increments.
|
||||
|
||||
#### 0x06 — Blink Enable Register (Read/Write)
|
||||
|
||||
Controls the controllable blink function.
|
||||
|
||||
- **Write**: writing a non-`0` value enables blink (blink applies to the LED selected by the current index); writing `0` disables blink.
|
||||
- **Read**: returns the current enable state (`0` / `1`).
|
||||
- **Blink behavior**: once enabled, the selected LED automatically cycles through "on duration → off duration → on duration…".
|
||||
- **Mutual exclusion**: see Section 4.
|
||||
|
||||
#### 0x07 — Blink Duration Register (Read/Write)
|
||||
|
||||
Sets the on and off durations of the blink.
|
||||
|
||||
- **Write**: byte 1 is the **on duration**, byte 2 is the **off duration**.
|
||||
- **Read**: returns the on duration and off duration bytes in sequence.
|
||||
- **Unit**: both are 10ms; a single byte ranges from 0 to 255, i.e., up to 2.55 seconds can be set.
|
||||
- **Default**: 500ms each for on and off.
|
||||
|
||||
#### 0xFF — Firmware Version Register (Read-only)
|
||||
|
||||
- **Read**: byte 1 is the major version, byte 2 is the minor version.
|
||||
- **Write**: not supported; writing causes NACK.
|
||||
- **Purpose**: it is recommended that the host read the firmware version during specific flows, so that when compatibility issues arise they can be adapted and fixed accordingly.
|
||||
|
||||
---
|
||||
|
||||
## 4. Register Mutual Exclusion Conditions
|
||||
|
||||
Controllable blink (after `0x06` is enabled) is **mutually exclusive** with the following operations; performing these operations **automatically disables blink**:
|
||||
|
||||
| Triggering operation | Register | Disables blink? |
|
||||
|----------|--------|--------------|
|
||||
| Write index | `0x02` | ✅ Yes |
|
||||
| Write data | `0x03` | ✅ Yes |
|
||||
| Read data | `0x03` | ✅ Yes |
|
||||
| Write lights-off | `0x04` | ✅ Yes (and turns off all LEDs) |
|
||||
| Write blink enable (value 0) | `0x06` | ✅ Yes |
|
||||
|
||||
> Design rationale: blink applies to the "LED selected by the current index", while index, data, and lights-off operations all change that LED's state, conflicting with blink. Therefore blink must be disabled first before performing these operations.
|
||||
|
||||
**Other read/write restrictions (mutual exclusion / constraints)**:
|
||||
|
||||
| Restriction | Description |
|
||||
|------|------|
|
||||
| `0x04` write-only | Reading causes NACK |
|
||||
| `0xFF` read-only | Writing causes NACK |
|
||||
| `0x00` invalid | Both reading and writing cause NACK |
|
||||
| Index out of range | Writing an index ≥ valid count causes NACK |
|
||||
| Count clamping | Writing a count above the upper limit is clamped to the upper limit |
|
||||
|
||||
---
|
||||
|
||||
## 5. Business Flowcharts
|
||||
|
||||
### 5.1 Power-on Initialization Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Power-on reset]) --> B[Controller internal initialization]
|
||||
B --> C[RGB initialization<br/>clear color buffer<br/>turn off all LEDs by default]
|
||||
C --> D[Blink timer initialization<br/>default on/off 500ms each]
|
||||
D --> E[I2C slave initialization]
|
||||
E --> F{Address-select pin<br/>level detection and debounce}
|
||||
F -->|High level| G[Slave address = 0x48]
|
||||
F -->|Low level| H[Slave address = 0x49]
|
||||
G --> I[Enter main loop]
|
||||
H --> I
|
||||
```
|
||||
|
||||
### 5.2 Main Loop Overall Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Main loop entry]) --> B[Sample I2C bus<br/>detect SCL / SDA transitions]
|
||||
B --> C{SCL transition?}
|
||||
C -->|Yes| D[I2C state machine handling]
|
||||
C -->|No| E{SDA transition?}
|
||||
E -->|Yes| F[START / STOP signal handling]
|
||||
E -->|No| G[Cache bus state]
|
||||
D --> G
|
||||
F --> G
|
||||
G --> H{10ms timer reached?}
|
||||
H -->|Yes| I[Blink timing accumulation +1]
|
||||
H -->|No| K{I2C communication in progress?}
|
||||
I --> K
|
||||
K -->|Yes| A
|
||||
K -->|No| L{Waiting for strip reset?}
|
||||
L -->|Yes| A
|
||||
L -->|No| M[Blink on / off switching decision]
|
||||
M --> N{Data updated?}
|
||||
N -->|No| A
|
||||
N -->|Yes| O[Refresh LED colors]
|
||||
O --> A
|
||||
```
|
||||
|
||||
### 5.3 I2C Communication State Machine
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> IDLE
|
||||
IDLE --> ADDR: START received
|
||||
ADDR --> OP: 7-bit address matches
|
||||
ADDR --> IDLE: address mismatch
|
||||
OP --> IACK1: parse read/write bit and prepare response
|
||||
IACK1 --> IACK2: SCL falling edge
|
||||
IACK2 --> WRITEDATA: write operation
|
||||
IACK2 --> READDATA: read operation
|
||||
WRITEDATA --> WACK1: 8 bits received
|
||||
WACK1 --> WACK2: SCL falling edge
|
||||
WACK2 --> WRITEDATA: continue receiving
|
||||
READDATA --> RACK: 8 bits sent
|
||||
RACK --> READDATA: host ACK received
|
||||
RACK --> IDLE: host NACK received
|
||||
WRITEDATA --> IDLE: STOP received
|
||||
READDATA --> IDLE: STOP received
|
||||
```
|
||||
|
||||
### 5.4 Write Operation Data Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Host write operation]) --> B[START + address + write bit]
|
||||
B --> C[Slave replies ACK]
|
||||
C --> D[Receive byte 1 = register address]
|
||||
D --> E{Address valid?}
|
||||
E -->|Invalid 0x00| F[Reply NACK to terminate]
|
||||
E -->|Valid| G[Save register address]
|
||||
G --> H[Receive subsequent data bytes]
|
||||
H --> I[Write by register type<br/>count / index / data / lock / blink …]
|
||||
I --> J[STOP]
|
||||
J --> K[Execute deferred actions<br/>lights off / disable blink]
|
||||
K --> L([Done])
|
||||
```
|
||||
|
||||
### 5.5 Read Operation Data Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A([Read operation preamble]) --> B[First write 1 byte to set register address]
|
||||
B --> C[START + address + read bit]
|
||||
C --> D{Register readable?}
|
||||
D -->|0x00 or 0x04| E[Reply NACK to terminate]
|
||||
D -->|Readable| F[Slave ACK]
|
||||
F --> G[Return data per current register<br/>multi-byte registers auto-advance]
|
||||
G --> H{Host continues reading?}
|
||||
H -->|ACK| G
|
||||
H -->|NACK + STOP| I([End])
|
||||
```
|
||||
|
||||
### 5.6 Blink On/Off Logic
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Blink enabled<br/>refreshed to target LED] --> B{Currently in on phase?}
|
||||
B -->|Yes| C{On duration reached?}
|
||||
C -->|Yes| D[Switch to off<br/>set color to 0<br/>restart timing]
|
||||
C -->|No| E[Keep waiting]
|
||||
B -->|No| F{Off duration reached?}
|
||||
F -->|Yes| G[Switch to on<br/>take color from buffer<br/>restart timing]
|
||||
F -->|No| H[Keep waiting]
|
||||
D --> A
|
||||
G --> A
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Key Business Feature Summary
|
||||
|
||||
1. **Deferred effect of changes**: actions such as lights-off and blink-disable are not executed immediately when the command arrives; instead they are processed uniformly **after the I2C communication ends (STOP)**, avoiding refresh operations interfering with bus communication stability.
|
||||
|
||||
2. **Index management**:
|
||||
- When writing data, the index auto-increments after every 3 bytes (lockable).
|
||||
- When reading data, the index always auto-increments.
|
||||
- The index wraps around to 0 after reaching the valid count.
|
||||
- The index is retained across transactions and does not reset when communication ends.
|
||||
|
||||
3. **Data refresh mechanism**: when data changes, a refresh-enable flag is set, and the main loop refreshes all LEDs once in a **full pass**; when there is no change, it refreshes only once, avoiding unnecessary refresh overhead.
|
||||
|
||||
4. **Blink frees the host**: blink is driven by the chip's internal timer; the host only needs to set the on/off durations and enable it, without continuously sending commands, thereby freeing the host CPU.
|
||||
|
||||
5. **Safety protection**:
|
||||
- Out-of-range protection: a count above the upper limit is automatically clamped; an out-of-range index returns NACK.
|
||||
- Communication priority: while I2C communication is in progress, LED refresh is skipped, reducing the probability of communication failure.
|
||||
|
||||
---
|
||||
|
||||
## 7. Usage Notes
|
||||
|
||||
1. It is recommended that the host first read the firmware version register (`0xFF`) after power-on, to adapt when compatibility issues arise.
|
||||
2. After executing lights-off (`0x04`), allow about 10ms; do not write the data/index register during this period.
|
||||
3. After setting the count (`0x01`), the legal range of the index (`0x02`) changes accordingly; be careful to avoid out-of-range writes.
|
||||
4. Before using the blink function, confirm that the current index points to the target LED; index/data/lights-off operations disable blink.
|
||||
5. It is recommended to keep the communication rate at around 10K; an excessively high rate may cause communication failures.
|
||||
6. The current slave address supports only two static selections, `0x48` (high level) and `0x49` (low level); `0x68`/`0x69` are reserved.
|
||||
Reference in new issue
Block a user