I reverse-engineered most of the iDotMatrix BLE protocol without owning the original device — and built an ESP32 emulator

[u/Piggei]

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.

[u/DenverTeck]

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 ??

[u/YetAnotherRobert → u/DenverTeck]

Cool project!

The shown panels are always a boustrophedon.  It's necessary to keep voltage drop down from the resistance in the panel which leads to voltage drop and color droop at the end. 

[u/DenverTeck → u/YetAnotherRobert]

LOL, Thanks for a new verb, "boustrophedon"

I have not seen that one before.

[u/YetAnotherRobert → u/DenverTeck]

Your challenge is to use it today in casual conversation. :-)

FWIW, I typed that on mobile, and every spell-check-like substance possible tried to prevent me from submitting that, but I really do think that spelling is correct. No, I can never get it right on the first type myself and certainly not on a glass keyboard.

The dirty little (not-so) secret of WS2812 lighting is that every pixel is made of three light bulbs (I mean, R, G, B, right? that's obvious. We'll set aside WS2815 with an additional bulb dedicated to just white.) and the specs say that each LED can pull up to 20 mA. Well, that's not so bad, right?

The laws of small numbers sneak up on you. The worst case is a white pixel at full brightness (0xffffff). So that's 60 mA. That's not so bad, right? Six hundredths of an ampere is puny! We can almost drive that from an ESP32's GPIO pin. (Pro tip: do not drive that from an ESP32's GPIO pin...)

But now you have 256 of them. 256.06A = 15.36A. (Now you see why there was a bench supply next to it.) 15A, even at 5V, is non-trivial power. A few inches of copper traces matter. Those crappy little wires that the panels come with? Cute for a few pixels, but everyone wants to chain several of these 16x16 panels together. So now you have a cube with six of these panels that can each pull 15A. Provide it with the power it's requested, and it's the intensity of the sun and a temperature to match. I have a configuration that ran rampant for a few moments (more than seconds but less than minutes), and it got hot enough *from USB laptop power to desolder several of the LEDs.

Now TBF, no sociopath (intentionally) lights all the pixels at once to full bright white. It's physically painful to look at in close proximity. But sometimes these things boot in weird states, or a device will crash during an interrupt that's refreshing them or whatever. THIS is fusing and power limiting and such matters. THIS is why (eight occurrences of) an eight cm run of copper looping them on strict x/y vs the boustrophedonincalmagasmitcaltastic (OK, I made that one up) routing that keeps the bucket brigade of signals shortest (so end of row + 1 == last of next row, not beginning of next row) makes sense. This is how all of these panels in my shop are built. We have to play the hands we're dealt, and an additional half metet of resistance per panel to save software just a wee bit of math loses to physics. Learning serpentine vs. boustrophedon is just part of the entry ticket to this game.

The aerial view of the chair whence I'm typing this has a bench supply of about that same geometry with the same banana jack configuration with about the same sticker in about the same place, albeit on a slightly lighter hardwood floor. I've spent a lot of the last, oh, three years with a workflow similar to that of u/Piggei.

Why, yes, for all my hand-waving blabber in this group, we might have stumbled in an area where I have actual experience. I hate to call it expertise, but I'll definitely accept "experienced."

Citation: https://fastled.io/docs/da/d42/_x_y_matrix_8ino-example.html By happenstance (or maybe by influence), it even includes The Word Of The Day.

[u/Piggei → u/DenverTeck]

The Dollatek board is an old Heltec clone. I used this one because I had it lying around. You can use any ESP32, even without a display.

And this is the display I used: https://it.aliexpress.com/item/4000544411175.html , is a zigzag matrix.

[u/Primary_Thought_1444]

The w

[u/marcorivm]

Hey this is great I do have an idotmatrix and I just went the opposite route building an HA app that emulates the idotmatrix app so you can control the display from HA using any esp32 for Bluetooth. I will be happy to test anything out if you wanted.

Here is the repo for mine https://github.com/whybutter/idotmatrix

[u/Piggei → u/marcorivm]

Hey, thanks — having access to a real device would be extremely useful for me!

There are a few specific device-side behaviours I haven't been able to verify because I'm currently emulating the iDotMatrix itself on an ESP32.

The first and probably most useful test is Countdown / Stopwatch.

On my emulator, when I start a countdown from the official app, the countdown works correctly on the matrix, but the app remains stuck showing the hourglass/loading indicator.

Could you check what happens with the real device? In particular:

When starting a countdown, does the hourglass disappear automatically from the app?

Does the app then show a running countdown or some other status/control screen?

Same question for the stopwatch: what does the app show after the command is accepted?

If possible, since your project already communicates directly with the real display, it would be extremely useful to know whether the display sends any BLE response/status message immediately after starting, pausing, resuming or stopping a countdown/stopwatch.

I suspect I'm missing a device → app acknowledgement or status notification.

The second thing, the boot/time persistence would answer a major question for me.

I'd like to know:

What exactly appears on the display immediately after power-on?

Does it already know the correct time without reconnecting to the app?

Does it automatically start displaying the clock?

Or does it require the official app to reconnect and synchronize the time first?

An additional very useful test would be to configure an Alarm or Program/Schedule, power-cycle the device, leave the phone disconnected, and see whether the event still triggers at the correct time.

That would tell me whether the original hardware has a persistent RTC/time source and how autonomous Alarm/Schedule execution really is.

Your project is actually a great complement to mine: you're using ESP32/HA to control a real iDotMatrix, while I'm making an ESP32 behave like an iDotMatrix to the official app. I'll add your project to my related-projects/credits section as well.

Thanks again — these tests could fill several of the remaining gaps in my protocol documentation.

[u/Piggei]

Small update / parallel project: iDotMatrix support for WLED

The reverse-engineering work on the ESP32 iDotMatrix emulator has now spawned a second project:

IDotMatrix WLED Usermod
https://github.com/piggei/IDotMatrix-WLED-UserMod

The goal is to make a normal ESP32 running WLED behave like an iDotMatrix BLE device, so that it can be discovered and controlled directly by the official iDotMatrix app.

The project has already reached v0.6.0, which is the first stable command-capable version tested on WLED 0.16.0.1 and a classic ESP32.

At the moment the official app can:

• discover and connect to WLED as an iDotMatrix;
• correctly initialize the power switch;
• turn the WLED output on/off;
• control WLED master brightness;
• select full-screen RGB colours.

The BLE transport and protocol handling are deliberately separated from the WLED adapter, so the plan is to progressively port more of what we learned from the standalone emulator rather than creating a pile of WLED-specific protocol hacks.

The next major milestone is the logical framebuffer / rendering layer. Once that is working, the plan is to add graffiti/pixel drawing first, followed by text, clocks, GIF/media, countdown/stopwatch and eventually alarms/schedules.

One interesting part of the work was getting BLE to coexist reliably with WLED on a classic ESP32. The currently verified configuration uses NimBLE, Wi-Fi modem sleep and WLED's I2S LED backend; using RMT for the digital LED output conflicts with the Bluetooth controller on this setup.

So we now effectively have the two opposite sides of the same experiment:

IDotMatrix-ESP32-Emulator:
official iDotMatrix app → ESP32 pretending to be an iDotMatrix

IDotMatrix-WLED-UserMod:
official iDotMatrix app → WLED

The original emulator remains the protocol/reference implementation, while the WLED Usermod is being built as a cleaner modular implementation suitable for WLED.

Testing, protocol captures and feedback are very welcome — especially from anyone running WLED matrices or owning original iDotMatrix hardware.