| Name | fauxmo JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | |
| Summary | Emulated Belkin WeMo devices that work with the Amazon Echo |
| upload_time | 2024-02-26 08:15:11 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | |
| license | MIT |
| keywords |
fauxmo
alexa
amazon
echo
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Fauxmo README
master: [](https://github.com/n8henrie/fauxmo/actions/workflows/python-package.yml)
dev: [](https://github.com/n8henrie/fauxmo/actions/workflows/python-package.yml)
Python 3 module that emulates Belkin WeMo devices for use with the Amazon Echo.
Originally forked from <https://github.com/makermusings/fauxmo>, unforked to
enable GitHub code search (which currently doesn't work in a fork), and because
the libraries have diverged substantially.
- Documentation: [fauxmo.readthedocs.org](https://fauxmo.readthedocs.org)
## Introduction
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 such as [Home
Assistant](https://home-assistant.io) or to run other commands locally on the
device and only require a JSON config file for setup.
As of version v0.4.0, Fauxmo uses several API features and f-strings that
require Python 3.6+. I highly recommend looking into
[pyenv](https://github.com/pyenv/pyenv) if you're currently on an older Python
version and willing to upgrade. Otherwise, check out the FAQ section at the
bottom for tips on installing an older Fauxmo version (though note that I will
not be continuing development or support for older versions).
For what it's worth, if you're concerned about installing pyenv on a
low-resource machine like the Raspberry Pi, I encourage you to [review my
notes](https://n8henrie.com/2018/02/pyenv-size-and-python-36-speed-installation-time-on-raspberry-pi/)
on the size and time required to install Python 3.6 with pyenv on a Raspberry
Pi and the nontrivial improvement in speed (with a simple pystone benchmark)
using an optimized pyenv-installed 3.6 as compared to the default Raspbian
3.5.3.
## Terminology
faux (`\ˈfō\`): imitation
WeMo: Belkin home automation product with which the Amazon Echo can interface
Fauxmo (`\ˈfō-mō\`): Python 3 module that emulates Belkin WeMo devices for use
with the Amazon Echo.
Fauxmo has a server component that helps register "devices" with the Echo (which
may be referred to as the Fauxmo server or Fauxmo core). These devices are then
exposed individually, each requiring its own port, and may be referred to as a
Fauxmo device or a Fauxmo instance. The Echo interacts with each Fauxmo device
as if it were a separate WeMo device.
## Usage
Installation into a venv is *highly recommended*, especially since it's baked
into the recent Python versions that Fauxmo requires.
Additionally, please ensure you're using a recent version of pip (>= 9.0.1)
prior to installation: `pip install --upgrade pip`
### Simple install: From PyPI
1. `python3 -m venv .venv`
1. `source ./.venv/bin/activate`
1. `python3 -m pip install fauxmo`
1. Make a `config.json` based on
[`config-sample.json`][config-sample.json]
1. `fauxmo -c config.json [-v]`
As of `v0.6.0`, you can *optionally* install `uvloop` for potentially better
performance, which *might* be helpful if you have a large number of devices or
a network with lots of broadcast mdns traffic. If it is present, `fauxmo` will
take advantage. It is not terribly difficult to install `uvloop` but you are on
your own: <https://github.com/MagicStack/uvloop>.
### Simple install of dev branch from GitHub
This is a good strategy for testing features in development -- for actually
contributing to development, clone the repo as per below)
1. `python3 -m venv .venv`
1. `source ./.venv/bin/activate`
1. `pip install [-e] git+https://github.com/n8henrie/fauxmo.git@dev`
### Install for development from GitHub
1. `git clone https://github.com/n8henrie/fauxmo.git`
1. `cd fauxmo`
1. `python3 -m venv .venv`
1. `source ./.venv/bin/activate`
1. `pip install -e .[dev,test]`
1. `cp config-sample.json config.json`
1. Edit `config.json`
1. `fauxmo [-v]`
### Set up the Echo
1. Open the Amazon Alexa webapp to the [Smart
Home](http://alexa.amazon.com/#smart-home) page
1. **With Fauxmo running**, click "Discover devices" (or tell Alexa to "find
connected devices")
1. Ensure that your Fauxmo devices were discovered and appear with their
names in the web interface
1. Test: "Alexa, turn on [the kitchen light]"
### Set Fauxmo to run automatically in the background
NB: As discussed in [#20](https://github.com/n8henrie/fauxmo/issues/20), the
example files in `extras/` are *not* included when you install from PyPI\*
(using `pip`). If you want to use them, you either need to clone the repo or
you can download them individually using tools like `wget` or `curl` by
navigating to the file in your web browser, clicking the `Raw` button, and
using the resulting URL in your address bar.
\* As of Fauxmo v0.4.0 `extras/` has been added to `MANIFEST.in` and may be
included somewhere depending on installation from the `.tar.gz` vs `whl`
format -- if you can't find them, you should probably just get the files
manually as described above.
#### systemd (e.g. Raspbian Jessie)
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
1. `sudo cp extras/fauxmo.service /etc/systemd/system/fauxmo.service`
1. Edit the paths in `/etc/systemd/system/fauxmo.service`
1. `sudo systemctl enable fauxmo.service`
1. `sudo systemctl start fauxmo.service`
#### launchd (OS X)
1. `cp extras/com.n8henrie.fauxmo.plist ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`
1. Edit the paths in `~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`
- You can remove the `StandardOutPath` and `StandardErrorPath` sections if
desired
1. `launchctl load ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`
1. `launchctl start com.n8henrie.fauxmo`
## Plugins
Plugins are small user-extendible classes that allow users to easily make their
own actions for Fauxmo to run by way of Alexa commands. They were previously
called Handlers and may be referred to as such in places in the code and
documentation.
Fauxmo v0.4.0 implements a new and breaking change in the way Handlers were
implemented in previous versions, which requires modification of the
`config.json` file (as described below).
A few plugins and the ABC from which the plugins are required to inherit may
be included and installed by default in the `fauxmo.plugins` package. Any
pre-installed plugins, like the rest of the core Fauxmo code, have no third
party dependencies.
So far, the pre-installed plugins include:
- [`fauxmo.plugins.simplehttpplugin.SimpleHTTPPlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/simplehttpplugin.py)
- [`fauxmo.plugins.commandlineplugin.CommandLinePlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/commandlineplugin.py)
- [`fauxmo.plugins.homeassistantplugin.HomeAssistantPlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/homeassistantplugin.py)
`SimpleHTTPPlugin` responds to Alexa's `on` and `off` commands by making
requests to URL endpoints by way of
[`urllib`](https://docs.python.org/3/library/urllib.html). Example uses cases
relevant to the IOT community might be a Flask server served from localhost
that provides a nice web interface for toggling switches, whose endpoints could
be added as the `on_cmd` and `off_cmd` args to a `SimpleHTTPPlugin` instance
to allow activation by way of Alexa -> Fauxmo.
As of Fauxmo v0.4.5, the `FauxmoPlugin` abstract base class (and therefore all
derivate Fauxmo plugins) requires a `get_state` method, which tells Alexa a
device's state. If you don't have a way to determine devices state, you can
just have your `get_state` method return `"unknown"`, but please review the
notes on `get_state` below.
Also, see details regarding plugin configuration in each class's docstring,
which I intend to continue as a convention for Fauxmo plugins. Users hoping to
make more complicated requests may be interested in looking at `RESTAPIPlugin`
in the [`fauxmo-plugins
repository`](https://github.com/n8henrie/fauxmo-plugins), which uses Requests
for a much friendlier API.
### User plugins
Users can easily create their own plugins, which is the motivation behind most
of the changes in Fauxmo v0.4.0.
To get started:
1. Decide on a name for your plugin class. I highly recommend something
descriptive, CamelCase and a `Plugin` suffix, e.g. `FooSwitcherPlugin`.
1. I strongly recommend naming your module the same as the plugin, but in all
lower case, e.g. `fooswitcherplugin.py`.
1. Note the path to your plugin, which will need to be included in your
`config.json` as `path` (absolute path recommended, `~` for homedir is
okay).
1. Write your class, which must at minimum:
- inherit from `fauxmo.plugins.FauxmoPlugin`.
- provide the methods `on()`, `off()`, and `get_state()`.
- Please note that unless the Echo has a way to determine the device
state, it will likely respond that your "device is not responding"
after you turn a device on (or in some cases off, or both), but it
should still be able to switch the device.
- If you want to ignore the actual device's state and just return the
last successful action as the current state (e.g. if `device.on()`
succeeded then return `"on"`), your plugin can return
`super().get_state()` as its `get_state()` method. Some of the
included plugins can be configured to have this behavior using a
`use_fake_state` flag in their configuration (please look at the
documentation and source code of the plugins for further details).
Note that this means it won't update to reflect state changes that
occur outside of Fauxmo (e.g. manually flipping a switch, or toggling
with a different program), whereas a proper `get_state`
implementation may be able to do so.
- If using fake state or if your device cannot readily report its state
upon request (for example if you poll for state with a background
process like mqtt), you should also set an `initial_state` in your
config. As of August 2023, prior to adding a newly discovered device,
Alexa requests its state and will fail to add the device if it can't
report a state.
1. Any required settings will be read from your `config.json` and passed into
your plugin as kwargs at initialization, see below.
In addition to the above, if you intend to share your plugin with others, I
strongly recommend that you:
- Include generous documentation as a module level docstring.
- Note specific versions of any dependencies in that docstring.
- Because these user plugins are kind of "side-loaded," you will need to
manually install their dependencies into the appropriate environment, so
it's important to let other users know exactly what versions you use.
Be aware, when fauxmo loads a plugin, it will add the directory
containing the plugin to the Python path, so any other Python modules in this
directory might be loaded by unscrupulous code. This behavior was adopted in
part to facilitate installing any plugin dependencies in a way that will be
available for import (e.g. `cd "$MYPLUGINPATH"; pip install -t $MYPLUGINDEPS`).
### Notable plugin examples
NB: You may need to *manually* install additional dependencies for these to
work -- look for the dependencies in the module level docstring.
- <https://github.com/n8henrie/fauxmo-plugins>
- `RESTAPIPlugin`
- Trigger HTTP requests with your Echo.
- Similar to `SimpleHTTPPlugin`, but uses
[Requests](https://github.com/kennethreitz/requests) for a simpler
API and easier modification.
- `MQTTPlugin`
- Trigger MQTT events with your Echo
- User contributions of interesting plugins are more than welcome!
## Configuration
I recommend that you copy and modify
[`config-sample.json`](https://github.com/n8henrie/fauxmo/blob/master/config-sample.json).
Fauxmo will use whatever config file you specify with `-c` or will search for
`config.json` in the current directory, `~/.config/fauxmo`, `~/.fauxmo/`, and
`/etc/fauxmo/` (in that order). The minimal configuration settings are:
- `FAUXMO`: General Fauxmo settings
- `ip_address`: Optional[str] - Manually set the server's IP address.
Recommended value: `"auto"`.
- `PLUGINS`: Top level key for your plugins, values should be a dictionary of
(likely CamelCase) class names, spelled identically to the plugin class, with
each plugin's settings as a subdictionary.
- `ExamplePlugin`: Your plugin class name here, case sensitive.
- `path`: The absolute path to the Python file in which the plugin
class is defined (please see the section on user plugins above).
Required for user plugins / plugins not pre-installed in the
`fauxmo.plugins` subpackage.
- `example_var1`: For convenience and to avoid redundancy, your plugin
class can *optionally* use config variables at this level that
will be shared for all `DEVICES` listed in the next section (e.g. an
API key that would be shared for all devices of this plugin type).
If provided, your plugin class must consume this variable in a custom
`__init__`.
- `DEVICES`: List of devices that will employ `ExamplePlugin`
- `name`: Optional[str] -- Name for this device. Optional in the
sense that you can leave it out of the config as long as you set
it in your plugin code as the `_name` attribute, but it does need
to be set somewhere. If you omit it from config you will also
need to override the `__init__` method, which expects a `name`
kwarg.
- `port`: Optional[int] -- Port that Echo will use connect to
device. Should be different for each device, Fauxmo will attempt
to set automatically if absent from config. NB: Like `name`, you
can choose to set manually in your plugin code by overriding the
`_port` attribute (and the `__init__` method, which expects a
`port` kwarg otherwise).
- `example_var2`: Config variables for individual Fauxmo devices
can go here if needed (e.g. the URL that should be triggered when
a device is activated). Again, your plugin class will need to
consume them in a custom `__init__`.
Each user plugin should describe its required configuration in its module-level
docstring. The only required config variables for all plugins is `DEVICES`,
which is a `List[dict]` of configuration variables for each device of that
plugin type. Under `DEVICES` it is a good idea to set a fixed, high, free
`port` for each device, but if you don't set one, Fauxmo will try to pick a
reasonable port automatically (though it will change for each run).
Please see [`config-sample.json`][config-sample.json] for a more concrete idea
of the structure of the config file, using the built-in `SimpleHTTPPlugin` for
demonstration purposes. Below is a description of the kwargs that
`SimpleHTTPPlugin` accepts.
- `name`: What you want to call the device (how to activate by
Echo)
- `port`: Port the Fauxmo device will run on
- `on_cmd`: str -- URL that should be requested to turn device on.
- `off_cmd`: str -- URL that should be requested to turn device off.
- `state_cmd`: str -- URL that should be requested to query device state
- `method` / `state_method`: Optional[str] = GET -- GET, POST, PUT, etc.
- `headers`: Optional[dict] -- Extra headers
- `on_data` / `off_data` / `state_data`: Optional[dict] -- POST data
- `state_response_on` / `state_response_off`: str -- If this string is in
contained in the response from `state_cmd`, then the devices is `on` or
`off`, respectively
- `user` / `password`: Optional[str] -- Enables HTTP authentication (basic or
digest only)
- `use_fake_state`: Optional[bool] -- If `True`, override the plugin's
`get_state` method to return the latest successful action as the device
state. NB: The proper json boolean value for Python's `True` is `true`, not
`True` or `"true"`.
## Security
I am not a technology professional and make no promises regarding the security
of this software. Specifically, plugins such as `CommandLinePlugin` execute
arbitrary code from your configuration without any validation. If your
configuration can be tampered with, you're in for a bad time.
That said, if your configuration can be tampered with (i.e. someone already has
write access on your machine), then you likely have bigger problems.
Regardless, a few reasonable precautions that I recommend:
- run `fauxmo` in a virtulaenv, even without any dependencies
- run `fauxmo` as a dedicated unprivileged user with its own group
- remove write access from the `fauxmo` user and group for your config file and
any plugin files (perhaps `chmod 0640 config.json; chown me:fauxmo
config.json`)
- consider using a firewall like `ufw`, but don't forget that you'll need to
open up ports for upnp (`1900`, UDP) and ports for all your devices that
you've configured (in `config.json`).
For example, if I had 4 echo devices at 192.168.1.5, 192.168.1.10,
192.168.1.15, and 192.168.1.20, and Fauxmo was configured with devices at each
of port 12345-12350, to configure `ufw` I might run something like:
```console
$ for ip in 5 10 15 20; do
sudo ufw allow \
from 192.168.1."$ip" \
to any \
port 1900 \
proto udp \
comment "fauxmo upnp"
sudo ufw allow \
from 192.168.1."$ip" \
to any \
port 12345:12350 \
proto tcp \
comment "fauxmo devices"
done
```
You use Fauxmo at your own risk, with or without user plugins.
## Troubleshooting / FAQ
Your first step in troubleshooting should probably be to "forget all devices"
(which as been removed from the iOS app but is still available at
[alexa.amazon.com](https://alexa.amazon.com)), re-discover devices, and make
sure to refresh your device list (e.g. pull down on the "devices" tab in the
iOS app, or just close out the app completely and re-open).
- How can I increase my logging verbosity?
- `-v[vv]`
- `-vv` (`logging.INFO`) is a good place to start when debugging
- 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/fauxmo.git@v0.1.11`
- 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`](https://github.com/n8henrie/fauxmo/blob/master/protocol_notes.md)
- Does Fauxmo work with non-Echo emulators like Alexa AVS or Echoism.io?
- [Apparently not.](https://github.com/n8henrie/fauxmo/issues/22)
- How do I find my Echo firmware version?
- https://alexa.amazon.com -> Settings -> [Device Name] -> Device Software Version
### Installing Python 3.10 with [pyenv](https://github.com/pyenv/pyenv)
```bash
sudo install -o $(whoami) -g $(whoami) -d /opt/pyenv
git clone https://github.com/pyenv/pyenv /opt/pyenv
cat <<'EOF' >> ~/.bashrc
export PYENV_ROOT="/opt/pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
EOF
source ~/.bashrc
pyenv install 3.10.6
```
You can then install Fauxmo into Python 3.10 in a few ways, including:
```bash
# Install with pip
"$(pyenv root)"/versions/3.10.6/bin/python3.10 -m pip install fauxmo
# Show full path to Fauxmo console script
pyenv which fauxmo
# Run with included console script
fauxmo -c /path/to/config.json -vvv
# I recommend using the full path for use in start scripts (e.g. systemd, cron)
"$(pyenv root)"/versions/3.10.6/bin/fauxmo -c /path/to/config.json -vvv
# Alternatively, this also works (after `pip install`)
"$(pyenv root)"/versions/3.10.6/bin/python3.10 -m fauxmo.cli -c config.json -vvv
```
## Docker (alpha)
I'm not a heavy docker user, but I thought it might be helpful to also provide
a docker image.
The Dockerfile can be run locally from a copy of the repo; you'll obviously
need to change `config-sample.json` to an absolute path to your `config.json`.
```bash
$ docker run --network=host --rm -it \
-v $(pwd)/config-sample.json:/etc/fauxmo/config.json:ro \
"$(docker build -q .)"
```
As far as I'm aware the `network=host` will be unavoidable due to the need to
listen (and respond) to UPnP broadcasts.
## Buy Me a Coffee
[☕️](https://n8henrie.com/donate)
## Acknowledgements / Reading List
- Tremendous thanks to @makermusings for [the original version of
Fauxmo](https://github.com/makermusings/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>
- [https://www.rilhia.com/tutorials/using-upnp-enabled-devices-talend-belkin-wemo-switch](https://web.archive.org/web/20160419092252/https://www.rilhia.com/tutorials/using-upnp-enabled-devices-talend-belkin-wemo-switch)
[config-sample.json]: https://github.com/n8henrie/fauxmo/blob/master/config-sample.json
# [Changelog](https://keepachangelog.com)
Will not contain minor changes -- feel free to look through `git log` for
more detail.
## v0.8.0 :: 20240219
- Force keyword arguments in `CommandLinePlugin` as done elsewhere
- This is really the only cause of the "highest nonzero version number" bump
- Fix plugins not passing `initial_state` to parent class (https://github.com/n8henrie/fauxmo/issues/122)
- Tweaks to nix development environment
- Add coverage testing to `tests/` to ensure all testing code paths are taken
## v0.7.0 :: 20230825
- Add `initial_state` kwarg for plugins
- See notes for eb749275a06c443bf4c914c450f9717ee3c7f212
- Python 3.11, drop official 3.7 support
- Add a basic config validation function
- Support config in `~/.config/fauxmo`
- Framework for nix and docker support
- Add timeouts to default plugins
- 2f9212b67dec62a4cc9c1609fbbe59dcea1c3d27
- Commands that block freeze *everything* due to the way asyncio works.
Highly recommended to leverage these timeouts for anything that may block
- Add support `shell=True` commands
- Use at your own risk :)
- Migrate setup.cfg to standalone pyproject.toml
- 09f80b364b85b327ab3f92c5e6f538b001a6becc
- type hinting updates
## v0.6.0 :: 20220304
- Python 3.10
- Add optional `uvloop` support (https://github.com/n8henrie/fauxmo/issues/112)
- Add option to override `domain` to `homeassistantplugin.py` (https://github.com/n8henrie/fauxmo/issues/114)
## v0.5.1, v0.5.2 :: 20210901
- Version bumps to upload new pyproject.toml format to PyPI
## v0.5.0 :: 20191212
- Add py38 support
- Add `use_fake_state` option to accommodate situations that state can't be
properly determined (thanks @johngo7470)
- Bugfix: fix unexpected behavior with a switch's state logic was true for both
`on` and `off`
- Migrated HomeAssistantPlugin and CommandLinePlugin from fauxmo-plugins repo
- Update tests, pytest fixtures, and add some mocks
## v0.4.9 :: 20190527
- Add py37 support (including Travis workaround)
- Fix bug in content-length calculation (thanks @tim15)
- Replace `find_unused_port` with local function (thanks @schneideradam)
- Use black for formatting
- Update `config-sample.txt` for changes in [HomeAssistant
API](https://developers.home-assistant.io/docs/en/external_api_rest.html)
## v0.4.8 :: 20180804
- Add `.close()` method to `FauxmoPlugin`s, allowing for cleanup (thanks
[@howdypierce](https://github.com/howdypierce))
[discussion](https://github.com/n8henrie/fauxmo/issues/58), e907245
- Append plugins directory to `sys.path` for more convenient loading of
additional modules (thanks [@howdypierce](https://github.com/howdypierce))
[discussion](https://github.com/n8henrie/fauxmo/issues/58), 03f2101
- Add HTTP headers to `/eventservice.xml` and `/metainfoservice.xml` endpoints
5a53268
## v0.4.7 :: 20180512
- Minor dev-side changes
- Use pipenv for dev dependency management
- Add utf-8 to readme parsing (5 days ago) (thanks
[@hestela](https://github.com/n8henrie/fauxmo/commits?author=hestela)!)
49d2c57
- Change newline to `\r\n` in HTTP responses (thanks
[@GlennPegden2](https://github.com/GlennPegden2)) 239bc79
- Match `MAN:` case insensitive (thanks [@wingett](https://github.com/wingett))
8307096
- Add GetBinaryState and GetFriendlyName commands including test cases (thanks
[@howdypierce](https://github.com/howdypierce)!) 71392de
- Make comparison of the "SOAPACTION" header case-insensitive, per UPnP spec
(thanks [@howdypierce](https://github.com/howdypierce)!) a5cdf82
- Add fallback for determining IP address when DNS resolution is a problem
(thanks [@howdypierce](https://github.com/howdypierce)!) c2d7f13
- Bugfix: ~/.fauxmo/ not being read as a location for config file (thanks
[@howdypierce](https://github.com/howdypierce)!) c322c9b
## v0.4.6 :: 20180212
- Mostly changes to try to fix compatibility with newer generation Echos / Echo
Plus, see #38
## v0.4.5 :: 20171114
- Support new GetBinaryState command (fixes n8henrie/fauxmo#31)
## v0.4.3 :: 20170914
- Add `--version` to cli
- Add `python_requires` specifier to `setup.py`
- Bind to specific address in `make_udp_sock` (`fauxmo.utils`), seems to fix
some intermittent failing tests on MacOS.
## v0.4.2 :: 20170601
- Add additional linters to tests
- Set reuseaddr and reuseport before binding socket
## v0.4.0 :: 20170402
- Rename handlers to plugins
- Add interface for user plugins
- Add type hints
- Require Python 3.6
- Eliminate third party dependencies
- Make sure to close connection when plugin commands fail / return False
## v0.3.3 :: 20160722
- Added compatibility for `rollershutter` to `handlers.hass`
- Changed `handlers.hass` to send values from a dict to make addition of new
services easier in the future
## v0.3.2 :: 20160419
- Update SSDPServer to `setsockopt` to permit receiving multicast broadcasts
- `sock` kwarg to `create_datagram_endpoint` no longer necessary, restoring
functionality to Python 3.4.0 - 3.4.3 (closes #6)
- `make_udp_sock()` no longer necessary, removed from `fauxmo.utils`
- Tox and Travis configs switched to use Python 3.4.2 instead of 3.4.4 (since
3.4.2 is the latest available in the default Raspbian Jessie repos)
## v0.3.1 :: 20160415
- Don't decode the UDP multicast broadcasts (hopefully fixes #7)
- They might not be from the Echo and might cause a `UnicodeDecodeError`
- Just search the bytes instead
- Tests updated for this minor change
## v0.3.0 :: 20160409
- Fauxmo now uses asyncio and requires Python >= 3.4.4
- *Extensive* changes to codebase
- Handler classes renamed for PEP8 (capitalization)
- Moved some general purpose functions to `fauxmo.utils` module
- Both the UDP and TCP servers are now in `fauxmo.protocols`
- Added some rudimentary [pytest](http://pytest.org/latest) tests including [tox](http://tox.readthedocs.org/en/latest) and [Travis](https://travis-ci.org/) support
- Updated documentation on several classes
## v0.2.0 :: 20160324
- Add additional HTTP verbs and options to `RestApiHandler` and Indigo sample
to config
- **NB:** Breaking change: `json` config variable now needs to be either
`on_json` or `off_json`
- Make `RestApiHandler` DRYer with `functools.partialmethod`
- Add `SO_REUSEPORT` to `upnp.py` to make life easier on OS X
## v0.1.11 :: 20160129
- Consolidate logger to `__init__.py` and import from there in other modules
## v0.1.8 :: 20160129
- Add the ability to manually specify the host IP address for cases when the
auto detection isn't working (https://github.com/n8henrie/fauxmo/issues/1)
- Deprecated the `DEBUG` setting in `config.json`. Just use `-vvv` from now on.
## v0.1.6 :: 20160105
- Fix for Linux not returning local IP
- restored method I had removed from Maker Musings original / pre-fork
version not knowing it would introduce a bug where Linux returned
127.0.1.1 as local IP address
## v0.1.4 :: 20150104
- Fix default verbosity bug introduced in 1.1.3
## v0.1.0 :: 20151231
- Continue to convert to python3 code
- Pulled in a few PRs by [@DoWhileGeek](https://github.com/DoWhileGeek) working
towards python3 compatibility and improved devices naming with dictionary
- Renamed a fair number of classes
- Added kwargs to several class and function calls for clarity
- Renamed several variables for clarity
- Got rid of a few empty methods
- Import devices from `config.json` and include a sample
- Support `POST`, headers, and json data in the RestApiHandler
- Change old debug function to use logging module
- Got rid of some unused dependencies
- Moved license (MIT) info to LICENSE
- Added argparse for future console scripts entry point
- Added Home Assistant API handler class
- Use "string".format() instead of percent
- Lots of other minor refactoring
Raw data
{
"_id": null,
"home_page": "",
"name": "fauxmo",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "fauxmo,alexa,amazon,echo",
"author": "",
"author_email": "Nathan Henrie <nate@n8henrie.com>",
"download_url": "https://files.pythonhosted.org/packages/5d/67/196b04583352cb0eb0ea427a6d436ef3420345b8cb2e6b5ca550bfcaee73/fauxmo-0.8.0.tar.gz",
"platform": null,
"description": "# Fauxmo README\n\nmaster: [](https://github.com/n8henrie/fauxmo/actions/workflows/python-package.yml)\ndev: [](https://github.com/n8henrie/fauxmo/actions/workflows/python-package.yml)\n\nPython 3 module that emulates Belkin WeMo devices for use with the Amazon Echo.\n\nOriginally forked from <https://github.com/makermusings/fauxmo>, unforked to\nenable GitHub code search (which currently doesn't work in a fork), and because\nthe libraries have diverged substantially.\n\n- Documentation: [fauxmo.readthedocs.org](https://fauxmo.readthedocs.org)\n\n## Introduction\n\nThe Amazon Echo is able to control certain types of home automation devices by\nvoice. Fauxmo provides emulated Belkin Wemo devices that the Echo can turn on\nand off by voice, locally, and with minimal lag time. Currently these Fauxmo\ndevices can be configured to make requests to an HTTP server such as [Home\nAssistant](https://home-assistant.io) or to run other commands locally on the\ndevice and only require a JSON config file for setup.\n\nAs of version v0.4.0, Fauxmo uses several API features and f-strings that\nrequire Python 3.6+. I highly recommend looking into\n[pyenv](https://github.com/pyenv/pyenv) if you're currently on an older Python\nversion and willing to upgrade. Otherwise, check out the FAQ section at the\nbottom for tips on installing an older Fauxmo version (though note that I will\nnot be continuing development or support for older versions).\n\nFor what it's worth, if you're concerned about installing pyenv on a\nlow-resource machine like the Raspberry Pi, I encourage you to [review my\nnotes](https://n8henrie.com/2018/02/pyenv-size-and-python-36-speed-installation-time-on-raspberry-pi/)\non the size and time required to install Python 3.6 with pyenv on a Raspberry\nPi and the nontrivial improvement in speed (with a simple pystone benchmark)\nusing an optimized pyenv-installed 3.6 as compared to the default Raspbian\n3.5.3.\n\n## Terminology\n\nfaux (`\\\u02c8f\u014d\\`): imitation\n\nWeMo: Belkin home automation product with which the Amazon Echo can interface\n\nFauxmo (`\\\u02c8f\u014d-m\u014d\\`): Python 3 module that emulates Belkin WeMo devices for use\nwith the Amazon Echo.\n\nFauxmo has a server component that helps register \"devices\" with the Echo (which\nmay be referred to as the Fauxmo server or Fauxmo core). These devices are then\nexposed individually, each requiring its own port, and may be referred to as a\nFauxmo device or a Fauxmo instance. The Echo interacts with each Fauxmo device\nas if it were a separate WeMo device.\n\n## Usage\n\nInstallation into a venv is *highly recommended*, especially since it's baked\ninto the recent Python versions that Fauxmo requires.\n\nAdditionally, please ensure you're using a recent version of pip (>= 9.0.1)\nprior to installation: `pip install --upgrade pip`\n\n### Simple install: From PyPI\n\n1. `python3 -m venv .venv`\n1. `source ./.venv/bin/activate`\n1. `python3 -m pip install fauxmo`\n1. Make a `config.json` based on\n [`config-sample.json`][config-sample.json]\n1. `fauxmo -c config.json [-v]`\n\nAs of `v0.6.0`, you can *optionally* install `uvloop` for potentially better\nperformance, which *might* be helpful if you have a large number of devices or\na network with lots of broadcast mdns traffic. If it is present, `fauxmo` will\ntake advantage. It is not terribly difficult to install `uvloop` but you are on\nyour own: <https://github.com/MagicStack/uvloop>.\n\n### Simple install of dev branch from GitHub\n\nThis is a good strategy for testing features in development -- for actually\ncontributing to development, clone the repo as per below)\n\n1. `python3 -m venv .venv`\n1. `source ./.venv/bin/activate`\n1. `pip install [-e] git+https://github.com/n8henrie/fauxmo.git@dev`\n\n### Install for development from GitHub\n\n1. `git clone https://github.com/n8henrie/fauxmo.git`\n1. `cd fauxmo`\n1. `python3 -m venv .venv`\n1. `source ./.venv/bin/activate`\n1. `pip install -e .[dev,test]`\n1. `cp config-sample.json config.json`\n1. Edit `config.json`\n1. `fauxmo [-v]`\n\n### Set up the Echo\n\n1. Open the Amazon Alexa webapp to the [Smart\n Home](http://alexa.amazon.com/#smart-home) page\n1. **With Fauxmo running**, click \"Discover devices\" (or tell Alexa to \"find\n connected devices\")\n1. Ensure that your Fauxmo devices were discovered and appear with their\n names in the web interface\n1. Test: \"Alexa, turn on [the kitchen light]\"\n\n### Set Fauxmo to run automatically in the background\n\nNB: As discussed in [#20](https://github.com/n8henrie/fauxmo/issues/20), the\nexample files in `extras/` are *not* included when you install from PyPI\\*\n(using `pip`). If you want to use them, you either need to clone the repo or\nyou can download them individually using tools like `wget` or `curl` by\nnavigating to the file in your web browser, clicking the `Raw` button, and\nusing the resulting URL in your address bar.\n\n\\* As of Fauxmo v0.4.0 `extras/` has been added to `MANIFEST.in` and may be\nincluded somewhere depending on installation from the `.tar.gz` vs `whl`\nformat -- if you can't find them, you should probably just get the files\nmanually as described above.\n\n#### systemd (e.g. Raspbian Jessie)\n\n1. Recommended: add an unprivileged user to run Fauxmo: `sudo useradd -r\n -s /bin/false fauxmo`\n - NB: Fauxmo may require root privileges if you're using ports below 1024\n1. `sudo cp extras/fauxmo.service /etc/systemd/system/fauxmo.service`\n1. Edit the paths in `/etc/systemd/system/fauxmo.service`\n1. `sudo systemctl enable fauxmo.service`\n1. `sudo systemctl start fauxmo.service`\n\n#### launchd (OS X)\n\n1. `cp extras/com.n8henrie.fauxmo.plist ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`\n1. Edit the paths in `~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`\n - You can remove the `StandardOutPath` and `StandardErrorPath` sections if\n desired\n1. `launchctl load ~/Library/LaunchAgents/com.n8henrie.fauxmo.plist`\n1. `launchctl start com.n8henrie.fauxmo`\n\n## Plugins\n\nPlugins are small user-extendible classes that allow users to easily make their\nown actions for Fauxmo to run by way of Alexa commands. They were previously\ncalled Handlers and may be referred to as such in places in the code and\ndocumentation.\n\nFauxmo v0.4.0 implements a new and breaking change in the way Handlers were\nimplemented in previous versions, which requires modification of the\n`config.json` file (as described below).\n\nA few plugins and the ABC from which the plugins are required to inherit may\nbe included and installed by default in the `fauxmo.plugins` package. Any\npre-installed plugins, like the rest of the core Fauxmo code, have no third\nparty dependencies.\n\nSo far, the pre-installed plugins include:\n\n- [`fauxmo.plugins.simplehttpplugin.SimpleHTTPPlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/simplehttpplugin.py)\n- [`fauxmo.plugins.commandlineplugin.CommandLinePlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/commandlineplugin.py)\n- [`fauxmo.plugins.homeassistantplugin.HomeAssistantPlugin`](https://github.com/n8henrie/fauxmo/blob/master/src/fauxmo/plugins/homeassistantplugin.py)\n\n`SimpleHTTPPlugin` responds to Alexa's `on` and `off` commands by making\nrequests to URL endpoints by way of\n[`urllib`](https://docs.python.org/3/library/urllib.html). Example uses cases\nrelevant to the IOT community might be a Flask server served from localhost\nthat provides a nice web interface for toggling switches, whose endpoints could\nbe added as the `on_cmd` and `off_cmd` args to a `SimpleHTTPPlugin` instance\nto allow activation by way of Alexa -> Fauxmo.\n\nAs of Fauxmo v0.4.5, the `FauxmoPlugin` abstract base class (and therefore all\nderivate Fauxmo plugins) requires a `get_state` method, which tells Alexa a\ndevice's state. If you don't have a way to determine devices state, you can\njust have your `get_state` method return `\"unknown\"`, but please review the\nnotes on `get_state` below.\n\nAlso, see details regarding plugin configuration in each class's docstring,\nwhich I intend to continue as a convention for Fauxmo plugins. Users hoping to\nmake more complicated requests may be interested in looking at `RESTAPIPlugin`\nin the [`fauxmo-plugins\nrepository`](https://github.com/n8henrie/fauxmo-plugins), which uses Requests\nfor a much friendlier API.\n\n### User plugins\n\nUsers can easily create their own plugins, which is the motivation behind most\nof the changes in Fauxmo v0.4.0.\n\nTo get started:\n\n1. Decide on a name for your plugin class. I highly recommend something\n descriptive, CamelCase and a `Plugin` suffix, e.g. `FooSwitcherPlugin`.\n1. I strongly recommend naming your module the same as the plugin, but in all\n lower case, e.g. `fooswitcherplugin.py`.\n1. Note the path to your plugin, which will need to be included in your\n `config.json` as `path` (absolute path recommended, `~` for homedir is\n okay).\n1. Write your class, which must at minimum:\n - inherit from `fauxmo.plugins.FauxmoPlugin`.\n - provide the methods `on()`, `off()`, and `get_state()`.\n - Please note that unless the Echo has a way to determine the device\n state, it will likely respond that your \"device is not responding\"\n after you turn a device on (or in some cases off, or both), but it\n should still be able to switch the device.\n - If you want to ignore the actual device's state and just return the\n last successful action as the current state (e.g. if `device.on()`\n succeeded then return `\"on\"`), your plugin can return\n `super().get_state()` as its `get_state()` method. Some of the\n included plugins can be configured to have this behavior using a\n `use_fake_state` flag in their configuration (please look at the\n documentation and source code of the plugins for further details).\n Note that this means it won't update to reflect state changes that\n occur outside of Fauxmo (e.g. manually flipping a switch, or toggling\n with a different program), whereas a proper `get_state`\n implementation may be able to do so.\n - If using fake state or if your device cannot readily report its state\n upon request (for example if you poll for state with a background\n process like mqtt), you should also set an `initial_state` in your\n config. As of August 2023, prior to adding a newly discovered device,\n Alexa requests its state and will fail to add the device if it can't\n report a state.\n\n1. Any required settings will be read from your `config.json` and passed into\n your plugin as kwargs at initialization, see below.\n\nIn addition to the above, if you intend to share your plugin with others, I\nstrongly recommend that you:\n\n- Include generous documentation as a module level docstring.\n- Note specific versions of any dependencies in that docstring.\n - Because these user plugins are kind of \"side-loaded,\" you will need to\n manually install their dependencies into the appropriate environment, so\n it's important to let other users know exactly what versions you use.\n\nBe aware, when fauxmo loads a plugin, it will add the directory\ncontaining the plugin to the Python path, so any other Python modules in this\ndirectory might be loaded by unscrupulous code. This behavior was adopted in\npart to facilitate installing any plugin dependencies in a way that will be\navailable for import (e.g. `cd \"$MYPLUGINPATH\"; pip install -t $MYPLUGINDEPS`).\n\n### Notable plugin examples\n\nNB: You may need to *manually* install additional dependencies for these to\nwork -- look for the dependencies in the module level docstring.\n\n- <https://github.com/n8henrie/fauxmo-plugins>\n - `RESTAPIPlugin`\n - Trigger HTTP requests with your Echo.\n - Similar to `SimpleHTTPPlugin`, but uses\n [Requests](https://github.com/kennethreitz/requests) for a simpler\n API and easier modification.\n - `MQTTPlugin`\n - Trigger MQTT events with your Echo\n - User contributions of interesting plugins are more than welcome!\n\n## Configuration\n\nI recommend that you copy and modify\n[`config-sample.json`](https://github.com/n8henrie/fauxmo/blob/master/config-sample.json).\nFauxmo will use whatever config file you specify with `-c` or will search for\n`config.json` in the current directory, `~/.config/fauxmo`, `~/.fauxmo/`, and\n`/etc/fauxmo/` (in that order). The minimal configuration settings are:\n\n- `FAUXMO`: General Fauxmo settings\n - `ip_address`: Optional[str] - Manually set the server's IP address.\n Recommended value: `\"auto\"`.\n- `PLUGINS`: Top level key for your plugins, values should be a dictionary of\n (likely CamelCase) class names, spelled identically to the plugin class, with\n each plugin's settings as a subdictionary.\n - `ExamplePlugin`: Your plugin class name here, case sensitive.\n - `path`: The absolute path to the Python file in which the plugin\n class is defined (please see the section on user plugins above).\n Required for user plugins / plugins not pre-installed in the\n `fauxmo.plugins` subpackage.\n - `example_var1`: For convenience and to avoid redundancy, your plugin\n class can *optionally* use config variables at this level that\n will be shared for all `DEVICES` listed in the next section (e.g. an\n API key that would be shared for all devices of this plugin type).\n If provided, your plugin class must consume this variable in a custom\n `__init__`.\n - `DEVICES`: List of devices that will employ `ExamplePlugin`\n - `name`: Optional[str] -- Name for this device. Optional in the\n sense that you can leave it out of the config as long as you set\n it in your plugin code as the `_name` attribute, but it does need\n to be set somewhere. If you omit it from config you will also\n need to override the `__init__` method, which expects a `name`\n kwarg.\n - `port`: Optional[int] -- Port that Echo will use connect to\n device. Should be different for each device, Fauxmo will attempt\n to set automatically if absent from config. NB: Like `name`, you\n can choose to set manually in your plugin code by overriding the\n `_port` attribute (and the `__init__` method, which expects a\n `port` kwarg otherwise).\n - `example_var2`: Config variables for individual Fauxmo devices\n can go here if needed (e.g. the URL that should be triggered when\n a device is activated). Again, your plugin class will need to\n consume them in a custom `__init__`.\n\n\nEach user plugin should describe its required configuration in its module-level\ndocstring. The only required config variables for all plugins is `DEVICES`,\nwhich is a `List[dict]` of configuration variables for each device of that\nplugin type. Under `DEVICES` it is a good idea to set a fixed, high, free\n`port` for each device, but if you don't set one, Fauxmo will try to pick a\nreasonable port automatically (though it will change for each run).\n\nPlease see [`config-sample.json`][config-sample.json] for a more concrete idea\nof the structure of the config file, using the built-in `SimpleHTTPPlugin` for\ndemonstration purposes. Below is a description of the kwargs that\n`SimpleHTTPPlugin` accepts.\n\n- `name`: What you want to call the device (how to activate by\n Echo)\n- `port`: Port the Fauxmo device will run on\n- `on_cmd`: str -- URL that should be requested to turn device on.\n- `off_cmd`: str -- URL that should be requested to turn device off.\n- `state_cmd`: str -- URL that should be requested to query device state\n- `method` / `state_method`: Optional[str] = GET -- GET, POST, PUT, etc.\n- `headers`: Optional[dict] -- Extra headers\n- `on_data` / `off_data` / `state_data`: Optional[dict] -- POST data\n- `state_response_on` / `state_response_off`: str -- If this string is in\n contained in the response from `state_cmd`, then the devices is `on` or\n `off`, respectively\n- `user` / `password`: Optional[str] -- Enables HTTP authentication (basic or\n digest only)\n- `use_fake_state`: Optional[bool] -- If `True`, override the plugin's\n `get_state` method to return the latest successful action as the device\n state. NB: The proper json boolean value for Python's `True` is `true`, not\n `True` or `\"true\"`.\n\n## Security\n\nI am not a technology professional and make no promises regarding the security\nof this software. Specifically, plugins such as `CommandLinePlugin` execute\narbitrary code from your configuration without any validation. If your\nconfiguration can be tampered with, you're in for a bad time.\n\nThat said, if your configuration can be tampered with (i.e. someone already has\nwrite access on your machine), then you likely have bigger problems.\n\nRegardless, a few reasonable precautions that I recommend:\n\n- run `fauxmo` in a virtulaenv, even without any dependencies\n- run `fauxmo` as a dedicated unprivileged user with its own group\n- remove write access from the `fauxmo` user and group for your config file and\n any plugin files (perhaps `chmod 0640 config.json; chown me:fauxmo\n config.json`)\n- consider using a firewall like `ufw`, but don't forget that you'll need to\n open up ports for upnp (`1900`, UDP) and ports for all your devices that\n you've configured (in `config.json`).\n\nFor example, if I had 4 echo devices at 192.168.1.5, 192.168.1.10,\n192.168.1.15, and 192.168.1.20, and Fauxmo was configured with devices at each\nof port 12345-12350, to configure `ufw` I might run something like:\n\n```console\n$ for ip in 5 10 15 20; do\n sudo ufw allow \\\n from 192.168.1.\"$ip\" \\\n to any \\\n port 1900 \\\n proto udp \\\n comment \"fauxmo upnp\"\n sudo ufw allow \\\n from 192.168.1.\"$ip\" \\\n to any \\\n port 12345:12350 \\\n proto tcp \\\n comment \"fauxmo devices\"\ndone\n```\n\nYou use Fauxmo at your own risk, with or without user plugins.\n\n## Troubleshooting / FAQ\n\nYour first step in troubleshooting should probably be to \"forget all devices\"\n(which as been removed from the iOS app but is still available at\n[alexa.amazon.com](https://alexa.amazon.com)), re-discover devices, and make\nsure to refresh your device list (e.g. pull down on the \"devices\" tab in the\niOS app, or just close out the app completely and re-open).\n\n- How can I increase my logging verbosity?\n - `-v[vv]`\n - `-vv` (`logging.INFO`) is a good place to start when debugging\n- How can I ensure my config is valid JSON?\n - `python -m json.tool < config.json`\n - Use `jsonlint` or one of numerous online tools\n- How can I install an older / specific version of Fauxmo?\n - Install from a tag:\n - `pip install git+git://github.com/n8henrie/fauxmo.git@v0.1.11`\n - Install from a specific commit:\n - `pip install\n git+git://github.com/n8henrie/fauxmo.git@d877c513ad45cbbbd77b1b83e7a2f03bf0004856`\n- Where can I get more information on how the Echo interacts with devices like\n Fauxmo?\n - Check out\n [`protocol_notes.md`](https://github.com/n8henrie/fauxmo/blob/master/protocol_notes.md)\n- Does Fauxmo work with non-Echo emulators like Alexa AVS or Echoism.io?\n - [Apparently not.](https://github.com/n8henrie/fauxmo/issues/22)\n- How do I find my Echo firmware version?\n - https://alexa.amazon.com -> Settings -> [Device Name] -> Device Software Version\n\n### Installing Python 3.10 with [pyenv](https://github.com/pyenv/pyenv)\n\n```bash\nsudo install -o $(whoami) -g $(whoami) -d /opt/pyenv\ngit clone https://github.com/pyenv/pyenv /opt/pyenv\ncat <<'EOF' >> ~/.bashrc\nexport PYENV_ROOT=\"/opt/pyenv\"\nexport PATH=\"$PYENV_ROOT/bin:$PATH\"\neval \"$(pyenv init -)\"\nEOF\nsource ~/.bashrc\npyenv install 3.10.6\n```\n\nYou can then install Fauxmo into Python 3.10 in a few ways, including:\n\n```bash\n# Install with pip\n\"$(pyenv root)\"/versions/3.10.6/bin/python3.10 -m pip install fauxmo\n\n# Show full path to Fauxmo console script\npyenv which fauxmo\n\n# Run with included console script\nfauxmo -c /path/to/config.json -vvv\n\n# I recommend using the full path for use in start scripts (e.g. systemd, cron)\n\"$(pyenv root)\"/versions/3.10.6/bin/fauxmo -c /path/to/config.json -vvv\n\n# Alternatively, this also works (after `pip install`)\n\"$(pyenv root)\"/versions/3.10.6/bin/python3.10 -m fauxmo.cli -c config.json -vvv\n```\n\n## Docker (alpha)\n\nI'm not a heavy docker user, but I thought it might be helpful to also provide\na docker image.\n\nThe Dockerfile can be run locally from a copy of the repo; you'll obviously\nneed to change `config-sample.json` to an absolute path to your `config.json`.\n\n```bash\n$ docker run --network=host --rm -it \\\n -v $(pwd)/config-sample.json:/etc/fauxmo/config.json:ro \\\n \"$(docker build -q .)\"\n```\n\nAs far as I'm aware the `network=host` will be unavoidable due to the need to\nlisten (and respond) to UPnP broadcasts.\n\n## Buy Me a Coffee\n\n[\u2615\ufe0f](https://n8henrie.com/donate)\n\n## Acknowledgements / Reading List\n\n- Tremendous thanks to @makermusings for [the original version of\n Fauxmo](https://github.com/makermusings/fauxmo)!\n - Also thanks to @DoWhileGeek for commits towards Python 3 compatibility\n- <http://www.makermusings.com/2015/07/13/amazon-echo-and-home-automation>\n- <http://www.makermusings.com/2015/07/18/virtual-wemo-code-for-amazon-echo>\n- <http://hackaday.com/2015/07/16/how-to-make-amazon-echo-control-fake-wemo-devices>\n- <https://developer.amazon.com/appsandservices/solutions/alexa/alexa-skills-kit>\n- <https://en.wikipedia.org/wiki/Universal_Plug_and_Play>\n- <http://www.makermusings.com/2015/07/19/home-automation-with-amazon-echo-apps-part-1>\n- <http://www.makermusings.com/2015/08/22/home-automation-with-amazon-echo-apps-part-2>\n- [https://www.rilhia.com/tutorials/using-upnp-enabled-devices-talend-belkin-wemo-switch](https://web.archive.org/web/20160419092252/https://www.rilhia.com/tutorials/using-upnp-enabled-devices-talend-belkin-wemo-switch)\n\n[config-sample.json]: https://github.com/n8henrie/fauxmo/blob/master/config-sample.json\n\n# [Changelog](https://keepachangelog.com)\n\nWill not contain minor changes -- feel free to look through `git log` for\nmore detail.\n\n## v0.8.0 :: 20240219\n\n- Force keyword arguments in `CommandLinePlugin` as done elsewhere\n - This is really the only cause of the \"highest nonzero version number\" bump\n- Fix plugins not passing `initial_state` to parent class (https://github.com/n8henrie/fauxmo/issues/122)\n- Tweaks to nix development environment\n- Add coverage testing to `tests/` to ensure all testing code paths are taken\n\n## v0.7.0 :: 20230825\n\n- Add `initial_state` kwarg for plugins\n - See notes for eb749275a06c443bf4c914c450f9717ee3c7f212\n- Python 3.11, drop official 3.7 support\n- Add a basic config validation function\n- Support config in `~/.config/fauxmo`\n- Framework for nix and docker support\n- Add timeouts to default plugins\n - 2f9212b67dec62a4cc9c1609fbbe59dcea1c3d27\n - Commands that block freeze *everything* due to the way asyncio works.\n Highly recommended to leverage these timeouts for anything that may block\n- Add support `shell=True` commands\n - Use at your own risk :)\n- Migrate setup.cfg to standalone pyproject.toml\n - 09f80b364b85b327ab3f92c5e6f538b001a6becc\n- type hinting updates\n\n## v0.6.0 :: 20220304\n\n- Python 3.10\n- Add optional `uvloop` support (https://github.com/n8henrie/fauxmo/issues/112)\n- Add option to override `domain` to `homeassistantplugin.py` (https://github.com/n8henrie/fauxmo/issues/114)\n\n## v0.5.1, v0.5.2 :: 20210901\n\n- Version bumps to upload new pyproject.toml format to PyPI\n\n## v0.5.0 :: 20191212\n\n- Add py38 support\n- Add `use_fake_state` option to accommodate situations that state can't be\n properly determined (thanks @johngo7470)\n- Bugfix: fix unexpected behavior with a switch's state logic was true for both\n `on` and `off`\n- Migrated HomeAssistantPlugin and CommandLinePlugin from fauxmo-plugins repo\n- Update tests, pytest fixtures, and add some mocks\n\n## v0.4.9 :: 20190527\n\n- Add py37 support (including Travis workaround)\n- Fix bug in content-length calculation (thanks @tim15)\n- Replace `find_unused_port` with local function (thanks @schneideradam)\n- Use black for formatting\n- Update `config-sample.txt` for changes in [HomeAssistant\n API](https://developers.home-assistant.io/docs/en/external_api_rest.html)\n\n## v0.4.8 :: 20180804\n\n- Add `.close()` method to `FauxmoPlugin`s, allowing for cleanup (thanks\n [@howdypierce](https://github.com/howdypierce))\n [discussion](https://github.com/n8henrie/fauxmo/issues/58), e907245\n- Append plugins directory to `sys.path` for more convenient loading of\n additional modules (thanks [@howdypierce](https://github.com/howdypierce))\n [discussion](https://github.com/n8henrie/fauxmo/issues/58), 03f2101\n- Add HTTP headers to `/eventservice.xml` and `/metainfoservice.xml` endpoints\n 5a53268\n\n## v0.4.7 :: 20180512\n\n- Minor dev-side changes\n - Use pipenv for dev dependency management\n- Add utf-8 to readme parsing (5 days ago) (thanks\n [@hestela](https://github.com/n8henrie/fauxmo/commits?author=hestela)!)\n 49d2c57\n- Change newline to `\\r\\n` in HTTP responses (thanks\n [@GlennPegden2](https://github.com/GlennPegden2)) 239bc79\n- Match `MAN:` case insensitive (thanks [@wingett](https://github.com/wingett))\n 8307096\n- Add GetBinaryState and GetFriendlyName commands including test cases (thanks\n [@howdypierce](https://github.com/howdypierce)!) 71392de\n- Make comparison of the \"SOAPACTION\" header case-insensitive, per UPnP spec\n (thanks [@howdypierce](https://github.com/howdypierce)!) a5cdf82\n- Add fallback for determining IP address when DNS resolution is a problem\n (thanks [@howdypierce](https://github.com/howdypierce)!) c2d7f13\n- Bugfix: ~/.fauxmo/ not being read as a location for config file (thanks\n [@howdypierce](https://github.com/howdypierce)!) c322c9b\n\n## v0.4.6 :: 20180212\n\n- Mostly changes to try to fix compatibility with newer generation Echos / Echo\n Plus, see #38\n\n## v0.4.5 :: 20171114\n\n- Support new GetBinaryState command (fixes n8henrie/fauxmo#31)\n\n## v0.4.3 :: 20170914\n\n- Add `--version` to cli\n- Add `python_requires` specifier to `setup.py`\n- Bind to specific address in `make_udp_sock` (`fauxmo.utils`), seems to fix\n some intermittent failing tests on MacOS.\n\n## v0.4.2 :: 20170601\n\n- Add additional linters to tests\n- Set reuseaddr and reuseport before binding socket\n\n## v0.4.0 :: 20170402\n\n- Rename handlers to plugins\n- Add interface for user plugins\n- Add type hints\n- Require Python 3.6\n- Eliminate third party dependencies\n- Make sure to close connection when plugin commands fail / return False\n\n## v0.3.3 :: 20160722\n\n- Added compatibility for `rollershutter` to `handlers.hass`\n- Changed `handlers.hass` to send values from a dict to make addition of new\n services easier in the future\n\n## v0.3.2 :: 20160419\n\n- Update SSDPServer to `setsockopt` to permit receiving multicast broadcasts\n- `sock` kwarg to `create_datagram_endpoint` no longer necessary, restoring\n functionality to Python 3.4.0 - 3.4.3 (closes #6)\n- `make_udp_sock()` no longer necessary, removed from `fauxmo.utils`\n- Tox and Travis configs switched to use Python 3.4.2 instead of 3.4.4 (since\n 3.4.2 is the latest available in the default Raspbian Jessie repos)\n\n## v0.3.1 :: 20160415\n\n- Don't decode the UDP multicast broadcasts (hopefully fixes #7)\n - They might not be from the Echo and might cause a `UnicodeDecodeError`\n - Just search the bytes instead\n- Tests updated for this minor change\n\n## v0.3.0 :: 20160409\n\n- Fauxmo now uses asyncio and requires Python >= 3.4.4\n- *Extensive* changes to codebase\n- Handler classes renamed for PEP8 (capitalization)\n- Moved some general purpose functions to `fauxmo.utils` module\n- Both the UDP and TCP servers are now in `fauxmo.protocols`\n- Added some rudimentary [pytest](http://pytest.org/latest) tests including [tox](http://tox.readthedocs.org/en/latest) and [Travis](https://travis-ci.org/) support\n- Updated documentation on several classes\n\n## v0.2.0 :: 20160324\n\n- Add additional HTTP verbs and options to `RestApiHandler` and Indigo sample\n to config\n - **NB:** Breaking change: `json` config variable now needs to be either\n `on_json` or `off_json`\n- Make `RestApiHandler` DRYer with `functools.partialmethod`\n- Add `SO_REUSEPORT` to `upnp.py` to make life easier on OS X\n\n## v0.1.11 :: 20160129\n\n- Consolidate logger to `__init__.py` and import from there in other modules\n\n## v0.1.8 :: 20160129\n\n- Add the ability to manually specify the host IP address for cases when the\n auto detection isn't working (https://github.com/n8henrie/fauxmo/issues/1)\n- Deprecated the `DEBUG` setting in `config.json`. Just use `-vvv` from now on.\n\n## v0.1.6 :: 20160105\n\n- Fix for Linux not returning local IP\n - restored method I had removed from Maker Musings original / pre-fork\n version not knowing it would introduce a bug where Linux returned\n 127.0.1.1 as local IP address\n\n## v0.1.4 :: 20150104\n\n- Fix default verbosity bug introduced in 1.1.3\n\n## v0.1.0 :: 20151231\n\n- Continue to convert to python3 code\n- Pulled in a few PRs by [@DoWhileGeek](https://github.com/DoWhileGeek) working\ntowards python3 compatibility and improved devices naming with dictionary\n- Renamed a fair number of classes\n- Added kwargs to several class and function calls for clarity\n- Renamed several variables for clarity\n- Got rid of a few empty methods\n- Import devices from `config.json` and include a sample\n- Support `POST`, headers, and json data in the RestApiHandler\n- Change old debug function to use logging module\n- Got rid of some unused dependencies\n- Moved license (MIT) info to LICENSE\n- Added argparse for future console scripts entry point\n- Added Home Assistant API handler class\n- Use \"string\".format() instead of percent\n- Lots of other minor refactoring\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Emulated Belkin WeMo devices that work with the Amazon Echo",
"version": "0.8.0",
"project_urls": {
"homepage": "https://github.com/n8henrie/fauxmo"
},
"split_keywords": [
"fauxmo",
"alexa",
"amazon",
"echo"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "38465e146ff5deb5076a95d7424b1013943fe044066c99d12f18a56f847b42bc",
"md5": "260f553c2ce83a93e59cd4dafdfdde94",
"sha256": "0e8d14f1a57b446e196d179c4b26f93ae8227d1325212d7bb9349cb074d6d0cb"
},
"downloads": -1,
"filename": "fauxmo-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "260f553c2ce83a93e59cd4dafdfdde94",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 32737,
"upload_time": "2024-02-26T08:15:05",
"upload_time_iso_8601": "2024-02-26T08:15:05.509323Z",
"url": "https://files.pythonhosted.org/packages/38/46/5e146ff5deb5076a95d7424b1013943fe044066c99d12f18a56f847b42bc/fauxmo-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5d67196b04583352cb0eb0ea427a6d436ef3420345b8cb2e6b5ca550bfcaee73",
"md5": "692def28a46cd2a2fa2b30f830a8e605",
"sha256": "518b7136a88cb5348f5e25a784d356592dbeaa394f42a3d4c6dbaaa15d861e17"
},
"downloads": -1,
"filename": "fauxmo-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "692def28a46cd2a2fa2b30f830a8e605",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 56687,
"upload_time": "2024-02-26T08:15:11",
"upload_time_iso_8601": "2024-02-26T08:15:11.167467Z",
"url": "https://files.pythonhosted.org/packages/5d/67/196b04583352cb0eb0ea427a6d436ef3420345b8cb2e6b5ca550bfcaee73/fauxmo-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 08:15:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "n8henrie",
"github_project": "fauxmo",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "fauxmo"
}
