Connect Doorman to Home Assistant: The Technical Setup

This is the technical companion to Call Home Assistant. Turn On the Lights.. It is for the person administering the Brain’s Linux and Asterisk installation. The optional route is disabled by default and needs hardware-specific verification; this is not a one-click account feature.

The steps follow the project’s Home Assistant runbook and shipped Asterisk examples. They were checked against source and documentation, not rehearsed on a physical handset for this article.

1. Confirm the pieces before editing

You need a working Doorman handset, a reachable Home Assistant installation, and an Assist pipeline that can already control one test lamp. Use a stable Home Assistant address on your trusted home network. Keep the connection private; do not expose SIP or Home Assistant to the public internet to follow this guide.

Save a copy of the Asterisk configuration you will edit. Work at a quiet time when the phone is not needed. If your installation uses different paths or manages these settings through an installer, follow that installation’s process instead of replacing its files.

Check the Brain’s audio support:

sudo asterisk -rx "module show like opus"
sudo asterisk -rx "core show translation"

The example connection needs usable Opus support, including translation to and from the handset codec where required. A listed module alone does not prove that audio will work. If Opus is unavailable or the needed translation path is missing, stop and use codec installation instructions appropriate to your Asterisk version and CPU. There is no universal package command that this article can safely substitute.

2. Prepare Home Assistant

In Home Assistant, add Voice over IP from Settings → Devices & services. Its integration documentation describes the current controls and supported configurations. Confirm Assist can understand and speak back, and expose only the devices you intend the phone to control.

When the first call creates a device entry, inspect that entry and enable Allow calls for the Brain. Home Assistant identifies this connection by its source address; the authorization is not per family member. Its phone tutorial explains this approval step. A first blocked call can therefore be expected during setup.

3. Enable the supplied Asterisk endpoint

Inspect /etc/asterisk/pjsip.conf for the commented homeassistant example. If present, enable it and replace HA_IP_HERE with the address of your Home Assistant installation. If absent, compare your installation with the shipped example before adding anything. Do not create duplicate endpoint or address entries.

[homeassistant]
type=endpoint
context=internal
disallow=all
allow=opus
allow=ulaw
aors=homeassistant
direct_media=no

[homeassistant]
type=aor
contact=sip:assist@HA_IP_HERE:5060

The two sections intentionally share a name but have different types. The port must match Home Assistant’s VoIP listener. This is a local connection, not an outside calling-provider registration.

4. Enable the 555 route

In the installation’s /etc/asterisk/extensions.conf, find the commented line in [features-internal] and remove its leading semicolon:

exten => 555,1,Dial(PJSIP/homeassistant,20)

Confirm 555 is unused in your installation before enabling it. Keep the route in the existing internal feature context; do not add it to the public inbound context or overwrite generated handset files.

Reload the affected configuration, then inspect what Asterisk loaded:

sudo asterisk -rx "pjsip reload"
sudo asterisk -rx "dialplan reload"
sudo asterisk -rx "pjsip show endpoint homeassistant"
sudo asterisk -rx "dialplan show 555@features-internal"

Review errors before proceeding. If the endpoint or route is missing, fix the configuration first.

5. Test the whole conversation

Dial 555 from one authorized handset. Complete Home Assistant’s Allow calls step if necessary, then redial. Ask it to turn on the test lamp and confirm both the physical result and the spoken response. Test turning it off and ending the call cleanly.

If only one side can hear, check codecs, translation, and local network reachability before changing unrelated phone settings. Confirm ordinary handset calls still work. Do not test by dialing emergency services.

To undo the experiment, disable the 555 route and reload the dialplan. Disable the Home Assistant device’s call permission if it is no longer needed; remove the optional endpoint only after confirming nothing else uses it. Leave the rest of the phone configuration intact.