Ever wanted to have your space sound like the engineering department of the Enterprise D? Maybe the warp core of Voyager in your home theater? Maybe you are in the mood for a rainstorm in your bed as you sleep. These are the kinds of things that pop into my head, and on long winter nights I make come true. If this is your jam then come along on this adventure! 

Prerequisites

Home Assistant

This project requires some things that need to be already in place. We will be using Home Assistant . Home assistant is a home automation system that you can build from the ground up for free, or buy pre-installed on a Raspberry Pi platform. The advantage of Home Assistant over other systems is that it can be operated cloud-free. This is paramount for people who value their privacy. The set up and install of Home Assistant is out of scope here, but it is something I will revisit in the future. It's not terribly hard to set up and even easier if you purchase the pre-built ones. If you don't already have this in place drop by their website and have a look around. If you already have it installed and working then onward we go! 

A stereo system with speakers.

Next let's consider that we want to make this environmental. That means that hooking it up to your home stereo won't be an option because you don't want this to be interrupted by your usual habits of music listening or nightly bit of binge watching. This is a great task for that old stereo you kept in the closet for ages, or a small inexpensive amplifier with an AUX in. This is also a great way to upcycle older equipment that has aged out or can be bought at a swap meet or flea market. There is no need for large exotic speakers or subwoofers, but hey - if you have them hanging around why not use them? Remember that speaker kit you bought for your home computer ages ago that you no longer use? Time to repurpose it! Get creative with multiple speakers , room speakers, or entire house wide speakers. The only limits are your imagination!

Parts!

How It Works

This is important because the way I deployed this may seem unintuitive or unusual, but it overcomes several limitations in the software we are using and keep things relatively secure. If you find a way that works better for you or meets your needs then huzzah! This is meant to be a guide for how I did it, using the system that is working in my home right now. Your mileage may vary :) 

In the broad strokes the process goes like this : 

HA dashboard button --> HA server --> SSH to Raspberry PI --> Run shell script to play audio

Depending on if the audio file is an environmental sound to be repeated or a sample to be played once there will be some variances in the shell script on the Pi. 

The way Home Assistant communicates via ssh, this system is designed to connect, execute the shell script for the sound or sample, then exit. This keeps the storage of the sound files, the player, and the load on the Pi and not on your Home Assistant server. IT also allows you to place the pi closer to the stereo that will be playing the sounds and not have to run long lengths of audio cable. 

You should be comfortable with Home Assistant, SSH, generating SSH keypairs, and basic shell scripting. Luckily for you if you need help with these assistance is just a google search away. I'll do my best to make this detailed and working, however the world changes quickly and software may change in the future. 

This system was made with : 

• Raspberry Pi 4 hardware
• Raspberry Pi OS : Bookworm 
• Home Assistant : 2023.12.3

Prepare The Pi

Part one : Assemble the Pi and the case.

This is pretty straightforward, but there are some tricky bits about it. The case is designed to hold both the Pi and the touchscreen monitor. Depending on which case you choose, make sure to follow the directions provided and to ensure that you do not pinch off any cables. The case listed in the parts manifest above has a link to a video showing the assembly. At some point I will update this with pictures, but I don't have any at the moment. 

Part Two : Install the OS onto the Pi. 

For best results follow the directions provided at The Pi home page . This will install the latest version of the Raspbian OS and walk you through the configuration. In order to make things easier down the line, here are a few things to do while installing the OS : 

• Choose the device that matches your Pi ( Pi 4 in this case ) 
• Install the full 64 bit version of the OS
• Choose to customize the OS before burning it to the SD card : 
  • Under the GENERAL tab
    • Set a host name for the Pi ( in our example we will call it ENV ) 
    • Set a user name and password ( For our example we will use YOURNAME , and pick a good password, please! ) 
    • If you are using Wifi , enter the WiFi information. If not don't worry, we will set up the Ethernet settings later. I strongly suggest using a Ethernet connection for this for security purposes. 
  • Under the SERVICES tab
    • Enable SSH

Let the installer work its magic, then install the SD card in the Pi and ensure it properly boots and that the touch screen is working. 

Part Three : Configure the Pi

Attach a keyboard and mouse to the Pi.

Log into the Pi using the credentials you set up ( YOURNAME and the good password you chose ). 

Perform the following commands from the shell : 

• Ensure that the operating system and installed software is up to date : 
  • sudo apt update
  • sudo apt full-upgrade
• Configure the Ethernet connection 
  • nmutl
• If you are like me and you think the older ways of verifying this is done correctly are better, run this command as well to bring back  ifconfig  and nslookup.
  • sudo apt install dnsutils
• Configure the Pi to auto login at startup. This will allow the Pi to run as a kiosk, and you can have it act as a control panel for Home Assistant as well as play your environmental sounds and samples. 
  • sudo raspi-config
  • Select System Options, option 1 , then Express Autologin option B4 as the name you set when installing the OS  (B4)
• Configure the Pi to open the browser and go to your Home Assistant main menu at startup. Using your favorite editor ( I'll use vi here ) use the following command : 
  • sudo vi .config/wayfire.ini
  • Add the following lines to the end of the file : 
    

    [autostart]
    panel = wfrespawn wf-panel-pi
    background = wfrespawn pcmanfm --desktop --profile LXDE-pi
    xdg-autostart = lxsession-xdg-autostart
    chromium = chromium-browser https://( YOUR HA ADDRESS AND MAIN MENU ) --kiosk --noerrdialogs --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --start-maximized
    switchtab = bash ~/switchtab.sh
    screensaver = false
    dpms = false
    
    

    Replace the part in paracentesis with your local Home Assistant address and main menu. For example : 
  • chromium = chromium-browser http://homeassistant.lan:8123/environmental-audio/default_view --kiosk --noerrdialogs --disable-infobars --no-first-run --ozone-platform=wayland --enable-features=OverlayScrollbar --start-maximized

The next few steps may seem odd at first, but they will make sense once everything is in place. 

• Turn the volume on your stereo all the way down.

• Connect the 3.5mm --> RCA cable to the audio out on the Pi, and to the AUX IN on the stereo. 
• Using your favorite method, transfer two files from your main computer to the ./Music directory on the pi. Make one of them an environmental sound file, and make the other a sample to play. For example let's make the first one oceanwaves.mp3 and the second one huzzah.mp3
• Turn the volume up slightly on your stereo, and test to ensure that the Pi is sending your audio out properly : 
  • vlc --play-and-exit ./Music/huzzah.mp3
    
    
• You should hear the grand call of "Huzzah" as done by Peter Dinklage.
• Now we will make two batch files to play these files, and one to stop any that are repeating.
  These batch files will be called by Home Assistant, and will be located in your home directory ( not in Music )
  
  
  
• vi go-ocean.sh

kill -9 $(pgrep vlc)
/usr/bin/cvlc -I dummy -R ./Music/oceanwaves.mp3& 

• vigo-huzzah.sh

/usr/bin/cvlc -I dummy --play-and-exit ./Music/huzzah.mp3& 

• vigo-silence.sh

kill -9 $(pgrep vlc)

Next we need to make sure that these files are executable from the command line, so .... 

• chmod +x go-oceanwaves.sh
• chmod +x go-huzzah.sh
• chmod +x go-silence.sh

If we test these in order from the command line , here's what will happen :

• ./go-oceanwaves.sh
  • The ocean waves will play on repeat, and you will get your command prompt back as it is running in the background.
• ./go-huzzah.sh
  • While the ocean waves are playing, you will hear a shout of "Huzzah!". This plays once then exits to the command prompt.
• ./go-silence
  • The ocean waves stop, and you will hear silence. 

Now that this is done, reboot the Pi and ensure that it comes back up in kiosk mode with your Home Assistant login page. Don't log in just yet, leave it like it is and we will come back to finish this part of the configuration. 

Part Four : Configure Home Assistant

So now we have to do a few things to Home Assistant in order to make this magic work. 

First off , we need to establish passwordless communication between your HA server and the Pi that is playing the sounds. This is done using SSH and public/private key files. 

• Log in to your HA with administrator rights, and navigate to "TERMINAL"
• Create the keypair for your HA server in the /config/.ssh directory.
  • ssh-keygen -t rsa -b 4096
• This will generate two files , id_rsa ( Private Key )  and id_rsa.pub ( Public Key ) 
• Copy the content of the PUBLIC key to your Pi into the file  .ssh/authorized_keys on your Pi.
• Test the setup from your HA Terminal window : 
  • ssh -i /config/.ssh/id_rsa (yourname)@(address of your pi) 
  • You should get a shell prompt from your Pi. Type exit to return to the shell in your HA server. 

Next we need to configure your HA instance to send commands to your Pi, triggering the shell scripts you made. 

You need to edit your /homeassistant/configuration.yaml file. I use the add-on file editor to do this. Make sure yto replace (yourname) and (YourPi) with the user ID and address of your Pi.

All the following lines to the end of your configuration.yaml file : 

shell_command:

   sound_ocean: ssh -o StrictHostKeyChecking=no -i /config/.ssh/id_rsa (yourname)@(yourpie) 'nohup ./go-ocean.sh > output.log 2>&1 & exit'

      sound_huzzah: ssh -o StrictHostKeyChecking=no -i /config/.ssh/id_rsa (yourname)@(yourpie) 'nohup ./go-huzzah.sh > output.log 2>&1 & exit'

     sound_silence: ssh -o StrictHostKeyChecking=no -i /config/.ssh/id_rsa (yourname)@(yourpie) 'nohup ./go-silence.sh > output.log 2>&1 & exit'

Once this is done restart your Home Assistant instance. 

Next we create the helper object : 

• From SETTINGS select HELPERS
• Select CREATE HELPER
• Select Create Helper
• Name : Environmental Audio
• Icon : mdi:speaker

Now all that's left is to add the buttons to a dashboard to trigger these sounds. 

Open whichever dashboard you would like to add these to in the dashboard editor and do the following : 

• Select "Add Card"
• Entity : Environmental Audio
• Name : Ocean
• Tap action : Call Service
• Service : shell command: sound_ocean

Repeat this for Huzzah and silence, replacing sound_ocean with sound_huzzah or sound_silence.

After saving your dashboard, load it up and try it out! 

That's it! 

It's been a long road, but this is what it looks like on my side. Note that I am using the LCARS theme so mine looks a bit trek-like , but it's the same stuff done here. My apartment now sounds like the engineering deck on the Enterprise-D and I can chalk up a few more nerd points! 

Happy hacking!