From 5ff16492717572ac811f2a0dd02ead7ce332fb32 Mon Sep 17 00:00:00 2001 From: Florian Asche Date: Thu, 14 May 2026 19:30:16 +0200 Subject: [PATCH 1/2] docs: update hardware documentation and README - Rename `hardware_respeaker-lite.md` to `hardware_respeaker_lite.md` - Update hardware compatibility in `hardware_2mic_v1.md` and `hardware_sattelite1.md` to include Raspberry Pi Zero 2 WH - Refine formatting and text in `README.md` - Improve clarity in `hardware_sattelite1.md` regarding 3D printing instructions --- README.md | 40 +++++++++---------- docs/hardware_2mic_v1.md | 7 ++-- ...ker-lite.md => hardware_respeaker_lite.md} | 6 +-- docs/hardware_sattelite1.md | 4 +- 4 files changed, 27 insertions(+), 30 deletions(-) rename docs/{hardware_respeaker-lite.md => hardware_respeaker_lite.md} (92%) diff --git a/README.md b/README.md index 58935f9..887f296 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,7 @@ [![CI](https://github.com/florian-asche/PiCompose/actions/workflows/build-all.yml/badge.svg)](https://github.com/florian-asche/PiCompose/actions/workflows/build-image.yml) [![GitHub Release Version](https://img.shields.io/github/v/release/florian-asche/PiCompose?label=version)](https://github.com/florian-asche/PiCompose/releases) [![GitHub License](https://img.shields.io/github/license/florian-asche/PiCompose)](https://github.com/florian-asche/PiCompose/blob/main/LICENSE) [![GitHub last commit](https://img.shields.io/github/last-commit/florian-asche/PiCompose)](https://github.com/florian-asche/PiCompose/commits) -Ready to use Raspberry Pi Images with Docker for projects like [linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) or [docker-snapcast](https://github.com/florian-asche/docker-snapcast) and soon more. - +Ready to use Raspberry Pi Images with Docker for projects like [linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) or [docker-snapcast](https://github.com/florian-asche/docker-snapcast). ## Overview @@ -18,13 +17,12 @@ The image is configured to: 5. Set audio volume to 100% 6. Set hostname 7. Search for Docker Compose files in a special directory on the main partition -💡 **Note:** If you use the Linux-Voice-Assistant Image LVA and Snapcast will be included in the project directory. + 💡 **Note:** If you use the Linux-Voice-Assistant Image LVA and Snapcast will be included in the project directory. 8. Automatically deploy each Docker Compose project found 9. Optionally set up regular re-deployments via Crontab This repository contains fully prepared images for specific voice hardware of Homeassistant with all needed drivers. - ## Features - Automated build of a customized Raspberry Pi OS image using GitHub Actions @@ -34,7 +32,6 @@ This repository contains fully prepared images for specific voice hardware of Ho - Image prepared for audio usage with the pipewire server - Prebuild images with drivers for various devices - ## Usage ### Hardware @@ -45,34 +42,38 @@ There is a seperated page for the supported hardware. You can find the link to i Here is a Overview for the specific images of each hardware: -| Name | Hardware | What's in the Image? | -| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Base Image** | If you use other hardware... | • Docker & Docker Compose (piCompose)
• Automatic Docker Compose deployment
• Pipewire Audio Server
• SSH enabled (pi User) | -| **[Sattelite1](docs/hardware_sattelite1.md)** | ReSpeaker Lite Board | • Base Image
• Satellite1 Hat Driver

Image is currently work in progress! | -| **[Sattelite1](docs/hardware_sattelite1.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker Lite Board | • Satellite1 Hat Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant

Image is currently work in progress! | -| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)** | ReSpeaker 2-Mics Pi HAT | • Base Image
• Seeed Voicecard Driver | -| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker 2-Mics Pi HAT | • 2-Mic HAT Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• 2-Mic HAT GPIO LED Control
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant | -| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)** | ReSpeaker Lite Board | • Base Image
• Audio keep-alive service
• Workaround for connectivity issues in combination with the Pi Zero 2W.

There is a USB connectivity issue with the Pi Zero 2W. I cannot recommend this board if you want to use it with that. Use Pi3 or higher. | -| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker Lite Board | • ReSpeaker Lite Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant
• Workaround for connectivity issues in combination with the Pi Zero 2W.

There is a USB connectivity issue with the Pi Zero 2W. If you want to use it with that, you need to use Pi3 or higher. | + +| Name | Hardware | What's in the Image? | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Base Image** | Your own hardware... | • Docker & Docker Compose (piCompose)
• Automatic Docker Compose deployment
• Pipewire Audio Server
• SSH enabled (pi User) | +| **[Sattelite1](docs/hardware_sattelite1.md)** | ReSpeaker Lite Board | • Base Image
• Satellite1 Hat Driver

Image is currently work in progress! | +| **[Sattelite1](docs/hardware_sattelite1.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker Lite Board | • Satellite1 Hat Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant

Image is currently work in progress! | +| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)** | ReSpeaker 2-Mics Pi HAT | • Base Image
• Seeed Voicecard Driver | +| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker 2-Mics Pi HAT | • 2-Mic HAT Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• 2-Mic HAT GPIO LED Control
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant | +| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)** | ReSpeaker Lite Board | • Base Image
• Audio keep-alive service
• Workaround for connectivity issues in combination with the Pi Zero 2W.

There is a USB connectivity issue with the Pi Zero 2W. Use this board with at least Raspberry PI 3. | +| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)**
**+Linux-Voice-Assistant**
**+Snapcast** | ReSpeaker Lite Board | • ReSpeaker Lite Image
• Linux-Voice-Assistant (OpenHomeFoundation)
• Snapcast MultiRoom Audio Client
• Pre-configured for Home Assistant
• Workaround for connectivity issues in combination with the Pi Zero 2W.

There is a USB connectivity issue with the Pi Zero 2W. Use this board with at least Raspberry PI 3. | + + ### Installation You can burn the image to your sd card with the [Raspberry Pi Imager tool](https://www.raspberrypi.com/software/). You can set wifi credentials, ssh public keys and other settings before you burn the image to your sd card. In order to use the feature where you can change the settings in the `Raspberry Pi Imager >=v2.5.0` you need to set a custom image repository. Windows -``` sh + +```sh "C:\Program Files (x86)\Raspberry Pi Imager\rpi-imager.exe" --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json ``` Linux -``` sh +```sh rpi-imager --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json ``` You can also put the [URL](https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json) in Settings - Image Repository - Use own URL. -If you dont want to use the Raspberry Pi Imager tool you can also [download](https://github.com/florian-asche/PiCompose/releases) the image and configure keyboard, timezone and wifi credentials with the `raspi-config` tool. +If you dont want to use the Raspberry Pi Imager tool you can also [download](https://github.com/florian-asche/PiCompose/releases) the image and configure keyboard, timezone and wifi credentials with the `raspi-config` tool. ### Configuration @@ -88,7 +89,7 @@ You can also add your own docker-compose projects to the system: The configuration file is named `picompose.conf` and is located in specific application directories. -``` ini +```ini # Disable this deployment DISABLED=false @@ -135,7 +136,6 @@ The process can take some time, since it downloads images from the internet! Snapcast is disabled by default. You can change that in the `picompose.conf` and reboot. - ## Development See [DEVELOPMENT.md](DEVELOPMENT.md) for information on the development and build process. @@ -145,8 +145,6 @@ See [DEVELOPMENT.md](DEVELOPMENT.md) for information on the development and buil - [docker-snapcast](https://github.com/florian-asche/docker-snapcast) - A Docker image for Snapcast server and client, providing multi-room audio streaming capabilities - [linux-voice-assistant](https://github.com/OHF-Voice/linux-voice-assistant) - A remote voice satellite implementation using the ESPHome protocol - ## License This project is released under the [BSD-3-Clause License](LICENSE). - diff --git a/docs/hardware_2mic_v1.md b/docs/hardware_2mic_v1.md index 118db5d..96e213f 100644 --- a/docs/hardware_2mic_v1.md +++ b/docs/hardware_2mic_v1.md @@ -3,7 +3,7 @@ ReSpeaker 2-Mics Pi HAT Features: -- Support the Raspberry Pi 3B,4B +- Support the Raspberry Pi Zero 2WH - Two microphones (Mic L and Mic R) - Two Grove connectors - One User-defined button @@ -15,15 +15,14 @@ Features: ### Base: -- [Raspberry Pi Zero 2 W](https://amzn.to/3M0G4hC) +- Raspberry Pi Zero 2 WH (currently no link) or if you can solder the pins yourself [Raspberry Pi Zero 2 W](https://amzn.to/3M0G4hC) - [SD-Card](https://amzn.to/4qfx06l) - [US MicroUSB Power Supply](https://amzn.to/4c52mt3) -- [Cable for Speaker](https://amzn.to/3ZvU0Dz) ### ReSpeaker 2-Mics Pi HAT v1 - [ReSpeaker 2Mic HAT](https://wiki.keyestudio.com/Ks0314_keyestudio_ReSpeaker_2-Mic_Pi_HAT_V1.0) - +- [Cable for Speaker](https://amzn.to/3ZvU0Dz) ## Additional information: diff --git a/docs/hardware_respeaker-lite.md b/docs/hardware_respeaker_lite.md similarity index 92% rename from docs/hardware_respeaker-lite.md rename to docs/hardware_respeaker_lite.md index 1e95eb1..f14d222 100644 --- a/docs/hardware_respeaker-lite.md +++ b/docs/hardware_respeaker_lite.md @@ -14,15 +14,15 @@ Features: ### Base: -- [Raspberry Pi Zero 2 W](https://amzn.to/3M0G4hC) +- [Raspberry Pi 3 B+](https://amzn.to/3P0bwhC) - [SD-Card](https://amzn.to/4qfx06l) - [US MicroUSB Power Supply](https://amzn.to/4c52mt3) -- [Cable for Speaker](https://amzn.to/3ZvU0Dz) ### Mic Array (ReSpeaker Lite Board): - [ReSpeaker Lite](https://www.seeedstudio.com/ReSpeaker-Lite-p-5928.html?srsltid=AfmBOopODKrejEe7WIXSLV5fjLuhhK8PO-AXG3WnDI1N1pwBu-PTWQHf) - [USB-Cable](https://de.aliexpress.com/item/1005004792246478.html?spm=a2g0o.order_list.order_list_main.5.4dac5c5fKkDzIc&gatewayAdapt=glo2deu) +- [Cable for Speaker](https://amzn.to/3ZvU0Dz) ## Important information: @@ -35,7 +35,7 @@ In connection with the Raspberry Pi Zero 2W there is a bug in RPI-OS where the b In order to use this board with the Raspberry Pi Zero 2W you need to flash the usb-firmware.
More information in the official Seeedstudio Wiki.
-I am currently running the [respeaker_lite_usb_dfu_firmware_v2.0.7.bin](https://github.com/respeaker/ReSpeaker_Lite/blob/master/xmos_firmwares/respeaker_lite_usb_dfu_firmware_v2.0.7.binhttps:/) +I am currently running the [respeaker_lite_usb_dfu_firmware_v2.0.7.bin](https://github.com/respeaker/ReSpeaker_Lite/blob/master/xmos_firmwares/respeaker_lite_usb_dfu_firmware_v2.0.7.bin) ## Additional information: diff --git a/docs/hardware_sattelite1.md b/docs/hardware_sattelite1.md index d1d2a69..0142a75 100644 --- a/docs/hardware_sattelite1.md +++ b/docs/hardware_sattelite1.md @@ -19,7 +19,7 @@ What you need to buy: ### Base: -- [Raspberry Pi Zero 2 W](https://amzn.to/3M0G4hC) +- Raspberry Pi Zero 2 WH (currently no link) or if you can solder the pins yourself [Raspberry Pi Zero 2 W](https://amzn.to/3M0G4hC) - [SD-Card](https://amzn.to/4qfx06l) ### Satellite1 HAT Board: @@ -32,7 +32,7 @@ What you need to buy: - [Whole Speaker kit](https://futureproofhomes.net/products/satellite1-smart-speaker-enclosure-kit) -Or if you want to print it yourself: +Or if you want to build and 3D-Print it yourself: - [Speaker](https://amzn.to/4k9gkfu) or [Aliexpress](https://de.aliexpress.com/item/1005011560142502.html?spm=a2g0o.productlist.main.3.33c9JJacJJacEB&algo_pvid=64814943-53f2-4063-858b-24b8bff7bd47&algo_exp_id=64814943-53f2-4063-858b-24b8bff7bd47-2&pdp_ext_f=%7B%22order%22%3A%22-1%22%2C%22eval%22%3A%221%22%2C%22fromPage%22%3A%22search%22%7D&pdp_npi=6%40dis%21EUR%217.78%213.89%21%21%2162.89%2131.44%21%402103868817699707030983290ea297%2112000055921741746%21sea%21DE%21797676231%21X%211%210%21n_tag%3A-29919%3Bd%3A64670a7c%3Bm03_new_user%3A-29895&curPageLogUid=uNvseW668v4i&utparam-url=scene%3Asearch%7Cquery_from%3A%7Cx_object_id%3A1005011560142502%7C_p_origin_prod%3A) - Optional: [Alternative Speaker](https://amzn.to/3ZIgnFA) From 979b9432e0c7639980997ce18f74d31e10dee65c Mon Sep 17 00:00:00 2001 From: Florian Asche Date: Thu, 14 May 2026 19:32:55 +0200 Subject: [PATCH 2/2] docs(hardware): remove Raspberry Pi Zero 2WH references and workarounds - Remove Raspberry Pi Zero 2WH support from 2-mic v1 documentation - Remove obsolete workaround section for Raspberry Pi Zero 2W in ReSpeaker Lite documentation - Clean up whitespace in hardware files --- docs/hardware_2mic_v1.md | 1 - docs/hardware_respeaker_lite.md | 5 ----- 2 files changed, 6 deletions(-) diff --git a/docs/hardware_2mic_v1.md b/docs/hardware_2mic_v1.md index 96e213f..11c9b3e 100644 --- a/docs/hardware_2mic_v1.md +++ b/docs/hardware_2mic_v1.md @@ -3,7 +3,6 @@ ReSpeaker 2-Mics Pi HAT Features: -- Support the Raspberry Pi Zero 2WH - Two microphones (Mic L and Mic R) - Two Grove connectors - One User-defined button diff --git a/docs/hardware_respeaker_lite.md b/docs/hardware_respeaker_lite.md index f14d222..05a9866 100644 --- a/docs/hardware_respeaker_lite.md +++ b/docs/hardware_respeaker_lite.md @@ -9,7 +9,6 @@ Features: - Interference Cancellation (IC) - Voice-to-Noise Ratio (VNR) - ## Order ### Base: @@ -27,10 +26,6 @@ Features: ## Important information: -### Workaround: - -In connection with the Raspberry Pi Zero 2W there is a bug in RPI-OS where the board stops working after 7 or 8 sound outputs with a reconnect to the audio card. I implemented a workaround for that where a constant not hearable output is played to the card. - ### Firmware: In order to use this board with the Raspberry Pi Zero 2W you need to flash the usb-firmware.