Skip to content

Latest commit

 

History

History
138 lines (77 loc) · 6.28 KB

DOCS.md

File metadata and controls

138 lines (77 loc) · 6.28 KB

Home Assistant Add-on: Asterisk

Asterisk is a free and open source framework for building communications applications. Asterisk powers IP PBX systems, VoIP gateways, conference servers, and is used by SMBs, enterprises, call centers, carriers and governments worldwide.

Installation

Follow these steps to get the add-on installed on your system:

  1. Click here:

    Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled.

  2. Scroll down the page to find the new repository, and click in the new add-on named Asterisk.

  3. Click in the INSTALL button.

Or you can also use it as a standalone docker container. See 4.0.0 release notes for more information.

Using

  1. The certificate to your registered domain should already be created via the Duck DNS or Let's Encrypt add-on or another method. Make sure that the certificate files exist in the /ssl/ directory.
  2. Check the add-on configuration by going to the Configuration tab. You need to at least fill the AMI Password and the Auto add secret (if you leave Auto add extensions enabled).
  3. Start the add-on by clicking in the START button.

Configuring Asterisk

The add-on copies all the default Asterisk config files to /config/asterisk/default on the add-on startup for your reference, and reads all customized config files from /config/asterisk/custom.

For example, if you need to change something in the /etc/asterisk/extensions.conf, you can copy the reference /config/asterisk/default/extensions.conf to /config/asterisk/custom/extensions.conf and make your changes there.

The way how this works is through symbolic links: if there is a custom config file, a symbolic link is created on top of the default config file pointing to the custom config file. Have in mind that this is only applicable for files under the root of /config/asterisk/custom. For example, the /config/asterisk/custom/subdir/file.conf will not be linked to /etc/asterisk/subdir/file.conf. The same applies to files that starts with a dot, like .gitignore.

Note: Remember to restart the add-on when the Asterisk configuration files are changed.

Configuring the add-on

We expose some configuration options to simplify the setup of the Asterisk server inside of the add-on. See below for more information on each option we provide.

Note: Remember to restart the add-on when the configuration is changed.

Option: ami_password

Set's the password for the Asterisk Manager Interface, to connect to the Asterisk integration.

Option: auto_add

Creates a extension for every person registered in Home Assistant. They will have their number and username auto-generated starting from 100, with the callerid set to the person's name.

This is enabled by default for add-on users but disabled by default for container users.

Option: auto_add_secret

The secret for the auto generated extensions, when auto_add is enabled.

Option: video_support

Enables video support for the auto generated extensions, when auto_add is enabled.

Option: additional_sounds

The additional sounds languages to download from https://asterisksounds.org on add-on startup, skipping when already downloaded. Example: pt-BR.

The sounds will be downloaded to /media/asterisk.

If you want the add-on to re-download the sounds, you can simply remove the folder from /media/asterisk and restart it.

Option: generate_ssl_cert

Enables/disables the generation of a self-signed certificate for use with the SSL interfaces (WSS and TLS).

Option: certfile

The certificate file to use for SSL in your /ssl/ folder, when generate_ssl_cert is disabled. If an absolute path is provided, it will be used as-is.

Option: keyfile

The key file to use for SSL in your /ssl/ folder, when generate_ssl_cert is disabled. If an absolute path is provided, it will be used as-is.

Option: mailbox

Enables the mailbox server to send voicemails to the Asterisk Mailbox integration.

Option: mailbox_port

The port used by the mailbox server.

Option: mailbox_password

The password for the mailbox server.

Option: mailbox_extension

Which extension to get the voicemails from.

Option: mailbox_google_api_key

The API Key for the speech-to-text used by Asterisk Mailbox. You can get a key here. Google says it's free, but requires a billing account.

Option: log_level

The log level to configure Asterisk to use. To know more about the existing presets, check logger.conf.

STDIN service

You can use the STDIN service to run any Asterisk CLI commands that you want. For example:

service: hassio.addon_stdin
  data:
    addon: b35499aa_asterisk
    input: dialplan reload

This is only possible when using as an add-on.

Startup script

If the add-on finds a script at /config/asterisk/startup.sh it will run it before starting Asterisk. You can use this to install custom packages, dependancies, etc.

Configuring the Asterisk integration

  • Host: localhost (when running as an add-on)
  • Port: 5038
  • Username: admin
  • Password: whatever you set in the ami_password configuration

Configuring the SIP.js card

  • Host: localhost (when running as an add-on)
  • Port: 8089
  • Video: false Video is not working at the moment, this will be fixed soon. For now you could use the camera entity instead.

And add a extension. To see which extension every person has, you can look at /config/asterisk/default/sip_default.conf.

Wiki

For more information, visit the SIP-HASS docs.