Skip to content

Commit 9091ef5

Browse files
troyhackstroyhacks
authored
Add DF2301Q voice control usermod documentation
Documented the DF2301Q voice control usermod for WLED, including hardware requirements, wiring, usage instructions, configuration options, command mappings, troubleshooting tips, and licensing information.
1 parent 29d3c94 commit 9091ef5

1 file changed

Lines changed: 198 additions & 0 deletions

File tree

‎docs/usermods/DF2301Q.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# DF2301Q Voice Control Usermod
2+
3+
Voice control for WLED using the DFRobot DF2301Q offline voice recognition module.
4+
5+
## Hardware Requirements
6+
7+
- **DF2301Q Voice Recognition Module** [DFRobot SKU: SEN0539](https://www.dfrobot.com/product-2665.html)
8+
- I2C connection to your ESP32/ESP8266
9+
10+
## Wiring
11+
12+
Connect the DF2301Q to your board's I2C bus:
13+
14+
| DF2301Q | ESP Board |
15+
|---------|-----------|
16+
| VCC | 3.3V or 5V |
17+
| GND | GND |
18+
| SDA (or D/T) | I2C SDA |
19+
| SCL (or C/R) | I2C SCL |
20+
21+
Configure your global I2C pins in WLED's LED Preferences before enabling this usermod.
22+
23+
## Usage
24+
25+
1. Say **"Hello Robot"** (or your custom wake word) to wake the module
26+
2. Give a voice command within the wake time window
27+
3. Each recognized command resets the wake timer, allowing multiple commands in sequence
28+
4. If you want this to work with "Sync" for controlling all your WLED devices, enable "Send notifications on button press or IR" in the Sync menu.
29+
30+
## Configuration
31+
32+
All settings are available in WLED's Config > Usermods > DF2301Q section.
33+
34+
### General Settings
35+
36+
| Setting | Default | Description |
37+
|---------|---------|-------------|
38+
| Enabled | Off | Enable/disable the usermod |
39+
| Volume | 10 | Speaker volume (0-20, higher values may distort) |
40+
| Wake Time | 20 | Seconds the module listens after wake word |
41+
| Poll Interval | 50 | Milliseconds between voice command checks |
42+
| Startup Sound | 2 | Phrase spoken when WLED starts (0=disabled, 1="Yes, I'm here", 2="How can I help?") |
43+
44+
NOTE: If your startup sound is 1, the module will start in listening mode until it times out.
45+
46+
### Command Mappings
47+
48+
Map DF2301Q voice commands to WLED actions. Set to 0 to disable any mapping.
49+
50+
| Setting | Default | Default Phrase |
51+
|---------|---------|----------------|
52+
| Power On | 103 | "Turn on the light" |
53+
| Power Off | 104 | "Turn off the light" |
54+
| Brightness Up | 105 | "Brighten the light" |
55+
| Brightness Down | 106 | "Dim the light" |
56+
| Next Preset | 95 | "The next track" |
57+
| Previous Preset | 94 | "The last track" |
58+
| Next Effect | 0 | Disabled |
59+
| Previous Effect | 0 | Disabled |
60+
61+
### Feature Toggles
62+
63+
| Setting | Default | Description |
64+
|---------|---------|-------------|
65+
| Numbered Presets | Off | Enable "Display number [0-9]" commands for presets 1-10 |
66+
| Color Commands | Off | Enable "Set to [color]" commands for solid colors |
67+
| Voice Feedback | Off | Module speaks back the recognized command |
68+
69+
NOTE: Numbered presets are 1..9 and 0 is mapped to 10 as we don't allow "0" as a preset number.
70+
71+
## Voice Commands Reference
72+
73+
### Default Built-in Commands (Always Available)
74+
75+
| Command ID | Voice Phrase |
76+
|------------|--------------|
77+
| 1 | "Hello Robot" (default wake word) |
78+
| 2 | Custom wake word |
79+
| 103 | "Turn on the light" |
80+
| 104 | "Turn off the light" |
81+
| 105 | "Brighten the light" |
82+
| 106 | "Dim the light" |
83+
| 107 | "Adjust brightness to maximum" |
84+
| 108 | "Adjust brightness to minimum" |
85+
| 94 | "The last track" |
86+
| 95 | "The next track" |
87+
88+
### Numbered Presets (When Enabled)
89+
90+
| Command ID | Voice Phrase | WLED Preset |
91+
|------------|--------------|-------------|
92+
| 53 | "Display number one" | Preset 1 |
93+
| 54 | "Display number two" | Preset 2 |
94+
| 55 | "Display number three" | Preset 3 |
95+
| 56 | "Display number four" | Preset 4 |
96+
| 57 | "Display number five" | Preset 5 |
97+
| 58 | "Display number six" | Preset 6 |
98+
| 59 | "Display number seven" | Preset 7 |
99+
| 60 | "Display number eight" | Preset 8 |
100+
| 61 | "Display number nine" | Preset 9 |
101+
| 52 | "Display number zero" | Preset 10 |
102+
103+
### Solid Color Commands (When Enabled)
104+
105+
These will set every LED to this color.
106+
107+
| Command ID | Voice Phrase | Color |
108+
|------------|--------------|-------|
109+
| 116 | "Set to red" | Red |
110+
| 117 | "Set to orange" | Orange |
111+
| 118 | "Set to yellow" | Yellow |
112+
| 119 | "Set to green" | Green |
113+
| 120 | "Set to cyan" | Cyan |
114+
| 121 | "Set to blue" | Blue |
115+
| 122 | "Set to purple" | Purple |
116+
| 123 | "Set to white" | White |
117+
118+
NOTE: You can edit the usermod to fill in more of the preset commands, but at some point it's too big for the JSON buffer and will fail to setup the usermod page.
119+
120+
### Custom Commands
121+
122+
The DF2301Q supports custom voice commands (IDs 5-21) that can be trained using the DFRobot Voice Configuration Tool. Map these to any WLED action using the command mapping settings.
123+
124+
| Command ID | Slot |
125+
|------------|------|
126+
| 5-21 | Custom Commands 1-17 |
127+
128+
NOTE: Learn how to train your custom wake-phrase and custom commands here: [Command Words and Training](https://wiki.dfrobot.com/SKU_SEN0539-EN_Gravity_Voice_Recognition_Module_I2C_UART#Command%20Words)
129+
130+
## Hot-Plug Support
131+
132+
The usermod includes automatic recovery for disconnected modules:
133+
134+
- If the module is not detected at startup, it will retry every 5 seconds
135+
- If the module disconnects during operation, it will automatically reconnect when available
136+
- No reboot required for hot-plug scenarios
137+
138+
## Status Display
139+
140+
The WLED Info page shows:
141+
142+
- Module detection status
143+
- Last received command ID
144+
- Current volume and wake time settings
145+
146+
## Compilation
147+
148+
Add to your `platformio_override.ini`:
149+
150+
```ini
151+
[env:your_env]
152+
extends = env:esp32dev
153+
build_flags = ${env:esp32dev.build_flags}
154+
-D USERMOD_VOICE_CONTROL
155+
```
156+
157+
Or include in your `my_config.h` file with:
158+
159+
```cpp
160+
#define USERMOD_VOICE_CONTROL
161+
```
162+
163+
## Troubleshooting
164+
165+
### Module Not Detected
166+
167+
1. Ensure the module is in **I2C mode** via the switch on the module.
168+
2. Verify I2C pins are configured in WLED's LED Preferences
169+
3. Check wiring connections
170+
4. Ensure the module is powered (3.3V and 5V tolerant)
171+
5. Check serial output (if available) for error messages
172+
173+
### Commands Not Recognized
174+
175+
1. Speak clearly and at a normal pace
176+
2. Ensure you've said the wake word first
177+
3. Check that the command mapping isn't set to 0 (disabled)
178+
4. Increase wake time if commands timeout too quickly
179+
180+
### No Audio Output
181+
182+
1. Check speaker connection to the DF2301Q module and the speaker switch, depending on the board version.
183+
2. Increase volume setting (default is 10)
184+
3. Enable Voice Feedback option to test audio
185+
186+
### My Google Home/Alexa/Home Assistant is answering too!
187+
188+
1. Change your custom wake-phrase to something not close to your other devices.
189+
2. Disable "no wake word needed" on those devices. Some answer to "turn off the lights" without a wake-phrase if enabled, for example.
190+
191+
## License
192+
193+
Licensed under the EUPL-1.2 or later.
194+
195+
## Credits
196+
197+
- Developed for MoonModules WLED by @TroyHacks
198+
- Uses a stripped down version of the DFRobot DF2301Q library

0 commit comments

Comments
 (0)