Skip to content

Commit 327a342

Browse files
that1guythat1guy
authored
Merge pull request #162 from FutureProofHomes:smart-speaker-documentation-and-general-updates
Renamed page from /satellite1-support to /satellite1-faqs to keep the old alread-indexed url relevant.
2 parents 43f0325 + 14c5c25 commit 327a342

6 files changed

Lines changed: 160 additions & 299 deletions

‎docs/satellite1-faqs.md‎

Lines changed: 157 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,175 @@
1-
<a id="faq_anchor_factory_reset"></a>
2-
???+ note "I messed something up, how do I start over?"
1+
# Satellite1 FAQs
32

4-
1. [Remove the Sat1 from ESPHome](satellite1-troubleshooting.md/#removing-the-sat1-from-esphome)
5-
2. [Flash the device back to factory firmware.](satellite1-flash-via-usb-c.md)
3+
Common questions and step-by-step fixes in one place.
64

7-
<a id="faq_anchor_inspect_logs"></a>
8-
???+ note "How do I access the Sat1 logs?"
5+
## Wake Words & Voice
96

10-
[If you want to look at the logs, click here](/satellite1-troubleshooting/#inspecting-sat1-esp32-logs){ .md-button .md-button--primary }
7+
### What wake words are supported? { .faq-question }
8+
??? note "What wake words are supported?"
9+
The Satellite1 uses ESPHome's [microWakeWord](https://esphome.io/components/micro_wake_word.html) and supports **"Hey Jarvis"** and **"Okay Nabu"**.
1110

12-
<a id="faq_anchor_wake_words"></a>
13-
???+ note "What wake words are supported?"
14-
15-
The Satellite1 uses ESPHome's [microWakeWord](https://esphome.io/components/micro_wake_word.html) and supports the "Hey Jarvis" and "Okay Nabu" wake words.
11+
### How do I add other wake words? { .faq-question }
12+
??? note "How do I add other wake words?"
13+
[Modify and compile your own firmware](satellite1-modifying-the-firmware.md) to add compatible MicroWakeWords. We recommend [TaterTotterson's collection](https://github.com/TaterTotterson/microWakeWords).
1614

17-
<a id="faq_add_more_wake_words"></a>
18-
???+ note "How do I add other wake words to the Sat1?"
15+
### How do I create my own wake word? { .faq-question }
16+
??? note "How do I create my own wake word?"
17+
You'll need a GPU, sample data, and some know-how. We recommend TaterTotterson's trainers:
18+
- [microWakeWord-Trainer-Nvidia-Docker](https://github.com/TaterTotterson/microWakeWord-Trainer-Nvidia-Docker)
19+
- [microWakeWord-Trainer-AppleSilicon](https://github.com/TaterTotterson/microWakeWord-Trainer-AppleSilicon)
1920

20-
You'll need to [modify and compile your own Satellite1 firmware](/satellite1-modifying-the-firmware/) to add alternate compatible MicroWakeWords. We recommend TaterTotterson's collection:
21-
22-
1. https://github.com/TaterTotterson/microWakeWords
21+
### Why isn't the wake word responding? { .faq-question }
22+
??? note "Why isn't the wake word responding?"
23+
1. Try both "Okay Nabu" and "Hey Jarvis".
24+
2. Increase **Wake Word Sensitivity** in the Sat1 ESPHome device settings.
25+
3. Speak normally toward the microphones; don't shout.
26+
4. Keep microphones unobstructed. Avoid enclosed spots (e.g. inside a shelf) or very reflective rooms (e.g. marble floors).
27+
5. Detection can be harder for non-English accents or higher-pitched voices; consider training your own wake word (see above).
28+
6. Loud background noise (water, wind, TV, oven hoods) can interfere; XMOS firmware updates keep improving this.
29+
7. Still stuck? Try [adding or training a custom wake word](#how-do-i-create-my-own-wake-word) above.
2330

24-
<a id="faq_create_custom_wake_word"></a>
25-
???+ note "How do I create my own wake word?"
31+
---
2632

27-
You will need a GPU, knowledge, and sample data to train your own wake word. Enjoy the journey and share what you create. We recommend TaterTotterson's work:
28-
29-
1. https://github.com/TaterTotterson/microWakeWord-Trainer-Nvidia-Docker
30-
2. https://github.com/TaterTotterson/microWakeWord-Trainer-AppleSilicon
33+
## Audio Out & Playback
3134

32-
<a id="faq_anchor_wake_word_success"></a>
33-
???+ note "The wake word isn't always responding!"
34-
35-
1. Try both "Okay Nabu" and "Hey Jarvis" wake word.
36-
2. Increase the "Wake Word Sensitivity" setting in the Sat1 ESPHome Device settings.
37-
3. Speak normally. Project your voice in the direction of the microphones. Don't scream.
38-
4. Ensure the microphones are unobstructed and the device isn’t placed in an enclosed space (like a shelf) or in a room with highly reflective surfaces (such as marble floors) that can cause echoes.
39-
5. Wake word detection may be more challenging for non-English speakers with accents or for higher-pitched voices (such as some women and children), as the wake words are not specifically trained for these voice profiles. Read above to consider training your own wake word.
40-
6. Loud background noise—such as running water, wind, children shouting, oven hoods, or a TV—can significantly interfere with wake word detection, though XMOS firmware updates will continue to improve performance in these challenging conditions over time.
41-
7. Try creating your own wake word (See FAQ above)
35+
### Why don't I hear any audio? { .faq-question }
36+
??? note "Why don't I hear any audio?"
37+
Use the USB-C port on the HAT labeled **"CORE/ESP"**. The port labeled **"XMOS/SNDCARD"** is for XMOS development only and does not drive the amplifier. Check the **USB-C Power Draw** sensor in the Sat1 ESPHome UI; we recommend 30W of power.
38+
![usbc power draw](/assets/usb-c_power_draw.png){ width="100%" }
4239

43-
Still having issues? This will get better in time. We have lots of ideas to solve these problems.
40+
### Why does my speaker sound distorted? { .faq-question }
41+
??? note "Why does my speaker sound distorted?"
42+
The Sat1 is likely underpowered. Check the **USB-C Power Draw** sensor in the Sat1 ESPHome UI; you should see about 30W.
43+
![Underpowered Sat1](/assets/underpowered.png){ width="100%" }
4444

45-
<a id="faq_anchor_no_sound"></a>
46-
???+ note "Why don’t I hear any audio through the speaker?"
45+
### Why is my speaker too quiet? { .faq-question }
46+
??? note "Why is my speaker too quiet?"
47+
1. We recommend 30W of power. Check the **USB-C Power Draw** sensor in the Sat1 ESPHome UI.
48+
2. In Music Assistant: open the Sat1 speaker's Player Settings, disable **Enable volume normalization (EBU-R128 based)** and **Enable limiting to prevent clipping**, then increase gain in Music Assistant's DSP. [Details here](satellite1-streaming-music.md#start-the-snapcast-server).
49+
![usbc power draw](/assets/usb-c_power_draw.png){ width="100%" }
4750

48-
Ensure you're powering your Satellite1 using the USB-C port on the HAT labeled "CORE/ESP32".
49-
50-
The other USB-C port on the HAT labeled "XMOS/SNDCARD" is intended for XMOS development only and will not enable the amplifier.
51+
### Why is music or TTS stuttering? { .faq-question }
52+
??? note "Why is music or TTS stuttering?"
53+
1. Make sure your Sat1 has a [good WiFi connection](#how-do-i-check-wifi-connection).
54+
2. Try other TTS voices.
55+
3. Try streaming music from Music Assistant's media player section to rule out MA.
5156

52-
<a id="faq_anchor_distorted_sound"></a>
53-
???+ note "Why does my speaker sound crackly, distorted and possibly blown?"
57+
---
5458

55-
Your Sat1 is likely under-powered. Check your "USB-C Power Draw" Sensor in the Sat1's ESPHome UI. You should see approx. 30W of power.
59+
## Audio In & Microphones
5660

57-
<a id="faq_anchor_speaker_too_quiet"></a>
58-
???+ note "My Sat1 speaker is too quiet. I want more boom in my music!"
61+
### How do I inspect audio recordings? { .faq-question }
62+
??? note "How do I inspect audio recordings?"
63+
Store a copy of your audio recordings on the Home Assistant server for inspection:
5964

60-
1. Ensure your Sat1 is receiving at least 30W or more of power by checking the "USB-C Power Draw" sensor in its ESPHome UI.
61-
2. In Music Assistant, open the Sat1 speaker’s Player Settings, disable both "Enable volume normalization (EBU-R128 based)" and "Enable limiting to prevent clipping" checkboxes, then increase the gain in Music Assistant’s DSP [(read more here)](/satellite1-streaming-music/#start-the-snapcast-server).
65+
1. In Home Assistant, add to your `configuration.yaml`:
6266

63-
<a id="faq_anchor_report_issue"></a>
64-
???+ note "How do I get help or report issues?"
65-
Need further help or have suggestions for the product or documentation? Reach out!
67+
```yaml
68+
assist_pipeline:
69+
debug_recording_dir: /share/assist_pipeline
70+
```
6671

67-
[There are many ways to contact us, click here](/satellite1-troubleshooting/#need-more-help){ .md-button .md-button--primary }
72+
2. Open that path in Home Assistant (e.g. Studio Code Server) and listen to the files.
73+
3. Don't leave this on permanently; it will fill your server with recordings.
74+
75+
76+
---
77+
78+
## Networking
79+
80+
### How do I check WiFi connection? { .faq-question }
81+
??? note "How do I check WiFi connection?"
82+
The Sat1 includes a Wi-Fi Signal Strength sensor that should read between -30 dBm and -75 dBm. If the reading is lower than -75 dBm, your Sat1 may underperform. Move closer to the access point or upgrade to a Core Board with an external antenna.
83+
![WiFi Signal Strength](/assets/wifi_signal_strength.png){ width="100%" }
84+
85+
86+
### How do I switch to a new WiFi SSID or Password? { .faq-question }
87+
??? note "How do I switch to a new WiFi SSID or Password?"
88+
[Wipe the Sat1 and flash fresh firmware](#how-do-i-flash-back-to-factory-settings). Or just [wipe the credentials from the device](#how-do-i-clear-wifi-and-restart-ble-improv).
89+
90+
---
91+
92+
## LED Color Codes
93+
94+
### Why do my LEDs flash red after giving command? { .faq-question }
95+
??? note "Why do my LEDs flash red after giving command?"
96+
Something is wrong with your voice pipeline in HA. [Debug your voice pipeline.](#how-do-i-debug-the-voice-pipeline).
97+
98+
### Why are my LEDs twinkling red? { .faq-question }
99+
??? note "Why are my LEDs twinkling red?"
100+
Your Sat1 cannot connect to your Home Assistant/ESPHome. Typically a networking issue. [Check your WiFi connection.](#how-do-i-check-wifi-connection)
101+
102+
### What do all the LED color codes mean? { .faq-question }
103+
??? note "What do all the LED color codes mean?"
104+
We follow the same patterns as Nabu Casa. [Read more here.](https://support.nabucasa.com/hc/en-us/articles/25764604971421-Status-colors-of-the-LEDs-status-LEDs-on-Home-Assistant-Voice-Preview-Edition)
105+
106+
107+
108+
## Logs & Debugging
109+
110+
### How do I view Sat1 logs? { .faq-question }
111+
??? note "How do I view Sat1 logs?"
112+
1. Connect the Sat1 to your computer with a USB-C cable.
113+
2. Click the connect button below and select the correct JTAG device.
114+
3. Choose **Logs & Console**.
115+
116+
<div id="firmware-installer" markdown="1">
117+
<esp-web-install-button id="install-button" manifest="https://raw.githubusercontent.com/FutureProofHomes/Documentation/refs/heads/main/manifest.json" install-supported></esp-web-install-button>
118+
</div>
119+
120+
### How do I debug the voice pipeline? { .faq-question }
121+
??? note "How do I debug the voice pipeline?"
122+
In Home Assistant: **Settings → Voice Assistants**, click the 3-dot menu next to that pipeline. [Learn more here.](https://www.home-assistant.io/voice_control/troubleshooting/).
123+
124+
![Debugging a Voice Pipeline](/assets/debug_assist.png){ width="100%" loading=lazy }
125+
126+
---
127+
128+
## Factory Settings & Flashing Releases
129+
130+
### How do I completely remove the Sat1 from Home Assistant & ESPHome? { .faq-question }
131+
??? note "How do I completely remove the Sat1 from Home Assistant & ESPHome?"
132+
1. In Home Assistant: **Settings → Devices and Services → ESPHome** → 3 dots next to the Satellite1 → **Delete**.
133+
![Delete ESPHome device](/assets/delete_sat1_esp_device.png){ width="100%" }
134+
2. If you "Took Control" in ESPHome Device Builder: **Settings → Add-Ons → ESPHome Device Builder** → Open Web UI → 3 dots next to the Satellite1 → **Delete**.
135+
![Remove from ESPHome Builder](/assets/delete_sat1_from_esp_builder.png){ width="100%" }
136+
137+
### How do I flash back to factory settings? { .faq-question }
138+
??? note "How do I flash back to factory settings?"
139+
Connect your Sat1 to your computer and use our web flashing tool to [flash the device back to factory firmware](satellite1-flash-via-usb-c.md)
140+
141+
### How do I clear WiFi and restart BLE Improv? { .faq-question }
142+
??? note "How do I clear WiFi and restart BLE Improv?"
143+
1. Press and hold the **RIGHT (Action)** button for about 22 seconds until the red LEDs complete a clockwise circle. When the LEDs turn blue, release the button and wait while the XMOS chip is erased (may take a few minutes). The Satellite1 will reboot to factory firmware; blue LEDs will complete another clockwise circle as the XMOS is flashed.
144+
2. [Add your Satellite1 to Home Assistant](satellite1-connecting-to-ha.md).
145+
146+
### What if flashing is failing or Sat1 is blinking on and off? { .faq-question }
147+
??? note "What if flashing is failing or Sat1 is blinking on and off?"
148+
1. Unplug the Sat1 from power.
149+
2. **Remove the Core from the Hat board:** Hold the **Boot** button on the Core, then plug power into the USB-C port. Release Boot button after 3 seconds. Now try to [flash the Sat1 via USB-C](satellite1-flash-via-usb-c.md). Unplug and mount the Hat back to the Core board.
150+
![CORE BOOT Button](/assets/boot_mode_core_board.png){ width="100%" }
151+
3. **If you really don't want to remove the Core board:** Hold the **Right/Action** button on the HAT, then plug power into the HAT's **"ESP32/CORE"** USB-C port. Release the Action button after 3 seconds. Try to [flash the Sat1 via USB-C](satellite1-flash-via-usb-c.md).
152+
![HAT BOOT Button](/assets/right_action_button.jpg){ width="100%" }
153+
154+
### How do I update my Sat1? { .faq-question }
155+
??? note "How do I update my Sat1?"
156+
1. Updates are delivered over the air. Simply click the "Update Available" button. If you don't see an expected update, please restart your Sat1 and toggle the "Beta Firmware" switch.
157+
![Update available button](/assets/update_available.png){ width="100%" }
158+
2. You can also update from our [Web Flasher Tool](satellite1-flash-via-usb-c.md)
159+
160+
161+
## Need More Help?
162+
163+
While we hope this documentation will answer all your questions, we realize support is sometimes needed. The FutureProofHomes team will do their best to keep up with support requests, but we also lean on our community to help all of us. See the links below and decide which method of support is best for your needs.
164+
165+
!!! question "Have a general question and need quick help from the community?"
166+
167+
[Chat with the Community on Discord :fontawesome-brands-discord:](https://discord.futureproofhomes.net){ .md-button }
168+
169+
!!! success "Do you have a feature request or reproducible bug?"
170+
Look through our existing tickets first, then open a new request if necessary: <br>
171+
[Request a feature on GitHub :fontawesome-solid-rocket:](https://github.com/FutureProofHomes/Satellite1-ESPHome/issues/new?template=feature-request--.md){ .md-button }
172+
[Report a bug :fontawesome-solid-bug:](https://github.com/FutureProofHomes/Satellite1-ESPHome/issues/new?template=bug-report--.md){ .md-button }
173+
174+
!!! failure "Hardware issue or need direct support?"
175+
[Email Support@futureproofhomes.net :material-email:](mailto:Support@FutureProofHomes.net){ .md-button }

‎docs/satellite1-modifying-the-firmware.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ The firmware running on the Satellite1 is [open source](https://github.com/Futur
66
- Hide or show more logs for deep troubleshooting
77
- Change or extend the core functionality in any way you desire.
88

9-
??? warning "After taking control of your device's firmware you will no longer receive official firmware updates. If you'd like to get back in sync with the official Sat1 firmware you'll need to [restore factory firmware back to the Sat1](/satellite1-faqs#faq_anchor_factory_reset)."
9+
??? warning "After taking control of your device's firmware you will no longer receive official firmware updates. If you'd like to get back in sync with the official Sat1 firmware you'll need to [restore factory firmware back to the Sat1](satellite1-flash-via-usb-c.md)."
1010

1111
??? warning "Please also be aware that flashing custom firmware can potentially damage the Sat1 device. These instructions are provided with the understanding that you have the necessary expertise to proceed. We will assume a certain level of familiarity with the process. Proceed with caution, and enjoy the journey!"
1212

‎docs/satellite1-set-up-voice-control.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ That's a voice pipeline. It's the backbone of any voice assistant. Each step in
3333
2. **In the Configuration section, select your Voice Pipeline.**
3434
<br>![Assistant Dropdown](/assets/Pipeline5.png){ width="100%" loading=lazy }
3535

36-
3. **You can also set your preferred wake word. (NOTE: If you want to build your own custom wake word, then [read here](/satellite1-faqs/#faq_add_more_wake_words))**
36+
3. **You can also set your preferred wake word. (NOTE: If you want to build your own custom wake word, then [read here](/satellite1-faqs/#how-do-i-add-other-wake-words))**
3737
<br>![Set Wake Word](/assets/Pipeline7.png){ width="100%" loading=lazy }
3838

3939
Congratulations! You've created your own voice pipeline for your Satellite1. Read below to expose the device you want to control to your voice assistant and build even more advanced voice pipelines.

0 commit comments

Comments
 (0)