Skip to content

docs: update hardware documentation and README #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
florian-asche merged 2 commits into from
May 14, 2026
+26 −35
Merged

docs: update hardware documentation and README #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5ff1649
docs: update hardware documentation and README
florian-asche May 14, 2026
979b943
docs(hardware): remove Raspberry Pi Zero 2WH references and workarounds
florian-asche May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 19 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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)<br>• Automatic Docker Compose deployment<br>• Pipewire Audio Server<br>• SSH enabled (pi User) |
| **[Sattelite1](docs/hardware_sattelite1.md)** | <img src="docs/sattelite1-hat.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Base Image<br>• Satellite1 Hat Driver<br><br><span style="color: red;">Image is currently work in progress!</span> |
| **[Sattelite1](docs/hardware_sattelite1.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/sattelite1-hat.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Satellite1 Hat Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant<br><br><span style="color: red;">Image is currently work in progress!</span> |
| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • Base Image<br>• Seeed Voicecard Driver |
| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • 2-Mic HAT Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• 2-Mic HAT GPIO LED Control<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant |
| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)** | <img src="docs/respeaker_lite.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Base Image<br>• Audio keep-alive service<br>• Workaround for connectivity issues in combination with the Pi Zero 2W.<br><br><span style="color: red;">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.</span> |
| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/respeaker_lite.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • ReSpeaker Lite Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant<br>• Workaround for connectivity issues in combination with the Pi Zero 2W.<br><br><span style="color: red;">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.</span> |

| Name | Hardware | What's in the Image? |
| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Base Image** | Your own hardware... | • Docker & Docker Compose (piCompose)<br>• Automatic Docker Compose deployment<br>• Pipewire Audio Server<br>• SSH enabled (pi User) |
| **[Sattelite1](docs/hardware_sattelite1.md)** | <img src="docs/sattelite1-hat.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Base Image<br>• Satellite1 Hat Driver<br><br><span style="color: red;">Image is currently work in progress!</span> |
| **[Sattelite1](docs/hardware_sattelite1.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/sattelite1-hat.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Satellite1 Hat Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant<br><br><span style="color: red;">Image is currently work in progress!</span> |
| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • Base Image<br>• Seeed Voicecard Driver |
| **[ReSpeaker 2-Mic HAT v1](docs/hardware_2mic_v1.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 200px; height: auto;"> | • 2-Mic HAT Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• 2-Mic HAT GPIO LED Control<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant |
| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)** | <img src="docs/respeaker_lite.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • Base Image<br>• Audio keep-alive service<br>• Workaround for connectivity issues in combination with the Pi Zero 2W.<br><br><span style="color: red;">There is a USB connectivity issue with the Pi Zero 2W. Use this board with at least Raspberry PI 3.</span> |
| **[ReSpeaker Lite](docs/hardware_respeaker_lite.md)**<br>**+Linux-Voice-Assistant**<br>**+Snapcast** | <img src="docs/respeaker_lite.jpg" alt="ReSpeaker Lite Board" style="width: 200px; height: auto;"> | • ReSpeaker Lite Image<br>• Linux-Voice-Assistant (OpenHomeFoundation)<br>• Snapcast MultiRoom Audio Client<br>• Pre-configured for Home Assistant<br>• Workaround for connectivity issues in combination with the Pi Zero 2W.<br><br><span style="color: red;">There is a USB connectivity issue with the Pi Zero 2W. Use this board with at least Raspberry PI 3.</span> |



### 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

Expand All @@ -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

Expand Down Expand Up @@ -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.
Expand All @@ -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).

6 changes: 2 additions & 4 deletions docs/hardware_2mic_v1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<img src="respeaker_2michats.webp" alt="ReSpeaker 2-Mics Pi HAT" style="width: 300px; height: auto;"></img>

Features:
- Support the Raspberry Pi 3B,4B
- Two microphones (Mic L and Mic R)
- Two Grove connectors
- One User-defined button
Expand All @@ -15,15 +14,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:

Expand Down
11 changes: 3 additions & 8 deletions docs/hardware_respeaker-lite.md → docs/hardware_respeaker_lite.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,33 +9,28 @@ Features:
- Interference Cancellation (IC)
- Voice-to-Noise Ratio (VNR)


## Order

### 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:

### 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. <br>
More information in the official Seeedstudio Wiki.<br>
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:
Expand Down
4 changes: 2 additions & 2 deletions docs/hardware_sattelite1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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)
Expand Down
Loading