respeaker 0.3.0

USB control library for Seeed ReSpeaker Mic Array v2.0 and XVF3800 (LEDs + DSP tuning), with reSpeaker Lite identification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

# respeaker

Rust USB control library for Seeed ReSpeaker microphone arrays:

| Model | USB ID | Protocol |
|-------|--------|----------|
| [Mic Array v2.0](https://wiki.seeedstudio.com/ReSpeaker_Mic_Array_v2.0/) (XVF-3000) | `2886:0018` | [`pixel_ring`](https://github.com/respeaker/pixel_ring) + [`tuning.py`](https://github.com/respeaker/usb_4_mic_array) |
| [XVF3800](https://wiki.seeedstudio.com/respeaker_xvf3800_introduction/) | `2886:001a` | Seeed [`xvf_host.py`](https://github.com/respeaker/reSpeaker_XVF3800_USB_4MIC_ARRAY) |

## Example

```rust
use respeaker::{Model, ReSpeaker};

fn main() -> respeaker::Result<()> {
    // Auto-detect first supported device (v2, XVF3800 or Lite):
    let dev = ReSpeaker::open()?;
    // Or force a model:
    // let dev = ReSpeaker::open_model(Model::Xvf3800)?;

    println!("model: {}", dev.model());
    dev.led().off()?;
    println!("DOA: {}°  voice={}", dev.tuning().doa_angle()?, dev.tuning().is_voice()?);
    Ok(())
}
```

Unified helpers (`led()`, `tuning().doa_angle()`, `is_voice()`, `version_string()`) work on the two controllable models. Model-specific APIs:

- Mic Array v2: `dev.pixel_ring()`, `tuning().read("AGCONOFF")`
- XVF3800: `dev.xvf3800()`, `tuning().read_xvf("DOA_VALUE")`, `save_configuration()`
- reSpeaker Lite: `dev.lite()` — `firmware_version()`, `product_name()`, `serial_number()`

## reSpeaker Lite

The Lite is detected and identified (`Model::Lite`, `dev.lite()`, and
`tuning().version_string()` reads the firmware version from `bcdDevice`), but it
cannot be controlled over USB. Its USB firmware presents a UAC2 sound card plus a
DFU interface and answers no vendor control transfers — verified against firmware
2.0.5, where every `xvf_host`-style and Mic Array v2-style request STALLs. LEDs,
DoA/VAD and DSP parameters therefore return `Error::Unsupported`, and
`Model::has_usb_control()` reports `false`.

On-board DSP control is the XMOS command transport over **I2C** (device address
`0x42`, resource id 240 for DFU and 241 for configuration), which needs an I2C
master such as a Raspberry Pi or a XIAO ESP32S3 rather than a USB host. Firmware
updates go over the USB DFU interface with Seeed's `xmosdfu` tool.

### CLI example

```bash
cargo run --example cli -- model
cargo run --example cli -- test-all
cargo run --example cli -- --model xvf3800 led mono --color ff8800
cargo run --example cli -- --model xvf3800 led effect rainbow
cargo run --example cli -- param get DOA_VALUE
cargo run --example cli -- param set LED_COLOR 0xff8800
cargo run --example cli -- param set LED_DOA_COLOR 0x202020 0x00ff00
cargo run --example cli -- save-config
cargo run --example cli -- --model lite model
```

## Permissions (Linux)

```bash
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2886", ATTR{idProduct}=="0018", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="2886", ATTR{idProduct}=="0019", MODE="0666"
SUBSYSTEM=="usb", ATTR{idVendor}=="2886", ATTR{idProduct}=="001a", MODE="0666"' \
  | sudo tee /etc/udev/rules.d/60-respeaker.rules
sudo udevadm control --reload-rules && sudo udevadm trigger
```

On macOS, grant the binary access if the system claims the USB device, or run with appropriate privileges.