Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/n8henrie/fauxmo-plugins

Plugins for Fauxmo (emulated Wemo devices for the Amazon Echo)
https://github.com/n8henrie/fauxmo-plugins

amazon-echo echo home-automation python3

Last synced: 2 months ago
JSON representation

Plugins for Fauxmo (emulated Wemo devices for the Amazon Echo)

Awesome Lists containing this project

README 

        
# fauxmo-plugins



master: [![master branch build

status](https://github.com/n8henrie/fauxmo-plugins/actions/workflows/python-package.yml/badge.svg?branch=master)](https://github.com/n8henrie/fauxmo-plugins/actions/workflows/python-package.yml)

dev: [![dev branch build

status](https://github.com/n8henrie/fauxmo-plugins/actions/workflows/python-package.yml/badge.svg?branch=dev)](https://github.com/n8henrie/fauxmo-plugins/actions/workflows/python-package.yml)



Plugins for Fauxmo (emulated Wemo devices for the Amazon Echo)



## Introduction and Rationale



As of Fauxmo 0.4.0, I am splitting the plugins out of the main

[Fauxmo](https://github.com/n8henrie/fauxmo) code. Plugins were previously

referred to as `handlers`.



- I've implemented a crude plugin import system that allows users to create

  and user their own plugins by inheriting from `FauxmoPlugin` and including

  the path to the file in their config.

- This means I can remove dependencies from Fauxmo that some users may not use,

  and hopefully users unfamiliar with virtualenvs will quit breaking their

  installations due to my pinned versions.

- I'll be able to update plugins without having to release a new version of

  Fauxmo core, keeping them in their own separate VCS silos.



## Using plugins



### Personal user plugins



The biggest motivation for the changes to Fauxmo 0.4.0 was to allow users to

create Fauxmo plugins to scratch their own itch. There are only a few

requirements to get started:



- Your plugin will be class that inherits from the

  `fauxmo.plugins.FauxmoPlugin` ABC.

- Your plugin will override the abstract methods `on`, `off`, and `get_state`,

  which will unsurprisingly be called when you tell Alexa to turn a Fauxmo

  device on or off, and when Alexa [queries the device

  state](https://github.com/n8henrie/fauxmo-plugins/issues/3). The `on` and

  `off` methods should return a `bool` that suggests whether they succeeded,

  and `get_state` should return `"on"`, `"off"`, or `"unknown"`. If you have no

  way to query state, consider using a simple `return "unknown"` as your

  `get_state` method, or you can return `super().get_state()` to use the last

  successful command as the current state (e.g. of `.on()` succeeded, return

  `"on"`). Note that this behavior means that if you manually switch a device

  or change it with another program that your reported state will be incorrect.

- Your plugin will be initialized if the exact (case sensitive) name is listed

  as a key under the `PLUGINS` section in your Fauxmo configuration (please see

  the Fauxmo docs for details), and if you include the path to the file

  that provides your plugin class as the `path` subkey.

- Each device you plan to use with a plugin will be listed under the `DEVICES`

  key of your plugin.

- Your plugin class will receive several `kwargs` on initialization, including

  the `name` and `port` that the Fauxmo device will use, as defined in your

  Fauxmo config. Hopefully this will allow users to implement some custom

  debugging / logging features.

- If you want your plugin class to determine its own port in code or if you

  decide to override the `__init__` method, you may need to do some combination

  of the following:

  - `super().__init__(name=name, port=port)` in your custom `__init__`.

  - Define the "private" `self._port` attribute.

  - Override the `FauxmoPlugin.port()` property.

- If your plugin has external dependencies, I highly recommend that you include

  the version of the dependency in your module-level docstring, especially if

  you're going to publish your plugin as a Gist.



I will not be providing much support to users needing help with plugins. I'm an

intermediate Pythonista at best, so if you are just learning about classes,

inheritance, and abstract methods, please feel free to make a new issue for

problems you encounter, but I might not be much help. On the other hand, if

you're a more advanced Pythonista, feel free to make suggestions.



### Plugins provided in the `fauxmo-plugins` repo



I'm going to include a few handy plugins here for reference. To use them in

your Fauxmo installation, all you need to do is get a local copy of the file

and include the `path` in your Fauxmo config as described above. You could do

this a few ways:



1. Clone the repo `git clone https://github.com/n8henrie/fauxmo-plugins.git`

1. Use `"path": "~/path/to/fauxmo-plugins/exampleplugin.py"` in your config



Alternatively,



1. Download the specific plugin you're interested in by clicking on the file in

   your web browser, clicking the `Raw` button, and using `wget` or `curl` to

   download the resulting file.

1. Include the path to that file as the `path` for that plugin.



If you think your plugin would be good to include in the `fauxmo-plugins`

repo, feel free to send me a pull request. To be merged:



- Must by python 3.6+ compatible

- Include a reasonable docstring that:

  - Explains the intended purpose, usage, and any required config variables.

  - Includes as pinned version numbers for any dependencies at the end.

- The file should:

  - Include type annotations.

  - Pass `mypy --ignore-missing-imports`.

  - Pass `flake8`.



Additionally, I'd like to include a list of interesting plugins here in the

README, even if the owners don't want to be included in this repo.



### Pre-installed plugins



Fauxmo comes with few plugin classes already available in the `fauxmo.plugins`

package. If you think your plugin would be good to include as one of these,

send a PR to that repo. Please note that I would strongly prefer not to have

any 3rd party / non-stdlib dependencies for the core Fauxmo package, in

addition to the requirements for the `fauxmo-plugin` repo above.



## Tests



Tests are *highly* recommended.



The modules are not installable, so you'll need to be able to import your class

directly from the module file. This can be done by monkeypatching `sys.path`,

but I prefer if you just use `python3 -m pytest tests/` from the root

directory, which will prompt Python to add it to `PYTHONPATH`, and should allow

you to import your class: `from myplugin import MyPlugin`.



You may find the `fauxmo_server` pytest fixture helpful -- given the path to a

config file as its only argument, it returns a context manager that is a Fauxmo

instance using that config. Using this context manager and a small sample

config, you can simulate receiving a "turn on" command from the Echo by posting

`'1'` to the

`http://localhost:12345/upnp/control/basicevent1` endpoint, where `localhost`

is your config's `["FAUXMO"]["ip_address"]` and `12345` is the `port` for one

of your plugin's Fauxmo device instances. See `tests/test_restapiplugin.py` and

`tests/test_restapiplugin_config.json` for an example.



Alternatively, you can test your plugin directly without using the rest of the

Fauxmo machinery by reading in your config and ensuring that e.g.

`YourPlugin(**device).on()` works as intended (again, see

`tests/test_restapiplugin.py` as an example).



NB: To facilitate simultaneous development between n8henrie/fauxmo and

n8henrie/fauxmo-plugins, `requirements-test.txt` pulls the latest version of

the dev branch of Fauxmo from GitHub; this is to help ensure that the automated

CI tests can run if I am pushing out changes to both repos that are not yet

ready to be merged into master or get pushed to PyPI. I suggest that if you're

developing locally and need to make simultaneous PRs against Fauxmo and

Fauxmo-plugins that you check out a separate branch in each and temporarily

change the `requirements-test.txt` file to something like `-e

git+file:///abs/path/to/local/fauxmo/repo#egg=fauxmo`.



## Interesting Plugins (not included in this repo)



- None yet. Why not be the first?



## Troubleshooting / FAQ



See also: [Fauxmo FAQ](https://github.com/n8henrie/fauxmo#troubleshooting--faq)