sidereon_core/rtcm/mod.rs
1//! RTCM 3 differential-GNSS stream decoding and encoding.
2//!
3//! RTCM 10403.x ("RTCM Standard for Differential GNSS Services, Version 3") is
4//! the dominant wire format for real-time GNSS correction and observation
5//! streams: base-station observations, reference coordinates, antenna metadata,
6//! and broadcast ephemerides flow from a caster to a rover as a sequence of
7//! framed binary messages. This module is a sans-I/O codec for that stream,
8//! built to the same shape as the crate's RINEX / SP3 / IONEX parsers:
9//!
10//! 1. a forgiving byte-level frame layer ([`framing`]) that syncs on the `0xD3`
11//! preamble, reads the 10-bit length, and verifies the 24-bit CRC-24Q;
12//! 2. a format-agnostic canonical IR ([`Message`] and its typed variants) that
13//! stores each field as its raw transmitted integer; and
14//! 3. an encoder that turns the IR back into bytes, so a decode followed by an
15//! encode round-trips byte-for-byte.
16//!
17//! ## Message coverage
18//!
19//! Decoded and encoded:
20//!
21//! | Message | Numbers | IR type |
22//! |--------------------|------------------------------------------|---------|
23//! | MSM4 observations | 1074 / 1084 / 1094 / 1104 / 1114 / 1124 / 1134 | [`MsmMessage`] |
24//! | MSM7 observations | 1077 / 1087 / 1097 / 1107 / 1117 / 1127 / 1137 | [`MsmMessage`] |
25//! | Station coordinates| 1005 / 1006 | [`StationCoordinates`] |
26//! | Antenna / receiver | 1007 / 1008 / 1033 | [`AntennaDescriptor`] |
27//! | GPS ephemeris | 1019 | [`GpsEphemeris`] |
28//! | GLONASS ephemeris | 1020 | [`GlonassEphemeris`] |
29//!
30//! Any other message number is preserved losslessly as [`Message::Unsupported`]
31//! (its raw body is kept so the frame still round-trips). Deferred message types
32//! include the other MSM variants (MSM1/2/3/5/6), the legacy L1/L1-L2
33//! observation messages (1001-1004, 1009-1012), the network-RTK and SSR
34//! correction families, and the Galileo / BeiDou / QZSS ephemerides
35//! (1042-1046). They decode as `Unsupported` rather than erroring.
36//!
37//! ## Quick start
38//!
39//! ```
40//! use sidereon_core::rtcm::{self, Message, StationCoordinates};
41//!
42//! // Build a 1006 reference-coordinate message and frame it.
43//! let station = StationCoordinates {
44//! message_number: 1006,
45//! reference_station_id: 2003,
46//! itrf_realization_year: 0,
47//! gps_indicator: true,
48//! glonass_indicator: true,
49//! galileo_indicator: false,
50//! reference_station_indicator: false,
51//! ecef_x: 11_446_021_400,
52//! single_receiver_oscillator: false,
53//! reserved: false,
54//! ecef_y: -7_415_136_500,
55//! quarter_cycle_indicator: 0,
56//! ecef_z: 12_602_528_900,
57//! antenna_height: Some(15_000),
58//! };
59//! // A constructed message encodes either directly on the typed value or
60//! // through the [`Message`] wrapper; both produce the same body bytes.
61//! let body = station.encode();
62//! assert_eq!(body, Message::StationCoordinates(station).encode());
63//! let frame = rtcm::encode_frame(&body).unwrap();
64//!
65//! // Decode it back out of the framed stream.
66//! let decoded = rtcm::decode_messages(&frame);
67//! assert_eq!(decoded.len(), 1);
68//! match &decoded[0] {
69//! Message::StationCoordinates(s) => assert_eq!(s.reference_station_id, 2003),
70//! _ => panic!("expected station coordinates"),
71//! }
72//! ```
73
74mod antenna;
75pub(crate) mod bits;
76pub(crate) mod crc;
77mod ephemeris;
78mod framing;
79mod msm;
80mod ssr;
81mod station;
82
83#[cfg(test)]
84mod tests;
85
86use crate::error::Result;
87
88use bits::BitReader;
89
90pub use antenna::AntennaDescriptor;
91pub use ephemeris::{GlonassEphemeris, GpsEphemeris};
92pub use framing::{
93 decode_frame, encode_frame, DecodedFrame, FrameScanner, FRAME_OVERHEAD, MAX_BODY_LEN, PREAMBLE,
94};
95pub use msm::{MsmHeader, MsmKind, MsmMessage, MsmSatellite, MsmSignal};
96pub use ssr::{
97 SsrClockRecord, SsrCodeBiasRecord, SsrHeader, SsrKind, SsrMessage, SsrOrbitRecord,
98 SsrPhaseBiasRecord, SsrPhaseBiasSignal,
99};
100pub use station::StationCoordinates;
101
102/// A message whose number is recognized but whose body this codec does not
103/// decode. The raw body is preserved so the frame still round-trips.
104#[derive(Clone, Debug, PartialEq, Eq)]
105pub struct UnsupportedMessage {
106 /// The RTCM message number (read from the first 12 bits of the body).
107 pub message_number: u16,
108 /// The undecoded message body.
109 pub body: Vec<u8>,
110}
111
112/// The canonical, format-agnostic RTCM 3 message IR.
113///
114/// Each variant stores raw transmitted field integers (see the per-type docs),
115/// and [`Message::encode`] is the exact inverse of [`Message::decode`].
116///
117/// The variant set is the codec's full supported coverage; any other message
118/// number decodes to [`Message::Unsupported`], so the enum is exhaustive and a
119/// caller can both build any variant from scratch and match every case.
120#[derive(Clone, Debug, PartialEq, Eq)]
121pub enum Message {
122 /// An MSM4 or MSM7 multi-signal observation message.
123 Msm(MsmMessage),
124 /// A 1005 / 1006 station antenna reference point.
125 StationCoordinates(StationCoordinates),
126 /// A 1007 / 1008 / 1033 antenna or receiver descriptor.
127 AntennaDescriptor(AntennaDescriptor),
128 /// A 1019 GPS broadcast ephemeris.
129 GpsEphemeris(GpsEphemeris),
130 /// A 1020 GLONASS broadcast ephemeris.
131 GlonassEphemeris(GlonassEphemeris),
132 /// A supported RTCM SSR correction message.
133 Ssr(SsrMessage),
134 /// A recognized-but-undecoded message, preserved verbatim.
135 Unsupported(UnsupportedMessage),
136}
137
138/// Read the 12-bit RTCM message number from the start of a message body.
139///
140/// Returns [`Error::Parse`] if the body is shorter than 12 bits.
141pub fn message_number(body: &[u8]) -> Result<u16> {
142 let mut r = BitReader::new(body);
143 Ok(r.u(12)? as u16)
144}
145
146impl Message {
147 /// Decode a single RTCM 3 message body (the bytes between a frame's length
148 /// word and its CRC).
149 ///
150 /// Never errors on an unknown message number: an unrecognized type decodes
151 /// to [`Message::Unsupported`]. Errors only on a truncated body of a
152 /// recognized type.
153 pub fn decode(body: &[u8]) -> Result<Self> {
154 let number = message_number(body)?;
155 let message = match number {
156 1005 | 1006 => Message::StationCoordinates(StationCoordinates::decode(body)?),
157 1007 | 1008 | 1033 => Message::AntennaDescriptor(AntennaDescriptor::decode(body)?),
158 1019 => Message::GpsEphemeris(GpsEphemeris::decode(body)?),
159 1020 => Message::GlonassEphemeris(GlonassEphemeris::decode(body)?),
160 n if msm::is_supported_msm(n) => Message::Msm(MsmMessage::decode(body)?),
161 n if ssr::is_supported_ssr(n) => Message::Ssr(SsrMessage::decode(body)?),
162 _ => Message::Unsupported(UnsupportedMessage {
163 message_number: number,
164 body: body.to_vec(),
165 }),
166 };
167 Ok(message)
168 }
169
170 /// Encode this message back into a body (without the transport frame).
171 pub fn encode(&self) -> Vec<u8> {
172 match self {
173 Message::Msm(m) => m.encode(),
174 Message::StationCoordinates(s) => s.encode(),
175 Message::AntennaDescriptor(a) => a.encode(),
176 Message::GpsEphemeris(e) => e.encode(),
177 Message::GlonassEphemeris(e) => e.encode(),
178 Message::Ssr(s) => s.encode(),
179 Message::Unsupported(u) => u.body.clone(),
180 }
181 }
182
183 /// The RTCM message number this IR encodes to.
184 pub fn message_number(&self) -> u16 {
185 match self {
186 Message::Msm(m) => m.message_number,
187 Message::StationCoordinates(s) => s.message_number,
188 Message::AntennaDescriptor(a) => a.message_number,
189 Message::GpsEphemeris(_) => 1019,
190 Message::GlonassEphemeris(_) => 1020,
191 Message::Ssr(s) => s.message_number,
192 Message::Unsupported(u) => u.message_number,
193 }
194 }
195
196 /// Decode this message and wrap it in a fresh RTCM transport frame.
197 ///
198 /// Returns [`Error::InvalidInput`] if the encoded body exceeds the frame
199 /// length limit.
200 pub fn to_frame(&self) -> Result<Vec<u8>> {
201 encode_frame(&self.encode())
202 }
203}
204
205/// Decode every CRC-valid frame in a byte buffer into the message IR.
206///
207/// Frames whose CRC fails, or whose body cannot be decoded, are skipped; the
208/// scan resynchronizes on the next preamble. This is the forgiving stream entry
209/// point for a noisy serial feed.
210pub fn decode_messages(bytes: &[u8]) -> Vec<Message> {
211 FrameScanner::new(bytes)
212 .filter_map(|frame| Message::decode(frame.body).ok())
213 .collect()
214}
215
216/// Owns an RTCM carry buffer for chunked stream decoding.
217#[derive(Clone, Debug, Default, PartialEq, Eq)]
218pub struct SsrStreamAssembler {
219 buf: Vec<u8>,
220}
221
222impl SsrStreamAssembler {
223 /// Build an empty assembler.
224 pub fn new() -> Self {
225 Self { buf: Vec::new() }
226 }
227
228 /// Append bytes and drain every complete CRC-valid frame.
229 pub fn push(&mut self, chunk: &[u8]) -> Vec<Result<Message>> {
230 self.buf.extend_from_slice(chunk);
231 let mut out = Vec::new();
232 let mut pos = 0usize;
233
234 while pos < self.buf.len() {
235 let Some(rel) = self.buf[pos..].iter().position(|&b| b == PREAMBLE) else {
236 pos = self.buf.len();
237 break;
238 };
239 pos += rel;
240 if self.buf.len() - pos < FRAME_OVERHEAD {
241 break;
242 }
243
244 let body_len =
245 ((usize::from(self.buf[pos + 1] & 0x03)) << 8) | usize::from(self.buf[pos + 2]);
246 let frame_len = 3 + body_len + 3;
247 if self.buf.len() - pos < frame_len {
248 break;
249 }
250
251 match decode_frame(&self.buf[pos..pos + frame_len]) {
252 Ok(frame) => {
253 out.push(Message::decode(frame.body));
254 pos += frame.frame_len;
255 }
256 Err(_) => {
257 pos += 1;
258 }
259 }
260 }
261
262 if pos > 0 {
263 self.buf.drain(..pos);
264 }
265 out
266 }
267
268 /// Number of bytes retained for the next chunk.
269 pub fn retained_len(&self) -> usize {
270 self.buf.len()
271 }
272}