diff --git a/docs/assets/cast-1-connect-ethernet-module.webp b/docs/assets/cast-1-connect-ethernet-module.webp new file mode 100644 index 0000000000..4d08706f1c Binary files /dev/null and b/docs/assets/cast-1-connect-ethernet-module.webp differ diff --git a/docs/assets/cast-1-import-blueprint.gif b/docs/assets/cast-1-import-blueprint.gif new file mode 100644 index 0000000000..b73a37b04d Binary files /dev/null and b/docs/assets/cast-1-import-blueprint.gif differ diff --git a/docs/assets/cast-1-intro-image.webp b/docs/assets/cast-1-intro-image.webp new file mode 100644 index 0000000000..feac7f0ef7 Binary files /dev/null and b/docs/assets/cast-1-intro-image.webp differ diff --git a/docs/assets/cast-1-pair-wizmote.gif b/docs/assets/cast-1-pair-wizmote.gif new file mode 100644 index 0000000000..d1aec36c49 Binary files /dev/null and b/docs/assets/cast-1-pair-wizmote.gif differ diff --git a/docs/assets/cast-1-play-in-multiple-rooms.gif b/docs/assets/cast-1-play-in-multiple-rooms.gif new file mode 100644 index 0000000000..ce73b94290 Binary files /dev/null and b/docs/assets/cast-1-play-in-multiple-rooms.gif differ diff --git a/docs/assets/cast-1-play-song.gif b/docs/assets/cast-1-play-song.gif new file mode 100644 index 0000000000..b053e67c16 Binary files /dev/null and b/docs/assets/cast-1-play-song.gif differ diff --git a/docs/products/cast1/addons/ethernet-module.md b/docs/products/cast1/addons/ethernet-module.md new file mode 100644 index 0000000000..cffad70aea --- /dev/null +++ b/docs/products/cast1/addons/ethernet-module.md @@ -0,0 +1,24 @@ +--- +title: Add the Ethernet Module to CAST-1 +description: How to install the Ethernet add-on module on your CAST-1 and move it onto the Ethernet firmware. +--- +# Adding the Ethernet Module + +The Ethernet add-on gives your CAST-1 a wired network connection in place of Wi-Fi. It's a small header board that presses onto the top of the CAST-1, so there's no case to open and nothing to solder. + +1\. Unplug your CAST-1 from power. + +2\. Find the two rows of female header pins on the top of the case. + +3\. Line the module's pins up with those two rows, pin side down, and press it straight down until it sits flat. (1) +{ .annotate } + +1. Press evenly on both ends. If the module won't sit flat against the case, lift it off and line the pins up again rather than forcing it. + +![](/assets/cast-1-connect-ethernet-module.webp) + +4\. Plug an Ethernet cable into the module, then plug the CAST-1 back into power. + +Your CAST-1 is still running Wi-Fi firmware, so the wired connection won't come up yet. Switch it over using the guide below. + +[Switch your CAST-1 to Ethernet firmware :material-lan-connect:](https://wiki.apolloautomation.com/products/cast1/setup/cast1-switch-firmware/){ .md-button .md-button--primary } diff --git a/docs/products/cast1/examples/tts-announcements.md b/docs/products/cast1/examples/tts-announcements.md new file mode 100644 index 0000000000..9987bc8be9 --- /dev/null +++ b/docs/products/cast1/examples/tts-announcements.md @@ -0,0 +1,82 @@ +--- +title: CAST-1 TTS and Announcements +description: Send text-to-speech and announcements to your CAST-1, with music ducking automatically. +--- +# TTS and Announcements + +Your CAST-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-1 just plays what Home Assistant sends it. + +### Which Player to Use + +Your CAST-1 has two media players and only one of them handles announcements. + +* **Apollo CAST-1 Player** is the one you want. It has the announcement pipeline. +* **Apollo CAST-1 Sendspin Player** is the Music Assistant streaming target. Send an announcement here and it won't duck your music. + +### Send an Announcement + +1\. Open **Developer Tools** in Home Assistant and go to the **Actions** tab. + +2\. Switch to YAML mode and paste this: (1) +{ .annotate } + +1. The number in the entity ID comes from your CAST-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_1_722124_apollo_cast_1_player + message: Testing announcements on the CAST dash 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-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_1_722124_apollo_cast_1_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_1_722124_apollo_cast_1_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/cast1/examples/wizmote-blueprint.md b/docs/products/cast1/examples/wizmote-blueprint.md index 66af13dedc..b075f64b36 100644 --- a/docs/products/cast1/examples/wizmote-blueprint.md +++ b/docs/products/cast1/examples/wizmote-blueprint.md @@ -26,13 +26,23 @@ Each dropdown offers the same choices: Nothing, Play, Pause, Play / Pause, Next Before the blueprint can control anything, pair your WizMote with the CAST-1. -1\. On your CAST-1 device page, turn on **WizMote Auto-Discovery**. +1\. Open the ESPHome integration, then click through to your Apollo CAST-1 to open its device page. -2\. Press any button on your WizMote. The CAST-1 pairs with it and **WizMote Status** updates to show the paired remote. (1) +Open your Home Assistant instance and show the ESPHome integration. + +2\. Turn on **WizMote Auto-Discovery**. + +3\. Press any button on your WizMote. The CAST-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. +![](/assets/cast-1-pair-wizmote.gif) + +!!! note "Pairing takes longer on the Ethernet firmware" + + With no Wi-Fi to follow, your CAST-1 scans radio channels 1 through 13 looking for the WizMote, waiting 30 seconds on each one before moving on. Press a button every few seconds and give it a few minutes to land on the right channel. + ### Import the Blueprint 1\. Click the Import Blueprint button below then click **Open link**. @@ -48,3 +58,5 @@ Before the blueprint can control anything, pair your WizMote with the CAST-1. 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-1 WizMote** and click **Save**. Your WizMote now controls your CAST-1! + +![](/assets/cast-1-import-blueprint.gif) diff --git a/docs/products/cast1/faq.md b/docs/products/cast1/faq.md new file mode 100644 index 0000000000..d7f4b265fe --- /dev/null +++ b/docs/products/cast1/faq.md @@ -0,0 +1,69 @@ +--- +title: CAST-1 FAQ +description: Frequently asked questions about the CAST-1 audio caster. +--- +1\. **What does the CAST-1 do?** + +* It adds streaming audio to speakers that aren't smart. Plug it into a 3.5mm line-in, add it to Home Assistant, and it shows up in Music Assistant as a player you can stream to. + +2\. **Do I need powered speakers?** + +* Yes. The CAST-1 outputs line level and has no amplifier of its own, so it needs powered speakers, a receiver, or an active soundbar. + +3\. **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. + +4\. **What power supply does it need?** + +* A 5V 1A USB-C supply is plenty. The CAST-1 is sensitive to power fluctuations and needs constant 5V, so use a quality supply and cable. + +5\. **Do I need Music Assistant?** + +* Music Assistant is how you stream to the CAST-1 out of the box, and your CAST-1 shows up there as a player automatically once Music Assistant is running. The [Getting Started guide](https://wiki.apolloautomation.com/products/cast1/setup/getting-started/) walks through installing it. +* A Squeezelite firmware is also on the way if you'd rather run your CAST-1 as a Squeezelite player instead. + +6\. **Do I need Home Assistant?** + +* Not strictly. The CAST-1 works with Music Assistant on its own, though most people run both. Home Assistant adds the device entities, text-to-speech, and announcements, and our [Getting Started guide](https://wiki.apolloautomation.com/products/cast1/setup/getting-started/) sets the CAST-1 up through it. + +7\. **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-1. +* AirPlay and Spotify Connect aren't built into the CAST-1 firmware. Music Assistant's AirPlay Receiver plugin can turn its players into AirPlay targets, though that plugin is early in development and its functionality is limited. + +8\. **Why are there two media players on my device?** + +* **Apollo CAST-1 Sendspin Player** is the player Music Assistant streams to, and the one you group with other CAST-1s for multi-room audio. +* **Apollo CAST-1 Player** is the Home Assistant media player. Use it for text-to-speech and announcements, which duck the music down and bring it back when they finish. See [TTS and Announcements](https://wiki.apolloautomation.com/products/cast1/examples/tts-announcements/). + +9\. **Can I play the same music in several rooms?** + +* Yes. Group multiple CAST-1s in Music Assistant and they play in sync. Volume can be set for the whole group or per player. + +10\. **Does it need a cloud account or subscription?** + +* No. Streaming runs locally through Music Assistant and Sendspin. + +11\. **Can I control playback without opening an app?** + +* Yes, pair a WizMote. Each of the nine buttons is configurable in Home Assistant using the CAST-1 WizMote blueprint. See [WizMote Control](https://wiki.apolloautomation.com/products/cast1/examples/wizmote-blueprint/). + +12\. **Can I connect it with an Ethernet cable instead of Wi-Fi?** + +* Yes, with the [Ethernet add-on module](https://wiki.apolloautomation.com/products/cast1/addons/ethernet-module/). It's a header board that presses onto the top of the case, and your CAST-1 then runs the Ethernet firmware. + +13\. **Can I pair my phone to the CAST-1 over Bluetooth?** + +* Not with the firmware it ships with today. Music reaches your CAST-1 over your network through Music Assistant instead. +* The Squeezelite firmware that's on the way adds Bluetooth support, so this will change. + +14\. **What does the Bluetooth Proxy switch do then?** + +* It lets the CAST-1 relay nearby Bluetooth devices back to Home Assistant, extending your Bluetooth coverage. That's for sensors and trackers, not for audio. + +15\. **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. + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/cast1/introduction.md b/docs/products/cast1/introduction.md index 4f70957e90..386bec16a1 100644 --- a/docs/products/cast1/introduction.md +++ b/docs/products/cast1/introduction.md @@ -4,6 +4,8 @@ description: Documentation for CAST-1, including setup, usage, and best practice --- # Introduction +![](/assets/cast-1-intro-image.webp) + **Make Any Speakers Smart:** Plug the CAST-1 into a 3.5mm line-in, add it to Home Assistant, and it shows up in Music Assistant as a player you can stream to. **Multi-Room Audio:** Group several CAST-1s 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. diff --git a/docs/products/cast1/setup/cast1-switch-firmware.md b/docs/products/cast1/setup/cast1-switch-firmware.md new file mode 100644 index 0000000000..9384f5c1c8 --- /dev/null +++ b/docs/products/cast1/setup/cast1-switch-firmware.md @@ -0,0 +1,51 @@ +--- +title: CAST-1 Switch Firmware +description: >- + Step by step guide to switching between Wi-Fi and Ethernet firmware on + CAST-1. +--- +# Switch Firmware + +Every CAST-1 ships on Wi-Fi firmware, because not everyone has Ethernet where their speakers are. Once you've installed the [Ethernet module](https://wiki.apolloautomation.com/products/cast1/addons/ethernet-module/), switch your CAST-1 to the Ethernet firmware to use the wired connection. You can switch back whenever you want. + +!!! tip "You can also switch over USB instead of from Home Assistant." + + The Apollo CAST-1 Installer flashes either the **WiFi** or **Ethernet** variant straight from your browser. Pick the variant you want, then follow the reflashing guide for the boot mode steps. Use this if your CAST-1 is on a network that can't reach github.com, since the steps below download the firmware image from our GitHub repo. + +### Switch to Ethernet + +1\. Plug the Ethernet cable into your CAST-1 before you start. (1) +{ .annotate } + +1. The Ethernet firmware has no Wi-Fi at all. If the cable isn't connected when it reboots, the CAST-1 has no way onto your network and you'll have to reflash it over USB. + +2\. Open the ESPHome integration, then click through to your Apollo CAST-1 to open its device page. + +Open your Home Assistant instance and show the ESPHome integration. + +3\. Scroll down to the **Firmware Type** dropdown and select **Ethernet**. + +4\. Find the **Firmware Update** entity and click **PRESS**. + +5\. Wait a few minutes. The CAST-1 downloads the Ethernet image, installs it, and reboots onto the wired connection. + +6\. Home Assistant reconnects to your CAST-1 automatically. Check the **IP Address** sensor on the device page to confirm the wired connection came up. + +### Switch to Wi-Fi + +1\. Open the ESPHome integration, then click through to your Apollo CAST-1 to open its device page. + +Open your Home Assistant instance and show the ESPHome integration. + +2\. Scroll down to the **Firmware Type** dropdown and select **WiFi**. + +3\. Find the **Firmware Update** entity and click **PRESS**. + +4\. Wait a few minutes while the CAST-1 downloads and installs the Wi-Fi image, then reboots. + +5\. Your CAST-1 rejoins the Wi-Fi network it used before. If it doesn't come back, it will broadcast the "**Apollo CAST 1 Hotspot**" network so you can enter your Wi-Fi details again. (1) +{ .annotate } + +1. The [Getting Started guide](https://wiki.apolloautomation.com/products/cast1/setup/getting-started/) walks through connecting over the hotspot. + +[Join our Discord if you need more help! :simple-discord:](https://link.apolloautomation.com/discord){ .md-button } diff --git a/docs/products/cast1/setup/getting-started.md b/docs/products/cast1/setup/getting-started.md index 60c6b45968..09c45cf6d5 100644 --- a/docs/products/cast1/setup/getting-started.md +++ b/docs/products/cast1/setup/getting-started.md @@ -15,12 +15,13 @@ Run a 3.5mm cable from the CAST-1 into the line-in on your powered speakers, rec ![](/assets/cast-1-physical-setup.webp) -### Connect to Wi-Fi +### Connect to Your Network -There are two ways to get your CAST-1 online. Pick whichever is easier, you only need to do one. +There are three ways to get your CAST-1 online. Pick whichever is easier, you only need to do one. - **Hotspot** works on any phone or computer. The CAST-1 broadcasts its own Wi-Fi network, you join it, then enter your Wi-Fi details. No extra hardware needed. - **Improv via BLE** sets the CAST-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** is for a CAST-1 with the Ethernet add-on module fitted. It connects over a network cable straight to your router or switch. === "Hotspot" @@ -56,7 +57,23 @@ There are two ways to get your CAST-1 online. Pick whichever is easier, you only ![](/assets/cast-1-add-via-improv-ble.gif) -Once your CAST-1 is on Wi-Fi, add it to Home Assistant below. If you used **Improv via BLE** it's already added, so you can jump straight to [installing Music Assistant](#music-assistant). + Improv adds your CAST-1 to Home Assistant as part of setup, so skip ahead to [installing Music Assistant](#music-assistant). + +=== "Ethernet" + + Wired setup needs the Ethernet module fitted and your CAST-1 running the Ethernet firmware. + + With the CAST-1 unplugged, line the module's pins up with the two rows of female header pins on top of the case, pin side down, and press it straight down until it sits flat. + + ![](/assets/cast-1-connect-ethernet-module.webp) + + 1\. Every CAST-1 ships on Wi-Fi firmware, so flash yours over to Ethernet first. Follow the reflashing guide and select **Ethernet** under **Variant**. + + 2\. Plug an Ethernet cable into the module, then plug the CAST-1 into power. + + 3\. Your CAST-1 picks up an address from your router on its own, so there's nothing to enter. + + 4\. Home Assistant discovers your CAST-1 automatically. Add it below, then check the **IP Address** sensor on the device page to confirm the wired connection came up. ### Add to Home Assistant @@ -92,6 +109,8 @@ The CAST-1 streams through