Improve SBP protocol PDF documentation [INFRA-280]

c/include/libsbp/cpp/message_traits.h

@@ -1140,24 +1140,6 @@ struct MessageTraits<msg_soln_meta_t> {
 };
 
 
-template<>
-struct MessageTraits<gnss_input_type_t> {
-  static constexpr u16 id = 65511;
-};
-
-
-template<>
-struct MessageTraits<imu_input_type_t> {
-  static constexpr u16 id = 65512;
-};
-
-
-template<>
-struct MessageTraits<odo_input_type_t> {
-  static constexpr u16 id = 65513;
-};
-
-
 template<>
 struct MessageTraits<msg_heartbeat_t> {
   static constexpr u16 id = 65535;

c/include/libsbp/linux.h

@@ -164,7 +164,8 @@ typedef struct SBP_ATTR_PACKED {
 a string representation of the process count and the file
 name whose count it being reported.  That is, in C string
 syntax "32\0/var/log/syslog\012\0/tmp/foo\0" with the end
-of the list being 2 NULL terminators in a row. */
+of the list being 2 NULL terminators in a row.
+ */
 } msg_linux_process_fd_summary_t;
 
 

c/include/libsbp/solution_meta.h

@@ -55,46 +55,40 @@ typedef struct SBP_ATTR_PACKED {
   u16 vdop;                      /**< Vertical Dilution of Precision, as per last available DOPS from Starling GNSS engine [0.01] */
   u8 n_sats;                    /**< Number of satellites, as per last available solution from Starling GNSS engine */
   u16 age_corrections;           /**< Age of the corrections (0xFFFF indicates invalid), as per last available AGE_CORRECTIONS from Starling GNSS engine [deciseconds] */
-  u8 alignment_status;          /**< Bits for reason why it cannot align (yet) */
+  u8 alignment_status;          /**< State of alignment and the status and receipt of the alignment inputs */
   u32 last_used_gnss_pos_tow;    /**< Tow of last-used GNSS position measurement [ms] */
   u32 last_used_gnss_vel_tow;    /**< Tow of last-used GNSS velocity measurement [ms] */
   solution_input_type_t sol_in[0];                 /**< Array of Metadata describing the sensors potentially involved in the solution. Each element in the array represents a single sensor type and consists of flags containing (meta)data pertaining to that specific single sensor. Refer to each (XX)InputType descriptor in the present doc. */
 } msg_soln_meta_t;
 
 
-/** Flags for a given GNSS sensor used as input for the fuzed solution.
+/** Instruments the physical type of GNSS sensor input to the fuzed solution.
  *
- * Metadata around the GNSS sensors involved in the fuzed solution. Accessible through sol_in[N].flags
- *                                                                         in a MSG_SOLN_META.
- * Note: Just to build descriptive tables in documentation and not actually used.
+ * Metadata around the GNSS sensors involved in the fuzed solution.
+ * Accessible through sol_in[N].flags in a MSG_SOLN_META.
  */
-#define SBP_GNSSInputType 0xFFE7
 typedef struct SBP_ATTR_PACKED {
   u8 flags;    /**< flags that store all relevant info specific to this sensor type. */
 } gnss_input_type_t;
 
 
-/** Flags for a given IMU sensor used as input for the fuzed solution.
+/** Provides detail about the IMU sensor, its timestamping mode, and its quality for input to the fuzed solution.
  *
- * Metadata around the IMU sensors involved in the fuzed solution. Accessible through sol_in[N].flags
- *                                                                        in a MSG_SOLN_META.
- * Note: Just to build descriptive tables in documentation and not actually used.
+ * Metadata around the IMU sensors involved in the fuzed solution.
+ * Accessible through sol_in[N].flags in a MSG_SOLN_META.
  */
-#define SBP_IMUInputType  0xFFE8
 typedef struct SBP_ATTR_PACKED {
-  u8 flags;    /**< flags that store all relevant info specific to this sensor type. */
+  u8 flags;    /**< Instrument time, grade, and architecture for a sensor. */
 } imu_input_type_t;
 
 
-/** Flags for a given Odometry sensor used as input for the fuzed solution.
+/** Provides detail about the Odometry sensor, its timestamping mode, and its quality for input to the fuzed solution.
  *
- * Metadata around the Odometry sensors involved in the fuzed solution. Accessible through sol_in[N].flags
- *                                                                             in a MSG_SOLN_META.
- * Note: Just to build descriptive tables in documentation and not actually used.
+ * Metadata around the Odometry sensors involved in the fuzed solution.
+ * Accessible through sol_in[N].flags in a MSG_SOLN_META.
  */
-#define SBP_OdoInputType  0xFFE9
 typedef struct SBP_ATTR_PACKED {
-  u8 flags;    /**< flags that store all relevant info specific to this sensor type. */
+  u8 flags;    /**< Instrument ODO rate, grade, and quality. */
 } odo_input_type_t;
 
 

generator/sbpg/specs/yaml2.py

@@ -259,7 +259,9 @@ def mk_definition(defn):
                                          desc=contents.get('desc', None),
                                          type_id=contents.get('type'),
                                          fields=fs,
-                                         public=contents.get('public', True)))
+                                         public=contents.get('public', True),
+                                         embedded_type=contents.get('embedded_type', False),
+                                         ))
 
 def mk_field(field):
   """Instantiates a field specification from a parsed "AST" of a

generator/sbpg/specs/yaml_schema.py

@@ -53,6 +53,7 @@
                       Optional('public'): bool,
                       Optional('size'): size,
                       Optional('type'): type_identifier,
+                      Optional('embedded_type'): bool,
                       Optional('fields'): [field]}})
 package_schema = Schema({Optional('package'): identifier,
                          Optional('description'): description,

generator/sbpg/syntax.py

@@ -71,11 +71,12 @@ def __repr__(self):
 class Definition(object):
   def __init__(self, identifier=None,
                sbp_id=None, short_desc=None, desc=None, type_id=None,
-               fields=[], public=False):
+               fields=[], public=False, embedded_type=False):
     self.identifier = identifier
     self.sbp_id = sbp_id
     self.short_desc = short_desc
     self.desc = desc
+    self.embedded_type = embedded_type
     self.type_id = type_id
     self.fields = fields
     self.public = public
@@ -88,6 +89,10 @@ def max_type_len(self):
   @property
   def max_fid_len(self):
     return max([0]+[len(f.identifier) for f in self.fields])
+
+  @property
+  def is_real_message(self):
+    return (not getattr(self, 'embedded_type', False)) and getattr(self, 'sbp_id', False)
 
   def __repr__(self):
     return fmt_repr(self)
@@ -133,6 +138,10 @@ def __init__(self, defn):
   @property
   def static(self):
     return True
+
+  # Some primitive types are defined like messages, 
+  # but are not standalone messages with their own ids that would go on the wire
+  # The is_real_message property disambiguates these.
 
   def __repr__(self):
     return fmt_repr(self)
@@ -151,7 +160,7 @@ def __init__(self, defn):
   @property
   def static(self):
     return True
-
+  
   def __repr__(self):
     return fmt_repr(self)
 

generator/sbpg/targets/c.py

@@ -125,7 +125,7 @@ def render_traits(output_dir, package_specs):
     if name != 'types' and name != 'base':
       includes.append(name)
     for m in package_spec.definitions:
-      if m.static and m.sbp_id:
+      if m.is_real_message:
         msgs.append(m)
   destination_filename = "%s/cpp/message_traits.h" % output_dir
   py_template = JENV.get_template(MESSAGE_TRAITS_TEMPLATE_NAME)

generator/sbpg/targets/haskell.py

@@ -208,7 +208,7 @@ def render_sbp(output_dir, package_specs):
     full_module_name = ".".join([module_prefix, module_name])
     modules.append(full_module_name)
     for m in package_spec.definitions:
-      if m.static and m.sbp_id:
+      if m.is_real_message:
         msgs.append(m)
   destination_filename = "%s/src/SwiftNav/SBP.hs" % output_dir
   py_template = JENV.get_template(SBP_TEMPLATE_NAME)

generator/sbpg/targets/latex.py

@@ -138,7 +138,8 @@ class TableItem(object):
   """
 
   def __init__(self, pkg, name, sbp_id, short_desc,
-               desc, size, fields, stable=False, pkg_desc=None):
+               desc, size, fields, stable=False, pkg_desc=None, is_real_message=True,
+               embedded_type=False):
     self.pkg = pkg
     self.name = name
     self.sbp_id = sbp_id
@@ -148,6 +149,8 @@ def __init__(self, pkg, name, sbp_id, short_desc,
     self.fields = fields
     self.stable = stable
     self.pkg_desc = pkg_desc
+    self.embedded_type = embedded_type
+    self.is_real_message = is_real_message
 
 
 class FieldItem (object):
@@ -277,7 +280,7 @@ def render_source(output_dir, package_specs, version):
     if pkg_name == "swiftnav.sbp.types":
       prims = p.definitions
     for d in p.definitions:
-      if d.public and d.static and d.sbp_id:
+      if d.public and (d.is_real_message or d.embedded_type):
         items, size, multiplier \
           = handle_fields(definitions, d.fields, "", 0, None)
         adj_size = ""
@@ -292,7 +295,9 @@ def render_source(output_dir, package_specs, version):
           adj_size = "%d" % size
         ti = TableItem(pkg_name, d.identifier, d.sbp_id,
                        d.short_desc, d.desc, adj_size, items, p.stable,
-                       p.description)
+                       pkg_desc=p.description,
+                       is_real_message=d.is_real_message,
+                       embedded_type=d.embedded_type)
         pkg_name = ""
         if stable:
           stable_msgs.append(ti)

generator/sbpg/targets/resources/MessageTable.java.j2

@@ -17,7 +17,7 @@ import com.swiftnav.sbp.SBPMessage.Builder;
 import com.swiftnav.sbp.SBPMessage.Parser;
 ((*- for p in packages *))
 ((*- for m in p.definitions *))
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 import com.(((p.identifier))).(((m.identifier|classnameify)));
 ((*- endif *))
 ((*- endfor *))
@@ -28,7 +28,7 @@ final class MessageTable {
         switch (msg.type) {
             ((*- for p in packages *))
             ((*- for m in p.definitions *))
-            ((*- if m.sbp_id *))
+            ((*- if m.is_real_message *))
             case (((m.identifier|classnameify))).TYPE:
                 return new (((m.identifier|classnameify)))(msg);
             ((*- endif *))

generator/sbpg/targets/resources/SbpMessagesTemplate.hs

@@ -38,12 +38,12 @@ import (((m)))
 
 ((* for m in msgs *))
 ((*- if m.static *))
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 (((m.identifier|hs_to_global))) :: Word16
 (((m.identifier|hs_to_global))) = ((('0x%04X'|format(m.sbp_id))))
 ((* endif *))
 ((*- if m.desc *))
-((*- if not m.sbp_id *))
+((*- if not m.is_real_message *))
 -- | (((m.identifier))).
 ((*- else *))
 -- | SBP class for message (((m.identifier))) ((('(0x%04X)'|format(m.sbp_id)))).
@@ -92,7 +92,7 @@ instance Binary (((m.identifier|hs_to_data))) where
 ((*- endfor *))
 ((* endif *))
 
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 $(makeSBP '(((m.identifier|hs_to_global))) ''(((m.identifier|hs_to_data))))
 ((*- endif *))
 $(makeJSON "_(((m.identifier|hs_to_global)))_" ''(((m.identifier|hs_to_data))))

generator/sbpg/targets/resources/sbp_base.tex

@@ -57,6 +57,7 @@
 \newcolumntype{e}{>{\hsize=.13\hsize}X}
 \newcolumntype{f}{>{\hsize=.16\hsize}X}
 \newcolumntype{g}{>{\hsize=.77\hsize}X}
+\newcolumntype{h}{>{\hsize=.6\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_construct_template.py.j2

@@ -30,7 +30,7 @@ from (((module_path))).(((i))) import *
 
 ((* for m in msgs *))
   ((*- if m.static *))
-    ((*- if not m.sbp_id *))
+    ((*- if not m.is_real_message *))
 class ((( m.identifier )))(object):
   """(((m.identifier))).
   ((* if m.desc *))
@@ -91,7 +91,7 @@ class ((( m.identifier )))(object):
 
 ((*- for m in msgs *))
   ((*- if m.static *))
-    ((*- if m.sbp_id *))
+    ((*- if m.is_real_message *))
 SBP_(((m.identifier))) = ((('0x%04X'|format(m.sbp_id))))
 class ((( m.identifier | classnameify )))(SBP):
   """SBP class for message (((m.identifier))) ((('(0x%04X)'|format(m.sbp_id)))).
@@ -214,7 +214,7 @@ class ((( m.identifier | classnameify )))(SBP):
 
 msg_classes = {
 ((*- for m in msgs *))
-  ((*- if m.sbp_id *))
+  ((*- if m.is_real_message *))
   ((('0x%04X'|format(m.sbp_id)))): ((( m.identifier | classnameify ))),
   ((*- endif*))
 ((*- endfor *))

generator/sbpg/targets/resources/sbp_java.java.j2

@@ -24,7 +24,7 @@ import com.swiftnav.sbp.(((i))).*;
 
 import org.json.JSONObject;
 import org.json.JSONArray;
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 
 ((* if m.desc *))
 /** SBP class for message (((m.identifier))) ((('(0x%04X)'|format(m.sbp_id)))).
@@ -80,7 +80,7 @@ public class (((m.identifier | classnameify))) extends SBPMessage {
     }
 }
 ((*- endif *))
-((*- if not m.sbp_id *))
+((*- if not m.is_real_message *))
 import com.swiftnav.sbp.SBPStruct;
 
 public class (((m.identifier))) extends SBPStruct {

generator/sbpg/targets/resources/sbp_js.js.j2

@@ -35,7 +35,7 @@ var (((ident))) = require("./(((file)))").(((ident)));
 ((*- for m in msgs *))
 
 /**
- * ((* if m.sbp_id *))SBP class for message (((m.identifier))) ((('(0x%04X)'|format(m.sbp_id)))).((* else *))SBP class for message fragment (((m.identifier))) ((*- endif *))
+ * ((* if m.is_real_message *))SBP class for message (((m.identifier))) ((('(0x%04X)'|format(m.sbp_id)))).((* else *))SBP class for message fragment (((m.identifier))) ((*- endif *))
  *
  ((* if m.desc *))* (((m.desc | starWordWrap )))
  *((*- endif *))
@@ -55,7 +55,7 @@ var ((( m.identifier | js_classnameify ))) = function (sbp, fields) {
 };
 ((( m.identifier | js_classnameify ))).prototype = Object.create(SBP.prototype);
 ((( m.identifier | js_classnameify ))).prototype.messageType = "(((m.identifier)))";
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 ((( m.identifier | js_classnameify ))).prototype.msg_type = ((('0x%04X'|format(m.sbp_id))));
 ((*- endif *))
 ((( m.identifier | js_classnameify ))).prototype.constructor = ((( m.identifier | js_classnameify )));
@@ -82,7 +82,7 @@ var ((( m.identifier | js_classnameify ))) = function (sbp, fields) {
 
 module.exports = {
 ((*- for m in msgs *))
-  ((*- if m.sbp_id *))
+  ((*- if m.is_real_message *))
   ((('0x%04X'|format(m.sbp_id)))): ((( m.identifier | js_classnameify ))),
   ((*- endif *))
   ((( m.identifier | js_classnameify ))): ((( m.identifier | js_classnameify ))),

generator/sbpg/targets/resources/sbp_messages_desc.tex

@@ -9,7 +9,8 @@ \subsection{(((m.pkg|packagenameify|header_write|no_us)))}
 (((m.pkg_desc | escape_tex )))
 \end{large}
 ((* endif *))
-\subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id)))) --- (((m.sbp_id)))}
+
+\subsubsection{(((m.name | escape_tex ))) ((*- if m.is_real_message *)) --- ((('0x%04X'|format(m.sbp_id)))) --- (((m.sbp_id))) ((*- endif -*))}
 \label{sec:(((m.name)))}
 
 \begin{large}
@@ -19,7 +20,7 @@ \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id)))) --- (
 \vspace{3em}
 \begin{table}[H]
   \centering
-  \begin{tabularx}{\textwidth}{ccaccX}
+  \begin{tabularx}{\textwidth}{baachX}
     \toprule
     Offset (bytes) & Size (bytes) & Format & Units & Name & Description \\
     \midrule
@@ -35,7 +36,10 @@ \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id)))) --- (
     & $(((m.size)))$ & & & & Total Payload Length\\
     \bottomrule
   \end{tabularx}
-  \caption{(((m.name|escape_tex))) (((('0x%04X'|format(m.sbp_id))))) message structure}
+  \caption{(((m.name|escape_tex))) 
+  ((*- if m.is_real_message *)) (((('0x%04X'|format(m.sbp_id))))) 
+  ((*- endif *))
+  message structure}
   \label{tab:(((m.name)))}
 \end{table}
 

generator/sbpg/targets/resources/sbp_messages_mod.rs

@@ -15,7 +15,7 @@ pub mod unknown;
 
 ((*- for p in packages *))
 ((*- for m in p.definitions *))
-((*- if m.sbp_id *))
+((*- if m.is_real_message *))
 use self::(((p.identifier|mod_name)))::(((m.identifier|camel_case)));
 ((*- endif *))
 ((*- endfor *))