PROTOCOL NOTES / 11
Wire reference
Field widths, versions, control authority, and implemented constants.
Android and iOS software implemented · Apple Wi-Fi Aware, Bluetooth LE and mixing tested on hosts and emulators only · Physical qualification pending
Start with the exact bytes
Unsigned binary integers use network byte order unless specified otherwise. Base64 uses the canonical unpadded URL-safe alphabet. JSON signatures cover exact body.dump() bytes. Unknown message types do not gain authority.
Versions on the wire
| Object | Version |
|---|---|
Signed control bodies, hello and readiness probes | v 2 |
Invitation text, after the rideweave:v2: prefix | Format 3 |
| Discovery advertisement | Format 3 |
| Transport greeting | transportVersion 4 |
| Media envelope | Version 3 |
A peer presenting another transport version is refused at the greeting. An invitation of another format is refused with update guidance, and an advertisement of another format is ignored, so phones of different versions never link.
An 18-byte bundle header and a 5-byte frame entry
Public synthetic fixture with one frame. The protected RTP packet and the 16-byte HMAC follow these bytes. Select a field to highlight its bytes; the complete explanation remains below.
| Field | Byte offsets | Meaning |
|---|---|---|
| Version | 0–0 | Media envelope version 3. |
| Ride tag | 1–8 | First eight SHA-256 bytes of the textual ride ID. |
| Hop sequence | 9–16 | Directional per-link sequence, one per datagram, used with authentication and the 1,024-position replay window. |
| Frame count | 17–17 | Number of bundled frames, 1–8. |
| Hop budget | 18–18 | Remaining forwarding budget of this frame; reduced across relays. |
| Age | 19–20 | Accumulated media age of this frame in milliseconds. |
| Length | 21–22 | Length of the protected RTP packet that follows. |
Public test-only values; payload demonstrates envelope layout, not a valid SRTP ciphertext
Discovery advertisement
| Offset | Bytes | Field |
|---|---|---|
| 0 | 1 | Version 3 (advertisementVersion) |
| 1 | 8 | Ride tag |
| 9 | 32 | Raw public Ed25519 key |
| 41 | 1 | Root roster index; 255 denotes unassigned admission state |
| 42 | 1 | Path length |
| 43 | path length | Roster indexes from root to advertiser |
| p | 4 | Root pulse |
| p+4 | 4 | Advertisement serial |
| p+8 | 1 | Capability flags (table below) |
| p+9 | 2 | Cumulative cost, at most 12,000; the parent's offered cost plus the adjacent cost of the parent link, with the BLE formula max(600, C_adj + 400) when that link is ble |
| p+11 | 64 | Ed25519 signature of every preceding byte |
Capability flags
The byte at offset p+8 carries capability flags, covered by the advertisement signature. The same layout without bit 0 is the static capabilities value of join and roster member records.
| Capability bit | Mask | Meaning |
|---|---|---|
| 0 | 0x01 | Wi-Fi Aware child capacity (live NDP headroom) |
| 1 | 0x02 | Apple platform |
| 2 | 0x04 | Wi-Fi Aware available |
| 3 | 0x08 | NAN Pairing capable; set with bit 2 by every Apple device and by an Android phone whose platform reports NAN Pairing candidacy |
| 4 | 0x10 | BLE link capable |
| 5 | 0x20 | BLE host capable; requires bit 4 |
| 6–7 | 0xC0 | Maximum BLE links minus one (0–3 means 1–4); 0 on Android API level 29 and older; ignored when bit 4 is clear |
Direct link objects
Direct link objects are TLS-protected, unsigned and never relayed; the ordered TLS stream supplies their order.
| Type | Fields | Authorization and timing |
|---|---|---|
hello | v:2, ride, name, token | First engine object on every link; see above |
advert | advertisement: base64url of the signed binary discovery advertisement | Accepted only on a verified link (valid hello received), in any role except closing. Its raw public key must hash to the TLS peer ID. A failed structural check or identity mismatch closes the link; a serial not above the last one received on this link is ignored; a path that contains the receiver is accepted as route information but excludes the sender as a parent candidate (a child's advertisement always contains its parent). Sent after the link is verified and whenever the local advertisement is re-signed (refresh period or route-shape change). Processed exactly like a discovery observation with this link as its path |
Control message catalogue
| Type | Additional body fields | Authorization and propagation |
|---|---|---|
join | name, key public PEM, token, capabilities:uint8 (static capability flags, bit 0 zero) | Open admission, matching secret, signed source identity; relayed to organizer; at most 24 pending candidates |
roster | version:uint32, name, open:boolean, members[] | Organizer only, increasing version; fixed after seal/start; can reach pending links |
stream | stream descriptor below | Admitted source after seal; increasing source control seq per descriptor key (source, kind, edge); admitted active propagation/state sync only |
sync | None | Admitted sealed source requests re-publication of every current descriptor (voice and mix); no microphone activation |
heartbeat | muted:boolean, active:boolean, root, pulse:uint32, path[], cost, optional media:{ssrc,nextIndex}, optional transmission; the immediate heartbeat of a local mute change carries only muted and active | Admitted source, propagated; route refresh only if source is direct neighbor and shape valid; over a BLE link only on a muted/active change or at most every 3 s per source |
source_status | transmission | Admitted sealed source; current SSRC and ordered source progress; propagated on active admitted aware edges, never over a BLE link |
feedback | reports[], links[] | Admitted receivers; source reports at most 11, link reports at most 16; propagated, advisory adaptation; over a BLE link only the sender's own, and never relayed onward from a BLE link |
ping | stamp:uint64 monotonic ms, token:uint64 | Direct TLS neighbor only; signed, never flooded |
pong | ping:uint64 echoed stamp, token:uint64, receivedAtMs:uint64, sentAtMs:uint64 responder monotonic ms | Direct neighbor only; ordered responder times with processing <= total RTT, matched outstanding single-use ping; never flooded |
leave | None | Signed local admitted departure; propagated; marks source unavailable, does not remove/rekey roster or end others' sessions |
path_offer | root, path[], pulse:uint32, cost, revision:uint64, parentGeneration:uint64 | Direct admitted neighbor only; ordered fresh signed route; never flooded |
handoff_prepare | attempt:uint64, generation:uint64, revision:uint64 | Direct child asks candidate parent; tuple binds current offer, excludes known cycles; creates bounded lease |
handoff_ready | Same tuple | Candidate parent after bidirectional probes; child still needs its own proof |
handoff_activate | Same tuple, optional rollback:true | Child commits candidate; rollback requires newer generation on retained old active-child edge |
handoff_ack | Same tuple | Candidate confirms its active-child role; child publishes new path only after exact match |
handoff_abort | attempt, generation, optional revision, optional reason | Exact current tuple only; release candidate/preparation, not unrelated links |
handoff_retire | attempt, generation | Exact old active-child tuple; drain then scoped release |
Bluetooth LE channel frames
A Bluetooth LE link multiplexes one L2CAP channel. Each frame is a 2-byte big-endian length (1–2,046, counting kind and body), a 1-byte kind and a body; a whole frame is at most 2,048 bytes.
| Kind | Body |
|---|---|
| 0 stream | 1–512 bytes of the TLS neighbor stream, in order; never dropped |
| 1 datagram | One media envelope version 3 (67–1,280 bytes) or one readiness probe (66 bytes), never split or combined |
| 2 ack | uint64 big-endian cumulative count of bytes of kind-0 and kind-1 frames received, headers included |
Mix payload header
A mix source’s SRTP plaintext begins with this header, followed by one 20 ms Opus frame. Bit i of each set is roster index i, 0–11; bits 12–15 are sent as zero and ignored.
| Offset | Bytes | Field |
|---|---|---|
| 0 | 2 | Speaker set, unsigned big-endian roster bitmask |
| 2 | 2 | Mixer set, unsigned big-endian roster bitmask |
| 4 | rest | One 20 ms Opus frame |
An exact signed-body example
This public test vector demonstrates deterministic serialization. It is a synthetic ping, not a live ride token or captured user message.
{"ride":"000102030405060708090a0b0c0d0e0f","seq":7,"source":"56475aa75463474c0285df5dbf2bcab73da651358839e9b77481b2eab107708c","stamp":1234,"token":9,"type":"ping","v":2}Implemented constants
These values are extracted from the generated protocol reference at build time. Bluetooth LE, Apple and mixing values belong to the mixed-platform extension, which is tested on hosts and emulators only. Timer, radio and acoustic defaults remain physically unqualified.
| Production name | C++ type | Value |
|---|---|---|
version | std::uint8_t | 2 |
invitationVersion | std::uint8_t | 3 |
advertisementVersion | std::uint8_t | 3 |
invitationPrefix | char | "rideweave:v2:" |
serviceName | char | "_rideweave._tcp" |
awareKeyLabel | char | "rideweave-aware-v2:" |
hopKeyLabel | char | "rideweave-hop-v2:" |
exporterLabel | char | "EXPORTER-RideWeave-hop-v2" |
controlPort | unsigned | 38471 |
maxControlBytes | std::size_t | 16384 |
maxQueuedControlBytes | std::size_t | 131072 |
maxMediaBytes | std::size_t | 1280 |
transportVersion | std::uint8_t | 4 |
mediaEnvelopeVersion | std::uint8_t | 3 |
mediaBundleHeaderBytes | std::size_t | 18 |
mediaEntryHeaderBytes | std::size_t | 5 |
mediaBundleFrames | std::size_t | 8 |
mediaCoalesceMs | std::uint64_t | 5 |
hopMacBytes | std::size_t | 16 |
maxMembers | unsigned | 12 |
initialHopBudget | unsigned | 12 |
mediaAgeMs | std::uint64_t | 180 |
mediaQueueMs | std::uint64_t | 40 |
ingressPackets | std::size_t | 48 |
egressPackets | std::size_t | 32 |
handshakeMs | std::uint64_t | 5000 |
pingIntervalMs | std::uint64_t | 1000 |
linkSuspectMs | std::uint64_t | 3000 |
linkEarlySuspectMs | std::uint64_t | 2000 |
linkMediaSilenceMs | std::uint64_t | 1000 |
linkDeadMs | std::uint64_t | 6000 |
linkRecoveryPongs | unsigned | 2 |
discoveryFreshMs | std::uint64_t | 6000 |
rootFreshMs | std::uint64_t | 4500 |
discoveryRefreshMs | std::uint64_t | 1000 |
discoverySettledRefreshMs | std::uint64_t | 3000 |
pathEstablishMs | std::uint64_t | 25000 |
handoffProbeMs | std::uint64_t | 1000 |
handoffProbeIntervalMs | std::uint64_t | 250 |
handoffProbeAttempts | unsigned | 3 |
handoffAckMs | std::uint64_t | 1000 |
handoffDrainMs | std::uint64_t | 500 |
preparationLeaseMs | std::uint64_t | 2000 |
probeBytes | std::size_t | 66 |
probeRequest | std::uint8_t | 128 |
probeReply | std::uint8_t | 129 |
parentBetterMs | std::uint64_t | 10000 |
parentBetterLargeMs | std::uint64_t | 2000 |
parentHoldMs | std::uint64_t | 1500 |
routeCostMax | unsigned | 12000 |
adjacentCostMax | unsigned | 1000 |
adjacentCostMin | unsigned | 5 |
adjacentUnknownCost | unsigned | 50 |
adjacentLossCost | unsigned | 200 |
improvementNumerator | unsigned | 4 |
improvementDenominator | unsigned | 5 |
discoveryPruneMs | std::uint64_t | 15000 |
feedbackFreshMs | std::uint64_t | 3000 |
bitrateRecoveryMs | std::uint64_t | 10000 |
bitrateLow | int | 16000 |
bitrateInitial | int | 24000 |
bitrateHigh | int | 32000 |
initialExpectedLossPercent | int | 5 |
maximumExpectedLossPercent | int | 20 |
lossDegraded | double | 0.03 |
lossHealthy | double | 0.01 |
congestionRttGrowthMs | unsigned | 40 |
congestionArrivalJitterMs | unsigned | 15 |
congestionWindows | unsigned | 2 |
jitterInitialMs | int | 60 |
jitterMinimumMs | int | 40 |
jitterMaximumMs | int | 160 |
receiverReanchorMs | std::uint64_t | 1000 |
maximumPlcFrames | unsigned | 3 |
lateSpeechMs | int | 600 |
sourceHintFreshMs | std::uint64_t | 3000 |
dtxStartupMs | std::uint64_t | 2000 |
dtxHangoverMs | std::uint64_t | 1000 |
dtxAnalysisFreshMs | std::uint64_t | 20 |
dtxCallbackGapMs | std::uint64_t | 30 |
dtxSpeechProbability | float | 0.5f |
dtxOnsetDb | float | 12.0f |
dtxFloorRiseDb | float | 0.05f |
dtxPrerollFrames | unsigned | 5 |
dtxNearRangeDb | float | 25.0f |
mediaReceiveBudget | unsigned | 16 |
mediaSendBudget | unsigned | 128 |
mediaMailboxPackets | std::size_t | 1024 |
controlDedupEntries | std::size_t | 4096 |
hopReplayWindow | std::uint64_t | 1024 |
capabilityChildCapacity | std::uint8_t | 0x01 |
capabilityApple | std::uint8_t | 0x02 |
capabilityAware | std::uint8_t | 0x04 |
capabilityNanPairing | std::uint8_t | 0x08 |
capabilityBleLink | std::uint8_t | 0x10 |
capabilityBleHost | std::uint8_t | 0x20 |
capabilityBleLinksShift | unsigned | 6 |
bleServiceUuidPrefix | char | "6B1E0000-7C3A-4E55-9D2E-" |
bleRideTagUuidBytes | std::size_t | 6 |
bleRideInfoCharacteristicUuid | char | "6B1E0001-7C3A-4E55-9D2E-000000000000" |
bleRideInfoKeyLabel | char | "rideweave-ble-v2:" |
discoveryKeyLabel | char | "rideweave-discovery-v2:" |
bleRideInfoNonceBytes | std::size_t | 12 |
bleFrameStream | std::uint8_t | 0 |
bleFrameDatagram | std::uint8_t | 1 |
bleFrameAck | std::uint8_t | 2 |
bleMaxFrameBytes | std::size_t | 2048 |
bleStreamFrameBytes | std::size_t | 512 |
bleTlsRecordBytes | std::size_t | 1024 |
bleWindowMinBytes | std::size_t | 1536 |
bleWindowMs | std::uint64_t | 100 |
bleStreamAllowanceBytes | std::size_t | 1024 |
bleMediaQueueMs | std::uint64_t | 100 |
bleAckIntervalMs | std::uint64_t | 20 |
bleAckBytes | std::size_t | 1024 |
bleMaxQueuedControlBytes | std::size_t | 32768 |
bleHeartbeatRelayMs | std::uint64_t | 3000 |
bleCostPenalty | unsigned | 400 |
bleCostMin | unsigned | 600 |
bleMaxLinks | unsigned | 4 |
bleLegacyMaxLinks | unsigned | 1 |
bleIdleLinkMs | std::uint64_t | 10000 |
bleHostIdleLinkMs | std::uint64_t | 20000 |
bleAdvertReadMs | std::uint64_t | 3000 |
bleAdvertSlowReadMs | std::uint64_t | 15000 |
bleAdvertIdleReadMs | std::uint64_t | 60000 |
bleRejectMs | std::uint64_t | 60000 |
bleClientHelloMs | std::uint64_t | 1000 |
bleMergeJitterMs | std::uint64_t | 2000 |
btCallStuckMs | std::uint64_t | 5000 |
appleAwareMaxLinks | unsigned | 4 |
mixBitrate | int | 32000 |
mixHeaderBytes | std::size_t | 4 |
mixAnomalyWindowMs | std::uint64_t | 1000 |
Authority: Wire reference; generated constants; public test vectors. Public examples are synthetic. This guide is maintained against the private implementation; it does not imply access to its source.