PiCompose

Ready to use Raspberry Pi Images with Docker for projects like linux-voice-assistant docker-snapcast and soon more.

Overview

PiCompose uses the official pi-gen tool from Raspberry Pi to create a customized Raspberry Pi OS image.

The image is configured to:

1. Install needed drivers for the hardware (2-MicHat)
2. Start seeed-voicecard service (If you use 2-MicHat)
3. Start Pipewire service
4. Start Keep-Audio-Alive service (If you use Respeaker Lite)
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.
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
• Easy addition of Docker Compose projects via the main partition (compose directory)
• Configurable regular re-deployments via a simple configuration file
• No manual configuration of the Raspberry Pi required
• Image prepared for audio usage with the pipewire server
• Prebuild images with drivers for various devices

Usage

Hardware

There is a seperated page for additional hardware like speaker or 3D-Prints here: docs/hardware.md.

Images overview

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		• Base Image • Satellite1 Hat Driver Image is currently work in progress!
Sattelite1 +Linux-Voice-Assistant +Snapcast		• 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		• Base Image • Seeed Voicecard Driver
ReSpeaker 2-Mic HAT v1 +Linux-Voice-Assistant +Snapcast		• 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		• 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 +Linux-Voice-Assistant +Snapcast		• 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.

Installation

You can burn the image to your sd card with the Raspberry Pi Imager tool. 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

"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

rpi-imager --repo https://github.com/florian-asche/PiCompose/releases/download/rpi-imager-json/rpi-imager.json

You can also put the URL in Settings - Image Repository - Use own URL.

If you dont want to use the Raspberry Pi Imager tool you can also download the image and configure keyboard, timezone and wifi credentials with the raspi-config tool.

Configuration

You can customize the PiCompose configuration in the /compose directory on the root filesystem. You can change how it is updated, how it is handling a reboot and you can remove snapcast if you dont want to use it.

You can also add your own docker-compose projects to the system:

1. Create directories for your Docker Compose projects in the compose folder on the main partition.
2. Place your docker-compose.yml files and associated configurations like .env in the appropriate subdirectories (see the example directory)
3. Configure the picompose.conf file to include your projects.

Configurationfile

The configuration file is named picompose.conf and is located in specific application directories.

# Configure if piCompose should run on boot
# When it runs without image pull, it does a docker compose down and up.
BOOT_ENABLED=true

# Configure if piCompose should update the docker image on boot
# BOOT_ENABLED needs to be true
BOOT_IMAGE_PULL=true

# Configure if piCompose should run periodically via cron
# When it runs without image pull, it does a docker compose down and up.
CRON_ENABLED=false

# Cron schedule for automatic re-deployments
# Format: Minute Hour Day Month Weekday
# Examples:
# "0 4 * * *"     - Every day at 4 AM
# "0 */6 * * *"   - Every 6 hours
# "0 0 * * 0"     - Every Sunday at midnight
CRON_SCHEDULE="0 4 * * *"

# Configure if piCompose should update the docker image on cron run
# CRON_ENABLED needs to be true
CRON_IMAGE_PULL=false

First start's

Make sure, that you configured your wifi credentials before the first boot. You can do this with the RPI-Imager tool when burning the image to your sd card.

On the first boot in will create new ssh server public keys for the ssh serve. You can see that if you have a monitor connected to your system.
The system will automatically reboot and install the audio drivers. After that you can login with the user pi. You can change the password raspberry if you didnt change it before with the imager tool.

You will notice that the hardware is not visible if you run aplay -L.
❗ You need to manually reboot one more time.

After that aplay -L should show the seeed2micvoicec or Lite soundcard depending on your hardware.

piCompose should download and install the containers. You can watch the /var/log/picompose.log logfile if you want to monitor the process. The process can take some time, since it downloads images from the internet!

Development

See DEVELOPMENT.md for information on the development and build process.

Example projects, that you can run on this:

• docker-snapcast - A Docker image for Snapcast server and client, providing multi-room audio streaming capabilities
• linux-voice-assistant - A remote voice satellite implementation using the ESPHome protocol

License

This project is released under the BSD-3-Clause License.