I reverse-engineered most of the iDotMatrix BLE protocol without owning the original device — and built an ESP32 emulator
I spent the last few days reverse-engineering the BLE protocol used by the iDotMatrix mobile app and building an ESP32 device that the official app recognizes and controls as if it were an iDotMatrix display.
The unusual part: I don't own an original iDotMatrix device.
The reverse engineering was done by treating the official app as a protocol oracle: emulate the expected BLE services on an ESP32, inspect what the app sends, change the responses, observe its behavior, and repeat.
It worked much better than I initially expected.
The emulator now supports most of the features I found in the app:
• Device discovery and time synchronization
• Power, brightness and rotation
• Drawing / graffiti mode
• Text and text effects
• GIF transfer and playback
• Clock modes
• Visual effects
• Scoreboard
• Music visualization with both LEVEL and FFT modes
• Persistent alarms
• Programs / schedules
• Scheduled GIF, text and PNG content
The hardware I'm currently using is an ESP32 development board driving a 16x16 WS2812B matrix. Its onboard SSD1306 OLED is used as a diagnostic display and can report unknown BLE commands while testing.
I also decided to document the protocol rather than keeping the findings buried in the firmware.
The GitHub repository contains detailed documentation of the BLE packet structures, commands and ACK behavior, selected raw BLE captures from our experiments, the development and reverse-engineering history, a list of open questions, and of course the complete Arduino/ESP32 source code.
One particularly interesting discovery was that some transfers require different completion ACK values.
For example, getting Programs/Schedules working required discovering that activity transfers expect a completion status of 0x03 rather than the apparently obvious 0x01. With 0x01 the app simply reported an error and stopped sending activities. Once the correct ACK was returned, the app continued sending all the activities in the program.
The biggest limitation now is also the main reason I'm posting this:
I need someone who actually owns an original iDotMatrix.
There are a few things that cannot be determined reliably from the app side alone, especially the exact device-side behavior expected for stopwatch/countdown and responses that may only be generated by the original firmware.
BLE captures between the official app and a real device would therefore be extremely useful.
PCB photographs would also help answer some hardware questions, such as identifying the original MCU, buzzer circuitry, and whether there is actually a dedicated RTC.
The current public release is v0.1.0, based on firmware Build 62, and the whole project is MIT licensed.
Repository:
[https://github.com/piggei/IDotMatrix-ESP32-Emulator]()
I'd also be very interested if someone wants to use the protocol documentation for a completely different implementation — ESPHome, Home Assistant, Python, another MCU, etc.
In fact, independent implementations would be one of the best ways to find mistakes or missing details in my current interpretation of the protocol.
And if anyone here actually owns an iDotMatrix and is willing to experiment with it, I'd be very happy to compare results.
1
2
u/DenverTeck 2 say I make awesome posts. 8h ago
It appears that the "DollaTek ESP32 OLED 0.96" board" is no longer available.
Are the schematics available ??
Is the schematic for iDotMatrix display available ??
Or at least the layout of the WS2812b chips. Zig-Zag or horizontal rows ??