From f1d2700fac5c6e0bfcc6f96b85e44f9265c4f0f1 Mon Sep 17 00:00:00 2001
From: imonlinux <39863321+imonlinux@users.noreply.github.com>
Date: Wed, 10 Dec 2025 14:43:04 -0800
Subject: [PATCH] LED Effect Mapping

Background on LED effect mapping from XVF3800 to LVA LED effects.
---
 docs/xvf3800_legacy_led_effects_mapping.md | 45 ++++++++++++++++++++++
 1 file changed, 45 insertions(+)
 create mode 100644 docs/xvf3800_legacy_led_effects_mapping.md

diff --git a/docs/xvf3800_legacy_led_effects_mapping.md b/docs/xvf3800_legacy_led_effects_mapping.md
new file mode 100644
index 0000000..21e6b1e
--- /dev/null
+++ b/docs/xvf3800_legacy_led_effects_mapping.md
@@ -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.