Python 3 module that emulates Belkin WeMo devices for use with the Amazon Echo.

• Documentation: fauxmo.readthedocs.org

The Amazon Echo is able to control certain types of home automation devices by voice. Fauxmo provides emulated Belkin Wemo devices that the Echo can turn on and off by voice, locally, and with minimal lag time. Currently these Fauxmo devices can be configured to make requests to an HTTP server or to a Home Assistant instance via its Python API and only require a JSON config file for setup.

As of version 0.3.0, Fauxmo uses the new asyncio module and therefore requires Python >= 3.4*. Python >= 3.5 is encouraged, in case I decide to use the new async and await keywords in the future.

* Fauxmo 0.3.0 required Python >= 3.4.4, but Fauxmo 0.3.2 has restored compatibility with Python >= 3.4.0.

1. python3 -m pip install fauxmo
2. Make a config.json based on config-sample.json
3. fauxmo -c config.json [-v]

1. pip install [-e] git+https://github.com/n8henrie/fauxmo.git@dev

1. git clone https://github.com/n8henrie/fauxmo.git
2. cd fauxmo
3. python3 -m venv venv
4. source venv/bin/activate
5. pip install -e .
6. cp config-sample.json config.json
7. Edit config.json
8. fauxmo [-v]

1. Open the Amazon Alexa webapp to the Smart Home page
2. With Fauxmo running, click "Discover devices" (or tell Alexa to "find connected devices")
3. Ensure that your Fauxmo devices were discovered and appear with their names in the web interface
4. Test: "Alexa, turn on [the kitchen light]"

1. Recommended: add an unprivileged user to run Fauxmo: sudo useradd -r -s /bin/false fauxmo
   • NB: Fauxmo may require root privileges if you're using ports below 1024
2. sudo cp extras/fauxmo.service /etc/systemd/system/fauxmo.service
3. Edit the paths in /etc/systemd/system/fauxmo.service
4. sudo systemctl enable fauxmo.service
5. sudo systemctl start fauxmo.service

1. cp extras/com.n8henrie.fauxmo.plist ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist
2. Edit the paths in ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist
   • You can remove the StandardOutPath and StandardErrorPath sections if desired
3. launchctl load ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist
4. launchctl start com.n8henrie.fauxmo

Fauxmo has an example REST handler class that reacts to on and off commands using the python-requests library as well as a handler for the Home Assistant Python API; these are examples of a multitude of ways that you could have the Echo trigger an action. In config-sample.json, you'll see examples of:

• A GET request to a local server
• A POST request to the Home Assistant REST API
• A PUT request to an Indigo server
• Requests to Home Asssistant's Python API

I recommend that you copy and modify config-sample.json. Fauxmo will use whatever config file you specify with -c or will search for config.json in the current directory, ~/.fauxmo/, and /etc/fauxmo/ (in that order).

• FAUXMO: General Fauxmo settings
  • ip_address: Manually set the server's IP address. Optional. Recommended value: auto
• DEVICES: List of devices that will employ RESTAPIHandler
  • port: Port that Echo will use connect to device, should be different for each device
  • handler: Dictionary for RESTAPIHandler configuration
    • on_cmd: URL that should be requested to turn device on
    • off_cmd: URL that should be requested to turn device off
    • method: GET, POST, PUT, etc.
    • headers: Optional dict for extra headers
    • on_json / off_json: Optional dict of JSON data
    • on_data / off_data: Optional POST data
    • auth_type: basic or digest authentication, optional
    • user / password: for use with auth_type, also optional
  • description: What you want to call the device (how to activate by Echo)
• HOMEASSISTANT: Section for Home Assistant Python API
  • enable: Disable this section by omitting or setting to false
  • host: IP of host running Hass
  • port: Port for Hass access (default: 8123)
  • password: Hass API password
  • DEVICES: List of devices that will employ HassApiHandler
    • description: What you want to call the device (how to activate by Echo)
    • port: Port that Echo will use connect to device, should be different for each device
    • entity_id: Hass identifier used in API, one easy way to find is to curl and grep the REST API, eg curl http://IP_ADDRESS/api/bootstrap | grep entity_id

• How can I increase my logging verbosity?
  • -v[vv]
• How can I ensure my config is valid JSON?
  • python -m json.tool < config.json
  • Use jsonlint or one of numerous online tools
• How can I install an older / specific version of Fauxmo?
  • Install from a tag:
    • pip install git+git://github.com/n8henrie/[email protected]
  • Install from a specific commit:
    • pip install git+git://github.com/n8henrie/fauxmo.git@d877c513ad45cbbbd77b1b83e7a2f03bf0004856
• Where can I get more information on how the Echo interacts with devices like Fauxmo?
  • Check out protocol_notes.md

sudo install -o $(whoami) -g $(whoami) -d /opt/pyenv
git clone https://github.com/yyuu/pyenv /opt/pyenv
echo 'export PYENV_ROOT="/opt/pyenv"' >> ~/.bashrc
echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc
pyenv install 3.5.1

You can then install Fauxmo into Python 3.5 in a few ways, including:

# Install with pip
"$(pyenv root)"/versions/3.5.1/bin/python3.5 -m pip install fauxmo

# Run with included console script
fauxmo -c /path/to/config.json -vvv

# Show full path to fauxmo console script
pyenv which fauxmo

# I recommend using the full path for use in start scripts (e.g. systemd, cron)
"$(pyenv root)"/versions/3.5.1/bin/fauxmo -c /path/to/config.json -vvv

# Alternatively, this also works (after `pip install`)
"$(pyenv root)"/versions/3.5.1/bin/python3.5 -m fauxmo.cli -c config.json -vvv

• Tremendous thanks to @makermusings for the original version of Fauxmo!
  • Also thanks to @DoWhileGeek for commits towards Python 3 compatibility
• http://www.makermusings.com/2015/07/13/amazon-echo-and-home-automation
• http://www.makermusings.com/2015/07/18/virtual-wemo-code-for-amazon-echo
• http://hackaday.com/2015/07/16/how-to-make-amazon-echo-control-fake-wemo-devices
• https://developer.amazon.com/appsandservices/solutions/alexa/alexa-skills-kit
• https://en.wikipedia.org/wiki/Universal_Plug_and_Play
• http://www.makermusings.com/2015/07/19/home-automation-with-amazon-echo-apps-part-1
• http://www.makermusings.com/2015/08/22/home-automation-with-amazon-echo-apps-part-2