# respeaker/usb_4_mic_array architecture

> Architecture diagram of the GitHub repository respeaker/usb_4_mic_array, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/respeaker/usb_4_mic_array
- Repository: https://github.com/respeaker/usb_4_mic_array

## Overview

This repository is a support/tooling repo for the ReSpeaker USB 4 Mic Array hardware, not a single application. Its core architecture is a set of host-side Python utilities plus bundled firmware images that interact with a USB audio/DSP device.

1. **Main hardware boundary**
   The device is the ReSpeaker USB 4 Mic Array itself. It exposes USB audio plus separate device functions for firmware update and control. The on-device DSP provides AEC, VAD, DOA, beamforming, noise suppression, and LED control.

2. **Firmware assets**
   The root `.bin` files and the `MicArrayV3_firmware/` directory contain prebuilt firmware images for different operating modes:
   - **1-channel firmware**: processed audio intended for ASR
   - **6-channel firmware**: one processed channel plus raw mic channels and playback
   These files are the primary artifacts flashed onto the hardware.

3. **Firmware update path**
   `dfu.py` is the main DFU utility for flashing firmware over USB DFU. It uses `pyusb` as the host-side transport layer. `dfu_windows.py` is the Windows-specific counterpart for the same DFU workflow.

4. **Platform/driver boundary**
   On Linux and macOS, audio works without special driver installation. On Windows, the repo requires `libusb-win32` via Zadig for the non-audio USB interfaces used by firmware upgrade and LED/control access. Audio playback/recording still uses the normal audio path.

5. **DSP parameter tuning**
   `tuning.py` is a host-side configuration tool for changing built-in DSP parameters in the firmware image or device configuration. The README shows it being used to toggle settings like AGC and to enumerate available parameters.

6. **Audio processing and verification**
   The `test/` folder contains small diagnostic scripts:
   - `echo.py` for echo-related behavior
   - `kws.py` for keyword spotting
   - `player.py` for playback
   - `rms.py` for signal level measurement
   - `pocketsphinx-data/` and `respeaker.wav` as sample data for speech/audio tests
   These are validation tools for confirming the device’s acoustic pipeline.

7. **Realtime localization integration**
   `odas.cfg` is configuration for ODAS, an external sound-source localization/tracking system. In the 6-channel firmware mode, the device provides raw mic channels that ODAS can consume as a soundcard input for localization and tracking.

8. **LED control is externalized**
   The README points to `pixel_ring` for RGB LED control rather than implementing a full LED stack here. This repo’s role is to document the device protocol and provide firmware/control entry points, while the actual LED API lives elsewhere.

9. **Repository shape**
   `requirements.txt` defines the Python dependency surface for the utilities, while `.gitmodules` suggests at least one external submodule dependency. The repo is therefore a thin host-tool layer around vendor hardware, firmware blobs, and external audio/diagnostic ecosystems.

10. **Typical data flow**
   The main flow is: host PC runs Python tools → USB DFU/control/audio interfaces → ReSpeaker hardware firmware/DSP → audio capture, playback, LED effects, or firmware reprogramming. For ODAS, the flow extends from the device’s 6-channel audio output into an external localization engine.

11. **Architectural takeaway for diagramming**
   Draw this as a hardware-centered system with three host-side concerns: firmware management, DSP tuning/control, and test/integration utilities. The device is the central runtime; the repo mostly supplies artifacts and scripts that configure or exercise it.

Main entry points: [`requirements.txt`](https://github.com/respeaker/usb_4_mic_array/blob/master/requirements.txt) (requirements.txt), [`test/respeaker.wav`](https://github.com/respeaker/usb_4_mic_array/blob/master/test/respeaker.wav) (Test data), [`tuning.py`](https://github.com/respeaker/usb_4_mic_array/blob/master/tuning.py) (tuning.py), [`test/echo.py`](https://github.com/respeaker/usb_4_mic_array/blob/master/test/echo.py) (echo.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_hardware["Hardware boundary"]
  node_device{{"ReSpeaker 4 Mic<br/>USB audio/DSP device"}}
  node_dsp(("On-device DSP<br/>audio processing"))
  node_usb_audio["Audio iface<br/>USB audio stream"]
  node_usb_control["Control iface<br/>USB control path"]
  node_dfu_iface["DFU iface<br/>firmware update path"]
end

subgraph group_firmware["Firmware assets"]
  node_firmware_1ch["1-ch image<br/>firmware blob"]
  node_firmware_6ch["6-ch image<br/>firmware blob"]
  node_micarray_fw_1ch["DFU 1-ch<br/>firmware blob"]
  node_micarray_fw_6ch["DFU 6-ch<br/>firmware blob"]
end

subgraph group_host_tools["Host tools"]
  node_dfu_py["dfu.py<br/>flash utility<br/>[dfu.py]"]
  node_dfu_win["dfu_windows.py<br/>flash utility<br/>[dfu_windows.py]"]
  node_tuning["tuning.py<br/>DSP config tool<br/>[tuning.py]"]
end

subgraph group_validation["Validation"]
  node_echo_test["echo.py<br/>diagnostic script<br/>[echo.py]"]
  node_kws_test["kws.py<br/>diagnostic script<br/>[kws.py]"]
  node_player_test["player.py<br/>diagnostic script<br/>[player.py]"]
  node_rms_test["rms.py<br/>diagnostic script<br/>[rms.py]"]
  node_sample_data["Test data<br/>audio/speech assets<br/>[respeaker.wav]"]
end

subgraph group_integration["External integration"]
  node_odas_cfg["odas.cfg<br/>ODAS config<br/>[odas.cfg]"]
  node_requirements["requirements.txt<br/>python deps<br/>[requirements.txt]"]
  node_pixel_ring["pixel_ring<br/>external LED lib"]
end

node_device -->|"runs"| node_dsp
node_device -->|"exposes"| node_usb_audio
node_device -->|"exposes"| node_usb_control
node_device -->|"exposes"| node_dfu_iface
node_dfu_py -->|"flashes"| node_dfu_iface
node_dfu_win -->|"flashes"| node_dfu_iface
node_tuning -->|"configures"| node_usb_control
node_tuning -->|"adjusts"| node_dsp
node_firmware_1ch -->|"flashed to"| node_device
node_firmware_6ch -->|"flashed to"| node_device
node_micarray_fw_1ch -->|"bundled for"| node_device
node_micarray_fw_6ch -->|"bundled for"| node_device
node_odas_cfg -->|"consumes"| node_usb_audio
node_player_test -->|"exercises"| node_usb_audio
node_echo_test -->|"exercises"| node_usb_audio
node_kws_test -->|"exercises"| node_usb_audio
node_rms_test -->|"measures"| node_usb_audio
node_sample_data -.->|"supports"| node_player_test
node_sample_data -.->|"supports"| node_echo_test
node_sample_data -.->|"supports"| node_kws_test
node_sample_data -.->|"supports"| node_rms_test
node_pixel_ring -.->|"implements"| node_usb_control
node_requirements -.->|"supports"| node_dfu_py
node_requirements -.->|"supports"| node_tuning
node_requirements -.->|"supports"| node_echo_test
node_requirements -.->|"supports"| node_kws_test
node_requirements -.->|"supports"| node_player_test
node_requirements -.->|"supports"| node_rms_test

click node_firmware_1ch "https://github.com/respeaker/usb_4_mic_array/blob/master/1_channel_firmware.bin"
click node_firmware_6ch "https://github.com/respeaker/usb_4_mic_array/blob/master/6_channels_firmware.bin"
click node_micarray_fw_1ch "https://github.com/respeaker/usb_4_mic_array/blob/master/MicArrayV3_firmware/1_channel_dfu_4.0.0_firmware.bin"
click node_micarray_fw_6ch "https://github.com/respeaker/usb_4_mic_array/blob/master/MicArrayV3_firmware/6_channels_dfu_4.0.0_firmware.bin"
click node_dfu_py "https://github.com/respeaker/usb_4_mic_array/blob/master/dfu.py"
click node_dfu_win "https://github.com/respeaker/usb_4_mic_array/blob/master/dfu_windows.py"
click node_tuning "https://github.com/respeaker/usb_4_mic_array/blob/master/tuning.py"
click node_echo_test "https://github.com/respeaker/usb_4_mic_array/blob/master/test/echo.py"
click node_kws_test "https://github.com/respeaker/usb_4_mic_array/blob/master/test/kws.py"
click node_player_test "https://github.com/respeaker/usb_4_mic_array/blob/master/test/player.py"
click node_rms_test "https://github.com/respeaker/usb_4_mic_array/blob/master/test/rms.py"
click node_sample_data "https://github.com/respeaker/usb_4_mic_array/blob/master/test/respeaker.wav"
click node_odas_cfg "https://github.com/respeaker/usb_4_mic_array/blob/master/odas.cfg"
click node_requirements "https://github.com/respeaker/usb_4_mic_array/blob/master/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_device,node_dsp,node_usb_audio,node_usb_control,node_dfu_iface toneBlue
class node_firmware_1ch,node_firmware_6ch,node_micarray_fw_1ch,node_micarray_fw_6ch toneAmber
class node_dfu_py,node_dfu_win,node_tuning toneMint
class node_echo_test,node_kws_test,node_player_test,node_rms_test,node_sample_data toneRose
class node_odas_cfg,node_requirements,node_pixel_ring toneIndigo
```

## Components

### Hardware boundary

The ReSpeaker USB 4 Mic Array device and its on-device DSP/audio interfaces.

- **ReSpeaker 4 Mic**: USB audio/DSP device · Central hardware target with audio, control, and DFU-facing interfaces.
- **On-device DSP**: audio processing · Performs AEC, VAD, DOA, beamforming, noise suppression, and LED-related control.
- **Audio iface**: USB audio stream · Normal playback/recording path exposed by the device.
- **Control iface**: USB control path · Non-audio USB interface used for device control and LED access.
- **DFU iface**: firmware update path · USB DFU path used to flash firmware images onto the device.

### Firmware assets

Prebuilt firmware images bundled for flashing different operating modes.

- [1-ch image](https://github.com/respeaker/usb_4_mic_array/blob/master/1_channel_firmware.bin): firmware blob · Processed-audio firmware for ASR-style use cases. · `1_channel_firmware.bin`
- [6-ch image](https://github.com/respeaker/usb_4_mic_array/blob/master/6_channels_firmware.bin): firmware blob · Firmware exposing one processed channel plus raw mic channels and playback. · `6_channels_firmware.bin`
- [DFU 1-ch](https://github.com/respeaker/usb_4_mic_array/blob/master/MicArrayV3_firmware/1_channel_dfu_4.0.0_firmware.bin): firmware blob · Versioned 1-channel firmware image in the MicArrayV3 bundle. · `MicArrayV3_firmware/1_channel_dfu_4.0.0_firmware.bin`
- [DFU 6-ch](https://github.com/respeaker/usb_4_mic_array/blob/master/MicArrayV3_firmware/6_channels_dfu_4.0.0_firmware.bin): firmware blob · Versioned 6-channel firmware image in the MicArrayV3 bundle. · `MicArrayV3_firmware/6_channels_dfu_4.0.0_firmware.bin`

### Host tools

Python utilities used for firmware update, tuning, and device interaction.

- [dfu.py](https://github.com/respeaker/usb_4_mic_array/blob/master/dfu.py): flash utility · Main host-side DFU flashing script over USB. · `dfu.py`
- [dfu_windows.py](https://github.com/respeaker/usb_4_mic_array/blob/master/dfu_windows.py): flash utility · Windows-specific DFU workflow counterpart. · `dfu_windows.py`
- [tuning.py](https://github.com/respeaker/usb_4_mic_array/blob/master/tuning.py): DSP config tool · Host-side tool for reading and changing built-in DSP parameters. · `tuning.py`

### Validation

Diagnostics and audio test scripts plus sample data.

- [echo.py](https://github.com/respeaker/usb_4_mic_array/blob/master/test/echo.py): diagnostic script · Echo-related validation script. · `test/echo.py`
- [kws.py](https://github.com/respeaker/usb_4_mic_array/blob/master/test/kws.py): diagnostic script · Keyword spotting validation script. · `test/kws.py`
- [player.py](https://github.com/respeaker/usb_4_mic_array/blob/master/test/player.py): diagnostic script · Playback validation script. · `test/player.py`
- [rms.py](https://github.com/respeaker/usb_4_mic_array/blob/master/test/rms.py): diagnostic script · Signal-level measurement script. · `test/rms.py`
- [Test data](https://github.com/respeaker/usb_4_mic_array/blob/master/test/respeaker.wav): audio/speech assets · Sample audio and speech data used by the diagnostic scripts. · `test/respeaker.wav`

### External integration

External configuration and dependency boundaries around the repo.

- [odas.cfg](https://github.com/respeaker/usb_4_mic_array/blob/master/odas.cfg): ODAS config · Configuration for external sound-source localization and tracking. · `odas.cfg`
- [requirements.txt](https://github.com/respeaker/usb_4_mic_array/blob/master/requirements.txt): python deps · Dependency surface for the host-side Python utilities. · `requirements.txt`
- **pixel_ring**: external LED lib · External RGB LED control library referenced by the repo.

## Connections

- ReSpeaker 4 Mic → On-device DSP: runs · The hardware hosts the on-device DSP pipeline.
- ReSpeaker 4 Mic → Audio iface: exposes · Standard audio capture/playback interface.
- ReSpeaker 4 Mic → Control iface: exposes · Device control and LED access interface.
- ReSpeaker 4 Mic → DFU iface: exposes · Firmware update interface over USB DFU.
- dfu.py → DFU iface: flashes · Primary host-side updater talks to DFU over USB.
- dfu_windows.py → DFU iface: flashes · Windows-specific updater uses the same DFU path.
- tuning.py → Control iface: configures · Reads and changes DSP/device parameters through the device interface.
- tuning.py → On-device DSP: adjusts · Targets built-in DSP settings such as AGC and related parameters.
- 1-ch image → ReSpeaker 4 Mic: flashed to · Primary firmware artifact for the hardware.
- 6-ch image → ReSpeaker 4 Mic: flashed to · Primary 6-channel firmware artifact for the hardware.
- DFU 1-ch → ReSpeaker 4 Mic: bundled for · Versioned image distributed for flashing.
- DFU 6-ch → ReSpeaker 4 Mic: bundled for · Versioned image distributed for flashing.
- odas.cfg → Audio iface: consumes · ODAS consumes the 6-channel audio output as input.
- player.py → Audio iface: exercises · Playback diagnostics validate the audio path.
- echo.py → Audio iface: exercises · Echo tests validate acoustic behavior through the audio path.
- kws.py → Audio iface: exercises · Keyword spotting tests validate the speech pipeline.
- rms.py → Audio iface: measures · Measures signal level from the audio stream.
- Test data → player.py: supports · Sample audio used by playback and speech diagnostics.
- Test data → echo.py: supports · Sample audio used by playback and speech diagnostics.
- Test data → kws.py: supports · Sample audio used by playback and speech diagnostics.
- Test data → rms.py: supports · Sample audio used by playback and speech diagnostics.
- pixel_ring → Control iface: implements · LED API is externalized to the pixel_ring library.
- requirements.txt → dfu.py: supports · Defines Python dependency surface for the tools.
- requirements.txt → tuning.py: supports · Defines Python dependency surface for the tools.
- requirements.txt → echo.py: supports · Defines Python dependency surface for diagnostics.
- requirements.txt → kws.py: supports · Defines Python dependency surface for diagnostics.
- requirements.txt → player.py: supports · Defines Python dependency surface for diagnostics.
- requirements.txt → rms.py: supports · Defines Python dependency surface for diagnostics.
