Additional documentation for MSG-1534 [OTA-284] (#1220)

c/include/libsbp/gnss_macros.h

@@ -47,6 +47,19 @@
  */
 #define SBP_V4_GNSS_SIGNAL_ENCODED_LEN 2u
 
+#define SBP_SVID__MASK (0xffu)
+#define SBP_SVID__SHIFT (0u)
+#define SBP_SVID__GET(flags) \
+  ((u8)((u8)((flags) >> SBP_SVID__SHIFT) & SBP_SVID__MASK))
+#define SBP_SVID__SET(flags, val)                                      \
+  do {                                                                 \
+    (flags) = (u8)((flags & (~(SBP_SVID__MASK << SBP_SVID__SHIFT))) |  \
+                   (((val) & (SBP_SVID__MASK)) << (SBP_SVID__SHIFT))); \
+  } while (0)
+
+#define SBP_SVID_GPS (0)
+#define SBP_SVID_BDS (3)
+#define SBP_SVID_GAL (5)
 /**
  * Encoded length of sbp_sv_id_t (V4 API) and
  * sv_id_t (legacy API)

c/include/libsbp/legacy/gnss.h

@@ -35,9 +35,8 @@ SBP_PACK_START
  */
 
 typedef struct SBP_ATTR_PACKED {
-  u8 sat;  /**< Constellation-specific satellite identifier. This field for
-                Glonass can either be (100+FCN) where FCN is in [-7,+6] or
-                the Slot ID in [1,28]. */
+  u8 sat;  /**< Constellation-specific satellite id. For GLO can either be
+                (100+FCN) where FCN is in [-7,+6] or the Slot ID in [1,28]. */
   u8 code; /**< Signal constellation, band and code */
 } sbp_gnss_signal_t;
 
@@ -48,7 +47,9 @@ typedef struct SBP_ATTR_PACKED {
  */
 
 typedef struct SBP_ATTR_PACKED {
-  u8 satId;         /**< ID of the space vehicle within its constellation */
+  u8 satId;         /**< Constellation-specific satellite id. For GLO can
+                         either be (100+FCN) where FCN is in [-7,+6] or the
+                         Slot ID in [1,28]. */
   u8 constellation; /**< Constellation ID to which the SV belongs */
 } sv_id_t;
 

c/include/libsbp/legacy/ssr.h

@@ -142,8 +142,8 @@ typedef struct SBP_ATTR_PACKED {
   s16 hydro; /**< Hydrostatic vertical delay. Add 2.3 m to get actual
                   value. [4 mm] */
   s8 wet;    /**< Wet vertical delay. Add 0.252 m to get actual value. [4 mm] */
-  u8 stddev; /**< Modified DF389 scale. Class is upper 3 bits, value is
-                  lower 5. stddev <= (3^class * (1 + value/16) - 1) mm [mm] */
+  u8 stddev; /**< Modified DF389. class 3 MSB, value 5 LSB. stddev =
+                  (3^class * (1 + value/16) - 1) [mm] */
 } tropospheric_delay_correction_t;
 
 /** None
@@ -165,9 +165,8 @@ typedef struct SBP_ATTR_PACKED {
 typedef struct SBP_ATTR_PACKED {
   sv_id_t sv_id; /**< space vehicle identifier */
   s16 residual;  /**< STEC residual [0.04 TECU] */
-  u8 stddev;     /**< Modified DF389 scale. Class is upper 3 bits, value is
-                      lower 5. stddev <= (3^class * (1 + value/16) - 1) * 10
-                      TECU */
+  u8 stddev;     /**< Modified DF389. class 3 MSB, value 5 LSB. stddev =
+                      (3^class * (1 + value/16) - 1) * 10 */
 } stec_residual_t;
 
 /** Precise orbit and clock correction

c/include/libsbp/v4/gnss/GnssSignal.h

@@ -44,8 +44,8 @@ extern "C" {
  */
 typedef struct {
   /**
-   * Constellation-specific satellite identifier. This field for Glonass can
-   * either be (100+FCN) where FCN is in [-7,+6] or the Slot ID in [1,28].
+   * Constellation-specific satellite id. For GLO can either be (100+FCN) where
+   * FCN is in [-7,+6] or the Slot ID in [1,28].
    */
   u8 sat;
 

c/include/libsbp/v4/gnss/SvId.h

@@ -45,7 +45,8 @@ extern "C" {
  */
 typedef struct {
   /**
-   * ID of the space vehicle within its constellation
+   * Constellation-specific satellite id. For GLO can either be (100+FCN) where
+   * FCN is in [-7,+6] or the Slot ID in [1,28].
    */
   u8 satId;
 

c/include/libsbp/v4/ssr/STECResidual.h

@@ -56,8 +56,8 @@ typedef struct {
   s16 residual;
 
   /**
-   * Modified DF389 scale. Class is upper 3 bits, value is lower 5. stddev <=
-   * (3^class * (1 + value/16) - 1) * 10 TECU
+   * Modified DF389. class 3 MSB, value 5 LSB. stddev = (3^class * (1 +
+   * value/16) - 1) * 10
    */
   u8 stddev;
 } sbp_stec_residual_t;

c/include/libsbp/v4/ssr/TroposphericDelayCorrection.h

@@ -54,8 +54,8 @@ typedef struct {
   s8 wet;
 
   /**
-   * Modified DF389 scale. Class is upper 3 bits, value is lower 5. stddev <=
-   * (3^class * (1 + value/16) - 1) mm [mm]
+   * Modified DF389. class 3 MSB, value 5 LSB. stddev = (3^class * (1 +
+   * value/16) - 1) [mm]
    */
   u8 stddev;
 } sbp_tropospheric_delay_correction_t;

generator/sbpg/targets/latex.py

@@ -47,8 +47,7 @@ def no_us(value):
 
 TEMPLATE_NAME = "sbp_messages_desc.tex"
 
-LATEX_SUBS = (
-    (re.compile(r'\\'), r'\\textbackslash'),
+LATEX_SUBS_MIN = (
     (re.compile(r'([{}_#%&$])'), r'\\\1'),
     (re.compile(r'@@(\S+)\[([^\]]+)\]'), r'\\href{\1}{\2}'),
     (re.compile(r'~'), r'\~{}'),
@@ -57,65 +56,92 @@ def no_us(value):
     (re.compile(r'\.\.\.+'), r'\\ldots'),
 )
 
+LATEX_SUBS_ALL = (
+    (re.compile(r'\\'), r'\\textbackslash'),
+) + LATEX_SUBS_MIN
+
+MAX_NAME_LENGTH = 27
+
+
 def append_signals_table(value):
     return value + " (see pg. ~\\pageref{sec:signals})"
 
+
+def _escape_tex(value, subs):
+    for pattern, replacement in subs:
+        value = pattern.sub(replacement, value)
+    return value
+
+
 def escape_tex(value):
-  """
-  Make text tex safe
-  """
-  newval = value
-  for pattern, replacement in LATEX_SUBS:
-    newval = pattern.sub(replacement, newval)
-  return newval
+    """
+    Make text tex safe
+    """
+    return _escape_tex(value, LATEX_SUBS_ALL)
+
+
+def escape_table_name(value):
+    if len(value) > MAX_NAME_LENGTH:
+        value = value[:MAX_NAME_LENGTH] + " \\newline " + value[MAX_NAME_LENGTH:]
+    return _escape_tex(value, LATEX_SUBS_MIN)
+
 
 def classnameify(s):
   """
   Makes a classname
   """
   return ''.join(w if w in ACRONYMS else w.title() for w in s.split('_'))
 
+
 def header_write(v):
   return re.sub('Io', 'IO', v)
 
+
 def packagenameify(s):
   """
   Makes a package name
   """
   return ''.join(w if w in ACRONYMS else w.title() for w in s.split('.')[-1:])
 
+
 def nobrackets(v):
   """
   Remove brackets
   """
   return v.replace('[', '').replace(']', '')
 
+
 def removearray(v):
   """
   Clean up array name
   """
   return re.sub('^[a-z]*\[N\]\.', '', v)
 
+
 def removehost(v):
   """
   Clean up array name
   """
   return re.sub('^[a-z]*\[N\]\.', '', v)
 
+
 def remove_dir(v):
   """
   Clean up array name
   """
   return v.split("(host")[0]
 
+
 def get_size(v):
   """
   Clean up array name
   """
   return field_sizes[v] if field_sizes.get(v, None) else "---"
 
+
 JENV.filters['append_signals_table'] = append_signals_table
 JENV.filters['escape_tex'] = escape_tex
+JENV.filters['escape_table_name'] = escape_table_name
 JENV.filters['classnameify'] = classnameify
 JENV.filters['packagenameify'] = packagenameify
 JENV.filters['nobrackets'] = nobrackets

generator/sbpg/targets/resources/rust/sbp_messages_template.rs

@@ -217,7 +217,7 @@ impl std::fmt::Display for (((b.type_name))) {
 
 impl TryFrom<(((b.type)))> for (((b.type_name))) {
     type Error = (((b.type)));
-    fn try_from(i: (((b.type))) ) -> Result<Self, Self::Error> {
+    fn try_from(i: (((b.type))) ) -> Result<Self, (((b.type)))> {
         match i {
             ((*- for v in b.vals *))
             (((v.value))) => Ok( (((b.type_name))) :: (((v.name))) ),

generator/sbpg/targets/resources/sbp_base.tex

@@ -1,5 +1,6 @@
 \documentclass[9pt]{extarticle}
 
+\usepackage[table]{xcolor}
 \usepackage{amsmath}
 \usepackage{booktabs}
 \usepackage{bytefield}
@@ -19,7 +20,6 @@
 \usepackage{soul}
 \usepackage{hyperref}
 \usepackage{ltxtable}
-\usepackage{caption}
 
 \hypersetup{bookmarks,bookmarksopen,bookmarksdepth=4}
 
@@ -50,6 +50,7 @@
 \renewcommand{\cftsubsecafterpnum}{\hspace*{7.5em}}
 \renewcommand\tableofcontents{\@starttoc{toc}}
 
+\newcolumntype{Z}{>{\hsize=.15\hsize}X}
 \newcolumntype{a}{>{\hsize=.2\hsize}X}
 \newcolumntype{b}{>{\hsize=.22\hsize}X}
 \newcolumntype{c}{>{\hsize=.3\hsize}X}
@@ -58,6 +59,7 @@
 \newcolumntype{f}{>{\hsize=.16\hsize}X}
 \newcolumntype{g}{>{\hsize=.77\hsize}X}
 \newcolumntype{h}{>{\hsize=.6\hsize}X}
+\newcolumntype{N}{>{\hsize=.77\hsize}X}
 
 % Shell out to git to get the most recent tag and pass it to the LateX
 % job name. Hopefully this doesn't screw with things.

generator/sbpg/targets/resources/sbp_messages_desc.tex

@@ -20,23 +20,27 @@ \subsubsection{(((m.name | escape_tex ))) ((*- if m.is_real_message *)) --- ((('
 \vspace{3em}
 \begin{table}[H]
   \centering
-  \begin{tabularx}{\textwidth}{baachX}
+  \rowcolors{2}{gray!20}{white}
+  \begin{tabularx}{\textwidth}{bZacNX}
     \toprule
+    \hiderowcolors
     Offset (bytes) & Size (bytes) & Format & Units & Name & Description \\
     \midrule
+    \showrowcolors
     ((*- for f in m.fields *))
       $\mathtt{(((f.offset)))}$ &
       $\mathtt{(((f.size)))}$ &
       (((f.fmt))) &
       (((f.units|escape_tex))) &
-      \texttt{(((f.name|escape_tex)))} &
+      \texttt{(((f.name|escape_table_name)))} &
       ((*- if f.is_gnss_signal *))
       \hangindent=0.5em{(((f.desc|append_signals_table)))} \\
       ((*- else *))
       \hangindent=0.5em{(((f.desc|escape_tex)))} \\
       ((*- endif *))
       ((*- endfor *))
     \midrule
+    \hiderowcolors
     & $\mathtt{(((m.size)))}$ & & & & Total Payload Length\\
     \bottomrule
   \end{tabularx}
@@ -116,19 +120,23 @@ \subsubsection*{(((m.name|escape_tex|no_us))) --- ((('0x%04X'|format(m.sbp_id)))
 \vspace{3em}
 \begin{table}[h]
   \centering
-  \begin{tabularx}{\textwidth}{ccaclX}
+  \rowcolors{2}{gray!20}{white}
+  \begin{tabularx}{\textwidth}{cZacNX}
     \toprule
+    \hiderowcolors
     Offset (bytes) & Size (bytes) & Format & Units & Name & Description \\
+    \showrowcolors
     \midrule
     ((*- for f in m.fields *))
       $\mathtt{(((f.offset)))}$ &
       $\mathtt{(((f.size)))}$ &
       (((f.fmt))) &
       (((f.units|escape_tex))) &
-      \texttt{(((f.name|escape_tex)))} &
+      \texttt{(((f.name|escape_table_name)))} &
       \hangindent=0.5em{(((f.desc|escape_tex)))} \\
       ((*- endfor *))
     \midrule
+    \hiderowcolors
     & $\mathtt{(((m.size)))}$ & & & & Total Payload Length\\
     \bottomrule
   \end{tabularx}

generator/sbpg/targets/rust.py

@@ -107,12 +107,24 @@ def snake_case(s):
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", s).lower()
 
 
+def camel_case_split(identifier):
+    # https://stackoverflow.com/a/29920015
+    matches = re.finditer('.+?(?:(?<=[a-z])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])|$)', identifier)
+    return [m.group(0) for m in matches]
+
 def lower_acronyms(s):
-    acronyms = ACRONYMS + ["GNSS", "IMU"]
-    lower_acronyms = LOWER_ACRONYMS + ["Gnss", "Imu"]
-    for (i, a) in enumerate(acronyms):
-        s = s.replace(a, lower_acronyms[i])
-    return s
+    if s.isupper() and s.isalpha():
+        return s.title()
+    acronyms = ACRONYMS + ["GNSS", "IMU", "GAL", "BDS"]
+    lower_acronyms = LOWER_ACRONYMS + ["Gnss", "Imu", "Gal", "Bds"]
+    result = []
+    for word in camel_case_split(s):
+        idx = acronyms.index(word) if word in acronyms else None
+        if idx is not None:
+            result.append(lower_acronyms[idx])
+        else:
+            result.append(word)
+    return "".join(result)
 
 
 def wrap_urls(s):

haskell/src/SwiftNav/SBP/Gnss.hs

@@ -40,8 +40,8 @@ import SwiftNav.SBP.Types
 -- Signal identifier containing constellation, band, and satellite identifier.
 data GnssSignal = GnssSignal
   { _gnssSignal_sat :: !Word8
-    -- ^ Constellation-specific satellite identifier. This field for Glonass can
-    -- either be (100+FCN) where FCN is in [-7,+6] or the Slot ID in [1,28].
+    -- ^ Constellation-specific satellite id. For GLO can either be (100+FCN)
+    -- where FCN is in [-7,+6] or the Slot ID in [1,28].
   , _gnssSignal_code :: !Word8
     -- ^ Signal constellation, band and code
   } deriving ( Show, Read, Eq )
@@ -65,7 +65,8 @@ $(makeLenses ''GnssSignal)
 -- vehicle.
 data SvId = SvId
   { _svId_satId       :: !Word8
-    -- ^ ID of the space vehicle within its constellation
+    -- ^ Constellation-specific satellite id. For GLO can either be (100+FCN)
+    -- where FCN is in [-7,+6] or the Slot ID in [1,28].
   , _svId_constellation :: !Word8
     -- ^ Constellation ID to which the SV belongs
   } deriving ( Show, Read, Eq )

haskell/src/SwiftNav/SBP/Ssr.hs

@@ -256,8 +256,8 @@ data TroposphericDelayCorrection = TroposphericDelayCorrection
   , _troposphericDelayCorrection_wet  :: !Int8
     -- ^ Wet vertical delay. Add 0.252 m to get actual value.
   , _troposphericDelayCorrection_stddev :: !Word8
-    -- ^ Modified DF389 scale. Class is upper 3 bits, value is lower 5. stddev
-    -- <= (3^class * (1 + value/16) - 1) mm
+    -- ^ Modified DF389. class 3 MSB, value 5 LSB. stddev = (3^class * (1 +
+    -- value/16) - 1)
   } deriving ( Show, Read, Eq )
 
 instance Binary TroposphericDelayCorrection where
@@ -308,8 +308,8 @@ data STECResidual = STECResidual
   , _sTECResidual_residual :: !Int16
     -- ^ STEC residual
   , _sTECResidual_stddev :: !Word8
-    -- ^ Modified DF389 scale. Class is upper 3 bits, value is lower 5. stddev
-    -- <= (3^class * (1 + value/16) - 1) * 10 TECU
+    -- ^ Modified DF389. class 3 MSB, value 5 LSB. stddev = (3^class * (1 +
+    -- value/16) - 1) * 10
   } deriving ( Show, Read, Eq )
 
 instance Binary STECResidual where

java/src/com/swiftnav/sbp/gnss/GnssSignal.java

@@ -22,8 +22,8 @@
 public class GnssSignal extends SBPStruct {
 
     /**
-     * Constellation-specific satellite identifier. This field for Glonass can either be (100+FCN)
-     * where FCN is in [-7,+6] or the Slot ID in [1,28].
+     * Constellation-specific satellite id. For GLO can either be (100+FCN) where FCN is in [-7,+6]
+     * or the Slot ID in [1,28].
      */
     public int sat;