Meteorological Cooperative › Developers › Warning wire format

Warning wire format

All three warning systems send the same kind of message. This page specifies it: the framing, the header shared by every message, the body that differs by hazard, the signature, and the rules a decoder follows. The reference encoder and decoder are at src.meteo.rof/rep-wire, and conformance is judged against them.

Current version3, broadcast alongside version 2

EncodingFixed-width binary, big-endian, no compression

Typical size184 bytes for a first alert; 1,120 bytes with the full sub-region table

FramingLength-prefixed, with a 32-bit checksum over the whole frame

AuthenticationEd25519 signature over the frame; public keys published and rotated yearly

RepetitionEvery segment is sent three times at 200 ms spacing on every path

Why the format is what it is

Three constraints shaped it. The message must fit inside a single cell broadcast page, which fixes the ceiling at 1,395 bytes. It must decode on a microcontroller with a few kilobytes of memory, which rules out any format requiring a parser. And it must be readable by a decoder written years earlier, which requires strict versioning.

Fixed-width binary satisfies all three. A field sits at a known offset, its width is known, and a decoder reads it with an offset and a length. No text parsing occurs anywhere in the warning path.

Frame

offset  width  field
   0      2    magic, 0x52 0x50            "RP"
   2      1    version                     currently 3
   3      1    hazard                      1 KJS, 2 LEW, 3 FEW
   4      2    body length in bytes
   6      8    message identifier          monotonic, unique per event and segment
  14      1    segment number              1 to 4
  15      1    flags                       bit 0 cancellation, bit 1 test,
                                           bit 2 revision, bit 3 foreign territory
  16      n    body                        see below
16+n     64    signature                   Ed25519 over bytes 0 to 15+n
80+n      4    checksum                    CRC-32 over bytes 0 to 79+n

A decoder that fails the checksum discards the frame in silence. A decoder that fails the signature discards the frame and records the failure, since a valid frame with a bad signature indicates an attempt to inject a warning.

Common header

Fields present in the body of every hazard
Field	Width	Units	Meaning
origin_time	8	ms since epoch	Time the event began, or the time the threshold was crossed
issue_time	8	ms since epoch	Time this segment left the issuing node
expiry	4	s from issue	After this the message is stale and a device says so
latitude	4	1e-7 degree	Epicentre, slope unit centroid or reach midpoint
longitude	4	1e-7 degree	As above
certainty	1	0 to 100	Confidence in the estimate at the moment of issue
severity	1	1 to 4	Watch, warning, severe or imminent, movement or onset
area_count	1	count	Number of area records following the hazard block

Hazard block, earthquake

REP-KJS body, following the common header
Field	Width	Units	Meaning
depth	2	100 m	Focal depth
magnitude	2	0.01	Moment magnitude estimate
rep_here	2	0.01 step	Continuous intensity for the receiving location, before flooring
rep_max	1	step	Highest whole step estimated anywhere
onset	2	100 ms	Seconds until S wave arrival at the receiving location
coastal	1	enum	0 none, 1 assessing, 2 advisory, 3 warning
station_count	1	count	Stations contributing to this estimate

A device computes its own step by flooring rep_here. The continuous value travels so that a device near a boundary can present the step and a client with a display can show the value it came from. Rounding is done once, at the device, from the continuous number.

The onset field is the single most time-critical value in the format, and a device presents it as a count of seconds falling in real time. Where onset is zero or negative, the shaking has already reached the device, and the presentation states this.

Hazard block, landslide and flood

REP-LEW and REP-FEW bodies
Field	Width	Present in	Meaning
window_start	4	Both	Seconds from issue to the start of the period the warning covers
window_end	4	Both	Seconds from issue to the end of that period
probability	1	Both	Chance of the event occurring inside the window, 0 to 100
trigger	1	Both	Rainfall, saturation, instrument acceleration, seismic, surge, snowmelt
slope_state	1	LEW	Creeping, accelerating, moved; from the probing limb
volume_class	1	LEW	Expected order of magnitude of the moving mass
flood_kind	1	FEW	Flash, riverine, surge, overtopping
level_now	2	FEW	Current stage or water level, in centimetres above the reference
level_expected	2	FEW	Expected peak, same reference

The window and probability fields exist because a landslide or flood warning states a period and a chance, quantities the earthquake block has no need of. Fitting them into a shared structure took three revisions of the format, and it is the reason a device certified for one hazard handles all three.

Area records

The body ends with area_count records of four bytes each. Each names an area and states the value estimated there.

offset  width  field
   0      2    area code       sub-region, slope unit, reach or coastal cell
   2      1    value           REP step, or severity for LEW and FEW
   3      1    flags           bit 0 foreign territory, bit 1 highest value
                               in this message, bit 2 estimate superseded
                               by observation

Segment 1 sends the receiving area alone. Segment 3 sends every area in descending order of value, which produces the national reading heard in a broadcast. Area codes for the Republic are in rep-wire; a fork replaces that table and nothing else.

The foreign territory flag marks areas outside the Republic. It is set on the Aporean areas of any event on the eastern segment of the margin, and a device presents those areas after the domestic ones and states that they lie beyond the frontier.

Rules a decoder follows

Required decoder behaviour
Situation	Required behaviour
Unknown version, higher than the decoder knows	Decode the header and every field the decoder knows; ignore the remainder
Unknown version, lower	Decode by the older specification; every published version stays valid
Duplicate message identifier	Discard silently; every segment arrives three times on several paths
Segment arriving out of order	Present the highest segment number received; discard the older
Revision flag set	Replace the presented values; state that the figures were revised
Cancellation flag set	Withdraw the presentation within 400 ms and state the reason field
Test flag set	Present as a test, distinguishable by sound and by wording from a real warning
Expiry passed	State the age of the information; never present a stale message as current
Signature invalid	Discard and record; present nothing

Signing and keys

Every frame is signed with Ed25519 by the issuing node. Public keys are published in the register and on this site, rotate each year, and overlap for ninety days at the rotation. A device holds the current key and the previous one.

Signing prevents a false warning being injected into a delivery path. It offers no protection against a warning being blocked, and no cryptography can offer that: a device out of contact receives nothing, which is why five delivery paths run in parallel.

Version 2 and version 3

What changed and what did not

Version 3 added the certainty field, the foreign territory flag, and the level_now and level_expected fields for flood. Every version 2 field kept its offset, its width and its meaning.

A version 2 decoder reads a version 3 message correctly, ignoring the three additions. Both versions are broadcast in parallel and will remain so until at least 2029, which is five years from the introduction of version 3.