https://github.com/terrabits/oittm-smart-plug
Hacking an ESP8266-based OITTM Smart Plug with Micropython.
https://github.com/terrabits/oittm-smart-plug
esp8266 hacking micropython
Last synced: about 1 month ago
JSON representation
Hacking an ESP8266-based OITTM Smart Plug with Micropython.
- Host: GitHub
- URL: https://github.com/terrabits/oittm-smart-plug
- Owner: Terrabits
- Created: 2019-12-23T23:13:10.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-01-13T19:08:11.000Z (over 6 years ago)
- Last Synced: 2025-10-08T19:58:58.143Z (8 months ago)
- Topics: esp8266, hacking, micropython
- Language: Python
- Size: 1.1 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Oittm Smart Plug Hack
Yet another ESP8266-based smart plug hack. This one is on the Oittm Smart Plug I purchased some time ago on Amazon.
I referenced [this Not Enough Tech article](https://notenoughtech.com/featured/esp8266-smart-plug/) which walks you through exactly how to get access to the ESP8266. From there, I began to code.
## User Interface
### Configuration Page
This is an MQTT-based hack.
To that end, the smart plug starts in access point mode and serves the following pages via HTTP:
After entering the config information and clicking `Submit`, the smart plug displays the following message:
The smart plug will then restart and attempt to connect to WiFi and the MQTT broker. If successful, it will continue to function. If unsuccessful, it will restart in access point mode and you can try again.
### Hard Reset
Pushing the button 10 times quickly (in < 3 s) will cause any saved settings to be deleted and the smart plug to perform a hard reboot.
### MQTT
When connected to WiFi and the MQTT broker, it can then be fully controlled via MQTT publishes to the following:
| Verb | Topic | Message | Result |
| --------- | ------------------- | ------------- | --------------------------------------------- |
| Publish | `main_topic/set` | `on` or `off` | Outlet is turned `on` or `off`, respectively |
| Publish | `main_topic/toggle` | don't care | Outlet state is toggled |
| Subscribe | `main_topic` | `on` or `off` | observed on state changes, with updated state |
## Hardware Requirements
- ESP8266-based smart plug
- micropython v1.12 or newer
If using a different smart plug, edit `src/smart_plug.py` to control the specifics of your device.
## Installation
From a fresh flash of micropython, copy all files from `src/` onto the microcontroller.
I use [rshell](https://github.com/dhylands/rshell).
```shell
# from rshell,
# with file system mounted to /pyboard:
cd path/to/project
cd src
cp -r http /pyboard
cp -r states /pyboard
cp *.py /pyboard
```
## Code
### State Diagram
The operation is summarized by the state diagram, below.
### Configuration
The configuration (handled by states with the `config/` prefix) is saved and recalled via the `Config` class in `src/config.py`.
All saved settings can be reset from the repl with the following snippet:
```python
from config import Config
import machine
# delete all saved state
config = Config()
config.delete()
# hard reboot
machine.reset()
```
This will force the smart plug to go into access point mode for reconfiguration.
### HTTP Server
I micro-HTTP server is included in `src/http`. This server is just "big" enough to handle this application.
It is not considered a complete or secure HTTP implementation.
### MQTT Server
As this hack uses MQTT, it requires access to a broker (server) on your network. MQTT is configured along with WiFi via the configuration page.
All MQTT settings are ultimately editable in `src/mqtt.py`.
### Wifi
Wifi control is implemented in `src/wifi.py`.