Documentation for asterisk_mbox component (#2908)

* Add asterisk_mbox documentation

* Bad filename

* Capitalization error

* Update documentation based on changes to the mailbox implementation

* Typos as per review

* Remove mailbox sensor, since the functionality is included in the mailbox component.  Added ha_version to each file since the code has now been merged.
This commit is contained in:
PhracturedBlue 2017-08-08 04:27:04 -07:00 committed by Fredrik Lindqvist
parent 92ca2cb93d
commit 6ccf851546
5 changed files with 180 additions and 0 deletions

View File

@ -0,0 +1,42 @@
---
layout: page
title: "Asterisk Voicemail"
description: "Instructions how to integrate your existing Asterisk voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Other
ha_version: 0.51
ha_iot_class: "Local Push"
---
The Asterisk Voicemail integration for Home Assistant allows you to view, listen-to, and delete voicemails from a Asterisk voicemail mailbox. The component includes a panel on the frontend that provides caller-id and speech-to-text transcription (using Google's API) of messages in addition to playback and message deletion. There is also an included sensor that provides an indication of the number of available messages. There is no requirement that the Asterisk PBX and Home Assistant are running on the same machine.
To enable the component, configuration is required in both Home Assistant as well as on the Asterisk server.
First follow the [Asterisk PBX configuration guide](/docs/asterisk_mbox) to setup the necessary server on the Asterisk PBX server (this is necessary even if Asterisk and Home Assistant are running on the same server)
Once that is complete, add the the following entry `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
asterisk_mbox:
password: ASTERISK_PBX_PASSWORD
host: ASTERISK_PBX_SERVER_IP_ADDRESS
port: ASTERISK_PBX_SERVER_PORT
```
This will add a new 'Mailbox' side-panel, as well as a sensor to indicate # of messages available.
Configuration variables:
- **password** (*Required*): The password that was set during Asterisk PBX confguration
- **host** (*Required*): The ip-address of the server that is running the Asterisk PBX
- **port** (*Required*): The port on the Asterisk PBX server that was configured during Asterisk PBX confguration
<p class='note warning'>
Communication between the Asterisk PBX server and the Home Assistant server is password-protected, but the data transmission is not encrypted. It is recommended to only use this component when communication will be contained within a local area network.
</p>

View File

@ -31,6 +31,7 @@ Available demo platforms:
- [Switch](/components/switch/) (`switch`)
- [Text-to-speech](/components/tts/) (`tts`)
- [Weather](/components/weather/) (`weather`)
- [Mailbox](/components/mailbox/) (`mailbox`)
To integrate a demo platform in Home Assistant, add the following section to your `configuration.yaml` file:

View File

@ -0,0 +1,15 @@
---
layout: page
title: "Asterisk Voicemail Mailbox"
description: "Instructions how to integrate an Asterisk Voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
ha_category: Mailbox
ha_version: 0.51
---
The Asterisk Voicemail Mailbox provides visual and audio access to voicemail on the Asterisk PBX server. This mailbox is enabled automatically through the [Asterisk Voicemail component](/components/asterisk_mbox) configuration.

View File

@ -0,0 +1,18 @@
---
layout: page
title: "Mailbox"
description: "Instructions how to setup your mailboxes with Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
ha_version: 0.51
footer: true
---
Mailboxes provide an list of messages with short information about each. Mailbox messages appear on a separate panel in the frontend.
Home Assistant currently supports only the [Asterisk Vaoicemail](/component/mailbox.asterisk_mbox) mailbox.
Each mailbox also provides an entity to indicate the number of messages available on the main page.

View File

@ -0,0 +1,104 @@
---
layout: page
title: "Asterisk Voicemail Server Installation"
description: "Instructions how to integrate your existing Asterisk voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
---
Asterisk Voicemail integration allows Home Assistant to view, listen-to, and delete voicemails from a Asterisk voicemail mailbox.
There are two components to the integration:
- A server that runs on the Asterisk PBX host and communicates over an open port.
- A client which can request inormation from the server.
Both parts are necessary for Asterisk voicemail integration.
The server installation is documented below. The client is [integrated inside Home Assistant](/components/asterisk_mbox)
<p class='note'>
Currently this module can only monitor a single Asterisk PBX mailbox. Multiple mailbox support is planned for the future
</p>
### {% linkable_title Prerequisites %}
Before beginning make sure that you have the following:
- A functional Asterisk PBX setup which is using the default `voicemail` application
- Both Home Assistant and Asterisk PBX running on the same LAN (or the same server)
- The Asterisk PBX server has python 3.4 or newer installed
- Administrator access on the Asterisk PBX (for python module installation)
- Account Access to the `asterisk` user that runs the Asterisk PBX software
### {% linkable_title Installation %}
1. Apply for a Google API key to enable speech-transcription services
2. Install the `asterisk_mbox_server` python module:
```bash
$ pip3 install asterisk_mbox_server
```
3. Create a configuration file for the server
As the `asterisk` user create a `asterisk_mbox.ini` file (You can place this in any directory you choose, but the rommended location is `/etc/asterisk/asterisk_mbox.ini`)
```ini
[default]
host = IP_ADDRESS
port = PORT
password = PASSWORD
mbox_path = PATH_TO_VOICEMAIL_FILES
cache_file = PATH_TO_CACHE_FILE
google_key = GOOGLE_API_KEY
```
- **host** (*Optional*): The IP address to listen on for client requests. This defaults to all IP addresses on the server. To listen only locally, choose `127.0.0.1`
- **port** (*Optional*): The port to listen on for client requests. (default: 12345)
- **password** (*Required*): A password shared between client and server. Use only alpha-numeric characters and spaces
- **mbox\_path** (*Required*): The path to the storage location of mailbox files. This is typically `/var/spool/asterisk/voicemail/default/<mailbox>/`
- **cache\_file** (*Required*): A fully-qualified path to a file thht can be written by the server containing transcriptions of voicemails. Example: `/var/spool/asterisk/transcription.cache`
- **google\_key** (*Required*): Your 40 character Google API key
Once complete, ensure this file is only accessible by the asterisk user:
```bash
$ sudo chown asterisk:asterisk /etc/asterisk/asterisk_mbox.ini
$ sudo chmod 600 /etc/asterisk/asterisk_mbox.ini
```
4. Interactively start the server to verify it is functioning
```bash
$ sudo -u asterisk asterisk_mbox_server -v --cfg /etc/asterisk/asterisk_mbox.ini
```
Now complete the [Home Assistant configuration](/components/asterisk_mbox) and verify that Home Assistant can communicate with the server
You can use `Ctrl-C` to terminate the server when done testing
5. Configure the server to start automatically
Copy the following code into `/etc/systemd/system/asterisk_mbox.service`:
```ini
[Unit]
Description=Asterisk PBX voicemail server for Home Assistant
Wants=network.target
After=network.target
[Service]
Type=simple
User=asterisk
Group=asterisk
ExecStart=/usr/local/bin/asterisk_mbox_server -cfg /etc/asterisk/asterisk_mbox.ini
Restart=on-failure
[Install]
WantedBy=multi-user.target
```
<p class='note'>
This assumes that your Asterisk PBX server is using `systemd` for init handling. If not, you will need to create the appropriate configuration files yourself.
</p>