diff --git a/README.md b/README.md index e883f9b..9da0148 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,124 @@ -# astra-receiver -Standalone Parallax node releases for raspi +# Parallax OS + +Parallax OS turns a Raspberry Pi into an always-on network speaker for +[Astra](https://github.com/Boof2015/astra). Put a Pi beside a stereo, powered speakers, or a TV +and Astra can play to it in sync with the rest of your Parallax speakers. + +Everything runs on your local network. There are no Parallax accounts, no cloud service, and no +telemetry. Once set up, the receiver and its security updates are handled automatically. + +Parallax OS works with or without a screen: + +| Mode | What happens | How you control it | +| --- | --- | --- | +| **Headless** | The Pi runs quietly beside your speakers with no display attached. | Use `http://parallax.local/` from a phone or computer for setup, pairing, status, and audio output. | +| **TV-connected** | Connect HDMI before boot to show artwork, track information, and setup instructions on the TV. | Use the TV remote when HDMI-CEC is available, or use `parallax.local` at any time. A compatible remote is not required. | + +## What you need + +- A compatible Raspberry Pi from the table below +- A microSD card and a way to flash it +- Ethernet or Wi-Fi +- An audio output: HDMI, a built-in headphone jack where available, or a USB DAC +- [Astra](https://github.com/Boof2015/astra) running on another computer on the same network + +## Install Parallax OS + +### 1. Download the image + +Open the [Parallax OS releases](https://github.com/Boof2015/parallax-os/releases?q=parallax-os-v&expanded=true) +and download the `.img.xz` file from the newest release named **Parallax OS**. + +This repository also contains releases named `Astra Receiver` with `receiver-v*` tags. Those are +used by the manual installer and Parallax OS's auto updater, they are not SD-card images. + +### 2. Flash the microSD card + +Flash the downloaded `.img.xz` file with +[Raspberry Pi Imager](https://www.raspberrypi.com/software/) using **Use custom**, or with +[balenaEtcher](https://etcher.balena.io/). You do not need to extract the file first. + +Insert the card into the Pi. If you want the TV display, connect HDMI before turning the Pi on. + +### 3. Connect it to your network + +The first boot takes about 2–3 minutes and may include an automatic reboot. + +- **Ethernet:** plug in the cable before boot. No network setup is needed. +- **Wi-Fi:** after about two minutes, join the temporary **Parallax-Setup** Wi-Fi network from a + phone or computer. The setup page will ask you to choose your home Wi-Fi and enter its password. + A connected TV also shows the setup network and a QR code. + +When the Pi is connected, open [http://parallax.local/](http://parallax.local/) from a device on +the same network. + +### 4. Pair it with Astra + +On the computer where you play music: + +1. Open Astra's **Settings**, then **Experimental**, and turn on **Enable Parallax**. +2. Open the new **Parallax** section and choose **Plays music** for this computer. +3. Select **Add a speaker**, then choose the Parallax speaker found on your network. +4. Enter the six-digit PIN shown at `parallax.local` or on the connected TV. +5. Approve the pairing on the web page or TV before the pairing window closes. + +After pairing, use the **Audio output** setting at `parallax.local` to choose HDMI, the headphone +jack, or a connected USB DAC. Start playing in Astra and the Pi will join the selected Parallax +speakers in sync. + +## Raspberry Pi compatibility + +| Raspberry Pi | Status | Notes | +| --- | --- | --- | +| **Pi 5** | Tested | Headless and TV-connected setups tested. Use HDMI or USB audio; the Pi 5 has no built-in headphone jack. | +| **Pi 4** | Expected compatible | 64-bit hardware and expected to support both modes, but currently untested. | +| **Pi 3 Model B** | Tested | Headless and TV-connected setups tested, including HDMI and the built-in headphone jack. | +| **Pi 3 Model B+** | Expected compatible | Expected to behave like the Pi 3 Model B, but not currently tested. | +| **Pi Zero 2 W** | Unverified | Not currently recommended; it has not been tested for Parallax OS performance or TV mode. | +| **Pi 2, Pi 1, Zero, Zero W, and other 32-bit-only models** | Unsupported | Parallax OS and its prebuilt receiver require 64-bit ARM hardware. | + +For a TV-connected setup, 720p, 1080p, and 4k displays are the tested targets. HDMI-CEC support varies +between TV manufacturers and models, but it is never required for audio playback or pairing. + +## Already running Raspberry Pi OS? + +If you already maintain a Pi with a current **64-bit** Raspberry Pi OS installation, you can add +the headless Astra receiver without replacing the operating system: + +```sh +curl -fsSL https://raw.githubusercontent.com/Boof2015/astra/dev/receiver/deploy/install.sh -o /tmp/astra-receiver-install.sh && sudo bash /tmp/astra-receiver-install.sh +``` + +When installation finishes, open `http://:38405/` and follow the same pairing steps. +This option installs the headless receiver only; it does not add Parallax OS's TV display, Wi-Fi +onboarding, boot experience, or appliance management. + +## Troubleshooting + +### `parallax.local` does not open + +Make sure the phone or computer is on the same network as the Pi. Some networks do not resolve +`.local` names; find the Pi's address in your router's connected-device list and open +`http:///` instead. + +### The Parallax-Setup network does not appear + +The setup network appears only when the Pi cannot reach a network. Disconnect Ethernet if you +intend to set up Wi-Fi, then allow about two minutes after boot. If a Wi-Fi password is rejected, +Parallax-Setup will reappear so you can try again. + +### The TV does not wake, switch inputs, or respond to its remote + +HDMI-CEC has different brand names and may need to be enabled in the TV's settings. CEC is +optional: open `http://parallax.local/` on another device to finish pairing or manage the speaker. + +### Audio comes from the wrong output + +Open `http://parallax.local/`, choose **Audio output**, select HDMI, the headphone jack, or your +USB DAC, and apply the change. + +## Updates + +Parallax OS automatically keeps its receiver software and operating-system security patches up +to date. Normal receiver updates do not require reflashing the card. You only need a newer image +for OS-level changes or a fresh installation.