Skip to main content

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}