Skip to content

Zwift controller protocol

TL;DR

Zwift talks to a Zwift Ride through three characteristics: Zwift writes requests to 0003, the device answers on 0004, and button frames arrive on 0002. The session starts with a "RideOn" handshake, then Zwift asks for device information, battery level and input configuration. After that the device sends 0x23 keypad frames: a protobuf message with an inverted 32-bit button bitmap and two analog paddle values. The app repeats frames every 100 ms while something is held and resends the current frame every 5 s as a keepalive.

Everything on this page travels inside Direct Connect writes and notifications. See Wahoo Direct Connect for the framing.

Service and characteristics

UUID Name Properties Used for
0xFC82 (0000FC82-0000-1000-8000-00805F9B34FB) Zwift controls service Holds the three characteristics below.
00000001-19CA-4651-86E5-FA29DCDD09D1 Zwift service (128-bit) Holds the same three characteristics.
00000002-19CA-4651-86E5-FA29DCDD09D1 Async (0002) Notify Button frames and status messages, device to Zwift.
00000003-19CA-4651-86E5-FA29DCDD09D1 Sync RX (0003) Write Requests, Zwift to device.
00000004-19CA-4651-86E5-FA29DCDD09D1 Sync TX (0004) Notify (indicate under the 128-bit service) Replies, device to Zwift.

Most messages start with a one-byte opcode, followed by a small protobuf message.

The RideOn handshake

Zwift writes the ASCII text RideOn followed by two bytes to 0003. The app treats any write to 0003 that starts with RideOn and has at least two more bytes as the handshake.

Step Characteristic Bytes Meaning
Zwift writes 0003 52 69 64 65 4F 6E 02 04 RideOn + 02 04. The last two bytes vary with the Zwift version.
App notifies 0004 52 69 64 65 4F 6E 02 00 RideOn + 02 00.
App notifies 0002 2A 08 03 12 0D 22 0B 52 49 44 45 5F 4F 4E 28 30 29 00 A status message (opcode 0x2A) holding the text RIDE_ON(0).

The app answers every RideOn, not only the first one. The first answered RideOn marks the session as connected.

No encryption on this path

Bluetooth Zwift controllers can append a public key to the RideOn reply. Over Direct Connect, the app sends none and Zwift does not ask for one.

Device information

After the handshake, Zwift writes GET requests to 0003. A GET is opcode 0x00 followed by a protobuf message whose field 1 is a data object id. The app answers on 0004 with opcode 0x3C (GET response): field 1 repeats the id, and field 2 holds the data.

Request bytes Data object id What Zwift asks for App reply
00 08 00 0 (0x000) Device information page 3C 08 00 12 ... (see below)
00 08 10 16 (0x010) Client/server configuration 3C 08 10 12 02 08 00
00 08 80 08 1024 (0x400) Controller input configuration 3C 08 80 08 12 06 08 FF FF 03 10 03
00 08 83 06 771 (0x303) Battery state 3C 08 83 06 12 08 08 00 10 <percent> 18 00 20 00

Any other request on 0003 gets no reply. That matches the behavior of the presentation Zwift is known to accept.

Decoding the request bytes

00 is the opcode. 08 is the protobuf tag for field 1 as a varint. The rest is the id as a varint: 80 08 is 1024 and 83 06 is 771.

Device information page

The reply to id 0 wraps a DevInfoPage message. The app sends these fields:

Field Name Value Notes
1 protocolVersion 515 (0x0203)
2 systemFwVersion 00 00 01 01 4 raw bytes.
3 deviceName Zwift Ride
6 serialNumber 15 characters
7 systemHwRevision B.0
8 deviceCapabilities deviceType 2, capabilities 1 deviceType 2 is USER_INPUT_DEVICE.
9 manufacturerId 1
10 productId 8
11 deviceUid 12 characters

The deviceCapabilities list is how a device tells Zwift what roles it plays. A pure controller claims only USER_INPUT_DEVICE. For comparison, see the replies seen from other devices.

Here is a full reply with synthetic serial and id values:

3C                      opcode 0x3C, GET response
08 00                   field 1: data object id 0
12 45                   field 2: 69 bytes of data
  0A 43                 DevInfo.field 1: DevInfoPage, 67 bytes
    08 83 04            protocolVersion 515
    12 04 00 00 01 01   systemFwVersion
    1A 0A 5A 77 69 66 74 20 52 69 64 65                         deviceName "Zwift Ride"
    32 0F 30 42 2D 30 31 32 33 34 35 36 37 38 39 41 42          serialNumber "0B-0123456789AB" (synthetic)
    3A 03 42 2E 30                                              systemHwRevision "B.0"
    42 04 08 02 10 01                                           deviceCapabilities {deviceType 2, capabilities 1}
    48 01                                                       manufacturerId 1
    50 08                                                       productId 8
    5A 0C 30 31 32 33 34 35 36 37 38 39 41 42                   deviceUid "0123456789AB" (synthetic)

Controller input configuration

The reply to id 1024 says which inputs the controller has: field 1 = 0xFFFF (supported digital inputs) and field 2 = 3 (supported analog inputs).

Battery

The reply to id 771 (0x303) carries the battery percentage in field 2 of the inner message:

Bytes Meaning
3C GET response
08 83 06 Data object id 771
12 08 Field 2, 8 bytes follow
08 00 Inner field 1 = 0
10 46 Inner field 2 = battery percent (here 0x46 = 70)
18 00 20 00 Inner fields 3 and 4 = 0

The app fills in the battery level of your game controller when Windows reports one. The SDL power levels map to percentages: empty 5, low 20, medium 70, full 100, wired 100. If the level is unknown, the app reports 100.

Keypad frames

Button and paddle state goes to Zwift as notifications on 0002. Each frame is opcode 0x23 followed by a RideKeyPadStatus protobuf message.

Part Protobuf Content
Opcode 0x23
Field 1 (tag 08) uint32 varint Button bitmap, inverted: a pressed button clears its bit.
Field 3 (tag 1A) repeated message One entry per analog paddle.
Entry field 1 (tag 08) varint Location: 0 = left paddle (ZL), 1 = right paddle (ZR).
Entry field 2 (tag 10) sint32, zigzag Paddle value, -100 to 100.

The bit for each button is listed in the button reference. With nothing pressed, every bit is set, so field 1 is 0xFFFFFFFF, which encodes as the varint FF FF FF FF 0F.

The app always sends both paddle entries, even when they are 0.

Paddles: steering and braking

Paddle Location Steer (tilt outward) Brake (squeeze inward)
ZL 0 Negative, down to -100 = full left Positive, up to +100
ZR 1 Positive, up to +100 = full right Negative, down to -100

The app turns its steering value (-1 to 1) and brake value (0 to 1) into paddle values by multiplying by 100 and rounding. Braking uses both paddles at once. If steering and braking want the same paddle, the bigger value wins (steering wins a tie).

Worked examples

Idle, nothing pressed

23  08 FF FF FF FF 0F  1A 04 08 00 10 00  1A 04 08 01 10 00
    buttons: none      ZL = 0             ZR = 0

Shift up (RS1, mask 0x1000). The bitmap is ~0x1000 = 0xFFFFEFFF.

23  08 FF DF FF FF 0F  1A 04 08 00 10 00  1A 04 08 01 10 00
    RS1 pressed        ZL = 0             ZR = 0

Steer left, half way (steer = -0.5, so ZL = -50, zigzag 99 = 0x63).

23  08 FF FF FF FF 0F  1A 04 08 00 10 63  1A 04 08 01 10 00
    buttons: none      ZL = -50           ZR = 0

Brake, full (brake = 1.0, so ZL = +100 and ZR = -100; zigzag 200 = C8 01, zigzag 199 = C7 01).

23  08 FF FF FF FF 0F  1A 05 08 00 10 C8 01  1A 05 08 01 10 C7 01
    buttons: none      ZL = +100             ZR = -100

The full Direct Connect message for "shift up", as it leaves the app:

01 06 00 00 00 23                                  header: notification, seq 0, 35 bytes
00 00 00 02 19 CA 46 51 86 E5 FA 29 DC DD 09 D1    characteristic 0002
23 08 FF DF FF FF 0F 1A 04 08 00 10 00 1A 04 08 01 10 00

Timing

Rule Value Why
Controller polling every 25 ms The app reads the gamepad.
Send on change at once A new frame goes out as soon as the button or paddle state changes.
Repeat while active every 100 ms While any button is held or a paddle is not 0, the frame is resent.
Release one neutral frame When everything is released, the app sends one idle frame and then stops repeating.
Keepalive every 5 s The current frame (usually idle) is resent while Zwift is connected, as a real Zwift Ride does. Without traffic, controllers can be dropped after about 30 s.
Disconnect reset to neutral When Zwift disconnects, the stored state is reset so nothing is "stuck" on reconnect.
sequenceDiagram
    participant P as Gamepad
    participant A as App
    participant Z as Zwift
    P->>A: Right bumper pressed (mapped to Shift up)
    A->>Z: 0x23 frame, RS1 pressed
    A->>Z: same frame after 100 ms
    A->>Z: same frame after 100 ms
    P->>A: Right bumper released
    A->>Z: 0x23 idle frame
    Note over A,Z: quiet until the next change...
    A->>Z: idle frame (5 s keepalive)