TPM2.net

showstack / protocols / tpm2net

Also called TPM2, tpm2net, TPM2 Net.

A minimal LED matrix protocol from the ledstyles.de community: a start byte, a block type, a 16-bit frame size and raw pixel bytes, sent over UDP. It turns up whenever Jinx! or cheap ESP-based matrix hardware meets a real show and something has to feed it.

Lighting controlOpenledstyles.de communityReported

Stewarded by ledstyles.de community; no formal standards body.

Control Small, urgent, must arrive

Small messages that either repeat constantly or fire once. Bandwidth is almost never the problem.

What kills it. Latency and loss on the messages that fire once. A repeating level survives a dropped packet; a GO does not.

The four flows, and why the model is worth having →

Ports

udp/65506 TPM2.net data frames
0xFFE2. This is the port WLED and other receivers listen on.

udp/65442 Receiver responses back to the sender
0xFFA2. Many receivers never answer at all, so do not depend on it.

Addressing

No universes. A frame is raw pixel bytes split across numbered packets, with a one-based packet number and total packet count from 1 to 255 telling the receiver where each chunk belongs.

What goes wrong

The serial and network variants use different start bytes: 0xC9 for TPM2 over serial, 0x9C for TPM2.net. A parser written for one silently rejects the other and you get a dead matrix with clean traffic on the wire.

Packet number and total packet count are one-based, 1 to 255. A mapper that counts panels from zero puts the first chunk of every frame in the wrong place, which looks like a wiring fault.

There is no acknowledgement, no sequence recovery and no discovery. The protocol assumes a small flat switch, so the first wifi hop or router in the path turns it into a slideshow.

Nothing in the header describes colour order. RGB versus GRB is a receiver setting, so a matrix with the wrong colours is almost never the sender's fault.

Frame size is a 16-bit field, so one packet cannot carry an arbitrarily large matrix. Big panels have to be split and reassembled in order by the receiver, with no help if a packet goes missing.

The specification is a forum post, originally in German, with no conformance test. Implementations differ in small ways, so budget time for a packet capture against any receiver you have not used before.

Open source implementations

tpm2net (ESP8266) — C++, MIT
WLED — C++, EUPL-1.2

Typical use

Jinx! and similar matrix software driving DIY LED controllers
ESP8266 and ESP32 LED controllers taking a live pixel feed
Small scenic LED panels where a full DMX-over-IP stack is overkill
Bench testing pixel hardware without a lighting console in the room

Sources

TPM2 Protocol Description (English translation; serial 0xC9 vs net 0x9C, ports 65506 and 65442, packet numbering) — jblang, translating the original ledstyles.de thread primary
UDP Realtime / tpm2.net — WLED documentation (listen port 65506) — WLED Project
tpm2net — ESP8266 receiver implementation — rehrbar

Understand the mechanism

DMX on the wire Show networks

Something wrong, or missing?

Known gaps on this entry: first_published. If you can source one of them, that is a ten minute pull request.

Edit this entry on GitHub — one file, editable in your browser, and your handle goes on it permanently.

Work at ledstyles.de community; no formal standards body? Confirm or correct this entry — it is free, it stays free, and nothing about it is for sale.