Grab an ESP32 dev board, a PCF8574 I2C expander, a few buttons or reed switches, and a laptop running Home Assistant with an MQTT broker. That is enough parts to make a puzzle prop report its state to a dashboard, which is what Djair Guilherme’s esp32_escaperoom library does.
What the library does
Djair released two open source Arduino libraries. esp32_escaperoom handles WiFi and MQTT on ESP32 boards. propmaker_escaperoom targets the RP2040 on the Adafruit PropMaker Feather, has no network at all, and talks to other puzzles over RS485. Both share one engine: a puzzle state machine, audio playback, and a pin contract per board. Both are MIT licensed.
On the Home Assistant side, the puzzle shows up through MQTT discovery using the ArduinoHA library, so entities appear without writing a line of YAML. The BombTimer example publishes eight sensors, a lock, four buttons, a select, two numbers, and a switch.
The wiring and config tricks
- A puzzle needs more inputs than an ESP32 has spare pins, so builds hang PCF8574 or PCF8575 expanders, an HT16K33 display, an ADS1115 analog input chip, a PCA9685 PWM driver, or a PN532 NFC reader off the I2C bus (SDA and SCL, 3.3 V logic).
- A hardware abstraction layer scans the I2C bus at boot, so the firmware finds which chips are present.
- Device name, room, puzzle ID, and broker credentials sit in a
wifi.jsonfile on the board. Moving a puzzle to another room means editing that file, not recompiling.
Wrap-up: try it on a classroom prop
Skip the escape room and start smaller. Wire one reed switch to a PCF8574 at address 0x20, add 4.7k pull-up resistors on SDA and SCL if your breakout lacks them, and flash the library’s example. Then check that the entity appears in Home Assistant under the MQTT integration. A “door opened” sensor for a school lab cabinet or a thesis demo box is a good first target. The write-up is at Hackster, the code is on GitHub, and ESP32 boards and I2C modules are stocked at circuit.rocks.
Frequently Asked Questions
How does the puzzle appear in Home Assistant?
The library uses ArduinoHA for MQTT discovery. The ESP32 publishes its entities to the broker, and Home Assistant adds them automatically, with no YAML to write.
Which boards does it support?
What will I learn if I build this?
You will practice I2C wiring with expanders, MQTT topics and discovery, state machine design, and config-file based deployment, useful for IoT thesis projects and classroom automation.
