Revise README for Parallax OS details and setup

Updated README to reflect changes in project name and features.

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://<pi-address>: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://<pi-address>/` 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.