sirmrak/linux-voice-assistant
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

LED Effect Mapping

Browse Source 
Background on LED effect mapping from XVF3800 to LVA LED effects.
This commit is contained in:
imonlinux
2025-12-10 14:43:04 -08:00
committed by GitHub
parent 70079d6a61
commit f1d2700fac
1 changed files with 45 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/xvf3800_legacy_led_effects_mapping.md
+45
View File
@@ -0,0 +1,45 @@
# XVF3800 Legacy LED Effects Mapping for Linux Voice Assistant
This document maps the **legacy ReSpeaker XVF3800 LED_EFFECT modes** to the higher-level LED effects used by the **linux-voice-assistant (LVA)**.
## XVF3800 Legacy LED_EFFECT Values
From the Seeed/XMOS documentation:
- `LED_EFFECT 0` → **off**
- `LED_EFFECT 1` → **breath**
- `LED_EFFECT 2` → **rainbow**
- `LED_EFFECT 3` → **single color**
- `LED_EFFECT 4` → **DoA mode**
## LVA Effects → XVF3800 Mapping
LVA exposes higher-level effects such as **Off / Solid / Slow/Medium/Fast Pulse / Slow/Medium/Fast Blink / Spin**.
On XVF3800 (legacy firmware), these are currently mapped onto the limited built-in modes as follows:
| LVA Effect Name | XVF3800 `LED_EFFECT` | Additional Parameters | Behavior on XVF3800 (Legacy) |
|------------------|----------------------|--------------------------------------|-------------------------------------------------------------------------|
| `off` | `0` (off) | – | LED ring completely off. |
| `solid` | `3` (single color) | `LED_COLOR`, `LED_BRIGHTNESS` | Full ring in a single static color. |
| `slow_pulse` | `1` (breath) | `LED_SPEED` = slow | Slow breathing in the configured color. |
| `medium_pulse` | `1` (breath) | `LED_SPEED` = medium | Medium breathing in the configured color. |
| `fast_pulse` | `1` (breath) | `LED_SPEED` = fast | Fast breathing in the configured color. |
| `slow_blink` | `1` (breath) * | `LED_SPEED` = slow | Approximated with slow breath (no true sharp on/off blink). |
| `medium_blink` | `1` (breath) * | `LED_SPEED` = medium | Approximated with medium breath. |
| `fast_blink` | `1` (breath) * | `LED_SPEED` = fast | Approximated with fast breath. |
| `spin` | `3` or `1` ** | Typically treated as solid/pulsed | No native “spin”; currently falls back to a static or pulsed behavior. |
\* There is no dedicated “blink” primitive in the legacy API, so all blink variants are currently rendered as **breathing** with different speeds. They will look like fading rather than a true square‑wave blink until we add a more advanced mapping or per‑LED pattern logic.
\** The legacy firmware does not offer a true “spin” animation. For now, `spin` is effectively treated as either **single color** or a **breath** variant to keep behavior predictable.
## Practical Notes
- Under the legacy backend, **only three real modes** are used:
- `0` → off
- `1` → breath (with speed control)
- `3` → single color
- All the LVA **pulse** and **blink** variants are essentially **different speeds of `LED_EFFECT=1`**.
- The **spin** effect is not yet a genuine rotating animation on XVF3800; it’s a placeholder mapped onto existing firmware modes.
As we move toward **firmware v2.0.7+** and `LED_RING_COLOR` support, we’ll be able to implement richer, per‑LED patterns (including real spin and more accurate blink behaviors) while keeping the same high-level LVA effect names.