Incorporating final team feedback on specs for release.

- Includes clarifying remarks for datasheet copy, as well as documentation for the existing SBP messages. Note that some of the feedback was out-of-scope for this current release, as they'd require some contract changes to existing messages. - A few bug fixes to the latex generation (missing fields and offset error with total message size). /cc @fnoble @denniszollo @mfine
swift-nav · Apr 15, 2015 · b1ef0ab · b1ef0ab
1 parent 05d8352
commit b1ef0ab
Show file tree

Hide file tree

Showing 19 changed files with 357 additions and 269 deletions.
diff --git a/docs/sbp.pdf b/docs/sbp.pdf
diff --git a/generator/sbpg/targets/latex.py b/generator/sbpg/targets/latex.py
@@ -95,7 +95,7 @@ def remove_dir(v):
   """
   Clean up array name
   """
-  return v.split("(Host")[0]
+  return v.split("(host")[0]
 
 def get_size(v):
   """
@@ -174,7 +174,16 @@ def handle_fields(definitions, fields, prefix, offset, multiplier):
       if 'size' in f.options:
         name = "%s[%s]" % (f.options['fill'].value, str(f.options['size'].value))
         size = field_sizes[f.options['fill'].value] * f.options['size'].value
-        item = FieldItem(prefix_name, name, offset, size, str(f.units), f.desc, n_with_values, bitfields)
+        item = FieldItem(prefix_name, name, offset, size,
+                         str(f.units), f.desc, n_with_values, bitfields)
+        items.append(item)
+        offset += size
+      else:
+        name = "%s[%s]" % (f.options['fill'].value, "N")
+        multiplier = field_sizes[f.options['fill'].value]
+        size = field_sizes[f.options['fill'].value] * 1
+        item = FieldItem(prefix_name, name, offset, "N",
+                         str(f.units), f.desc, n_with_values, bitfields)
         items.append(item)
         offset += size
     elif f.type_id == "string":
@@ -184,13 +193,15 @@ def handle_fields(definitions, fields, prefix, offset, multiplier):
       if 'size' in f.options:
         name = "string"
         size = field_sizes['u8'] * f.options['size'].value
-        item = FieldItem(prefix_name, name, offset, size, str(f.units), f.desc, n_with_values, bitfields)
+        item = FieldItem(prefix_name, name, offset, size,
+                         str(f.units), f.desc, n_with_values, bitfields)
         items.append(item)
         offset += size
       else:
         name = "string"
         size = field_sizes['u8']
-        item = FieldItem(prefix_name, name, offset, size,
+        multiplier = 1
+        item = FieldItem(prefix_name, name, offset, "N",
                          str(f.units), f.desc, n_with_values, bitfields)
         items.append(item)
         offset += size
@@ -255,7 +266,13 @@ def render_source(output_dir, package_specs):
       if d.public and d.static and d.sbp_id:
         items, size, multiplier \
           = handle_fields(p.definitions, d.fields, "", 0, None)
-        adj_size = "%dN+%d" % (multiplier, size) if multiplier else size
+        adj_size = ""
+        if multiplier == 1:
+          adj_size = "N+%d" % (size - 1) if size > 1 else "N"
+        elif multiplier:
+          adj_size = "%dN+%d" % (multiplier, size - multiplier)
+        else:
+          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)

diff --git a/generator/sbpg/targets/resources/sbp_base.tex b/generator/sbpg/targets/resources/sbp_base.tex
@@ -39,6 +39,8 @@
 %% \def\numberline#1{\if\relax#1\relax\else\latex@numberline{#1}\fi}
 %% \makeatother
 
+\newcommand{\specialcell}[2][c]{%
+  \begin{tabular}[#1]{@{}c@{}}#2\end{tabular}}
 
 \renewcommand{\regLabelFamily}{}
 
@@ -57,8 +59,8 @@
 \newcolumntype{c}{>{\hsize=.3\hsize}X}
 \newcolumntype{d}{>{\hsize=.7\hsize}X}
 
-\title{SwiftNav Binary Protocol}
-\version{0.15}
+\title{Swift Navigation Binary Protocol}
+\version{1.29}
 \author{Swift Navigation}
 \mysubtitle{Protocol Specification v\theversion}
 \date{\today}
@@ -76,67 +78,92 @@
 \bigskip
 \bigskip
 \begin{large}
+\section{Overview}
+\label{sec:Overview}
 The Swift Navigation Binary Protocol (SBP) is a fast, simple, and
 minimal binary protocol for communicating with Swift devices. It is
 the native binary protocol used by the Piksi GPS receiver to transmit
-solutions, observations, status and debugging messages, as well as
+solutions, observations, status, and debugging messages, as well as
 receive messages from the host operating system, such as differential
-corrections and the almanac. As such, it is an important piece of
-interfacing with your Piksi receiver and integrating it with other
+corrections and the almanac. As such, it is an important interface
+with your Piksi receiver and the primary integration method with other
 systems.
 
-This document provides language-agnostic specification and
-documentation for messages used with SBP. SBP client libraries in a
-variety of programming languages are available at
-\url{http://docs.swiftnav.com/wiki/SwiftNav_Binary_Protocol}.
+This document provides a specification of SBP framing and the payload
+structures of the messages currently used with Swift devices. SBP
+client libraries in a variety of programming languages are available
+at~\url{http://docs.swiftnav.com/wiki/SwiftNav_Binary_Protocol}.
+
 \end{large}
 
 \newpage
 \section{Message Structure}
 \label{sec:Message}
 
 \begin{large}
-SBP consists of two pieces: (i) an over-the-wire message framing
-format and (ii) structured payload definitions. As of Version 1.0, the
-packet consists of a 6-byte binary header section, a variable-sized
-payload field, and a 16-bit CRC value. SBP uses the CCITT CRC16
-(XMODEM implementation) for error detection.
+SBP consists of two pieces:
+\begin{itemize}
+  \item an over-the-wire message framing format
+  \item structured payload definitions
+\end{itemize}
+As of Version~\theversion, the packet consists of a 6-byte binary
+header section, a variable-sized payload field, and a 16-bit CRC
+value. All multibyte values are ordered in \textbf{little-endian}
+format. SBP uses the CCITT CRC16 (XMODEM implementation) for error
+detection\footnote{CCITT 16-bit CRC Implementation uses parameters
+  used by XMODEM, i.e. the polynomial: $x^{16} + x^{12} + x^5 +
+  1$. For more details, please see the implementation
+  at~\url{https://github.com/swift-nav/libsbp/blob/master/c/src/edc.c\#L59}. See
+  also \emph{A Painless Guide to CRC Error Detection Algorithms}
+  at~\url{http://www.ross.net/crc/download/crc_v3.txt}}.
 \end{large}
 
 \begin{table}[h]
   \centering
-  \begin{tabularx}{\textwidth}{aaX}
+  \begin{tabularx}{\textwidth}{aaaX}
     \toprule
-    Name & Size & Description \\
+    Offset (bytes) & Size (bytes) & Name & Description \\
     \midrule
-    {Preamble} & $1$ & Denotes the start of frame transmission. Always 0x55. \\
-    {Message Type} & $2$ & Identifies the payload contents. \\
-    {Sender} & $2$ & \hangindent=0.5em{A unique identifier of the sending hardware. Set to the 2 least significant bytes of the Piksi serial number.} \\
-    {Length} & $1$ & Length in bytes of the {Payload} field. \\
-    {Payload} & $N$ & Binary data of the message. \\
-    {CRC} & $2$ & \hangindent=0.5em{Cyclic Redundancy Check of the packet's binary data from the Message Type up to the end of Payload (does not include the Preamble).} \\
+    $0$ & $1$ & {Preamble} & Denotes the start of frame transmission. Always 0x55. \\
+    $1$ & $2$ & {Message Type} & Identifies the payload contents. \\
+    $3$ & $2$ & {Sender} & \hangindent=0.5em{A unique identifier of the sender. On the Piksi, this is set to the 2 least significant bytes of the device serial number. A stream of SBP messages may also included sender IDs for forwarded messages.} \\
+    $5$ & $1$ & {Length} & Length (bytes) of the {Payload} field. \\
+    $6$ & $N$ & {Payload} & Binary message contents. \\
+    $N+6$ & $2$ & {CRC} & \hangindent=0.5em{Cyclic Redundancy Check of the packet's binary data from the Message Type up to the end of Payload (does not include the Preamble).} \\
     \midrule
-    & $N+8$ \\
+    & $N+8$ & &Total Payload Length \\
     \bottomrule
   \end{tabularx}
-  \caption{Swift Binary Protocol message structure}
+  \caption{Swift Binary Protocol message structure. $N$ denotes a variable-length size.}
   \label{tab:message}
 \end{table}
+
+\begin{large}
+Note that Swift devices, such as the Piksi, also support the standard
+NMEA-0183 protocol for single-point position solutions. Observations
+transmitted via SBP can be converted into RINEX. Note that NMEA
+doesn't define a standardized message string for RTK solutions. To
+make it possible to achieve RTK accuracy with legacy host hardware or
+software that can only read NMEA, recent firmware versions implement a
+``pseudo-absolute'' mode.
+
+\end{large}
+
 \newpage
 
 \section{Basic Formats and Payload Structure}
 \label{sec:Payload}
 \begin{large}
-The binary payload of an SBP message can be decoded into structured
-data based on the message type defined in the header. SBP uses several
-primitive numerical and collection types for defining the contents of
-these payloads:
+The binary payload of an SBP message decodes into structured data
+based on the message type defined in the header. SBP uses several
+primitive numerical and collection types for defining payload
+contents.
 \end{large}
 \begin{table}[h]
   \centering
-  \begin{tabularx}{0.80\textwidth}{aaX}
+  \begin{tabularx}{\textwidth}{aaX}
     \toprule
-    Name & Size & Description \\
+    Name & Size (bytes) & Description \\
     \midrule
     ((*- for t in prims *))
     (((t.identifier))) & (((t.identifier | getsize))) & \hangindent=0.5em{(((t.desc)))} \\
@@ -146,31 +173,34 @@ \section{Basic Formats and Payload Structure}
   \caption{SBP primitive types}
   \label{tab:types}
 \end{table}
+\hspace{-5em}
+\subsubsection*{Example Message}
 \begin{large}
- \par As an example, consider this deframed series of bytes read
-from a serial port:
+ \par As an example, consider this framed series of bytes read from a
+ serial port:
 \begin{verbatim}
 55 02 02 cc 04 14 70 3d d0 18 cf ef ff ff ef e8 ff ff f0 18 00 00 00 00 05 00 43 94
 \end{verbatim}
-This cryptic byte array decodes into a \texttt{MSG\_BASELINE\_ECEF}
-(see pg.~\pageref{sec:MSG_POS_ECEF}), which reports the baseline
-position solution of the rover receiver relative to the base station
-receiver in Earth Centered Earth Fixed (ECEF) coordinates. The
-segments of this byte array and its contents breakdown as follows:
+This byte array decodes into a \texttt{MSG\_BASELINE\_ECEF} (see
+pg.~\pageref{sec:MSG_POS_ECEF}), that reports the baseline position
+solution of the rover receiver relative to the base station receiver
+in Earth Centered Earth Fixed (ECEF) coordinates. The segments of this
+byte array and its contents breakdown as follows:
 \end{large}
 \begin{table}[h]
   \centering
   \begin{tabular}{llrl}
     \toprule
     Field Name & Type & Value & Bytestring Segment\\
     \midrule
-    {Preamble} & u8 & 0x55 & \verb|55| \\
-    {Message Type}& u16 & 0x0202 & \verb|02 02| \\
-    {Sender}& u16 & 0x4cc & \verb!cc 04! \\
+    {Preamble} & u8 & 0x55 & \verb!55! \\
+    {Message Type}& u16 & \texttt{MSG\_BASELINE\_ECEF} & \verb!02 02! \\
+    {Sender}& u16 & 1228 & \verb!cc 04! \\
     {Length}& u8 & 20 &  \verb!14! \\
-    {Payload}& & --- & \verb!70 3d d0 18 cf ef ff ff ef e8 ff ff f0 18 00 00 00 00 05 00! \\
+    {Payload}& & --- & \verb!70 3d d0 18 cf ef ff ff ef e8 ff ff! \\
+    & & & \verb!f0 18 00 00 00 00 05 00! \\
     \quad~\texttt{MSG\_BASELINE\_ECEF} & & & \\
-    \quad~.tow & u32 & $416300400~\textrm{sec}$  & \verb!70 3d d0 18! \\
+    \quad~.tow & u32 & $416300400~\textrm{msec}$  & \verb!70 3d d0 18! \\
     \quad~.x & s32 & $-4145~\textrm{mm}$  & \verb!cf ef ff ff! \\
     \quad~.y & s32 & $-5905~\textrm{mm}$  & \verb!ef e8 ff ff! \\
     \quad~.z & s32 & $6384~\textrm{mm}$  & \verb!f0 18 00 00! \\

diff --git a/generator/sbpg/targets/resources/sbp_messages_desc.tex b/generator/sbpg/targets/resources/sbp_messages_desc.tex
@@ -6,7 +6,7 @@ \section{Stable Message Definitions}
 ((*- if m.pkg *))
 \subsection{(((m.pkg|packagenameify)))}
 \begin{large}
-(((m.pkg_desc)))
+(((m.pkg_desc | escape_tex | no_us)))
 \end{large}
 ((* endif *))
 \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id))))}
@@ -21,7 +21,7 @@ \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id))))}
   \centering
   \begin{tabularx}{\textwidth}{ccaclX}
     \toprule
-    Offset & Size & Format & Units & Name & Description \\
+    Offset (bytes) & Size (bytes) & Format & Units & Name & Description \\
     \midrule
     ((*- for f in m.fields *))
       $(((f.offset)))$ &
@@ -32,7 +32,7 @@ \subsubsection{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id))))}
       \hangindent=0.5em{(((f.desc|escape_tex)))} \\
       ((*- endfor *))
     \midrule
-    & $(((m.size)))$ \\
+    & $(((m.size)))$ & & & & Total Payload Length\\
     \bottomrule
   \end{tabularx}
   \caption{(((m.name|escape_tex))) (((('0x%04X'|format(m.sbp_id))))) message structure}
@@ -106,7 +106,7 @@ \subsubsection*{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id))))}
   \centering
   \begin{tabularx}{\textwidth}{ccaclX}
     \toprule
-    Offset & Size & Format & Units & Name & Description \\
+    Offset (bytes) & Size (bytes) & Format & Units & Name & Description \\
     \midrule
     ((*- for f in m.fields *))
       $(((f.offset)))$ &
@@ -117,7 +117,7 @@ \subsubsection*{(((m.name|escape_tex))) --- ((('0x%04X'|format(m.sbp_id))))}
       \hangindent=0.5em{(((f.desc|escape_tex)))} \\
       ((*- endfor *))
     \midrule
-    & $(((m.size)))$ \\
+    & $(((m.size)))$ & & & & Total Payload Length\\
     \bottomrule
   \end{tabularx}
   \caption{(((m.name|escape_tex))) (((('0x%04X'|format(m.sbp_id))))) message structure}

diff --git a/generator/sbpg/targets/resources/sbp_messages_table.tex b/generator/sbpg/targets/resources/sbp_messages_table.tex
@@ -1,23 +1,23 @@
 ((* extends "sbp_base.tex" *))
 ((* block messages_table *))
 \newpage
+\newpage
 \section{Message Types}
 \label{sec:Messages}
 \begin{large}
-Packages define a logical collection of SBP messages. By convention,
-the contents and layout of messages in packages marked \textbf{stable}
-are unlikely to change in the future. On the other hand, the contents
-of \textbf{draft} messages \ul{will change with future development},
-and are included here purely for \ul{informational purposes
-only}. Many draft messages are implementation-defined, and some
-collections, such as the bootloader package, are intended for internal
-development.
+Packages define a logical collection of SBP messages. The contents and
+layout of messages in packages marked \textbf{stable} are unlikely to
+change in the future. \textbf{Draft} messages \ul{will change with
+future development} and are detailed purely for \ul{informational
+purposes only}. Many draft messages are implementation-defined, and
+some collections, such as the acquisition package, are used for
+internal development.
 \end{large}
 \begin{table}[h]
   \centering
-  \begin{tabularx}{\textwidth}{badaX}
+  \begin{tabularx}{\textwidth}{badcX}
     \toprule
-    Package & Message & Name & Size & Description \\
+    Package & Msg ID & Name & Size (bytes) & Description \\
     \midrule
     \multicolumn{5}{c}{\textbf{Stable}} \\
     \midrule

diff --git a/spec/yaml/swiftnav/sbp/acquisition.yaml b/spec/yaml/swiftnav/sbp/acquisition.yaml
@@ -9,7 +9,7 @@
 # WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 
 package: swiftnav.sbp.acquisition
-description: Satellite acquisition messages from the Piksi.
+description: Satellite acquisition messages from the device.
 stable: False
 public: True
 include:
@@ -29,7 +29,9 @@ definitions:
     fields:
         - snr:
             type: float
-            desc: SNR of best point
+            desc: |
+              SNR of best point. Currently dimensonless, but will be
+              in dB Hz in the revision of this message.
         - cp:
             type: float
             units: chips
@@ -41,5 +43,5 @@ definitions:
         - prn:
             type: u8
             desc: |
-              PRN identifier of the satellite signal for which
+              PRN-1 identifier of the satellite signal for which
               acquisition was attempted
diff --git a/spec/yaml/swiftnav/sbp/base.yaml b/spec/yaml/swiftnav/sbp/base.yaml
@@ -35,9 +35,9 @@ definitions:
         - sender:
             type: u16
             desc: |
-              A unique identifier of the sending hardware. For v1.0 on Piksi,
-              set to the 2 least significant bytes of the Piksi serial.
-              number.
+              A unique identifier of the sending hardware. For v1.0,
+              set to the 2 least significant bytes of the device serial
+              number
         - length:
             type: u8
             units: bytes