Background
I just discovered the wonderful local Voice Assistant pipeline. After building a terminal with ESP32 and enduring a few days of its instability, I decided to try other methods. I found out that there is a VoIP integration which basically opens up a public SIP server inside HA, and external SIP clients can dial in to access the voice assistant. Nice.
Digging down the hole of VoIP I also found the DSS VoIP Notifier, which is an addon that can be programmatically called to actively dial out through VoIP and play a predefined audio file. Also nice since this is a function I wanted before.
Now the problem is how to make them work together? The Assist integration acts like a server, and the DSS Notifier acts like a client (again no field knowlege here, terms may be incorrect). I think I may need some external server to allow the Notifier to send the call to other devices, and also forward the call from other devices to the Assist server. The server also need to be able to transcode the voice data, since the Assist server only supports OPUS codec which may not be supported by other clients.
I have found this tutorial which looks great, but the configuration file never worked for me. I have fiddled around with the Asterisk addon for almost a day and it’s becoming frustrating. Then I remembered there is something called FreePBX, which provides a comprehensive UI to the underlying Asterisk. So let’s try that!
DISCLAIMER
I have zero knowledge about SIP/Asterisk before. Everything is whipped up through other tutorials, trial and error etc. This is more like a note for myself. It may not work even if you follow it exactly and I may not be able to answer your questions. Also the setup of the FreePBX server does not meet basic security standards. If you want to use it for a prolonged time you need to also consider and harden the instance yourself. Sorry for that.
Prerequisite
It assume that you have HAOS or a supervised installation (since addon will be used), and you have a working Voice Assistant Pipeline.
Blueprint
Because the aforementioned difference in working mechanism, we need to split the HA part into two directions:
An SIP account on the server for the DSS Notifier, so that it can call me. I choose the extension to be
998.
An SIP trunk (think it as the cable to the carrier company for landline or the WAN connection of your router, allow you to dial something outside the local server) to HA’s Assist SIP server, and an outbound rule to remap an extension to that trunk so that you can dial to the Assist. I choose the rule matching extension to be
999.
And of course an SIP account on the server for myself, which I will use with my actual phone (here I use a software phone for testing purposes) to call
999and receive calls from998. I choose the extension to be100.
Installation
Install it however you’d prefer. Since I decided to enclose my instance inside the LAN and this is more for testing purposes, I didn’t enable the firewall. If your installation would be otherwise, you must enable that and configure the rules accordingly.
Setup
After you have finished up the initial setup wizard, you will be presented with the dashboard.
Two things to note:
Each time when you save something by clicking
Submit, a redApply Configbutton will appear on the menu bar in the top right corner of the page. You MUST click that to make your new configuration effective.
Do NOT connect your client to the network UNTIL you have correctly configured the server information (provisioning). FreePBX has
fail2banpreinstalled and if the client trys to connect with invalid credentials for too many times, it will cut the connection completely. If you are testing with software clients, it will even cause the WebUI to also be unavailable on that machine (which I have stumbled on upon).
Set up default codec
Go to Settings -> Asterisk SIP Settings, scroll down to Audio Codecs.
Find opus, check it and drag it to the top. However do NOT uncheck other common codecs since you may need them for the clients.
Click Submit to save and the red button to apply.
Set up extensions
Now we will add the clients. Here I will add the extension for myself and the DSS Notifier.
Go to Applications -> Extensions
Click on the Quick Create Extension button, make sure SIP [chan_pjisp] is chosen as the type. Fill in the extension and display name you want.
Click Next, choose Enable Voicemail to NO and click Finish. Do that again to add the other extension.
Here I use [100] whc2001 and [998] homeassistant_outbound accordingly. When confuguration finished, the extension page should be looking like this:
Don’t forget to click the red button to apply.
Test the extensions
Now we can setup two phones to the created two accounts and test if they can connect each other. Here I am using MicroSIP.
Click the edit button on the right of each account and find the secret field. This is the password you need for the SIP client to connect. You can copy the default random password, or change them as you want and apply.
Add the account to your client. The procedure varies with each product, but the key fields are the following:
SIP server: use the IP address of your FreePBX server
Domain: use the IP address of your FreePBX server
User Name: use the account extension number
Login: use the account extension number
Password: use the secret you just copied/changed
It should look like this (sorry for the Chinese, didn’t find the language setting in MicroSIP):
After saving your client should be connected to the server.
Do that again with another client, then try to call each other’s extension and it should work bidirectionally.
Connect the DSS Notifier
Now turn off the SIP client registered with the account for the DSS Notifier (here extension 998), but keep the other one running. We are going to replace the test client with the actual DSS Notifier.
Add the addon repo to HA, then install the DSS VoIP Notifier addon.
Go to the Configuration tab of the addon, fill in the informations:
caller_id_uri: use
sip:<extension number>@<server IP>
username: use the extension number (remember the quotes as YAML requires that)
password: use the corresponding secret
Go to the Info tab, click Start to run the extension.
Go to the Developer Tools of HA, select Services tab, find the service called hassio.addon_stdin. This is how we send the command into the addon. Select the correct addon, then click the Go To YAML Mode on the bottom left.
In the data section of the YAML, add input field and fill in a JSON according to the addon documentation. The call_sip_uri need to be sip:<target extension number>@<server IP>, and other parameters you need to refer to the documentation. Here I am using the audio_file_url to play an MP3 to the phone. If you want to use message_tts make sure you have tts configured in the configuration.yaml.
Click Call Service, and your own extenstion should immediately get a ring-in from the preconfigured extension. Lift the (virtual) handset and you will hear the message you set.
Reroute a nonexistent extension to HA’s Assist
We are halfway done! One direction is working and now we need to configure the other. We first introduce the external SIP server to FreePBX, then hijack a nonexistent extension to it (kind like DNS hijacking I guess?).
Add the VoIP server integration to HA
Just like how you would add an integration, search for VoIP and add it. Now HA would have port 5060 running as an SIP server.
Add the HA’s server as a trunk
Go to Connectivity -> Trunks, add a new SIP (chan_pjisp) trunk.
In the General tab, set a trunk name.
In the Dialed Number Manipulation Rules tab, fill in the nonexistent extension you wanted to use in the match pattern field (here I choose 999)
In the pjsip Settings -> General tab, since HA’s SIP server don’t require authentication, set the following fields:
Authentication: set to None
Registration: set to None
SIP Server: set to your FreePBX server IP
SIP Server Port: keep default (5060) unless you have changed that
In the pjsip Settings -> Advanced tab, set AOR and AOR Contact to sip:<extension number>@<server IP>.
In the pjsip Settings -> Codecs tab, select and bring to the top the opus codec. The setting here may influence globally, so again do NOT uncheck the others.
Click Submit. You can ignore the warning about the unset CallerID. Do not forget to click the red button to apply.
Configure outbound route to forward the nonexistent extension to that trunk
Now if you click the edit button on the trunk you have just created, you will see a warning.
That’s because we haven’t told FreePBX how to use that trunk. We need to add an Outbound Rule. Click Connectivity -> Outbound Routes, or just the link in the warning to the configure page.
In the Route Settings tab, give the route a name, and select your newly created trunk in the Trunk Sequence for Matched Routes field.
In the Dial Patterns tab, again fill in the nonexistent extension you wanted to use in the match pattern field.
Click Submit to save and the red button to apply. Now go to your phone client, dial the extension you just set and you should be able to hear the voice prompt (This is your smart home speaking…)
Now just follow the official document, turn on the switch in the integration devices to allow the access to Assist inside HA. Dial again and you will hear a beep, then you can start interacting with the Assist.