misb/lib.rs
1//! MISB KLV metadata, the telemetry carried next to the video in STANAG 4609
2//! full motion video from drones and other airborne sensors.
3//!
4//! | Standard | Module | What it is |
5//! |---|---|---|
6//! | SMPTE ST 336, MISB ST 0107 | [`klv`] | Keys, BER lengths, BER-OID tags, local sets, splitting a byte stream into packets |
7//! | MISB ST 0601 | [`st0601`] | UAS Datalink Local Set: platform, sensor and frame-center position, footprint, timestamps, 143 tags |
8//! | MISB ST 0102 | [`st0102`] | Security Local Set (classification markings), nested in ST 0601 tag 48 |
9//! | MISB ST 0903 | [`st0903`] | Video Moving Target Indicator (VMTI): detections in the frame, nested in tag 74 or standalone |
10//! | MISB ST 1201 | [`imapb`] | IMAPB floating point to integer mapping used by the newer tags |
11//! | ST 0601, ST 1201 conformance | [`conform`] (`std`) | Fails a stream on missing KLV, mandatory tags, checksums, sizes, mappings, time going backwards and impossible positions |
12//! | ISO 13818-1 | [`ts`] (`std`) | Takes the KLV data streams out of an MPEG transport stream without ffmpeg |
13//!
14//! Decoding is zero-copy and does not allocate: a [`st0601::Packet`] borrows
15//! the input and hands out typed values on demand. The checksum is verified
16//! by [`st0601::Packet::parse`]; lengths are bounded by the input, so
17//! corrupt or hostile data returns an [`Error`] instead of panicking.
18//! Encoding (the `Builder`s) needs the `alloc` feature, which `std` (the
19//! default) turns on.
20//!
21//! ```
22//! # fn main() -> Result<(), misb::Error> {
23//! use misb::st0601::{Builder, Packet, Tag};
24//!
25//! // Build a packet the way a payload computer would ...
26//! let mut b = Builder::new(1_700_000_000_000_000);
27//! b.text(Tag::MissionId, "TRAINING 4")?
28//! .float(Tag::SensorLatitude, 38.8895)?
29//! .float(Tag::SensorLongitude, -77.0353)?
30//! .float(Tag::SensorTrueAltitude, 450.0)?
31//! .float(Tag::PlatformHeadingAngle, 92.5)?;
32//! let bytes = b.finish();
33//!
34//! // ... and read it back the way a ground station would.
35//! let (packet, used) = Packet::parse(&bytes)?;
36//! assert_eq!(used, bytes.len());
37//! let pos = packet.sensor_position().unwrap();
38//! assert!((pos.lat - 38.8895).abs() < 1e-6);
39//! assert_eq!(packet.text(Tag::MissionId), Some("TRAINING 4"));
40//! # Ok(()) }
41//! ```
42//!
43//! Items that describe weapons (ST 0601 tags 60, 61, 62 and 140) are passed
44//! through as raw bytes and never interpreted. This crate covers metadata
45//! for situational awareness and interoperability only.
46#![no_std]
47#![forbid(unsafe_code)]
48#![warn(missing_docs)]
49
50#[cfg(feature = "alloc")]
51extern crate alloc;
52#[cfg(feature = "std")]
53extern crate std;
54
55#[cfg(feature = "std")]
56pub mod conform;
57pub mod imapb;
58pub mod klv;
59mod math;
60pub mod st0102;
61pub mod st0601;
62pub mod st0903;
63#[cfg(feature = "std")]
64pub mod ts;
65
66#[cfg(doctest)]
67#[doc = include_str!("../README.md")]
68struct ReadmeDoctests;
69
70#[cfg(doctest)]
71#[doc = include_str!("../docs/integration.md")]
72struct IntegrationDoctests;
73
74use core::fmt;
75
76/// Everything that can go wrong while decoding or encoding.
77#[derive(Clone, Copy, Debug, PartialEq, Eq)]
78#[non_exhaustive]
79pub enum Error {
80 /// The input ended in the middle of a key, length or value.
81 Truncated,
82 /// A BER length or BER-OID tag is malformed (too long, or longer than the input).
83 BadLength,
84 /// The 16-byte key is not the one this decoder expects.
85 WrongKey,
86 /// The packet does not end with a checksum item (tag 1, two bytes).
87 MissingChecksum,
88 /// The checksum item does not match the packet.
89 Checksum {
90 /// Checksum found in the packet.
91 found: u16,
92 /// Checksum computed over the packet.
93 computed: u16,
94 },
95 /// A value has the wrong length or type for its tag (encoding).
96 BadValue {
97 /// The tag being encoded.
98 tag: u32,
99 },
100 /// A number is outside the range its tag can carry (encoding).
101 OutOfRange {
102 /// The tag being encoded.
103 tag: u32,
104 },
105}
106
107impl fmt::Display for Error {
108 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
109 match self {
110 Error::Truncated => f.write_str("KLV data ends early"),
111 Error::BadLength => f.write_str("malformed BER length or tag"),
112 Error::WrongKey => f.write_str("unexpected universal key"),
113 Error::MissingChecksum => f.write_str("packet does not end with a checksum item"),
114 Error::Checksum { found, computed } => {
115 write!(
116 f,
117 "checksum mismatch: packet says {found:#06x}, computed {computed:#06x}"
118 )
119 }
120 Error::BadValue { tag } => write!(f, "tag {tag}: value has the wrong type or length"),
121 Error::OutOfRange { tag } => {
122 write!(f, "tag {tag}: value outside the range the tag can carry")
123 }
124 }
125 }
126}
127
128#[cfg(feature = "std")]
129impl std::error::Error for Error {}
130
131/// A WGS84 position: latitude and longitude in degrees, height in metres
132/// (above mean sea level or the ellipsoid, as the source tag says).
133#[derive(Clone, Copy, Debug, PartialEq)]
134pub struct GeoPoint {
135 /// Latitude, degrees north.
136 pub lat: f64,
137 /// Longitude, degrees east.
138 pub lon: f64,
139 /// Height in metres, if the packet has it.
140 pub height: Option<f64>,
141}