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.

source/_docs/asterisk_mbox.markdown

@@ -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>