Protocol

The DUPLO train's locomotive is a Bluetooth Low Energy (BLE) device that speaks the LEGO Wireless Protocol 3.0 (LWP3). It's the same protocol used by the other Powered Up hubs (BOOST Move Hub, Technic Hub, Powered Up remote). LEGO publishes the specification, so the message formats on this page are not guesswork: https://lego.github.io/lego-ble-wireless-protocol-docs/

What I had to measure myself, everything specific to the 2025 hub, is on The 2025 hub page.

Identifying a train

Bonding means saving a pairing between two Bluetooth devices. The system type is byte 1 of the LEGO-specific data in the train's Bluetooth advertisement (the signal it broadcasts so it can be found), so you can tell the generations apart before connecting. ./duplo scan prints it.

The Bluetooth service

BLE devices expose data through services and characteristics (GATT). This train uses one of each:

All traffic goes through that one characteristic: commands out, sensor values in. You write to it without asking for a response, and subscribe to it for notifications.

The LEGO part of the advertisement is six bytes:

[button, system_type, capabilities, last_network_id, status, option]

A 2025 train at rest advertises 00 21 02 ff 01 00. Watch the indexing: libraries such as node-poweredup count the two-byte company ID as part of the data. That's why their code checks manufacturerData[3] for the hub type, while in bleak the same byte is manufacturer_data[0x0397][1].

The train only advertises while it is switched on and not already connected. Close the LEGO app first, and press the button to wake the train.

Message format

Every message, in both directions, looks like this:

[length, hub_id (0x00), message_type, ...payload]

length includes itself. Messages longer than 127 bytes use a two-byte length, but nothing on this train is that long.

The message types used here:

Discovering what a hub has

As soon as you subscribe to notifications, the hub sends one Hub Attached I/O (0x04) message per built-in device:

[len, 0x00, 0x04, port, event, type_lo, type_hi, hw_rev×4, sw_rev×4]

event is 0x00 detached, 0x01 attached, 0x02 attached virtual. The 16-bit device type tells you what is on the port, for example a motor or a colour sensor. Always look ports up by device type, never by port number, because the port numbers changed between train generations.

Then ask the firmware to describe each port, which beats any hand-written table:

Port Information Request        [0x05, 0x00, 0x21, port, 0x01]
Port Mode Information Request   [0x06, 0x00, 0x22, port, mode, info_type]

Info type 0x01 returns MODE INFO:

[len, 0x00, 0x43, port, 0x01, capabilities, mode_count, input_modes×2, output_modes×2]

capabilities bits: 0x01 output, 0x02 input, 0x04 logically combinable, 0x08 logically synchronizable. input_modes and output_modes are 16-bit masks with one bit per mode. On the 2025 train these are unreliable; see The 2025 hub.

Each mode information reply (0x44) carries one info_type:

In VALUE FORMAT, type is 0 int8, 1 int16, 2 int32, 3 float. Together with datasets (how many values are in each reading), that is everything you need to decode a port value. So a client can read any device without hardcoding anything. ./duplo probe requests all of this and caches it.

Sending commands

Every write used here is a Port Output Command with the WriteDirectModeData subcommand:

[len, 0x00, 0x81, port, startup_completion, 0x51, mode, ...value]

• startup_completion 0x11 means execute immediately (0x10) and send feedback (0x01). The feedback comes back as a 0x82 message.
• 0x51 is the WriteDirectModeData subcommand.

So an 8-byte motor write is 08 00 81 <port> 11 51 <mode> <value>.

Reading sensors

Sensors send nothing until you ask. Turn on notifications one port at a time with Port Input Format Setup (Single):

[0x0A, 0x00, 0x41, port, mode, delta_u32_le, notify(0|1)]

delta is how much a value must change before the hub reports it. delta = 0 reports every sample: handy for seeing a stored value at once, but a flood otherwise. delta = 1 reports changes only.

One mode per port. Selecting a mode replaces whatever mode was active on that port. To read several modes of one port at once you need Combined Mode (0x42), and only ports that advertise the combinable capability support it. In practice you have to choose, for example between the speedometer's SPEED, COUNT and VELO.

Values then arrive as Port Value (Single):

[len, 0x00, 0x45, port, ...data]

Decode data using the VALUE FORMAT of the active mode. The message doesn't say which mode it is, so a client has to remember what it subscribed to.

In theory a long message can be split across BLE notifications, so a robust client rejoins them using the leading length byte. Nothing this train sends needs it.

Hub properties

Hub properties are facts about the hub itself, such as name or battery level:

Request   [0x05, 0x00, 0x01, property, 0x05]
Reply     [len, 0x00, 0x01, property, 0x06, ...value]

Operations: 0x01 set, 0x02 enable updates, 0x03 disable updates, 0x04 reset, 0x05 request update, 0x06 update.

RSSI is the received signal strength. Version numbers are packed into 32 bits, mostly as BCD (each decimal digit stored in 4 bits): major version in bits 31–28 (top bit reserved), minor in 27–24, bugfix as two BCD digits in 23–16, and build as four BCD digits in 15–0.

Hub actions

[0x04, 0x00, 0x02, action]

The 2025 train sends 0x30 and then 0x31 before it powers itself off. That is a useful warning; see the power management notes on The 2025 hub.

Generic errors

[0x05, 0x00, 0x05, offending_command, error_code]

A 0x06 reply to a 0x81 command is how I found out that a port is read-only: the hub understood the command but didn't accept the parameters.

The 2018 train

I haven't tested the 2018 train. This section comes from community sources.

motor   08 00 81 00 11 51 00 <speed>     signed, -100..100
sound   08 00 81 01 11 51 01 <sound>     3 brake, 5 depart, 7 water, 9 horn, 10 steam
LED     08 00 81 11 11 51 00 <colour>    LWP3 colour index

LWP3 colour numbers, used by the LED and the old colour sensor: 0 black, 1 pink/magenta, 2 purple, 3 blue, 4 light blue, 5 cyan, 6 green, 7 yellow, 8 orange, 9 red, 10 white, 0xFF none.

On that hub, voltage is a raw uint16; roughly raw × 6.4 / 3047 gives volts. The 2025 hub reports millivolts directly, so don't apply that scaling there.

The tool keeps these values as fallbacks, but finds ports by device type at runtime, so it works on either generation.