Skip to content

Commit 81e2508

Browse files
klaasnicolaasklaasnicolaas
committed
Add Docusaurus docs website
1 parent 8d6d750 commit 81e2508

39 files changed

+17575
-0
lines changed

‎docs/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎docs/blog/2024-10-22-placeholder.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
slug: placeholder
3+
title: Placeholder
4+
authors: klaas
5+
tags: [onju voice, release, update]
6+
---
7+
8+
This is a placeholder for the release notes of the next release. The release notes will be added here once the release is published.
9+
10+
<!-- truncate -->

‎docs/blog/authors.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
klaas:
2+
name: Klaas Schoute
3+
title: Community member of Home Assistant
4+
url: https://github.com/klaasnicolaas
5+
image_url: https://github.com/klaasnicolaas.png
6+
7+
tetele:
8+
name: Tudor Sandu
9+
title: Creator of the ESPHome config for the Onju Voice
10+
url: https://github.com/tetele
11+
image_url: https://github.com/tetele.png

‎docs/docs/advanced/firmware_customization.mdx‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
id: firmware_customization
3+
title: Customizing the firmware
4+
description: How to adopt and customize the firmware for your own needs.
5+
---
6+
7+
The Onju Voice Satellite's firmware is built on [ESPHome](https://esphome.io), a platform
8+
designed for customization through simple YAML configurations. Whether you need to tweak
9+
the device's functionality or adapt it for different use cases, the process is straightforward.
10+
This guide will walk you through how to adopt the device and customize its firmware using
11+
the [ESPHome Dashboard](https://esphome.io/guides/getting_started_hassio.html).
12+
13+
## Adopting the Device
14+
15+
Before making any changes to the firmware, you first need to adopt the device into the ESPHome.
16+
Once your ESPHome Dashboard is up and running, and the Onju Voice Satellite is connected to your
17+
local network, you should see an option to adopt it.
18+
19+
<p align="left">
20+
<img src={require('@site/static/img/customization/adopt-esphome.png').default} />
21+
</p>
22+
23+
Following the adoption steps will automatically:
24+
25+
1. Create a unique ESPHome configuration file for your device.
26+
2. Set up a secure API encryption key, allowing communication between Home Assistant and your device.
27+
3. Embed your Wi-Fi credentials directly into the firmware, enabling automatic reconnections.
28+
4. Upload the customized firmware onto the Onju Voice Satellite.

‎docs/docs/configuration.mdx‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
id: configuration
3+
title: Configuration
4+
---
5+
6+
## Changing the Device Name
7+
8+
When you first add your device to Home Assistant, it's assigned a default name like `onju-voice-satellite-XXXXXX`,
9+
where `XXXXXX` is a portion of the device's MAC address. While functional, this default name isn't very user-friendly
10+
or descriptive, especially if you have multiple devices. Renaming it to something more meaningful helps with organization
11+
and makes it easier to recognize within your smart home setup.
12+
13+
### How to Rename Your Device
14+
15+
To change the name of your device, follow these steps:
16+
17+
1. Open the Home Assistant user interface.
18+
2. Navigate to **Settings** > **Devices & Services**.
19+
3. Under the **ESPHome** section, find and select your device. If you have multiple devices, you may need to identify it by its current name (the default format described earlier).
20+
21+
Alternatively, you can click the badge below to be taken directly to the ESPHome devices overview page:
22+
23+
[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)][esphome-devices]
24+
25+
4. Once on the device's page, locate the pencil icon in the top-right corner. Clicking this icon will allow you to edit the device name.
26+
5. Enter your preferred name, something that reflects the purpose or location of the device (e.g., “Onju Voice” or “Satellite”). This will help you easily identify it later.
27+
6. Click **Update** to apply the changes and save the new name.
28+
29+
<p align="left">
30+
<img src={require('@site/static/img/configuration/rename-device.png').default} />
31+
</p>
32+
33+
### Renaming Entity IDs (Optional)
34+
35+
After renaming the device, Home Assistant may prompt you to rename the associated entity IDs as well. Entity IDs are used to reference your device in automations, dashboards, and other parts of Home Assistant.
36+
37+
- **If you haven't created any automations or dashboards yet**: It's generally a good idea to rename the entity IDs to match the new device name. This makes them easier to recognize and use in future configurations.
38+
- **If you already have automations or dashboards**: You may want to keep the existing entity IDs if they are already used in various setups. Renaming the entity IDs will require you to update those configurations to reference the new names. In this case, you can opt to change only the device name and leave the entity IDs as they are.
39+
40+
## Related links
41+
42+
- [Home Assistant - Terminology](https://home-assistant.io/getting-started/concepts-terminology)
43+
44+
[esphome-devices]: https://my.home-assistant.io/redirect/integration/?domain=esphome

‎docs/docs/faq/faq_nr1.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
id: placeholder
3+
title: placeholder
4+
description: placeholder
5+
---

‎docs/docs/getting-started.mdx‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
id: getting-started
3+
title: Getting Started
4+
description: 'Instructions how to get started with the Onju Voice Satellite'
5+
---
6+
7+
import Tabs from '@theme/Tabs';
8+
import TabItem from '@theme/TabItem';
9+
import ESPHomeButton from '@site/src/components/ESPWebTools';
10+
import { faUsb } from '@fortawesome/free-brands-svg-icons';
11+
12+
# Get started
13+
14+
This guide will walk you through the steps needed to set up your Onju Voice PCB with ESPHome. You'll go through the steps of replacing the PCB in the Google Nest mini V2, installing the necessary software, and configuring the settings to get everything up and running smoothly.
15+
16+
## Step 1: Install firmware
17+
18+
Use the method below to provide your Onju Voice PCB with the correct firmware.
19+
20+
<Tabs>
21+
<TabItem value="usb" label={<><icon icon={faUsb} size="lg"/> USB</>}>
22+
23+
_Make sure this page is opened in a Chromium-based browser on a desktop. The software installation does not work with a tablet or phone._
24+
25+
:::note
26+
If your device does not appear in the list, make sure you are using a USB data cable (i.e., not power-only), and try installing the [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers?tab=downloads) for the serial chip.
27+
:::
28+
29+
1. Press the blue **connect** button below, a pop-up window will appear with a list of available USB devices.
30+
2. Hold down the `BOOT` button on the Onju Voice PCB ans connect a USB cable.
31+
- _Note_: this prevents the device from reconnecting repeatedly.
32+
3. In the pop-up window, a new entry should appear. Select this USB serial port and click **Connect**.
33+
4. Choose **Install Onju Voice Satellite**, then click **Install**.
34+
5. After installation, click **Next**.
35+
- _Note_: since the device is still in BOOT mode, you'll return to a previous pop-up window.
36+
6. Refresh the browser page.
37+
7. Press the `RST` button on the Onju Voice PCB and repeat steps 1 and 3 to reconnect to the device.
38+
8. In the pop-up window, choose **Connect to Wi-Fi**.
39+
- Add the Onju Voice Satellite to your Wi-Fi network:
40+
- Select your network from the list and enter the credentials for your 2.4 GHz Wi-Fi network.
41+
- Click **Connect**.
42+
- The Onju Voice Satellite is now connected to your network.
43+
- _note_: If you wait to long, the option to connect to Wi-Fi disappears. In that case, repeat step 6 - 8.
44+
9. Congratulations 🎉 You have successfully installed the firmware on your Onju Voice Satellite.
45+
- The LEDs on the Onju Voice PCB should now be blinking green.
46+
47+
<ESPHomeButton />
48+
</TabItem>
49+
</Tabs>
50+
51+
## Step 2: Replace PCB in Google Nest Mini
52+
53+
Use the video below to perform the PCB "transplant". You can find some [instructions for disassembly here](<https://www.ifixit.com/Teardown/Google+Nest+Mini+(2nd+generation)+Teardown/130974>).
54+
55+
<iframe class="youtube-video" src="https://www.youtube.com/embed/VaQkc-sgc04?si=YNCnI69w53uL8fLk&amp;start=168" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
56+
57+
## Step 3: Connect to Home Assistant
58+
59+
You have two options to add the Onju Voice Satellite to Home Assistant.
60+
61+
### Option 1: During firmware installation
62+
63+
1. Immediately after setting up your Wi-Fi network (from step 1), you will see a screen with the option **Add to Home Assistant**.
64+
- This opens the **My** link to Home Assistant (see image below).
65+
- If you have not used My Home Assistant before, you will need to configure it. If your Home Assistant URL is not accessible on `http://homeassistant.local:8123`, replace it with the URL to your Home Assistant instance.
66+
2. Click on **Open the link**.
67+
3. It opens your Home Assistant instance and asks you to set up, click **OK**.
68+
4. Congratulations 🎉 You have successfully added the Onju Voice Satellite to your Home Assistant instance.
69+
70+
<p align="left">
71+
<img width="60%" src={require('@site/static/img/installation/my-link.png').default} />
72+
</p>
73+
74+
### Option 2: Auto discovery
75+
76+
When the Onju Voice Satellite is added to a network to which your Home Assistant instance is also connected, your device will automatically be recognized in Home Assistant.
77+
78+
1. Under [**Settings** > **Devices & Services**](https://my.home-assistant.io/redirect/integrations/), your Onju Voice Satellite should be discovered (see image below).
79+
2. Click on **Configure**, at the discovered device.
80+
3. It asks if you want to add the device and click **Submit**.
81+
4. Congratulations 🎉 You have successfully added the Onju Voice Satellite to your Home Assistant instance.
82+
83+
<p align="left">
84+
<img width="40%" src={require('@site/static/img/installation/auto-discovery.png').default} />
85+
</p>
86+
87+
## Step 4: Talk to your voice assistant
88+
89+
Congratulations 🎉 You have gone successfully through everything to get started with your Onju Voice Satellite. If you have any questions, please check the [FAQ page](/docs/faq) first and if you can't find the answer there, you can always ask your question on [Github](https://github.com/tetele/onju-voice-satellite).

‎docs/docs/introduction.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
id: introduction
3+
title: Introduction
4+
description: 'Introduction to the Onju Voice Satellite'
5+
---
6+
7+
Ever since voice satellites [were introduced][voice-satellite] to [Home Assistant](https://www.home-assistant.io/), people wanted to use good microphones and speakers for this purpose, but not many were really available. In a valiant attempt to free a [Google Nest Mini (2nd generation)][nest-mini] from its privacy ignoring overlords, [Justin Alvey](https://github.com/justLV) created [Onju Voice](https://github.com/justLV/onju-voice), a drop-in replacement PCB for the Mini, with an ESP32-S3 at its heart, capable of [some pretty funky stuff](https://twitter.com/justLV/status/1681377298308820992).
8+
9+
The purpose of this project is to be able to use such a modded Nest Mini as a voice satellite in Home Assistant. Here's a small demo:
10+
11+
<iframe class="youtube-video" src="https://www.youtube.com/embed/fuX6IYa79gA?si=DAuEWS87kSnQtX6U" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
12+
13+
## Features
14+
15+
- Wake word, push to talk, on-demand and continuous conversation support
16+
- Response playback
17+
- Audio media player
18+
- Service exposed in HA to start and stop the voice assistant from another device/trigger
19+
- Visual feedback of the wake word listening/audio recording/success/error status via the Mini's onboard top LEDs
20+
- Uses all 3 of the original Mini's touch controls as volume controls and a means of manually starting the assistant and setting the volume
21+
- Uses the original Mini's microphone mute button to prevent the wake word engine from starting unintendedly
22+
- Automatic continuous touch control calibration
23+
24+
## Prerequisites
25+
26+
- Home Assistant 2024.7.x or newer
27+
- A voice assistant [configured in HA](https://my.home-assistant.io/redirect/voice_assistants/) with STT and TTS in a language of your choice
28+
- ESPHome 2024.7.3 or newer
29+
30+
## Known issues and limitations
31+
32+
- You have to be able to retrofit an Onju Voice PCB inside a 2nd generation Google Nest Mini.
33+
- ESPHome currently can't use the I2S bus for both listening and playing **simultaneously**. As such, if you want to stream audio (like a TTS notification) to the Onju, you **need** to stop wake word listening first
34+
- The version for `microWakeWord` is in BETA and probably full of bugs (please [report them](https://github.com/tetele/onju-voice-satellite/issues/new?assignees=&labels=bug&projects=&template=bug.yml) if you find any)
35+
36+
## License
37+
38+
The PCB is **NOT** my work and has [its own license](https://github.com/justLV/onju-voice/blob/master/LICENSE). This repository only refers to the ESPHome config that makes the board a HA-compatible voice satellite.
39+
40+
The config is distributed under the **MIT** License. See [`LICENSE`](https://github.com/tetele/onju-voice-satellite/blob/main/LICENSE) for more information.
41+
42+
The notification sounds used are under [CC BY 4.0 ATTRIBUTION](https://creativecommons.org/licenses/by/4.0/) license.
43+
44+
## Credits
45+
46+
- Obviously, a huge thanks to [Justin Alvey](https://twitter.com/justLV) (@justLV) for the excellent Onju Voice project
47+
- Many thanks to Mike Hansen ([@synesthesiam](https://github.com/synesthesiam)) for the relentless work he's put into [Year of the Voice](https://www.home-assistant.io/voice_control/) at Home Assistant
48+
- Thanks to [@kahrendt](https://github.com/kahrendt) for [microWakeWord](https://github.com/kahrendt/microWakeWord)
49+
- Thanks to [@gnumpi](https://github.com/gnumpi) for migrating the ESPHome [`media_player` component to ESP-IDF](https://github.com/gnumpi/esphome_audio)
50+
- Thanks to [Klaas Schoute](https://github.com/klaasnicolaas) for helping with a creating a microsite for the automatic installation of this config (still experimental)
51+
- Thanks to the [ESPHome Discord server](https://discord.gg/KhAMKrd) members for both creating the most time saving piece of software ever and for helping out with some kinks with the config - in particular @jesserockz, @ssieb, @Hawwa, @BigBobba
52+
- Thanks to [UNIVERSFIELD](https://freesound.org/people/UNIVERSFIELD/) for the notification sounds (licensed [CC BY 4.0 ATTRIBUTION](https://creativecommons.org/licenses/by/4.0/), slightly shortened and converted to mono)
53+
54+
[nest-mini]: https://store.google.com/product/google_nest_mini
55+
[voice-satellite]: https://www.home-assistant.io/blog/2023/04/27/year-of-the-voice-chapter-2/#composing-voice-assistants

0 commit comments

Comments
 (0)