Add proper errors (#37)

Author: jbangelo

build.rs

@@ -66,6 +66,7 @@ fn main() {
         .whitelist_function("is_gal")
         .whitelist_function("is_qzss")
         .whitelist_function("sid_to_constellation")
+        .whitelist_function("sid_valid")
         .whitelist_function("code_to_constellation")
         .whitelist_function("constellation_to_sat_count")
         .whitelist_function("constellation_to_string")
@@ -75,6 +76,18 @@ fn main() {
         .whitelist_function("sid_to_carr_freq")
         .whitelist_function("code_string_to_enum")
         .whitelist_function("code_to_string")
+        .whitelist_var("NUM_SATS_GPS")
+        .whitelist_var("NUM_SATS_SBAS")
+        .whitelist_var("NUM_SATS_GLO")
+        .whitelist_var("NUM_SATS_BDS")
+        .whitelist_var("NUM_SATS_GAL")
+        .whitelist_var("NUM_SATS_QZS")
+        .whitelist_var("GPS_FIRST_PRN")
+        .whitelist_var("SBAS_FIRST_PRN")
+        .whitelist_var("GLO_FIRST_PRN")
+        .whitelist_var("BDS_FIRST_PRN")
+        .whitelist_var("GAL_FIRST_PRN")
+        .whitelist_var("QZS_FIRST_PRN")
         .whitelist_function("llhrad2deg")
         .whitelist_function("llhdeg2rad")
         .whitelist_function("wgsllh2ecef")
@@ -89,6 +102,7 @@ fn main() {
         .whitelist_function("calc_sat_az_el")
         .whitelist_function("calc_sat_doppler")
         .whitelist_function("get_ephemeris_status_t")
+        .whitelist_function("ephemeris_valid_detailed")
         .whitelist_function("ephemeris_valid")
         .whitelist_function("ephemeris_equal")
         .whitelist_function("ephemeris_healthy")

src/ephemeris.rs

@@ -11,32 +11,19 @@
 use crate::{
     c_bindings,
     coords::{AzimuthElevation, ECEF},
-    signal::{Code, Constellation, GnssSignal},
+    signal::{Code, Constellation, GnssSignal, InvalidGnssSignal},
     time::GpsTime,
 };
-use std::fmt::{Display, Formatter};
+use std::error::Error;
+use std::fmt;
 
 /// Number of bytes in  the Galileo INAV message
 // TODO(jbangelo) bindgen doesn't catch this variable on linux for some reason
 pub const GAL_INAV_CONTENT_BYTE: usize = (128 + 8 - 1) / 8;
 
-/// An error indicating that the ephemeris is invalid
-#[derive(Copy, Clone, Debug)]
-pub struct InvalidEphemeris {}
-
-impl Display for InvalidEphemeris {
-    fn fmt(&self, f: &mut Formatter) -> std::result::Result<(), std::fmt::Error> {
-        write!(f, "Invalid Ephemeris")
-    }
-}
-
-impl std::error::Error for InvalidEphemeris {}
-
-type Result<T> = std::result::Result<T, InvalidEphemeris>;
-
-/// Various statuses that an ephemeris can be in
-#[derive(Copy, Clone, Debug)]
-pub enum Status {
+/// Different ways an ephemeris can be invalid
+#[derive(Debug, Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash)]
+pub enum InvalidEphemeris {
     Null,
     Invalid,
     WnEqualsZero,
@@ -45,22 +32,55 @@ pub enum Status {
     TooOld,
     InvalidSid,
     InvalidIod,
+}
+
+impl fmt::Display for InvalidEphemeris {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "Invalid ephemeris ({:?})", self)
+    }
+}
+
+impl Error for InvalidEphemeris {}
+
+/// Various statuses that an ephemeris can be in
+#[derive(Debug, Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash)]
+pub enum Status {
+    Invalid(InvalidEphemeris),
     Valid,
 }
 
 impl Status {
     fn from_ephemeris_status_t(value: c_bindings::ephemeris_status_t) -> Status {
         match value {
-            c_bindings::ephemeris_status_t_EPH_NULL => Status::Null,
-            c_bindings::ephemeris_status_t_EPH_INVALID => Status::Invalid,
-            c_bindings::ephemeris_status_t_EPH_WN_EQ_0 => Status::WnEqualsZero,
-            c_bindings::ephemeris_status_t_EPH_FIT_INTERVAL_EQ_0 => Status::FitIntervalEqualsZero,
-            c_bindings::ephemeris_status_t_EPH_UNHEALTHY => Status::Unhealthy,
-            c_bindings::ephemeris_status_t_EPH_TOO_OLD => Status::TooOld,
+            c_bindings::ephemeris_status_t_EPH_NULL => Status::Invalid(InvalidEphemeris::Null),
+            c_bindings::ephemeris_status_t_EPH_INVALID => {
+                Status::Invalid(InvalidEphemeris::Invalid)
+            }
+            c_bindings::ephemeris_status_t_EPH_WN_EQ_0 => {
+                Status::Invalid(InvalidEphemeris::WnEqualsZero)
+            }
+            c_bindings::ephemeris_status_t_EPH_FIT_INTERVAL_EQ_0 => {
+                Status::Invalid(InvalidEphemeris::FitIntervalEqualsZero)
+            }
+            c_bindings::ephemeris_status_t_EPH_UNHEALTHY => {
+                Status::Invalid(InvalidEphemeris::Unhealthy)
+            }
+            c_bindings::ephemeris_status_t_EPH_TOO_OLD => Status::Invalid(InvalidEphemeris::TooOld),
             c_bindings::ephemeris_status_t_EPH_VALID => Status::Valid,
             _ => panic!("Invalid ephemeris_status_t value: {}", value),
         }
     }
+
+    /// Converts a `Status` into a Result.
+    ///
+    /// A valid status is represented by the empty `Ok` variant and an invalid status
+    /// is represented by the `Err` variant.
+    pub fn to_result(self) -> Result<(), InvalidEphemeris> {
+        match self {
+            Status::Valid => Ok(()),
+            Status::Invalid(invalid_status) => Err(invalid_status),
+        }
+    }
 }
 
 /// Orbital terms of an ephemeris
@@ -265,7 +285,10 @@ impl Ephemeris {
     }
 
     /// Calculate satellite position, velocity and clock offset from ephemeris.
-    pub fn calc_satellite_state(&self, t: GpsTime) -> Result<SatelliteState> {
+    pub fn calc_satellite_state(&self, t: GpsTime) -> Result<SatelliteState, InvalidEphemeris> {
+        // First make sure the ephemeris is valid at `t`, and bail early if it isn't
+        self.get_detailed_status(t).to_result()?;
+
         let mut sat = SatelliteState {
             pos: ECEF::default(),
             vel: ECEF::default(),
@@ -288,16 +311,20 @@ impl Ephemeris {
             )
         };
 
-        if result == 0 {
-            Ok(sat)
-        } else {
-            Err(InvalidEphemeris {})
-        }
+        assert_eq!(result, 0);
+        Ok(sat)
     }
 
     /// Calculate the azimuth and elevation of a satellite from a reference
     /// position given the satellite ephemeris.
-    pub fn calc_satellite_az_el(&self, t: &GpsTime, pos: &ECEF) -> Result<AzimuthElevation> {
+    pub fn calc_satellite_az_el(
+        &self,
+        t: GpsTime,
+        pos: ECEF,
+    ) -> Result<AzimuthElevation, InvalidEphemeris> {
+        // First make sure the ephemeris is valid at `t`, and bail early if it isn't
+        self.get_detailed_status(t).to_result()?;
+
         let mut sat = AzimuthElevation::default();
 
         let result = unsafe {
@@ -312,16 +339,21 @@ impl Ephemeris {
             )
         };
 
-        if result == 0 {
-            Ok(sat)
-        } else {
-            Err(InvalidEphemeris {})
-        }
+        assert_eq!(result, 0);
+        Ok(sat)
     }
 
     /// Calculate the Doppler shift of a satellite as observed at a reference
     /// position given the satellite ephemeris.
-    pub fn calc_satellite_doppler(&self, t: &GpsTime, pos: &ECEF, vel: &ECEF) -> Result<f64> {
+    pub fn calc_satellite_doppler(
+        &self,
+        t: GpsTime,
+        pos: ECEF,
+        vel: ECEF,
+    ) -> Result<f64, InvalidEphemeris> {
+        // First make sure the ephemeris is valid at `t`, and bail early if it isn't
+        self.get_detailed_status(t).to_result()?;
+
         let mut doppler = 0.0;
 
         let result = unsafe {
@@ -335,15 +367,12 @@ impl Ephemeris {
             )
         };
 
-        if result == 0 {
-            Ok(doppler)
-        } else {
-            Err(InvalidEphemeris {})
-        }
+        assert_eq!(result, 0);
+        Ok(doppler)
     }
 
-    pub fn get_sid(&self) -> GnssSignal {
-        GnssSignal::from_gnss_signal_t(self.0.sid).unwrap()
+    pub fn get_sid(&self) -> std::result::Result<GnssSignal, InvalidGnssSignal> {
+        GnssSignal::from_gnss_signal_t(self.0.sid)
     }
 
     /// Gets the status of an ephemeris - is the ephemeris invalid, unhealthy,
@@ -352,6 +381,12 @@ impl Ephemeris {
         Status::from_ephemeris_status_t(unsafe { c_bindings::get_ephemeris_status_t(&self.0) })
     }
 
+    pub fn get_detailed_status(&self, t: GpsTime) -> Status {
+        Status::from_ephemeris_status_t(unsafe {
+            c_bindings::ephemeris_valid_detailed(&self.0, t.c_ptr())
+        })
+    }
+
     /// Is this ephemeris usable?
     pub fn is_valid_at_time(&self, t: GpsTime) -> bool {
         let result = unsafe { c_bindings::ephemeris_valid(&self.0, t.c_ptr()) };
@@ -407,13 +442,13 @@ mod tests {
     #[test]
     fn bds_decode() {
         let expected_ephemeris = Ephemeris::new(
-            GnssSignal::new(25, Code::Bds2B1),      // sid
-            GpsTime::new_unchecked(2091, 460800.0), // toe
-            2.0,                                    //ura
-            0,                                      // fit_interval
-            0,                                      // valid
-            0,                                      // health_bits
-            0,                                      // source
+            GnssSignal::new(25, Code::Bds2B1).unwrap(), // sid
+            GpsTime::new_unchecked(2091, 460800.0),     // toe
+            2.0,                                        //ura
+            0,                                          // fit_interval
+            0,                                          // valid
+            0,                                          // health_bits
+            0,                                          // source
             EphemerisTerms::new_kepler(
                 Constellation::Bds,
                 [-2.99999997e-10, -2.99999997e-10],    // tgd
@@ -456,7 +491,7 @@ mod tests {
             ],
         ];
 
-        let sid = GnssSignal::new(25, Code::Bds2B1);
+        let sid = GnssSignal::new(25, Code::Bds2B1).unwrap();
 
         let decoded_eph = Ephemeris::decode_bds(&words, sid);
 
@@ -468,13 +503,13 @@ mod tests {
         use super::GAL_INAV_CONTENT_BYTE;
 
         let expected_ephemeris = Ephemeris::new(
-            GnssSignal::new(8, Code::GalE1b),      // sid
-            GpsTime::new_unchecked(2090, 135000.), // toe
-            3.120000,                              // ura
-            14400,                                 // fit_interval
-            1,                                     // valid
-            0,                                     // health_bits
-            0,                                     // source
+            GnssSignal::new(8, Code::GalE1b).unwrap(), // sid
+            GpsTime::new_unchecked(2090, 135000.),     // toe
+            3.120000,                                  // ura
+            14400,                                     // fit_interval
+            1,                                         // valid
+            0,                                         // health_bits
+            0,                                         // source
             EphemerisTerms::new_kepler(
                 Constellation::Gal,
                 [-5.5879354476928711e-09, -6.5192580223083496e-09], // tgd

src/ionosphere.rs

@@ -10,11 +10,25 @@
 
 use crate::{c_bindings, time::GpsTime};
 use crate::{coords::ECEF, navmeas::NavigationMeasurement};
+use std::error::Error;
+use std::fmt::{Display, Formatter};
 
 /// Represents an ionosphere model
 #[derive(Debug, Clone, PartialOrd, PartialEq)]
 pub struct Ionosphere(c_bindings::ionosphere_t);
 
+/// An error indicating that the iono model failed to be decoded
+#[derive(Debug, Copy, Clone, PartialOrd, Ord, PartialEq, Eq, Hash)]
+pub struct IonoDecodeFailure;
+
+impl Display for IonoDecodeFailure {
+    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), std::fmt::Error> {
+        write!(f, "Error decoding iono model")
+    }
+}
+
+impl Error for IonoDecodeFailure {}
+
 impl Ionosphere {
     fn as_ptr(&self) -> *const c_bindings::ionosphere_t {
         &self.0
@@ -54,7 +68,7 @@ impl Ionosphere {
     /// --------
     /// References:
     /// * IS-GPS-200H, Section 20.3.3.5.1.7
-    pub fn decode_parameters(words: &[u32; 8]) -> Option<Ionosphere> {
+    pub fn decode_parameters(words: &[u32; 8]) -> Result<Ionosphere, IonoDecodeFailure> {
         let mut iono = Ionosphere(c_bindings::ionosphere_t {
             toa: GpsTime::unknown(),
             a0: 0.0,
@@ -70,9 +84,9 @@ impl Ionosphere {
         let success = unsafe { c_bindings::decode_iono_parameters(words, &mut iono.0) };
 
         if success {
-            Some(iono)
+            Ok(iono)
         } else {
-            None
+            Err(IonoDecodeFailure)
         }
     }