DOCSEARCHbyAlgolia
Submit Docs

fauxmo

repository·master·Indexed 19 days ago

https://github.com/n8henrie/fauxmo

A Python 3 module that emulates Belkin WeMo devices, allowing Amazon Echo devices to control home automation via local voice commands. Fauxmo can trigger HTTP requests (e.g., to Home Assistant) or run local commands based on a JSON configuration. It includes pre-installed plugins such as SimpleHTTPPlugin, CommandLinePlugin, and HomeAssistantPlugin, and supports custom user plugins.

Tokens
10.5K
Snippets
34
Records
46
Agent score
64%

What's inside fauxmo

  1. Understand the Echo and Fauxmo interaction model

    master

    The interaction between an Amazon Echo and Fauxmo follows a specific discovery and setup lifecycle:

    1. Discovery: The Echo broadcasts a UDP 'device search' to 239.255.255.250:1900.
    2. Response: Fauxmo responds via UDP with the LOCATION of the setup.xml endpoint for each configured device.
    3. Request: The Echo performs an HTTP GET request to the provided LOCATION (TCP) to retrieve the setup.xml file.
    4. Setup: Fauxmo responds with the device's setup information in XML format via HTTP.
    5. Completion: Alexa announces the discovered devices, and they appear in the Alexa webapp.

  2. What are Fauxmo plugins and how do they work?

    master

    Plugins (formerly called Handlers) are extendible classes that allow users to create custom actions triggered by Alexa commands. Fauxmo provides several pre-installed plugins in the fauxmo.plugins package, such as SimpleHTTPPlugin, CommandLinePlugin, and HomeAssistantPlugin.

    To function, a plugin must implement a way to handle device state. As of v0.4.5, all plugins must implement a get_state() method. If your device cannot report its actual state, you can return "unknown" or use the use_fake_state configuration flag to return the last successful action (on/off) instead.

  3. Run Fauxmo as a background service with launchd (macOS)

    master

    To run Fauxmo as a background agent on macOS, use launchd with a .plist file.

    # 1. Copy the plist file to your LaunchAgents directory
cp extras/com.n8henrie.fauxmo.plist ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist

# 2. Edit the paths inside ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist
# (You can remove StandardOutPath and StandardErrorPath if desired)

# 3. Load and start the agent
launchctl load ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist
launchctl start com.n8henrie.fauxmo

  4. Create a custom user plugin

    master

    To create a custom plugin, follow these steps:

    1. Define the class: Create a class that inherits from fauxmo.plugins.FauxmoPlugin.
    2. Implement required methods:
      • on(): Logic to execute when the device is turned on.
      • off(): Logic to execute when the device is turned off.
      • get_state(): Logic to return the current state (e.g., "on", "off", or "unknown").
    3. Handle State: If your device cannot report state, you can return super().get_state() in your get_state() method to return the last successful action, provided you use the use_fake_state flag in your config.
    4. Configure: Ensure your plugin's required settings are documented in its module-level docstring. Fauxmo will pass configuration variables from config.json as kwargs to your plugin's __init__ method.

    Note on discovery: Alexa requires a device to report a state during discovery. If your get_state() method cannot return a valid state immediately, Alexa may fail to add the device.

    from fauxmo.plugins import FauxmoPlugin

class FooSwitcherPlugin(FauxmoPlugin):
    def on(self, **kwargs):
        # logic to turn on
        pass

    def off(self, **kwargs):
        # logic to turn off
        pass

    def get_state(self, **kwargs):
        # return "on", "off", or "unknown"
        return "unknown"

  5. Install Fauxmo for development

    master

    To contribute to the project, clone the repository and install it in editable mode with development and test dependencies.

    git clone https://github.com/n8henrie/fauxmo.git
cd fauxmo
python3 -m venv .venv
source ./.venv/bin/activate
pip install -e .[dev,test]

# Setup configuration
cp config-sample.json config.json
# (Edit config.json as needed)

# Run fauxmo
fauxmo [-v]

  6. Find your Echo's IP address using nmap

    master

    To debug network traffic, you first need the IP address of your Echo. You can scan your local subnet using nmap. Replace the subnet mask in the command below with your actual local subnet (e.g., 192.168.1.1/24).

    # Assuming your local subnet is 192.168.27.*
sudo nmap -sP 192.168.27.1/24 | grep -i -B 2 amazon

  7. Install a specific version of Fauxmo

    master

    If you need a specific version or a specific commit of Fauxmo, you can install it directly from GitHub using pip.

    To install from a specific tag:

    pip install git+git://github.com/n8henrie/fauxmo.git@v0.1.11

    To install from a specific commit:

    pip install git+git://github.com/n8henrie/fauxmo.git@d877c513ad45cbbbd77b1b83e7a2f03bf0004856

  8. Discover Fauxmo devices with Amazon Echo

    master

    Once Fauxmo is running with a valid config.json, you must trigger a device discovery on your Amazon Echo to make the emulated WeMo devices visible.

    1. Ensure the Fauxmo server is running.
    2. Open the Amazon Alexa Smart Home webapp.
    3. Click Discover devices (or tell Alexa: "find connected devices").
    4. Verify that your Fauxmo device names appear in the Alexa interface.
    5. Test with a voice command like: "Alexa, turn on [the kitchen light]".

  9. Run Fauxmo using Docker (alpha)

    master

    Fauxmo provides a Docker image (currently in alpha). Because Fauxmo must respond to UPnP broadcasts, you must use --network=host when running the container.

    To run Fauxmo via Docker, build the image locally and mount your configuration file as a read-only volume. Note that you must use an absolute path for the configuration file mapping.

    $ docker run --network=host --rm -it \
    -v $(pwd)/config-sample.json:/etc/fauxmo/config.json:ro \
    "$(docker build -q .)"

  10. Run Fauxmo as a background service with systemd

    master

    To run Fauxmo automatically on Linux (e.g., Raspbian), use systemd. Note that files in extras/ might not be included in PyPI installations; you may need to download them manually from the GitHub repository.

    Note on Privileges: Fauxmo may require root privileges if you are using ports below 1024. It is recommended to create an unprivileged user for running the service.

    # 1. Create an unprivileged user (optional but recommended)
sudo useradd -r -s /bin/false fauxmo

# 2. Copy the service file (ensure extras/fauxmo.service is available)
sudo cp extras/fauxmo.service /etc/systemd/system/fauxmo.service

# 3. Edit the paths inside /etc/systemd/system/fauxmo.service to match your setup

# 4. Enable and start the service
sudo systemctl enable fauxmo.service
sudo systemctl start fauxmo.service

  11. Inspect Echo commands using netcat

    master

    To examine the exact HTTP/SOAP requests an Amazon Echo sends to a Fauxmo device, you can intercept the traffic using netcat.

    1. Stop Fauxmo to free up the target port.
    2. Use nc.traditional (or nc) to listen on the device's configured port (e.g., 12345).
    3. Trigger the command via the Echo (e.g., "turn on [device name]").

    Note: On Raspberry Pi, nc.traditional is recommended. This method may not work as expected on OSX.

    # Listen on port 12345
nc.traditional -l 12345

  12. Inspect raw network traffic with tcpdump

    master

    For a raw view of all information sent to and from the Echo, use tcpdump. You must specify the correct network interface (e.g., eth0) and the Echo's IP address.

    To find your interface name, use ip link.

    # Replace eth0 with your interface and 192.168.27.100 with Echo IP
sudo tcpdump -s 0 -i eth0 -A host 192.168.27.100