diff --git a/AGENTS.md b/AGENTS.md index 4b84e22f90..2593338b54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,9 +28,10 @@ Read the full style guide, but these are the ones worth checking twice: - Product IDs are uppercase with a hyphen: **AIR-1**, **MTR-1**, never `Air-1` or `air1`. -- **R PRO-1** is the exception: a space after the R, not a hyphen, in - all display text. Keep `rpro1`, `r-pro-1`, and `R_PRO-1` only in file - names, URLs, hostnames, and literal device names. +- **R PRO-1** and **CAST PRO-1** are the exceptions: a space before + PRO, not a hyphen, in all display text. Never `CAST-1 PRO`. Keep + `rpro1`, `r-pro-1`, `R_PRO-1`, `castpro1`, and `cast-pro-1` only in + file names, URLs, hostnames, entity IDs, and literal device names. - **US English** spelling: color, center, meter, behavior. - Flag must-know info with admonitions (`note` for prerequisites, `tip`, `warning`, `success` for a "Next step" box with a primary diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md index 1fba7bc276..2c78d4b801 100644 --- a/STYLE_GUIDE.md +++ b/STYLE_GUIDE.md @@ -105,7 +105,7 @@ Product IDs are always uppercase with a hyphen: **AIR-1**, **MTR-1**, Never `Air-1`, `air1`, or `AIR1` in body copy. mkdocs.yml is the source of truth for the canonical form. -**R PRO-1** is the one exception: its name has a space after the R, not +**R PRO-1** is an exception: its name has a space after the R, not a hyphen. Write **R PRO-1** in titles, headings, nav labels, and body copy, never `R-PRO-1`. The hyphenated and underscored forms survive only where a space isn't allowed or where you quote the device @@ -117,6 +117,16 @@ literally, and those must not be changed: - The device name Home Assistant and Homey show: **Apollo R_PRO-1** - The setup hotspot: **Apollo R PRO 1 Hotspot** +**CAST PRO-1** follows the same pattern: a space after CAST, then +**PRO-1**. Never `CAST-1 PRO`, `CAST-PRO-1`, or `Cast Pro`. It's a +different product from the **CAST-1**, so don't shorten it to CAST-1. +The same literal forms keep their own spelling: + +- File and folder names and URLs: `castpro1/`, `cast-pro-1-intro-image.webp` +- Entity IDs: `media_player.apollo_cast_pro_1_xxxxxx_player` +- The device name Home Assistant and Music Assistant show: **Apollo CAST_PRO-1** +- The setup hotspot: **Apollo CAST_PRO-1 Hotspot** + ### First mention per page On the first mention of a product in body copy, use the full brand name: diff --git a/docs/assets/cast-pro-1-connect-to-hotspot.webp b/docs/assets/cast-pro-1-connect-to-hotspot.webp new file mode 100644 index 0000000000..8168364a93 Binary files /dev/null and b/docs/assets/cast-pro-1-connect-to-hotspot.webp differ diff --git a/docs/assets/cast-pro-1-hero.webp b/docs/assets/cast-pro-1-hero.webp new file mode 100644 index 0000000000..44d5210d3d Binary files /dev/null and b/docs/assets/cast-pro-1-hero.webp differ diff --git a/docs/assets/cast-pro-1-plug-in-audio-in.webp b/docs/assets/cast-pro-1-plug-in-audio-in.webp new file mode 100644 index 0000000000..19b11cfddd Binary files /dev/null and b/docs/assets/cast-pro-1-plug-in-audio-in.webp differ diff --git a/docs/assets/cast-pro-1-plug-in-audio-out.webp b/docs/assets/cast-pro-1-plug-in-audio-out.webp new file mode 100644 index 0000000000..afa9a549a5 Binary files /dev/null and b/docs/assets/cast-pro-1-plug-in-audio-out.webp differ diff --git a/docs/assets/cast-pro-1-ports.webp b/docs/assets/cast-pro-1-ports.webp new file mode 100644 index 0000000000..b9859637d0 Binary files /dev/null and b/docs/assets/cast-pro-1-ports.webp differ diff --git a/docs/assets/cast-pro-1-press-boot-button.webp b/docs/assets/cast-pro-1-press-boot-button.webp new file mode 100644 index 0000000000..1f05dc0962 Binary files /dev/null and b/docs/assets/cast-pro-1-press-boot-button.webp differ diff --git a/docs/assets/cast-pro-1-remove-cover.webp b/docs/assets/cast-pro-1-remove-cover.webp new file mode 100644 index 0000000000..6d09798c14 Binary files /dev/null and b/docs/assets/cast-pro-1-remove-cover.webp differ diff --git a/docs/assets/cast-pro-1-remove-pcb.webp b/docs/assets/cast-pro-1-remove-pcb.webp new file mode 100644 index 0000000000..a3adcc4a31 Binary files /dev/null and b/docs/assets/cast-pro-1-remove-pcb.webp differ diff --git a/docs/assets/cast-pro-1-replace-cover.webp b/docs/assets/cast-pro-1-replace-cover.webp new file mode 100644 index 0000000000..9d6bb91829 Binary files /dev/null and b/docs/assets/cast-pro-1-replace-cover.webp differ diff --git a/docs/assets/cast-pro-1-replace-pcb.webp b/docs/assets/cast-pro-1-replace-pcb.webp new file mode 100644 index 0000000000..958e52f81d Binary files /dev/null and b/docs/assets/cast-pro-1-replace-pcb.webp differ diff --git a/docs/products/castpro1/additional-info/analog-in.md b/docs/products/castpro1/additional-info/analog-in.md new file mode 100644 index 0000000000..add583b160 --- /dev/null +++ b/docs/products/castpro1/additional-info/analog-in.md @@ -0,0 +1,48 @@ +--- +title: Play a source through CAST PRO-1 Analog In +description: Connect a turntable, TV, or other audio source to the CAST PRO-1 Analog In jack and play it through Music Assistant as a Sendspin Source. +--- +# Play a source through Analog In + +The **Analog In** jack on your CAST PRO-1 turns any line-level source into something Music Assistant can play. Plug in a turntable, TV, or CD player, and it shows up in Music Assistant as a **Sendspin Source**. Play it on the speakers connected to your CAST PRO-1, or on any other Music Assistant player in your home. + +!!! note "Before you start" + + Finish the [Getting Started guide](../setup/getting-started.md) first, so your CAST PRO-1 is in Home Assistant and Music Assistant is running. + +## What you'll need + +- **A line-level source.** Most TVs, CD players, and streamers output line level. A turntable needs a phono preamp between it and the CAST PRO-1, unless the turntable has one built in. If the turntable has a **PHONO / LINE** switch on the back, set it to **LINE**. +- **A cable with a 3.5mm plug** for the CAST PRO-1 end. For a source with RCA outputs, use an RCA-to-3.5mm cable. + +## Connect your source + +1\. Plug the source into the **Analog In** jack, the left of the two 3.5mm jacks. The **Analog/Optical Out** jack is output only, so a source plugged in there won't play. + +![Plugging a USB-C power cable into the CAST PRO-1, then a 3.5mm cable into the Analog In jack](/assets/cast-pro-1-plug-in-audio-in.webp) + +## Play it in Music Assistant + +1\. Open **Music Assistant** from the Home Assistant sidebar and select **Browse**. + +2\. Select **Sendspin Source (Apollo CAST_PRO-1 xxxxxx)**, where `xxxxxx` matches the end of your device's name. (1) +{ .annotate } + +1. Your device's name is at the top of its device page in Home Assistant, for example **Apollo CAST_PRO-1 04c6d0**. + +3\. Pick the player to hear it on. Choose your CAST PRO-1 to play the source through its own speakers, or any other player to hear it in another room. + + + +## Choose the streaming quality + +The **Line In Streaming** setting on your CAST PRO-1's device page sets how it sends your source over the network: + +| Option | When to use it | +| --- | --- | +| **Compressed** | The default. Best for a weaker Wi-Fi connection, since it uses less bandwidth. | +| **Lossless** | Full quality. Pick it when your CAST PRO-1 is on Ethernet or a strong Wi-Fi signal. | + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/additional-info/esphome-device-builder.md b/docs/products/castpro1/additional-info/esphome-device-builder.md new file mode 100644 index 0000000000..6ec95ca32d --- /dev/null +++ b/docs/products/castpro1/additional-info/esphome-device-builder.md @@ -0,0 +1,143 @@ +--- +title: ESPHome Device Builder +description: Optional. Use ESPHome Device Builder to rename your CAST PRO-1 or edit its YAML. +--- +# ESPHome Device Builder + +!!! tip "Most people don't need this" + + Your CAST PRO-1 ships ready to use. You only need the ESPHome Device Builder if you want to rename it or make manual edits to its YAML. To add your CAST PRO-1 to Home Assistant, follow the [Getting Started guide](https://wiki.apolloautomation.com/products/castpro1/setup/getting-started/#add-to-home-assistant). + +ESPHome Device Builder is the software that gives you a user interface for editing, compiling, and flashing ESPHome YAML. You'll use it to take control of your CAST PRO-1 and edit its configuration. + +## Install ESPHome Device Builder + +Pick the platform you'll be running ESPHome Device Builder on: + +=== "Windows" + + 1. Open esphome.io/install and click **Download installer (.exe)** on the **Windows** tab. + 2. Open the downloaded `.exe` file. If Windows asks whether to allow the app to make changes, choose **Yes**, then follow the installer prompts. + 3. On the last screen, leave **Run ESPHome Device Builder** checked and click **Finish**. + 4. When **Allow network pairing** appears, click **Allow access**. Windows then asks for administrator approval and shows its own firewall prompt for the Python backend. Allow that one too, or other ESPHome dashboards on your network won't be able to reach this computer. + + !!! warning "If Windows blocks the installer" + + If a blue **Windows protected your PC** warning appears when you open the `.exe`, click **More info → Run anyway** to continue. + + ![Downloading the ESPHome Device Builder Windows installer, choosing Run anyway, and running setup](/assets/esphome-builder-install-windows.gif) + + The first launch takes a moment while it sets itself up, then the dashboard opens in your browser at http://localhost:6052/. An ESPHome icon lands in your notification area for getting back to it later. + + A short wizard runs the first time: + + 1. Click **Continue** on the welcome screen. + 2. Choose **Installation of the ESPHome Device Builder**, since you're building on this computer. + 3. Choose **New to ESPHome** for the simpler, guided interface. + + Then take **Start guided tour** for a five minute walkthrough, or **Maybe later**. + + ![ESPHome Device Builder first-run wizard, choosing local installation and New to ESPHome](/assets/device-builder-first-time-install-pick-your-experience.gif) + +=== "Mac" + + 1. Open esphome.io/install. The page detects your OS and opens the **macOS** tab. Pick the build that matches your chip: + + - **Apple Silicon** (M1, M2, M3, M4, M5) + - **Intel** + + Not sure which you have? Click the Apple menu → **About This Mac**. + + 2. Open the `.dmg` and drag **ESPHome Device Builder** into your Applications folder. + + 3. Open your Applications folder and double-click **ESPHome Device Builder**. The first time you run it, macOS may ask you to confirm. Click **Open**. + + - If macOS blocks it outright with a Gatekeeper warning instead, right-click the app in Applications and choose **Open**, then click **Open** in the confirmation dialog. After that, double-click works normally. + + The first launch takes a moment while it sets itself up, then the dashboard opens in your browser at http://localhost:6052/. An ESPHome icon lands in your menu bar for getting back to it later. + + A short wizard runs the first time: + + 1. Click **Continue** on the welcome screen. + 2. Choose **Installation of the ESPHome Device Builder**, since you're building on this computer. + 3. Choose **New to ESPHome** for the simpler, guided interface. + + Then take **Start guided tour** for a five minute walkthrough, or **Maybe later**. + + ![ESPHome Device Builder first-run wizard, choosing local installation and New to ESPHome](/assets/device-builder-first-time-install-pick-your-experience.gif) + +=== "Home Assistant App" + + The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the easiest option if you already run Home Assistant OS or a supervised install. + + **Method 1** + + To add the **ESPHome Device Builder** to your Home Assistant instance, use this My button: + + [![Open your Home Assistant instance and show the dashboard of an app.](https://my.home-assistant.io/badges/supervisor_app.svg)](https://my.home-assistant.io/redirect/supervisor_app/?app=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon) + + **Method 2** + + You can also install it yourself from the Home Assistant App Store. + + 1. In Home Assistant, open **Settings → Apps → App Store**. + 2. Search for **ESPHome Device Builder** and click **Install**. + 3. Once installed, click **Start**, then **Open Web UI**. The Device Builder will open inside your Home Assistant dashboard. + +=== "Linux" + + 1. Open esphome.io/install. The page opens on the **Linux** tab with **Debian / Ubuntu** selected. Choose the package format your distro uses, then the CPU architecture (**x86_64** for a normal desktop or laptop, **arm64** for a Raspberry Pi or similar board): + + - **Debian / Ubuntu** → downloads a `.deb` + - **Fedora / openSUSE** → downloads a `.rpm` + - **Arch (AUR)** → installs the `esphome-desktop-bin` package + - **AppImage** → a portable build that runs on any distro + + 2. Install it. Double-click the downloaded `.deb` or `.rpm` in your file manager, or run the matching command in a terminal: + + - **Debian / Ubuntu:** `sudo apt install ./ESPHome.Device.Builder_*.deb` + - **Fedora / openSUSE:** `sudo dnf install ./ESPHome.Device.Builder-*.rpm` + - **Arch:** `yay -S esphome-desktop-bin` + - **AppImage:** `chmod +x ESPHome.Device.Builder_*.AppImage` then run `./ESPHome.Device.Builder_*.AppImage` + + 3. Launch **ESPHome Device Builder** from your applications menu. + + If your CAST PRO-1 doesn't appear as a serial port later, add your user to the `dialout` group with `sudo usermod -a -G dialout $USER`, then log out and back in. + + The first launch takes a moment while it sets itself up, then the dashboard opens in your browser at http://localhost:6052/. An ESPHome icon lands in your system tray for getting back to it later. Some Linux desktops, notably GNOME without a tray extension, don't show tray icons at all. The app still runs, so use the dashboard in your browser. + + A short wizard runs the first time: + + 1. Click **Continue** on the welcome screen. + 2. Choose **Installation of the ESPHome Device Builder**, since you're building on this computer. + 3. Choose **New to ESPHome** for the simpler, guided interface. + + Then take **Start guided tour** for a five minute walkthrough, or **Maybe later**. + + ![ESPHome Device Builder first-run wizard, choosing local installation and New to ESPHome](/assets/device-builder-first-time-install-pick-your-experience.gif) + +## Take control of your CAST PRO-1 + +Taking control adopts your device into the ESPHome Device Builder so you can rename it or edit its YAML. + +1\. Open the ESPHome Device Builder. + +[![Open your Home Assistant instance and show the dashboard of an app.](https://my.home-assistant.io/badges/supervisor_app.svg)](https://my.home-assistant.io/redirect/supervisor_app/?app=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon) + +2\. Click **Show** next to **Discovered** at the top, then click **Take Control** next to your CAST PRO-1. Change the **Name** and **Friendly Name** if you'd like, or leave them, then click **Take Control** again. + + + +3\. Click **Install** (the up arrow icon), then click **On the network** and watch it finish installing. (1) +{ .annotate } + +1. This takes 5 to 10 minutes depending on how fast your device is. + + + +4\. Once it completes, click **Stop**, then press the **reset** button (on the left) on your device. Your CAST PRO-1 will reboot and it's now ready to test out! + +!!! success "You're all set!" + + Your CAST PRO-1 is now adopted into the ESPHome Device Builder, where you can rename it or edit its YAML. + diff --git a/docs/products/castpro1/examples/led-strip.md b/docs/products/castpro1/examples/led-strip.md index 45c92f3150..4a73764aec 100644 --- a/docs/products/castpro1/examples/led-strip.md +++ b/docs/products/castpro1/examples/led-strip.md @@ -6,9 +6,9 @@ description: "Connect an addressable LED strip to your CAST PRO-1 and control it Your CAST PRO-1 has LED strip terminals, **5V**, **GND** and **IO1**, for an addressable LED strip. There's no soldering: the strip's wires go straight into the terminals. Once it's connected, the strip shows up in Home Assistant as a light with effects, and it can switch on by itself whenever music is playing. -!!! note "Coming in a firmware update" +!!! note "Update your firmware first" - LED strip support for the CAST PRO-1 is coming in a firmware update. Once it's available, update your CAST PRO-1 from the **Firmware Update** entity on its device page. + If you don't see any **LED Strip** entities on your CAST PRO-1's device page, update it from the **Firmware Update** entity first. ## What you'll need @@ -21,7 +21,7 @@ Strips with separate data and clock wires (APA102, SK9822), RGBW strips, and pla Every LED draws current. A WS2812B LED pulls up to about 60 mA at full white, so a strip adds up fast: 30 LEDs can draw about 1.8 A, and a 5 m roll of 150 LEDs about 9 A. -- **Short strips** can run from the CAST PRO-1's 5V terminal. Keep **LED Strip Max Brightness** at its default of 50% or lower. +- **Short strips** can run from the CAST PRO-1's 5V terminal. Power the CAST PRO-1 from a **5V 3A** USB-C supply instead of the usual 5V 1A, and keep **LED Strip Max Brightness** at its default of 50% or lower. - **Long strips** need their own 5V power supply sized for the strip. Connect the supply to the strip's 5V and GND, connect the CAST PRO-1's **GND** terminal to the strip's GND as well, and run only the data wire from **IO1**. Don't connect the CAST PRO-1's 5V terminal to a strip that has its own supply. !!! warning "Too much load reboots the CAST PRO-1" @@ -39,7 +39,7 @@ You'll connect the strip's power, ground and data wires to the matching terminal 1. Data only travels one way along the strip. Wired to the **DOUT** end, the strip stays dark. -3\. Connect the strip's wires to the terminals: +3\. Loosen each screw terminal, slide the strip's wire in, and tighten it down. From left to right, the terminals are **5V**, **GND** and **IO1**: | CAST PRO-1 terminal | LED strip | | --- | --- | @@ -64,7 +64,7 @@ The LED strip controls are hidden until you turn them on, so a CAST PRO-1 withou 1. Multiply the strip's length by its LEDs per meter. A 5 m roll of a 30 LEDs/m strip has 150 LEDs. LEDs past the count stay off. -4\. Press **LED Strip Test**. The strip shows red, green, blue and white, then a rainbow, and turns off. +4\. Press **LED Strip Test** under **Diagnostic**. The strip shows red, green, blue and white, then a rainbow, and turns off. If the colors come out in the wrong order (for example, green when the test shows red), change **LED Strip Color Order** until they match. GRB is right for most WS2812B strips. @@ -72,19 +72,126 @@ If the colors come out in the wrong order (for example, green when the test show | Entity | What it does | | --- | --- | -| **LED Strip** | The strip itself. Turn it on and off, pick a color and brightness, or choose an effect: Rainbow, Color Wipe, Scan, Twinkle, Random Twinkle, Fireworks, Flicker, Pulse or Strobe. | -| **LED Strip Count** | How many LEDs to drive, up to 300. | +| **LED Strip** | The strip itself. Turn it on and off, pick a color and brightness, or choose an effect: Rainbow, Color Wipe, Scan, Twinkle, Random Twinkle, Fireworks, Flicker, Pulse, Strobe, **Effect A** or **Effect B**. | +| **LED Strip Count** | How many LEDs to drive, up to 300. Defaults to 30. | | **LED Strip Max Brightness** | Caps the brightness of every LED to keep the current draw down. Defaults to 50%. | | **LED Strip Color Order** | The order your strip expects its colors in. | | **LED Strip Chipset** | The type of LED on your strip. Leave it on **WS2812** unless the strip flickers or shows random colors. | +| **LED Strip Effect A Pattern** and **LED Strip Effect A Speed** | The pattern **Effect A** runs, and how fast. | +| **LED Strip Effect B Pattern** and **LED Strip Effect B Speed** | The pattern **Effect B** runs, and how fast. | | **LED Strip Music Mode** | Turns the strip on with the **Music Effect** whenever music is playing, and off about 3 seconds after it stops. | | **LED Strip Music Effect** | The effect Music Mode uses. | -| **LED Strip Test** | Runs the color test from the steps above. | +| **LED Strip Test** | Runs the color test from the steps above. Under **Diagnostic**. | + +## Effects + +**Effect A** and **Effect B** are two effect slots. Give each one a pattern and a speed, then pick it from the **LED Strip** light's effect list. Changes apply live while the effect runs, so you can drag the speed slider and watch the strip react. The other effects in the list run at a fixed speed. + +Speed runs from 1 to 100 on a curve: 1 is one step per second, and 100 is one step every 32 ms. + +| Pattern | What it does | +| --- | --- | +| **Flicker** | Dips to random levels between full and 30% brightness. | +| **Strobe** | On for one step and off for the next. | +| **Rainbow** | Moves a rainbow along the strip. It ignores the light's color. | +| **Color Wipe** | Fills the strip one LED at a time, then clears it the same way. | +| **Scan** | Moves one lit LED back and forth. | +| **Twinkle** | Fades random LEDs in and out. | +| **Pulse** | Fades the whole strip from off to full and back. | +| **Fireworks** | Lights random sparks that spread and fade. | + +!!! danger "Photosensitivity warning" + + **Strobe** flashes faster than 3 times per second from about Speed 50 up, and reaches about 16 flashes per second at Speed 100. **Pulse** passes 3 flashes per second from about Speed 75. Flashing in this range can trigger seizures in people with photosensitive epilepsy. + +??? example "Set an effect from an automation" + + Set the pattern and speed first, then turn the strip on with that effect slot: + + ```yaml + actions: + - action: select.select_option + target: + entity_id: select.apollo_cast_pro_1_04c6d0_led_strip_effect_a_pattern + data: + option: Twinkle + - action: number.set_value + target: + entity_id: number.apollo_cast_pro_1_04c6d0_led_strip_effect_a_speed + data: + value: 20 + - action: light.turn_on + target: + entity_id: light.apollo_cast_pro_1_04c6d0_led_strip + data: + effect: Effect A + ``` + + Swap in the entity IDs from your own device page. The end of each ID comes from your device's MAC address, so yours won't be `04c6d0`. !!! info "Music Mode follows playback, not the beat" Music Mode turns the strip on and off with playback. The effects run at their own pace and don't react to the music itself. +## Split the strip into segments + +You can split one strip into segments and control each segment as its own light in Home Assistant, for example one color per shelf. Segments are ESPHome partition lights, so you'll add them to your CAST PRO-1's YAML. + +!!! note "Before you start" + + Take control of your CAST PRO-1 in the [ESPHome Device Builder](../additional-info/esphome-device-builder.md) first, so you can edit its YAML. + +1\. Open your CAST PRO-1's YAML in the ESPHome Device Builder. + +2\. Add a `light:` section like the one below. Keep your own name, encryption key and Wi-Fi lines. This example splits a 30 LED strip into two segments of 15. (1) +{ .annotate } + +1. `from` and `to` count from 0, and `to` is included, so `from: 0` and `to: 14` is the first 15 LEDs. Every segment has to fit inside the **LED Strip Count** you set in Home Assistant. + +```yaml +light: + - platform: partition + name: "LED Segment 1" + segments: + - id: led_strip + from: 0 + to: 14 + default_transition_length: 0s + # LED Strip Max Brightness doesn't reach segments, so cap each one here + color_correct: [50%, 50%, 50%] + # A light restores its effect by position, so add new effects at the end + effects: &led_segment_effects + # Effect A and B follow the strip's Pattern and Speed settings + - addressable_lambda: + name: "Effect A" + update_interval: 15ms + lambda: "id(led_strip_slot_effect)(it, current_color, initial_run, 0);" + - addressable_lambda: + name: "Effect B" + update_interval: 15ms + lambda: "id(led_strip_slot_effect)(it, current_color, initial_run, 1);" + # Built-in effects run at a fixed speed + - addressable_rainbow: + name: "Rainbow" + - addressable_twinkle: + name: "Twinkle" + - pulse: + name: "Pulse" + - platform: partition + name: "LED Segment 2" + segments: + - id: led_strip + from: 15 + to: 29 + default_transition_length: 0s + color_correct: [50%, 50%, 50%] + effects: *led_segment_effects +``` + +3\. Click **Install** and choose **On the network**. Once it finishes, **LED Segment 1** and **LED Segment 2** show up on your CAST PRO-1's device page. + +Both segments share the **Effect A** and **Effect B** pattern and speed settings with the **LED Strip** light. + ## Troubleshooting **Nothing lights up** diff --git a/docs/products/castpro1/examples/tts-announcements.md b/docs/products/castpro1/examples/tts-announcements.md new file mode 100644 index 0000000000..e9094f4e93 --- /dev/null +++ b/docs/products/castpro1/examples/tts-announcements.md @@ -0,0 +1,86 @@ +--- +title: CAST PRO-1 TTS and announcements +description: Send text-to-speech and announcements to your CAST PRO-1, with music ducking automatically. +--- +# TTS and announcements + +Your CAST PRO-1 can speak. Send it a text-to-speech message and it plays over whatever is already going, ducking the music down and bringing it back when it's done. Nothing stops or resumes, the two run at once. + +You'll need a text-to-speech engine set up in Home Assistant first. The examples below use Piper, which runs locally and sounds good, but any engine works since the CAST PRO-1 plays what Home Assistant sends it. + +## Which player to use + +Your CAST PRO-1 has two media players and either one handles announcements. + +* **Player** is the ESPHome media player with the announcement pipeline. +* **Sendspin Player** is the Music Assistant streaming target. Announcements sent here get forwarded to the announcement pipeline, so your music still ducks. + +## Send an announcement + +You'll send a test announcement from Developer Tools and hear it play over your music. + +1\. Open **Developer Tools** in Home Assistant (**Settings → Tools** in Home Assistant 2026.8 and newer) and go to the **Actions** tab. + +[![Open your Home Assistant instance and show your action tools.](https://my.home-assistant.io/badges/tools_actions.svg)](https://my.home-assistant.io/redirect/tools_actions/) + +2\. Switch to YAML mode and paste this: (1) +{ .annotate } + +1. The number in the entity ID comes from your CAST PRO-1's MAC address, so yours won't be `722124`. Copy the real one from your device page in Home Assistant. + +```yaml +action: tts.speak +target: + entity_id: tts.piper +data: + media_player_entity_id: media_player.apollo_cast_pro_1_722124_player + message: Testing announcements on the CAST pro one +``` + +3\. Run it with music playing and you'll hear the music drop, the message play, then the music come back. + +## What happens during an announcement + +The CAST PRO-1 ducks the music by 40 dB the instant an announcement starts, so speech stays clear without the music stopping. The onboard LEDs turn cyan while it's talking. When the message finishes, the music fades back over a second and the LEDs go out. + +That LED change is a handy way to tell an announcement from a glitch when you're across the room. + +## Announce a sound instead of speech + +Anything you can play can be an announcement, not just speech. A doorbell chime works the same way, ducking the music and lighting the LEDs: + +```yaml +action: media_player.play_media +target: + entity_id: media_player.apollo_cast_pro_1_722124_player +data: + media_content_id: media-source://media_source/local/doorbell.mp3 + media_content_type: music + announce: true +``` + +The `announce: true` is what routes it to the announcement pipeline. Leave it out and the sound replaces your music instead of playing over it. + +## Use it in an automation + +??? example "Announce when the washing machine finishes" + + ```yaml + alias: Announce laundry done + triggers: + - trigger: state + entity_id: sensor.washing_machine_status + to: "off" + for: + minutes: 2 + actions: + - action: tts.speak + target: + entity_id: tts.piper + data: + media_player_entity_id: media_player.apollo_cast_pro_1_722124_player + message: The washing machine is finished + mode: single + ``` + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/examples/wizmote-blueprint.md b/docs/products/castpro1/examples/wizmote-blueprint.md new file mode 100644 index 0000000000..8fe4dddc0e --- /dev/null +++ b/docs/products/castpro1/examples/wizmote-blueprint.md @@ -0,0 +1,66 @@ +--- +title: CAST PRO-1 WizMote control +description: Control your CAST PRO-1 with a WizMote using the Apollo CAST PRO-1 WizMote blueprint in Home Assistant. +--- +# WizMote control + +A WizMote gives you physical control over playback on your CAST PRO-1. The **Apollo CAST PRO-1 WizMote** blueprint maps each of the nine buttons to a playback action, a light toggle, or any Home Assistant action you want, all set up without leaving Home Assistant. + +Every button ships with a sensible default, so your WizMote works the moment you import the blueprint. Open any button's dropdown to change it, or set one to **Send HA Event** to run a custom action like playing a Music Assistant playlist. + +| Button | Default action | +|--------|----------------| +| On | Play | +| Off | Pause | +| Night | Toggle Light | +| Brightness Up | Volume Up | +| Brightness Down | Volume Down | +| Button 1 | Previous Track | +| Button 2 | Next Track | +| Button 3 | Send HA Event | +| Button 4 | Send HA Event | + +Each dropdown offers the same choices: Nothing, Play, Pause, Play / Pause, Next Track, Previous Track, Volume Up, Volume Down, Toggle Light, or Send HA Event. + +## Pair your WizMote + +Before the blueprint can control anything, pair your WizMote with the CAST PRO-1. + +1\. Open the ESPHome integration, then click through to your Apollo CAST PRO-1 to open its device page. + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + +2\. Turn on **WizMote Auto-Discovery**. + +3\. Press any button on your WizMote. The CAST PRO-1 pairs with it and **WizMote Status** updates to show the paired remote. (1) +{ .annotate } + +1. Pairing a different WizMote later? Use **Clear WizMote Pairing** on the device to unpair, then turn **WizMote Auto-Discovery** back on and press a button on the new remote. + + + +!!! note "Pairing takes longer on a CAST PRO-1 running Ethernet only" + + A CAST PRO-1 that's on Ethernet and not joined to any Wi-Fi network has no channel to follow, so it hops through radio channels 1 through 13 hunting for the WizMote, moving on every couple of seconds until it hears one. Keep pressing a button and it should pair within a minute. + +## Import the blueprint + +You'll import the blueprint, pick your device, and choose what each WizMote button does. + +1\. Click the Import Blueprint button below then click **Open link**. + + + +[![Open your Home Assistant instance and show the blueprint import dialog with a specific blueprint pre-filled.](https://my.home-assistant.io/badges/blueprint_import.svg)](https://my.home-assistant.io/redirect/blueprint_import/?blueprint_url=https%3A%2F%2Fraw.githubusercontent.com%2FApolloAutomation%2FBlueprints%2Frefs%2Fheads%2Fmain%2FCAST-1%2FCAST-1-WizMote.yaml) + +2\. Click **Preview** then click **Import Blueprint**. + +3\. Click on **Apollo CAST PRO-1 WizMote**, then click **Select a device** and choose your **Apollo CAST_PRO-1** from the dropdown. + +4\. Every button already has a default, so your WizMote works right away. To change one, open its dropdown and pick a different action. + +5\. For any button set to **Send HA Event** (Buttons 3 and 4 by default), click **Add Action** below it and choose what it should do, like playing a Music Assistant playlist or toggling a light. + +6\. Name your automation something like **Apollo CAST PRO-1 WizMote** and click **Save**. Your WizMote now controls your CAST PRO-1! + + diff --git a/docs/products/castpro1/faq.md b/docs/products/castpro1/faq.md new file mode 100644 index 0000000000..14b013813d --- /dev/null +++ b/docs/products/castpro1/faq.md @@ -0,0 +1,85 @@ +--- +title: CAST PRO-1 FAQ +description: Frequently asked questions about the CAST PRO-1 audio caster. +--- +1\. **What does the CAST PRO-1 do?** + +* It adds streaming audio to speakers that aren't smart. Connect it to your speakers, receiver, or soundbar, add it to Home Assistant, and it shows up in Music Assistant as a player you can stream to. + +2\. **How is it different from the CAST-1?** + +* **Built-in Ethernet:** no addon module needed for a wired connection. +* **Optical output:** the output jack takes an optical cable as well as a regular 3.5mm audio cable. +* **Analog In:** a second jack for audio in, so you can play a turntable or TV through Music Assistant. +* **LED strip terminals:** screw terminals for an addressable LED strip, no soldering. + +3\. **Which jack is which?** + +* The left jack is **Analog In**, audio in only. Whatever you plug in shows up in Music Assistant as a **Sendspin Source**. See [Play a source through Analog In](additional-info/analog-in.md). +* The right jack is **Analog/Optical Out**, audio out only. It takes a 3.5mm audio cable for analog or a mini-TOSLINK optical cable for digital. +* The [Getting Started guide](setup/getting-started.md#know-your-ports) has a labeled photo of every port. + +4\. **What cable do I need for optical?** + +* A mini-TOSLINK to TOSLINK cable, sometimes sold as a "3.5mm optical to TOSLINK" cable. The small end looks like a 3.5mm plug and goes into the CAST PRO-1, the square end goes into your receiver or soundbar. A regular 3.5mm audio cable won't carry optical audio. +* After you plug it in, set **Audio Output** to **Optical** on the device page. + +5\. **Do I need powered speakers?** + +* Yes. The CAST PRO-1 has no amplifier of its own, so it needs powered speakers, a receiver, or an active soundbar. + +6\. **My speakers use RCA or 6.35mm inputs, will it work?** + +* Yes, with a 3.5mm-to-RCA or 3.5mm-to-6.35mm adapter cable on the **Analog/Optical Out** jack. + +7\. **How do I power it?** + +* With **USB-C** from a 5V supply. A 5V 1A supply is plenty. Use a quality supply and cable. +* Running an LED strip from the screw terminals? Use a 5V 3A supply instead, since the strip draws its power through the CAST PRO-1. +* The Ethernet port is for network only. It doesn't take power over Ethernet (PoE), so the CAST PRO-1 needs USB-C power even on a wired connection. + +8\. **Can I use Wi-Fi instead of Ethernet?** + +* Yes. Set it up through its hotspot or Improv via BLE. See the [Getting Started guide](setup/getting-started.md#connect-to-your-network). +* If it has both, it keeps both up at once, so Home Assistant doesn't lose the device while you plug or unplug the cable. Take the cable out and it goes back to Wi-Fi on its own. +* The **Network Connection** sensor on the device page shows which one is in use. It reads **Ethernet**, **WiFi**, **Ethernet + WiFi**, or **Hotspot**. +* The setup hotspot never broadcasts while an Ethernet cable is connected. + +9\. **Do I need Music Assistant?** + +* Music Assistant is how you stream to the CAST PRO-1 out of the box, and your CAST PRO-1 shows up there as a player automatically once Music Assistant is running. The [Getting Started guide](setup/getting-started.md#music-assistant) walks through installing it. + +10\. **What can I stream to it?** + +* Anything Music Assistant can play, including your local library, streaming services, and radio. Music Assistant handles the sources and sends the audio to your CAST PRO-1. +* AirPlay and Spotify Connect aren't built into the CAST PRO-1 firmware. Music Assistant has a plugin for each: AirPlay Receiver and Spotify Connect, which make its players show up as AirPlay or Spotify Connect targets. Both are early in development with limited functionality, and Spotify Connect needs a Spotify Premium account. + +11\. **Can I play the same music in several rooms?** + +* Yes. Group your CAST PRO-1 with other CAST PRO-1s and CAST-1s in Music Assistant and they play in sync. Volume can be set for the whole group or per player. + +12\. **Does it need a cloud account or subscription?** + +* No. Streaming runs locally through Music Assistant and Sendspin. + +13\. **Can I control playback without opening an app?** + +* Yes, pair a WizMote. See [WizMote Control](examples/wizmote-blueprint.md). + +14\. **What are the RGB LEDs for?** + +* The four onboard RGB LEDs are exposed as the **RGB Light** entity. Change the color, use the **Slow Pulse** or **Fast Pulse** effect, or turn them off entirely. +* For more light, connect an addressable LED strip to the screw terminals. See [Add an LED strip](examples/led-strip.md). + +15\. **What are the two buttons on the front?** + +* Both are recessed, so press them with a pin or a small screwdriver. +* The **left** button is **reset**, which restarts the device. +* The **right** button is **boot**. While the CAST PRO-1 is running, hold it for about 3 seconds for a status check on the onboard LEDs, or for 10 seconds to factory reset it. Hold it while powering up to put the CAST PRO-1 into boot mode for reflashing. See [Boot button status check and factory reset](troubleshooting/castpro1-boot-button.md). +* They're the other way round from the CAST-1, where boot is on the left. + +16\. **How do I try beta firmware?** + +* Set **Firmware Channel** to **Beta** on your CAST PRO-1's device page, then select **Press** next to **Firmware Update**. See [Switch to Beta Firmware](../general/setup/switch-to-beta-branch.md) for a step-by-step guide. + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/introduction.md b/docs/products/castpro1/introduction.md index 43a52aa100..4bccc5b5ab 100644 --- a/docs/products/castpro1/introduction.md +++ b/docs/products/castpro1/introduction.md @@ -4,18 +4,23 @@ description: Documentation for CAST PRO-1, including setup, usage, and best prac --- # Introduction -**Make Any Speakers Smart:** Connect the CAST PRO-1 to your speakers, receiver or soundbar, add it to Home Assistant, and it shows up in Music Assistant as a player you can stream to. It needs Music Assistant 2.10.7 or newer. +![CAST PRO-1 glowing pink on a wooden table next to a turntable, with a Made for ESPHome badge](/assets/cast-pro-1-hero.webp) -**Analog or Optical Output:** Use the analog output for powered speakers, or the optical output for a receiver or soundbar. Pick which one plays with the **Audio Output** setting on the device page. +**Make Any Speakers Smart:** Connect the CAST PRO-1 to your speakers, receiver or soundbar, add it to Home Assistant, and it shows up in Music Assistant as a player you can stream to. -**Audio In:** Plug in a turntable, TV or other source and turn on **Line In** to play it through the speakers connected to your CAST PRO-1. +**Analog or Optical Output:** The **Analog/Optical Out** jack takes a 3.5mm audio cable for powered speakers, or a mini-TOSLINK optical cable for a receiver or soundbar. Pick which one plays with the **Audio Output** setting on the device page. -**Built-In Ethernet:** The CAST PRO-1 has an Ethernet port on board, so it can run on a wired connection with no add-on. Without a cable, it works over WiFi. +**Audio In:** Plug a turntable, TV or other source into the **Analog In** jack and it shows up in Music Assistant as a source you can play on any player in your home. See [Play a source through Analog In](additional-info/analog-in.md). + +**Built-In Ethernet:** The CAST PRO-1 has an Ethernet port on board, so it can run on a wired connection with no addon. Without a cable, it works over Wi-Fi. **Multi-Room Audio:** Group the CAST PRO-1 with other CAST players to play the same music in sync across every room. Streaming runs locally through Music Assistant and Sendspin, so there's no cloud account and no subscription. -**LED Strip Terminals:** Connect an addressable LED strip to the terminals, with no soldering, and control it from Home Assistant. See [Add an LED Strip](examples/led-strip.md). +**Onboard RGB LEDs:** Four RGB LEDs on the device show the color and effect you pick in Home Assistant, and turn cyan during announcements. + +**LED Strip Terminals:** Connect an addressable LED strip to the screw terminals, with no soldering, and control it from Home Assistant. See [Add an LED strip](examples/led-strip.md). -**WizMote Control:** Pair a WizMote for physical control over playback without opening an app. Each button is configurable in Home Assistant. +**WizMote Control:** [Pair a WizMote](examples/wizmote-blueprint.md) for physical control over playback without opening an app. Each button is configurable in Home Assistant. +[Get started with your CAST PRO-1 :material-arrow-right:](setup/getting-started.md){ .md-button .md-button--primary } [Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/setup/getting-started.md b/docs/products/castpro1/setup/getting-started.md new file mode 100644 index 0000000000..6a718a4c6d --- /dev/null +++ b/docs/products/castpro1/setup/getting-started.md @@ -0,0 +1,165 @@ +--- +title: CAST PRO-1 getting started guide +description: Step by step guide to getting started with your CAST PRO-1! +--- +# CAST PRO-1 getting started + +This will guide you through connecting your CAST PRO-1 to your speakers, getting it on your network, adding it to Home Assistant, and streaming to it with Music Assistant. + +## Know your ports + +Every port is on the front of the CAST PRO-1. The two 3.5mm jacks each do a single job, so check which is which before you plug anything in. + +![CAST PRO-1 front panel labeled from left to right: reset, boot, Analog In, Analog/Optical Out, USB-C, Ethernet (data only), and screw terminals (5V, GND, IO1)](/assets/cast-pro-1-ports.webp) + +| Port | What it's for | +| --- | --- | +| **Reset** and **Boot** | Two recessed buttons. Press them with a pin or a small screwdriver. See [Boot button status check and factory reset](../troubleshooting/castpro1-boot-button.md) for what each hold does. | +| **Analog In** | Audio in only. Connect a turntable (through a phono preamp), TV, or other source here to play it through Music Assistant. See [Play a source through Analog In](../additional-info/analog-in.md). | +| **Analog/Optical Out** | Audio out only. Takes a regular 3.5mm audio cable for analog speakers, or a mini-TOSLINK optical cable for a receiver or soundbar. | +| **USB-C** | Power. A 5V 1A supply, or 5V 3A if you run an LED strip from the screw terminals. | +| **Ethernet** | Wired network. Data only, it doesn't take power over Ethernet (PoE). | +| **Screw terminals** | **5V**, **GND** and **IO1** from left to right, for an [addressable LED strip](../examples/led-strip.md). | + +## Physical setup + +1\. Plug your CAST PRO-1 into a 5V USB-C power supply. A 5V 1A supply is plenty. (1) +{ .annotate } + +1. Running an [LED strip](../examples/led-strip.md) from the screw terminals? Use a 5V 3A supply instead. The Ethernet port is for network only and doesn't take power over Ethernet (PoE), so the CAST PRO-1 always needs USB-C power. + +2\. Connect your speakers to the **Analog/Optical Out** jack. Pick the cable that matches your speakers: + +- **Analog:** a 3.5mm audio cable into the line-in on your powered speakers, receiver, or active soundbar. The CAST PRO-1 has no amplifier of its own, so it needs powered speakers or an amp. For RCA or 6.35mm inputs, use a 3.5mm-to-RCA or 3.5mm-to-6.35mm adapter cable. +- **Optical:** a mini-TOSLINK to TOSLINK cable into the optical input on your receiver or soundbar. The small end looks like a 3.5mm plug and goes into the CAST PRO-1, the square end goes into your receiver. You'll switch the CAST PRO-1 to optical with the **Audio Output** setting once it's in Home Assistant. + +![Plugging a USB-C power cable into the CAST PRO-1, then a 3.5mm audio cable into the Analog/Optical Out jack](/assets/cast-pro-1-plug-in-audio-out.webp) + +## Connect to your network + +There are three ways to get your CAST PRO-1 online. Pick whichever is easier, you only need to do one. + +- **Ethernet** connects over a network cable straight to your router or switch. +- **Hotspot** works on any phone or computer. The CAST PRO-1 broadcasts its own Wi-Fi network, you join it, then enter your Wi-Fi details. +- **Improv via BLE** sets the CAST PRO-1 up over Bluetooth straight from Home Assistant. It's quick, but it needs Bluetooth on your Home Assistant host or an ESP32 Bluetooth proxy. + +=== "Ethernet" + + 1\. Plug an Ethernet cable from your router or switch into the CAST PRO-1. + + 2\. Your CAST PRO-1 picks up an address from your router on its own, so there's nothing to enter. (1) + { .annotate } + + 1. Unplug the cable later and your CAST PRO-1 falls back to Wi-Fi on its own, as long as it has Wi-Fi details saved. The [FAQ](../faq.md) covers how the two connections work together. + + 3\. Home Assistant discovers your CAST PRO-1 automatically. Add it below, then check the **Network Connection** sensor on the device page to confirm it reads **Ethernet**. + +=== "Hotspot" + + !!! note "Unplug the Ethernet cable first" + + Your CAST PRO-1 doesn't broadcast its hotspot while an Ethernet cable is connected. Unplug it while you set up Wi-Fi. + + 1\. Plug the CAST PRO-1 in via USB-C. + + !!! success "If your CAST PRO-1 is restarting or not broadcasting Wi-Fi try another USB-C cable and power supply!" + + The CAST PRO-1 needs constant 5V power. Most quality phone chargers will work fine. + + Still no hotspot? A [factory reset](../troubleshooting/castpro1-boot-button.md#factory-reset) makes it broadcast again. + + 2\. On your phone or PC, open the Wi-Fi settings and connect to "**Apollo CAST_PRO-1 Hotspot**". Once connected it should automatically open a dashboard for your CAST PRO-1. If it doesn't, open your web browser and go to [http://192.168.4.1/setup](http://192.168.4.1/setup) + + 3\. Select the Wi-Fi network that you would like your CAST PRO-1 to connect to and type in your Wi-Fi password, then click "**Save**". + + ![Joining the CAST PRO-1 hotspot on a phone and entering Wi-Fi details at 192.168.4.1/setup](/assets/cast-pro-1-connect-to-hotspot.webp) + + 4\. Once connected, the dashboard will automatically close. You've successfully connected your CAST PRO-1 to your Wi-Fi. + + !!! tip "Dashboard still open?" + + The dashboard doesn't always close by itself. If you see **Saved. Connecting...** and your phone switches back to your own Wi-Fi, setup is complete and you can close it. + +=== "Improv via BLE" + + !!! note "Pre-requirement: Bluetooth proxy or Bluetooth Home Assistant hardware required" + + Bluetooth built in such as a Raspberry Pi or at least one ESP32 BLE Proxy is required to use this to set up your Apollo device. + + 1\. Open your integrations page in Home Assistant. + + [![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integrations/) + + 2\. Click the **Add** button on your discovered CAST PRO-1, type in your Wi-Fi SSID and password, then click **Submit**. + + 3\. Click **Submit** again, give it an **Area**, then click **Finish**. + + + + Improv adds your CAST PRO-1 to Home Assistant as part of setup, so skip ahead to [choosing your audio output](#choose-your-audio-output). + +## Add to Home Assistant + +Open the ESPHome Integration, then click **Add** and **Submit**. Edit the name and choose an **Area** then click **Finish**. + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + + + +## Choose your audio output + +Your CAST PRO-1 needs to know whether the **Analog/Optical Out** jack is feeding analog speakers or an optical input. + +1\. Open your CAST PRO-1's device page in Home Assistant. + +2\. Under **Configuration**, set **Audio Output** to match the cable you plugged in: **Analog** or **Optical**. + +## Music Assistant + +The CAST PRO-1 streams through Music Assistant. Once Music Assistant is running, your CAST PRO-1 shows up as a player automatically, no extra configuration needed. + +### Install Music Assistant + +You'll install the Music Assistant app, then add its integration in Home Assistant. + +1\. Head to the App Store to install Music Assistant. + +[![Open your Home Assistant instance and show the dashboard of an app.](https://my.home-assistant.io/badges/supervisor_app.svg)](https://my.home-assistant.io/redirect/supervisor_app/?app=d5369777_music_assistant&repository_url=https%3A%2F%2Fgithub.com%2Fmusic-assistant%2Fhome-assistant-addon) + +2\. Click **Install**, then click **Start** once it finishes. + +![Music Assistant app page in Home Assistant, clicking Start until it shows Running](/assets/cast-1-start-music-assistant.gif) + +3\. Home Assistant discovers the Music Assistant integration automatically. Open your integrations page, find **Music Assistant**, then click **Add** and **Submit**. + +[![Open your Home Assistant instance and show your integrations.](https://my.home-assistant.io/badges/integrations.svg)](https://my.home-assistant.io/redirect/integrations/) + +### Stream to your CAST PRO-1 + +With Music Assistant running, you can start playing music through your speakers. + +1\. Open **Music Assistant** from the Home Assistant sidebar. + +2\. Your CAST PRO-1 appears in the player list in Music Assistant. Select it as your player. + +3\. Pick any song, playlist, or radio station and it plays through the speakers connected to your CAST PRO-1. + + + +### Play in multiple rooms + +Have more than one CAST player? Group your CAST PRO-1 with other CAST PRO-1s and CAST-1s to play the same music in sync across every room. + +1\. In Music Assistant, open the player you're listening on. + +2\. Click the group/sync button and select the other CAST players you want to join. + +3\. All grouped players now play the same audio together. Adjust the volume for the whole group or per player. + + + +!!! success "Next step: play a source through Analog In" + + Plug a turntable, TV, or other source into the **Analog In** jack and play it through Music Assistant. + + [Play a source through Analog In :material-audio-input-stereo-minijack:](../additional-info/analog-in.md){ .md-button .md-button--primary } diff --git a/docs/products/castpro1/setup/sensor-definitions.md b/docs/products/castpro1/setup/sensor-definitions.md new file mode 100644 index 0000000000..d8e93d282b --- /dev/null +++ b/docs/products/castpro1/setup/sensor-definitions.md @@ -0,0 +1,68 @@ +--- +title: CAST PRO-1 sensor definitions +description: These are all of the entities exposed by the CAST PRO-1 to automate on! +--- +# Sensor definitions + +Once added to Home Assistant you can configure different settings for your CAST PRO-1. Use the tabs below to see what each entity does, grouped the same way Home Assistant displays them. + +=== "Controls" + + | Control | What it does | + |---------|--------------| + | **Player** | The main media player for Home Assistant. Use it to play media, text-to-speech, and announcements to the speakers connected to your CAST PRO-1. Announcements duck the music down, then bring it back when they finish. See [TTS and Announcements](../examples/tts-announcements.md). | + | **Sendspin Player** | The Music Assistant streaming player. This is the player your CAST PRO-1 exposes to Music Assistant, and it's the one you group with other CAST players for synchronized multi-room audio. Announcements sent to it forward to the ESPHome player and duck the music the same way. | + | **RGB Light** | The four onboard RGB LEDs. Click the light bulb or color wheel to change the color, pick a **Slow Pulse** or **Fast Pulse** effect, or use the toggle to turn it on or off. | + | **LED Strip** | An addressable LED strip on the screw terminals. Disabled by default. See [Add an LED strip](../examples/led-strip.md). | + | **LED Strip Music Mode** | Turns the LED strip on whenever music is playing. Disabled by default. | + +=== "Sensors" + + | Sensor | What it reports | + |--------|-----------------| + | **Track Title** | Title of the track currently playing through the CAST PRO-1. | + | **Artist** | Artist of the current track. | + | **Album** | Album of the current track. | + +=== "Configuration" + + | Setting | Default | What it does | + |---------|:-------:|--------------| + | **Firmware Channel** | Stable | Which firmware channel the CAST PRO-1 updates from. **Beta** gets new features earlier but is less tested than **Stable**. See [Switch to Beta Firmware](../../general/setup/switch-to-beta-branch.md). | + | **Firmware Update** | n/a | Checks for and installs a firmware update from the selected channel, straight from Home Assistant. See [Updating Firmware](https://wiki.apolloautomation.com/products/general/calibrating-and-updating/updating-firmware/) for the full walkthrough. | + | **Audio Output** | Analog | Which output the **Analog/Optical Out** jack uses: **Analog** for a 3.5mm audio cable, or **Optical** for a mini-TOSLINK optical cable. | + | **Line In Streaming** | Compressed | How the CAST PRO-1 sends the **Analog In** source over your network. **Compressed** suits a weaker Wi-Fi connection, **Lossless** suits Ethernet or a strong Wi-Fi signal. See [Play a source through Analog In](../additional-info/analog-in.md#choose-the-streaming-quality). | + | **Bluetooth Proxy** | Off | Lets the CAST PRO-1 act as a Bluetooth proxy for Home Assistant, extending Bluetooth range to nearby devices. | + | **WizMote Auto-Discovery** | Off | Turn on to pair a WizMote. While it's on, the next WizMote button press links that remote to your CAST PRO-1. | + | **Clear WizMote Pairing** | n/a | Unpairs the current WizMote so you can pair a different one. | + | **WizMote MAC Address** | n/a | MAC address of the paired WizMote. Set automatically during pairing, or type one in manually. | + | **WizMote On** | Play | Action the WizMote **On** button runs. Choose from Nothing, Play, Pause, Play / Pause, Next Track, Previous Track, Volume Up, Volume Down, Toggle Light, or Send HA Event. | + | **WizMote Off** | Pause | Action the WizMote **Off** button runs. | + | **WizMote Night** | Toggle Light | Action the WizMote **Night** button runs. | + | **WizMote Brightness Up** | Volume Up | Action the WizMote **Brightness Up** button runs. | + | **WizMote Brightness Down** | Volume Down | Action the WizMote **Brightness Down** button runs. | + | **WizMote Button 1** | Previous Track | Action the WizMote **1** button runs. | + | **WizMote Button 2** | Next Track | Action the WizMote **2** button runs. | + | **WizMote Button 3** | Send HA Event | Action the WizMote **3** button runs. | + | **WizMote Button 4** | Send HA Event | Action the WizMote **4** button runs. | + | **ESP Reboot** | n/a | Restarts the device. Helpful for troubleshooting or refreshing the connection. | + | **Factory Reset ESP** | n/a | Erases settings and returns the device to factory firmware defaults. Disabled by default. Holding the **boot** button for 10 seconds does the same thing, see [Factory reset](../troubleshooting/castpro1-boot-button.md#factory-reset). | + | **LED Strip** settings | n/a | **Chipset**, **Color Order**, **Count**, **Effect A Pattern**, **Effect A Speed**, **Effect B Pattern**, **Effect B Speed**, **Max Brightness** and **Music Effect**. Disabled by default. See [Add an LED strip](../examples/led-strip.md). | + +=== "Diagnostic" + + + | Entity | What it shows | + |--------|---------------| + | **LED Strip Test** | Runs a color test on an [LED strip](../examples/led-strip.md): red, green, blue and white, then a rainbow. Disabled by default. | + | **WizMote Status** | Whether a WizMote is paired. Shows "No WizMote paired", "Discovery mode active", or "Paired:" with the remote's MAC address. | + | **Apollo Firmware Version** | The Apollo firmware build installed on the device (for example, `26.7.12.1`). | + | **ESPHome Version** | The ESPHome version the firmware was compiled with, and its config hash. | + | **Network Connection** | Which connection the CAST PRO-1 is using: **Ethernet**, **WiFi**, **Ethernet + WiFi** when it's on both at once, **Hotspot** while it's waiting for Wi-Fi details, or **Connecting**. | + | **Ethernet IP Address** | The device's IP address on the wired connection. Reads **Unknown** when no Ethernet cable is connected. | + | **WiFi IP Address** | The device's IP address on your Wi-Fi network. | + | **Online** | Connection status of the device to Home Assistant. | + | **ESP Temperature** | Internal temperature of the ESP32 chip. Runs warmer than the room because of the processor and Wi-Fi radio. Disabled by default. | + | **Uptime** | How long the device has been running since its last reboot. | + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/troubleshooting/castpro1-boot-button.md b/docs/products/castpro1/troubleshooting/castpro1-boot-button.md new file mode 100644 index 0000000000..7b2b0e028d --- /dev/null +++ b/docs/products/castpro1/troubleshooting/castpro1-boot-button.md @@ -0,0 +1,56 @@ +--- +title: CAST PRO-1 boot button status check and factory reset +description: Hold the CAST PRO-1 boot button to check its connection status, or to factory reset it. +--- +# Boot button status check and factory reset + +The **boot** button on your CAST PRO-1 does two things while the device is running, depending on how long you hold it: + +| Hold for | What happens | +| --- | --- | +| About 3 seconds | **Status check.** The onboard LEDs show the connection status, then run a component check. | +| 10 seconds | **Factory reset.** Erases your Wi-Fi details and settings, and the setup hotspot comes back. | + +The boot button is the second recessed button from the left, next to **reset**. Press it with a pin or a small screwdriver. + +![Pressing the recessed boot button on the CAST PRO-1 with a small screwdriver](/assets/cast-pro-1-press-boot-button.webp) + +## Status check + +Use this to see whether your CAST PRO-1 is on your network and talking to Home Assistant, without opening an app. + +1\. With the CAST PRO-1 plugged in, hold the **boot** button for about 3 seconds, then let go. + +2\. Watch the onboard LEDs. They flash one color to show the connection status: + +| Color | What it means | +| --- | --- | +| Yellow | No network connection. Check your Wi-Fi details or Ethernet cable. | +| Green | On your network, but not connected to Home Assistant. | +| Blue | Connected to Home Assistant. | + +3\. The LEDs then flash green once more. That's the component check passing. + +## Factory reset + +A factory reset erases your Wi-Fi details and settings, so you'll set your CAST PRO-1 up again afterward. + +!!! note "Unplug the Ethernet cable first" + + Your CAST PRO-1 doesn't broadcast its hotspot while an Ethernet cable is connected, so take the cable out before you start. + +1\. With the CAST PRO-1 plugged in, hold the **boot** button for 10 seconds, then let go. + +2\. The CAST PRO-1 restarts and broadcasts its hotspot again. + +3\. In Home Assistant, delete the old CAST PRO-1 from the ESPHome integration. Open its device page, select the three dots menu, then **Delete**. + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration/?domain=esphome) + +4\. Follow the [Getting Started guide](../setup/getting-started.md#connect-to-your-network) to connect your CAST PRO-1 to your network, then [add it to Home Assistant](../setup/getting-started.md#add-to-home-assistant) again. + +!!! tip "Still not broadcasting a hotspot?" + + If your CAST PRO-1 won't broadcast its hotspot after a factory reset, [reflash it](castpro1-reflash.md) to restore the factory firmware. + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/castpro1/troubleshooting/castpro1-boot-mode.md b/docs/products/castpro1/troubleshooting/castpro1-boot-mode.md new file mode 100644 index 0000000000..4b6cacde3c --- /dev/null +++ b/docs/products/castpro1/troubleshooting/castpro1-boot-mode.md @@ -0,0 +1,45 @@ +--- +title: Putting the CAST PRO-1 in boot mode +description: Step by step guide for putting the CAST PRO-1 in boot mode. +--- +# Putting the CAST PRO-1 in boot mode + +!!! info "This will cover how to put the CAST PRO-1 into boot mode." + + This is needed to force the device into boot mode to reflash the firmware. Both methods do the same thing, so use whichever is easier for you. + +!!! warning "The buttons are swapped compared to the CAST-1" + + On the CAST PRO-1, **reset** is on the left and **boot** is on the right. Both are recessed, so press them with a pin or a small screwdriver. + +## Method 1: Boot button only + +1\. Unplug the CAST PRO-1 from power. + +2\. Hold down the **boot** button (on the right) while plugging a USB-C data cable into the CAST PRO-1. Once connected, release the button. + +![Pressing the recessed boot button on the CAST PRO-1 with a small screwdriver](/assets/cast-pro-1-press-boot-button.webp) + + + +3\. You are now ready to reflash your device! + +[Click here to go to the reflashing guide!](castpro1-reflash.md){ .md-button .md-button--primary } + +## Method 2: Boot and reset buttons + +This method puts your device into boot mode with the boot and reset buttons. + +1\. Plug a USB-C cable that supports power and data into your computer and connect the other end to your CAST PRO-1. + +2\. Locate the reset and boot buttons on the front of the CAST PRO-1. + +![CAST PRO-1 front panel labeled from left to right: reset, boot, Analog In, Analog/Optical Out, USB-C, Ethernet (data only), and screw terminals (5V, GND, IO1)](/assets/cast-pro-1-ports.webp) + +3\. Hold down the **boot** button (on the right), then press and release the **reset** button (on the left) while keeping the boot button pressed. Finally, release the boot button. + + + +4\. You are now ready to reflash your device! + +[Click here to go to the reflashing guide!](castpro1-reflash.md){ .md-button .md-button--primary } diff --git a/docs/products/castpro1/troubleshooting/castpro1-reflash.md b/docs/products/castpro1/troubleshooting/castpro1-reflash.md new file mode 100644 index 0000000000..c38e793441 --- /dev/null +++ b/docs/products/castpro1/troubleshooting/castpro1-reflash.md @@ -0,0 +1,38 @@ +--- +title: Reflashing the CAST PRO-1 +description: Step by step guide for reflashing the CAST PRO-1. +--- +# Reflashing the CAST PRO-1 + +!!! info "Use this to put your CAST PRO-1 back on the latest factory firmware." + + Reflash if your device becomes unresponsive and you've exhausted the other troubleshooting methods, or to get onto the latest firmware. + +1\. Plug a USB-C cable that supports power and data into your computer and connect the other end to your CAST PRO-1. + +2\. Locate the **reset** and **boot** buttons on the front of your CAST PRO-1. They're recessed, so you'll need a pin or a small screwdriver. (1) +{ .annotate } + +1. Prefer to boot with a single button? Follow [Method 1 on the Boot Mode page](castpro1-boot-mode.md#method-1-boot-button-only) instead. + +![CAST PRO-1 front panel labeled from left to right: reset, boot, Analog In, Analog/Optical Out, USB-C, Ethernet (data only), and screw terminals (5V, GND, IO1)](/assets/cast-pro-1-ports.webp) + +3\. Put the CAST PRO-1 into boot mode. Hold down the **boot** button (on the right), then press and release the **reset** button (on the left) while keeping the boot button pressed. Finally, release the boot button. + + + +4\. Open the Apollo CAST PRO-1 Installer. + + + +5\. Click **Connect & Install**. In the browser popup, select **USB JTAG/serial debug unit** and click **Allow**. When the installer opens, click **Install** to flash the firmware, then click **Install** again to confirm. + + + +6\. Once you see "**Installation complete!**" you are finished. Click **Next** then close out of the browser window. + +!!! warning "Power cycle your device before doing anything else!" + + Your device is still in boot mode and needs to be power cycled, meaning power removed, to make it boot in a normal mode! + +[Head to the Getting Started article to set up your CAST PRO-1 as a new device!](../setup/getting-started.md){ .md-button .md-button--primary } diff --git a/docs/products/castpro1/troubleshooting/castpro1-teardown.md b/docs/products/castpro1/troubleshooting/castpro1-teardown.md new file mode 100644 index 0000000000..70e10f77de --- /dev/null +++ b/docs/products/castpro1/troubleshooting/castpro1-teardown.md @@ -0,0 +1,36 @@ +--- +title: CAST PRO-1 teardown +description: Step by step guide for opening your CAST PRO-1 to inspect or replace parts, and putting it back together. +--- +# Teardown and reassembly of CAST PRO-1 + +You'll pry the cover off, tilt the circuit board out of the case, and reverse the steps to put it back together. You'll need a small flathead screwdriver or a plastic pry tool. + +!!! danger "Unplug before opening" + + Unplug the USB-C power cable, the Ethernet cable, both audio cables and any LED strip from the CAST PRO-1 before you open it. + +## Disassembly + +1\. Hold the case with the cover facing up. Slide a small flathead screwdriver into the gap between the cover and the case, then twist gently to pop the cover off. + +![Prying the cover off the CAST PRO-1 with a small flathead screwdriver, exposing the circuit board](/assets/cast-pro-1-remove-cover.webp) + +2\. With the ports facing you, tilt the circuit board toward you and lift it out of the case. (1) +{ .annotate } + +1. The ports sit in cutouts along the front of the case. Tilting the board toward you lifts them clear of the cutouts, so don't pull the board straight up. + +![Tilting the CAST PRO-1 circuit board toward the camera and lifting it out of the case](/assets/cast-pro-1-remove-pcb.webp) + +## Reassembly + +1\. Tilt the circuit board toward you, slide the ports into their cutouts in the front of the case, then lower the back of the board until it sits flat. + +![Tilting the CAST PRO-1 circuit board into the case, ports first, then pressing it flat](/assets/cast-pro-1-replace-pcb.webp) + +2\. Line the cover up with the case and press it down until it snaps into place. + +![Pressing the cover back onto the CAST PRO-1 until it snaps into place](/assets/cast-pro-1-replace-cover.webp) + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/mkdocs.yml b/mkdocs.yml index 8f8d1462cd..ad973ee7cb 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -293,8 +293,21 @@ nav: - Reset Wi-Fi Credentials: products/cast1/troubleshooting/cast1-reset-wi-fi-credentials.md - CAST PRO-1: - Introduction: products/castpro1/introduction.md + - FAQ: products/castpro1/faq.md + - Getting Started: products/castpro1/setup/getting-started.md + - Additional Info: + - Sensor Definitions: products/castpro1/setup/sensor-definitions.md + - ESPHome Device Builder: products/castpro1/additional-info/esphome-device-builder.md + - Analog In: products/castpro1/additional-info/analog-in.md - Examples: - LED Strip: products/castpro1/examples/led-strip.md + - TTS and Announcements: products/castpro1/examples/tts-announcements.md + - WizMote Control: products/castpro1/examples/wizmote-blueprint.md + - Troubleshooting: + - CAST PRO-1 Boot Mode: products/castpro1/troubleshooting/castpro1-boot-mode.md + - Factory Re-Flash CAST PRO-1: products/castpro1/troubleshooting/castpro1-reflash.md + - Status Check and Factory Reset: products/castpro1/troubleshooting/castpro1-boot-button.md + - Teardown and Reassembly Of CAST PRO-1: products/castpro1/troubleshooting/castpro1-teardown.md - Dev Boards & Breakouts: - DEV-1: - Introduction: products/dev1/introduction.md