An overly ambitious but surprisingly successful attempt to build a home automation framework entirely in MicroPython. Runs on ESP32.
- Stand-alone nodes: Each ESP32 runs independently with no hub or cloud required.
- Designed for automation: Configure things to do what you want, when you want.
- Extensible hardware drivers: Object-oriented framework allows new device and sensor drivers to be added with just a few lines of code.
- Django-powered PWA: Installable web frontend to view node status, change configuration, and send API calls.
- Command line client: Interactive menus or CLI arguments, synchronizes with the django backend (or can be used standalone).
- Local API: Everything can be controlled with HTTP on LAN, no data leaves the network.
- Secure wifi setup: After flashing firmware a captive portal is served with HTTPS to securely set wifi credentials.
- Automation over remote control: Lots of commercial IOT products emphasize controlling things with your phone. This is a bad user experience - walking to the light switch is usually faster than finding the right button in a bloated app that gets a UI update right when you learn where everything is. Instead, this project aims to provide granular configuration options so you can automate things once and forget about it.
- Maintainability and testability: The project aims to be as DRY as possible. Functions shared by the web frontend and CLI tools are imported from modules in the util package so they can be maintained in one place. Most of the hardware-level API is abstracted into base classes and inherited by individual drivers to reduce bugs and make testing easier.
- Extensibility: New device and sensor drivers can often be written with fewer than 50 lines of code thanks to a cooperative class inheritance system. JSON metadata automatically integrates new drivers into the frontend with no additional javascript needed.
- Responsive and reliable: Since all requests stay on the LAN, latency is very low and everything still works when the internet goes down.
Pre-built firmware binaries can be downloaded from releases.
See firmware for build, flash, and wifi setup instructions.
The command line client can be used to generate config files, provision new nodes, check status, and send API commands using either interactive menus or CLI arguments. See the CLI readme for details.
See test readme.
Requirements:
- pipenv (>=2023.6.2)
- npm
- docker
Install dependencies for the frontend, firmware, and CLI tools:
pipenv install --dev
cd frontend
npm install
cd ..
cd firmware
npm install
Build the frontend and apply django database migrations:
cd frontend
npm run build
pipenv run python3 manage.py migrate
- Note: run
npm run watchto automatically rebuild bundles when react components change.
Install git hooks (see comments at the top of each file):
cp hooks/pre-commit hooks/post-commit .git/hooks/