{"id":16343346,"url":"https://github.com/n8henrie/fauxmo-plugins","last_synced_at":"2025-10-04T06:37:02.958Z","repository":{"id":49239461,"uuid":"85603406","full_name":"n8henrie/fauxmo-plugins","owner":"n8henrie","description":"Plugins for Fauxmo (emulated Wemo devices for the Amazon Echo)","archived":false,"fork":false,"pushed_at":"2025-06-10T08:30:57.000Z","size":110,"stargazers_count":14,"open_issues_count":2,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-08-23T06:12:45.282Z","etag":null,"topics":["amazon-echo","echo","home-automation","python3"],"latest_commit_sha":null,"homepage":"https://github.com/n8henrie/fauxmo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/n8henrie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["n8henrie"],"patreon":"n8henrie","open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":"n8henrie","issuehunt":null,"otechie":null,"custom":["https://n8henrie.com/donate"]}},"created_at":"2017-03-20T17:00:25.000Z","updated_at":"2024-06-30T16:22:56.000Z","dependencies_parsed_at":"2025-08-23T06:12:48.080Z","dependency_job_id":"31eee5e4-9775-4bd5-8761-a7190607f1d8","html_url":"https://github.com/n8henrie/fauxmo-plugins","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/n8henrie/fauxmo-plugins","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8henrie%2Ffauxmo-plugins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8henrie%2Ffauxmo-plugins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8henrie%2Ffauxmo-plugins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8henrie%2Ffauxmo-plugins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/n8henrie","download_url":"https://codeload.github.com/n8henrie/fauxmo-plugins/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/n8henrie%2Ffauxmo-plugins/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278277859,"owners_count":25960428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-04T02:00:05.491Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-echo","echo","home-automation","python3"],"created_at":"2024-10-11T00:24:15.719Z","updated_at":"2025-10-04T06:37:02.939Z","avatar_url":"https://github.com/n8henrie.png","language":"Python","funding_links":["https://github.com/sponsors/n8henrie","https://patreon.com/n8henrie","https://liberapay.com/n8henrie","https://n8henrie.com/donate"],"categories":[],"sub_categories":[],"readme":"# fauxmo-plugins\n\nmaster: [![master branch build\nstatus](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)\ndev: [![dev branch build\nstatus](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)\n\nPlugins for Fauxmo (emulated Wemo devices for the Amazon Echo)\n\n## Introduction and Rationale\n\nAs of Fauxmo 0.4.0, I am splitting the plugins out of the main\n[Fauxmo](https://github.com/n8henrie/fauxmo) code. Plugins were previously\nreferred to as `handlers`.\n\n- I've implemented a crude plugin import system that allows users to create\n  and user their own plugins by inheriting from `FauxmoPlugin` and including\n  the path to the file in their config.\n- This means I can remove dependencies from Fauxmo that some users may not use,\n  and hopefully users unfamiliar with virtualenvs will quit breaking their\n  installations due to my pinned versions.\n- I'll be able to update plugins without having to release a new version of\n  Fauxmo core, keeping them in their own separate VCS silos.\n\n## Using plugins\n\n### Personal user plugins\n\nThe biggest motivation for the changes to Fauxmo 0.4.0 was to allow users to\ncreate Fauxmo plugins to scratch their own itch. There are only a few\nrequirements to get started:\n\n- Your plugin will be class that inherits from the\n  `fauxmo.plugins.FauxmoPlugin` ABC.\n- Your plugin will override the abstract methods `on`, `off`, and `get_state`,\n  which will unsurprisingly be called when you tell Alexa to turn a Fauxmo\n  device on or off, and when Alexa [queries the device\n  state](https://github.com/n8henrie/fauxmo-plugins/issues/3). The `on` and\n  `off` methods should return a `bool` that suggests whether they succeeded,\n  and `get_state` should return `\"on\"`, `\"off\"`, or `\"unknown\"`. If you have no\n  way to query state, consider using a simple `return \"unknown\"` as your\n  `get_state` method, or you can return `super().get_state()` to use the last\n  successful command as the current state (e.g. of `.on()` succeeded, return\n  `\"on\"`). Note that this behavior means that if you manually switch a device\n  or change it with another program that your reported state will be incorrect.\n- Your plugin will be initialized if the exact (case sensitive) name is listed\n  as a key under the `PLUGINS` section in your Fauxmo configuration (please see\n  the Fauxmo docs for details), and if you include the path to the file\n  that provides your plugin class as the `path` subkey.\n- Each device you plan to use with a plugin will be listed under the `DEVICES`\n  key of your plugin.\n- Your plugin class will receive several `kwargs` on initialization, including\n  the `name` and `port` that the Fauxmo device will use, as defined in your\n  Fauxmo config. Hopefully this will allow users to implement some custom\n  debugging / logging features.\n- If you want your plugin class to determine its own port in code or if you\n  decide to override the `__init__` method, you may need to do some combination\n  of the following:\n  - `super().__init__(name=name, port=port)` in your custom `__init__`.\n  - Define the \"private\" `self._port` attribute.\n  - Override the `FauxmoPlugin.port()` property.\n- If your plugin has external dependencies, I highly recommend that you include\n  the version of the dependency in your module-level docstring, especially if\n  you're going to publish your plugin as a Gist.\n\nI will not be providing much support to users needing help with plugins. I'm an\nintermediate Pythonista at best, so if you are just learning about classes,\ninheritance, and abstract methods, please feel free to make a new issue for\nproblems you encounter, but I might not be much help. On the other hand, if\nyou're a more advanced Pythonista, feel free to make suggestions.\n\n### Plugins provided in the `fauxmo-plugins` repo\n\nI'm going to include a few handy plugins here for reference. To use them in\nyour Fauxmo installation, all you need to do is get a local copy of the file\nand include the `path` in your Fauxmo config as described above. You could do\nthis a few ways:\n\n1. Clone the repo `git clone https://github.com/n8henrie/fauxmo-plugins.git`\n1. Use `\"path\": \"~/path/to/fauxmo-plugins/exampleplugin.py\"` in your config\n\nAlternatively,\n\n1. Download the specific plugin you're interested in by clicking on the file in\n   your web browser, clicking the `Raw` button, and using `wget` or `curl` to\n   download the resulting file.\n1. Include the path to that file as the `path` for that plugin.\n\nIf you think your plugin would be good to include in the `fauxmo-plugins`\nrepo, feel free to send me a pull request. To be merged:\n\n- Must by python 3.6+ compatible\n- Include a reasonable docstring that:\n  - Explains the intended purpose, usage, and any required config variables.\n  - Includes as pinned version numbers for any dependencies at the end.\n- The file should:\n  - Include type annotations.\n  - Pass `mypy --ignore-missing-imports`.\n  - Pass `flake8`.\n\nAdditionally, I'd like to include a list of interesting plugins here in the\nREADME, even if the owners don't want to be included in this repo.\n\n### Pre-installed plugins\n\nFauxmo comes with few plugin classes already available in the `fauxmo.plugins`\npackage. If you think your plugin would be good to include as one of these,\nsend a PR to that repo. Please note that I would strongly prefer not to have\nany 3rd party / non-stdlib dependencies for the core Fauxmo package, in\naddition to the requirements for the `fauxmo-plugin` repo above.\n\n## Tests\n\nTests are *highly* recommended.\n\nThe modules are not installable, so you'll need to be able to import your class\ndirectly from the module file. This can be done by monkeypatching `sys.path`,\nbut I prefer if you just use `python3 -m pytest tests/` from the root\ndirectory, which will prompt Python to add it to `PYTHONPATH`, and should allow\nyou to import your class: `from myplugin import MyPlugin`.\n\nYou may find the `fauxmo_server` pytest fixture helpful -- given the path to a\nconfig file as its only argument, it returns a context manager that is a Fauxmo\ninstance using that config. Using this context manager and a small sample\nconfig, you can simulate receiving a \"turn on\" command from the Echo by posting\n`'\u003cBinaryState\u003e1\u003c/BinaryState\u003e'` to the\n`http://localhost:12345/upnp/control/basicevent1` endpoint, where `localhost`\nis your config's `[\"FAUXMO\"][\"ip_address\"]` and `12345` is the `port` for one\nof your plugin's Fauxmo device instances. See `tests/test_restapiplugin.py` and\n`tests/test_restapiplugin_config.json` for an example.\n\nAlternatively, you can test your plugin directly without using the rest of the\nFauxmo machinery by reading in your config and ensuring that e.g.\n`YourPlugin(**device).on()` works as intended (again, see\n`tests/test_restapiplugin.py` as an example).\n\nNB: To facilitate simultaneous development between n8henrie/fauxmo and\nn8henrie/fauxmo-plugins, `requirements-test.txt` pulls the latest version of\nthe dev branch of Fauxmo from GitHub; this is to help ensure that the automated\nCI tests can run if I am pushing out changes to both repos that are not yet\nready to be merged into master or get pushed to PyPI. I suggest that if you're\ndeveloping locally and need to make simultaneous PRs against Fauxmo and\nFauxmo-plugins that you check out a separate branch in each and temporarily\nchange the `requirements-test.txt` file to something like `-e\ngit+file:///abs/path/to/local/fauxmo/repo#egg=fauxmo`.\n\n## Interesting Plugins (not included in this repo)\n\n- None yet. Why not be the first?\n\n## Troubleshooting / FAQ\n\nSee also: [Fauxmo FAQ](https://github.com/n8henrie/fauxmo#troubleshooting--faq)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn8henrie%2Ffauxmo-plugins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fn8henrie%2Ffauxmo-plugins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fn8henrie%2Ffauxmo-plugins/lists"}