TPHome is the home automation system that runs my house. I replaced the factory firmware on commercial blind controllers with my own, and built every layer on top of it: C++ firmware on the chips, a Python backend on a Raspberry Pi, and a Vue control panel with a live floor plan of the house. It's one of the modules of my personal cloud, tpcloud, and it's also a tab in my native app, tpapp.
I got tired of needing a different app, account and cloud for every brand of device in the house. They barely talk to each other, they stop working when the internet goes down, and none of them let me change how a device behaves. So I opened the switches, flashed my own firmware, and wrote the rest.
- Local first — the devices only talk to a broker on my LAN, with no vendor cloud involved
- No black boxes — every byte on the wire is my own binary protocol
- My rules — a blind stops at 20% on the first press down and only closes fully on the second
- One screen — every device in the house on a single floor plan, on the web or on my phone
🔌 |
⚙️ |
🗺️ |
browser tpapp (iOS · macOS)
│ │
└───────────────┬─────────────────┘
│ HTTPS · WSS
┌────────────────────────────▼─────────────────────────────┐
│ tpcloud gateway · Caddy │
│ /home and /home/api · protected by auth │
└───────────────┬──────────────────────────┬───────────────┘
│ │
┌───────────────▼────────────┐ ┌───────────▼───────────────┐
│ control panel (in tpcloud) │ │ api/ │
│ Vue 3 · served by gateway │ │ FastAPI · SQLite · OTA │
└────────────────────────────┘ └───────────┬───────────────┘
│ MQTT (binary)
┌───────────▼───────────────┐
│ Mosquitto broker (LAN) │
└───────────┬───────────────┘
│ WiFi
┌───────────▼───────────────┐
│ firmware/ │
│ blind switches · ESP8266 │
└───────────────────────────┘
Everything above the switches runs on the Raspberry Pi as part of tpcloud: its single tpcloud file carries this repo's API and a Mosquitto broker, and runs both when Home is turned on. TPHome doesn't have its own reverse proxy or web app: tpcloud's gateway puts the API behind the same login as the rest of my services, and the control panel is one of tpcloud's web apps.
Pressing "down" on a blind, from the floor plan:
Frontend sends POST /commands/B0101/down
│
▼
API publishes 0xC1 to tp/B0101/c
│
▼
Switch receives the byte, closes the relay and starts the motor
│
▼
Switch publishes a 2-byte state (position + motor state) every second while moving
│
▼
API parses it, saves it to SQLite and pushes a WebSocket event
│
▼
Floor plan animates the blind in real time
Every message on the wire is binary, and the first byte says what it is. Each device has an ID like B0102 (blind, zone 01, device 02) and its own set of topics:
| Topic | Direction | Purpose |
|---|---|---|
tp/{ID}/c |
to device | Control: 0x00–0x64 sets a position, 0xC0 up, 0xC1 down, 0xC2 stop, 0xC3 ping, 0xC4 state |
tp/{ID}/a |
to device | Admin: OTA, reboot, factory reset, device info, position override, preferences, lock |
tp/{ID}/s |
from device | State: 2 bytes, position (0–100) and motor state |
tp/a/c |
to all | Broadcast: every device answers with its ID, after a random delay so they don't collide |
If a switch drops off the network, the broker publishes its last will (0xFF) on its state topic and the API marks it offline straight away.
An admin can lock a blind from the device settings. The switch turns off every LED and its backlight, ignores its buttons, and refuses any movement until it's unlocked. The lock is stored in flash, so a reboot or a power cut doesn't clear it. Only tpcloud admins can lock or unlock: the API asks tpcloud's auth service on every call. While a blind is locked, the API also refuses movement, factory reset and deletion. If the switch was offline when it was locked or unlocked, the API sends the change again when it reconnects. Needs firmware 2.3.0 or later.
Fresh switch boots with no ID
│
▼
Derives a temporary ID from its MAC and announces itself on def/{MAC4}/s
│
▼
Shows up as "pending" in the control panel's device settings
│
▼
I assign it a zone and number, the API sends the ID to def/{MAC4}/a
│
▼
Switch saves the ID to flash, reboots and starts listening on tp/{ID}/*
If a switch can't reach the WiFi or the broker, a short press on the middle button in connection mode turns it into an access point named after its ID. Connecting to it and opening http://192.168.4.1 shows a form to enter new WiFi and MQTT credentials. The access point closes and the switch reboots after 10 minutes without a configuration.
The firmware is split into four layers, each one only depending on the ones below it, so porting to a new chip only means rewriting hardware/:
| Layer | Responsibility |
|---|---|
logic/ |
Device behaviour: blind motor, buttons, LEDs, button-to-action mapping |
network/ |
WiFi, MQTT, OTA and access-point provisioning |
settings/ |
Device ID, credentials and preferences persisted in flash |
hardware/ |
Pin drivers and chip-specific code |
A few rules I kept to, since the ESP8266 only has 80KB of RAM:
- Non-blocking loop — everything runs on
millis()timers, and the only wait is a 10 ms idle at the end of each loop so the WiFi modem can sleep between beacons. Nothing that blocks (MQTT reconnects, OTA, access point) runs while the motor is moving - No dynamic allocation — no
new,mallocorstd::vector, all state lives in fixed structs - Packed structs — anything written to flash or sent over MQTT has a predictable byte layout
- Low power when offline — a switch that can't reach the router turns its radio off between reconnect attempts, and reboots itself after 15 minutes offline
The blind's position is tracked from time, not from a sensor: each direction has a calibrated travel time, and the motor state machine (IDLE → MOVING → STOPPING, with a WAITING pause before reversing direction) accumulates the position every loop tick. The relays are interlocked so both directions can never be on at once, and the wiring can be inverted from the preferences without reflashing.
| Device | Chip | Status |
|---|---|---|
| Matismo WIP100 blind controller | TYWE3S · ESP8266 | ✅ Supported |
| BK7231N-based switches | CB3S / T34 · BK7231N | 🚧 In development |
Support for BK7231N chips (newer revisions of the same blind controller, and light switches) is in progress through LibreTiny. The build environments are there, but the drivers aren't finished yet.
| Layer | Technology |
|---|---|
| Firmware | C++17 · Arduino ESP8266 Core · PlatformIO · PubSubClient |
| API | FastAPI · Python · SQLModel · SQLite |
| Messaging | Mosquitto (MQTT) · custom binary protocol · WebSocket |
| Control panel | Vue 3 · Composition API · Pinia · TPCloud's shared UI, in tpcloud's web/home |
| Hosting | Inside the tpcloud server (home-api and mqtt-broker processes) · Raspberry Pi · behind the tpcloud gateway |
The API and the broker come with TPCloud, so there's nothing to install from this repo on the server. On the Linux machine that runs it:
curl -fsSL https://tpcloud.migueltaibo.com/install | sh # then say yes to Home in the setup
# or, on a server that already has TPCloud:
sudo tpcloud module enable homeThat starts the API and Mosquitto (port 1883 on the local network, where the switches connect), serves the control panel at /home and the API at /home/api, and adds the tphome command to move the blinds from the server's terminal (tphome --blind B0101 down). Home's settings (WiFi and MQTT) live in /var/lib/tpcloud/home/home.env.
With Docker instead, start tpcloud's compose file first, then this one: the API joins its tpcloud_gateway network.
git clone https://github.com/mtaibo/tphome
cd tphome
cp .env.example .env # WiFi, MQTT and database values, shared by the API and the firmware
docker compose up --build -dThe firmware runs on the physical switches, not on the server. The first flash needs a USB-TTL adapter at 3.3V (never 5V) wired to the chip's TX, RX, GND and VCC, with GPIO 0 pulled to GND on power-up to enter the bootloader.
The build takes the WiFi and broker values from this repo's .env (cp .env.example .env, with MQTT_IP set to the server's address on the local network):
cd firmware
pip install -r requirements.txt # PlatformIO and esptool
./build.sh # build, generating the credentials header from .env
./build.sh flash # build and flash over serialAfter that, updates go over the air: upload the binary in the control panel's firmware manager, activate it, and trigger the OTA from each device's settings. The switch downloads it from the Pi and reboots into the new version.