Swift Navigation Binary Protocol Protocol Specification v0.33
Contents 1 2 3 4 5 5.1 5.2 6 6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9
1
Overview Message Structure Basic Formats and Payload Message Types Stable Message Definitions Navigation . . . . . . . . . . System . . . . . . . . . . . Draft Message Definitions Acquisition . . . . . . . . . Bootload . . . . . . . . . . File IO . . . . . . . . . . . . Flash . . . . . . . . . . . . . Logging . . . . . . . . . . . Observation . . . . . . . . . Piksi . . . . . . . . . . . . . Settings . . . . . . . . . . . Tracking . . . . . . . . . . .
Structure
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
. . . . . . . . .
1 2 3 4 5 5 13 15 15 16 18 22 29 30 32 36 38
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 receive messages from the host operating system, such as differential 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 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 http://docs.swiftnav.com/wiki/SwiftNav˙Binary˙Protocol.
Version 0.33, April 15, 2015
1
Swift Navigation
2
Swift Navigation Binary Protocol
Message Structure
SBP consists of two pieces:
an over-the-wire message framing format
structured payload definitions
As of Version 0.33, 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 little-endian format. SBP uses the CCITT CRC16 (XMODEM implementation) for error detection1 . Offset (bytes)
Size (bytes)
Name
Description
0 1
1 2
Denotes the start of frame transmission. Always 0x55. Identifies the payload contents.
3
2
Preamble Message Type Sender
5 6 N +6
1 N 2
Length Payload CRC
N +8
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. Length (bytes) of the Payload field. Binary message contents. Cyclic Redundancy Check of the packet’s binary data from the Message Type up to the end of Payload (does not include the Preamble). Total Payload Length
Table 2.0.1: Swift Binary Protocol message structure. N denotes a variable-length size.
Swift devices, such as the Piksi, also support the standard NMEA-0183 protocol for single-point position solutions. Observations transmitted via SBP can also 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.
1 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 https://github.com/swift-nav/libsbp/blob/master/c/src/edc.c#L59. See also A Painless Guide to CRC Error Detection Algorithms at http://www.ross.net/crc/download/crc˙v3.txt
Version 0.33, April 15, 2015
2
Swift Navigation
3
Swift Navigation Binary Protocol
Basic Formats and Payload Structure
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. Name
Size (bytes)
Description
s8 s16 s32 s64 u8 u16 u32 u64 float double array bytes string bitfield
1 2 4 8 1 2 4 8 4 8 — — — —
Signed 8-bit integer Signed 16-bit integer Signed 32-bit integer Signed 64-bit integer Unsigned 8-bit integer Unsigned 16-bit integer Unsigned 32-bit integer Unsigned 64-bit integer Single-precision float (IEEE-754) Double-precision float (IEEE-754) Fixed or variable length array of any fill type Fixed or variable length array of bytes Fixed or variable length string (NULL padded/terminated) A primitive type, typically a u8, can encode boolean and enumerated status flags. Table 3.0.2: SBP primitive types
Example Message
As an example, consider this framed series of bytes read from a serial port: 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 This byte array decodes into a MSG BASELINE ECEF (see pg. 7), 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: Field Name
Type
Preamble Message Type Sender Length Payload
u8 u16 u16 u8
MSG BASELINE ECEF .tow .x .y .z .accuracy .nsats .flags CRC
u32 s32 s32 s32 u16 u8 u8 u16
Value
Bytestring Segment
0x55 MSG BASELINE ECEF 1228 20 —
55 02 cc 14 70 f0
416300400 msec −4145 mm −5905 mm 6384 mm 0 5 0 0x9443
70 cf ef f0 00 05 00 43
02 04 3d d0 18 cf ef ff ff ef e8 ff ff 18 00 00 00 00 05 00 3d ef e8 18 00
d0 ff ff 00
18 ff ff 00
94
Table 3.0.3: SBP breakdown for MSG BASELINE ECEF
Version 0.33, April 15, 2015
3
Swift Navigation
4
Swift Navigation Binary Protocol
Message Types
Packages define a logical collection of SBP messages. The contents and layout of messages in packages marked stable are unlikely to change in the future. Draft messages will change with future development and are detailed purely for informational purposes only. Many draft messages are implementation-defined, and some collections, such as the acquisition package, are used for internal development. Package
Msg ID
Name
Size (bytes)
Description
0x0100 0x0206 0x0200 0x0201 0x0202 0x0203 0x0204 0x0205 0xFF00 0xFFFF
MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG
GPS TIME DOPS POS ECEF POS LLH BASELINE ECEF BASELINE NED VEL ECEF VEL NED STARTUP HEARTBEAT
11 14 32 34 20 22 20 22 4 4
GPS Time Dilution of Precision Single-point position in ECEF Geodetic Position Baseline Position in ECEF Baseline in NED Velocity in ECEF Velocity in NED System start-up message System heartbeat message
0x0015 0x00B0 0x00DD 0x00A8 0x00A9 0x00AC 0x00AD 0x00E0 0x00E0 0x00E1 0x00E2 0x00E3 0x00E4 0x00E5 0x0010 0x0045 0x0044 0x00B2 0x0023 0x0017 0x0018 0x00A0 0x00A1 0x0016 0x001A
MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG MSG
ACQ RESULT 13 BOOTLOADER HANDSHAKE N NAP DEVICE DNA 8 FILEIO READ 25 FILEIO READ DIR 24 FILEIO REMOVE 20 FILEIO WRITE N + 24 FLASH PROGRAM N +5 FLASH DONE 1 FLASH READ 5 FLASH ERASE 5 STM FLASH LOCK SECTOR 4 STM FLASH UNLOCK SECTOR 4 STM UNIQUE ID 12 PRINT N OBS 13N + 7 BASE POS 24 RESET 0 INIT BASE 0 THREAD STATE 26 UART STATE 58 SETTINGS N SETTINGS SAVE 0 TRACKING STATE 6N EPHEMERIS 175
Stable Navigation
System Draft Acquisition Bootload File IO
Flash
Logging Observation Piksi
Settings Tracking
Satellite acquisition result Bootloading handshake Read FPGA device ID over UART Read file from the file system List files in a directory Delete a file from the file system Write to file Program flash addresses Flash response message Read STM or M25 flash address Erase sector of device flash memory Lock sector of STM flash memory Unlock sector of STM flash memory Read device’s hardcoded unique ID Plaintext logging messages GPS satellite observations Base station position Reset the device Initialize IAR from known baseline State of an RTOS thread State of the UART channels R/W device configuration settings Save settings to flash Satellite tracking channel states WGS84 satellite ephemeris parameters
Table 4.0.4: SBP message types
Version 0.33, April 15, 2015
4
Swift Navigation
Swift Navigation Binary Protocol
5
Stable Message Definitions
5.1
Navigation
Geodetic navigation messages reporting GPS time, position, velocity, and baseline position solutions. For position solutions, these messages define several different position solutions: single-point (SPP), RTK, and pseudo-absolute position solutions. The SPP is the standalone, absolute GPS position solution using only a single receiver. The RTK solution is the differential GPS solution, which can use either a fixed/integer or floating carrier phase ambiguity. The pseudo-absolute position solution uses a user-provided, well-surveyed base station position (if available) and the RTK solution in tandem. MSG GPS TIME — 0x0100
This message reports the GPS time, representing the time since the GPS epoch began on midnight January 6, 1980 UTC. GPS time counts the weeks and seconds of the week. The weeks begin at the Saturday/Sunday transition. GPS week 0 began at the beginning of the GPS time scale. Within each week number, the GPS time of the week is between between 0 and 604800 seconds (=60*60*24*7). Note that GPS time does not accumulate leap seconds, and as of now, has a small offset from UTC. In a message stream, this message precedes a set of other navigation messages referenced to the same time (but lacking the ns field) and indicates a more precise time of these messages.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 2
2 4
u16 u32
weeks ms
wn tow
6
4
s32
ns
ns
10
1
u8
GPS week number GPS time of week rounded to the nearest millisecond Nanosecond residual of millisecond-rounded TOW (ranges from -500000 to 500000) Status flags (reserved)
11
flags
Total Payload Length Table 5.1.1: MSG GPS TIME 0x0100 message structure
Version 0.33, April 15, 2015
5
Swift Navigation
Swift Navigation Binary Protocol
MSG DOPS — 0x0206
This dilution of precision (DOP) message describes the effect of navigation satellite geometry on positional measurement precision.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 6 8 10 12
4 2 2 2 2 2
u32 u16 u16 u16 u16 u16
ms
tow gdop pdop tdop hdop vdop
GPS Time of Week Geometric Dilution of Precision Position Dilution of Precision Time Dilution of Precision Horizontal Dilution of Precision Vertical Dilution of Precision
14
Total Payload Length Table 5.1.2: MSG DOPS 0x0206 message structure
Version 0.33, April 15, 2015
6
Swift Navigation
Swift Navigation Binary Protocol
MSG POS ECEF — 0x0200
The position solution message reports absolute Earth Centered Earth Fixed (ECEF) coordinates and the status (single point vs pseudo-absolute RTK) of the position solution. If the rover receiver knows the surveyed position of the base station and has an RTK solution, this reports a pseudo-absolute position solution using the base station position and the rover’s RTK baseline vector. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 12 20 28
4 8 8 8 2
u32 double double double u16
ms m m m mm
tow x y z accuracy
30 31
1 1
u8 u8
GPS Time of Week ECEF X coordinate ECEF Y coordinate ECEF Z coordinate Position accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution Status flags
n sats flags
32
Total Payload Length
7
Fi
x
R es
er
m
ve
d
od e
(T ab
le
5. 1. 4)
Table 5.1.3: MSG POS ECEF 0x0200 message structure
3
2
0
Field 5.1.1: Status flags (flags)
Version 0.33, April 15, 2015
Value
Description
0 1 2
Single Point Positioning (SPP) Float RTK Fixed RTK
Table 5.1.4: Fix mode values (flags[0:2])
7
Swift Navigation
Swift Navigation Binary Protocol
MSG POS LLH — 0x0201
This position solution message reports the absolute geodetic coordinates and the status (single point vs pseudo-absolute RTK) of the position solution. If the rover receiver knows the surveyed position of the base station and has an RTK solution, this reports a pseudo-absolute position solution using the base station position and the rover’s RTK baseline vector. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 12 20 28
4 8 8 8 2
u32 double double double u16
ms deg deg m mm
tow lat lon height h accuracy
30
2
u16
mm
v accuracy
32 33
1 1
u8 u8
GPS Time of Week Latitude Longitude Height Horizontal position accuracy estimate (not implemented). Defaults to 0. Vertical position accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution. Status flags
n sats flags
34
Total Payload Length
Value
Description
0 1 2
Single Point Positioning (SPP) Fixed RTK Float RTK
Table 5.1.6: Fix mode values (flags[0:2])
7
4
H
R es
er
ve ei d gh Fi t M x m od od e e (T (T ab ab le le 5. 5. 1. 1. 7) 6)
Table 5.1.5: MSG POS LLH 0x0201 message structure
3
2
0
Field 5.1.2: Status flags (flags)
Value
Description
0 1
Height above Ellipsoid Height above mean sea level
Table 5.1.7: Height Mode values (flags[3])
Version 0.33, April 15, 2015
8
Swift Navigation
Swift Navigation Binary Protocol
MSG BASELINE ECEF — 0x0202
This message reports the baseline solution in Earth Centered Earth Fixed (ECEF) coordinates. This baseline is the relative vector distance from the base station to the rover receiver. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 8 12 16
4 4 4 4 2
u32 s32 s32 s32 u16
ms mm mm mm mm
tow x y z accuracy
18 19
1 1
u8 u8
GPS Time of Week Baseline ECEF X coordinate Baseline ECEF Y coordinate Baseline ECEF Z coordinate Position accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution Status flags
n sats flags
20
Total Payload Length
R
Fi x
es
er v
m od
ed
e
(T ab
le
5. 1. 9)
Table 5.1.8: MSG BASELINE ECEF 0x0202 message structure
7
3
2
0
Field 5.1.3: Status flags (flags)
Version 0.33, April 15, 2015
Value
Description
0 1
Float RTK Fixed RTK
Table 5.1.9: Fix mode values (flags[0:2])
9
Swift Navigation
Swift Navigation Binary Protocol
MSG BASELINE NED — 0x0203
This message reports the baseline solution in North East Down (NED) coordinates. This baseline is the relative vector distance from the base station to the rover receiver, and NED coordinate system is defined at the local tangent plane centered at the base station position. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 8 12 16
4 4 4 4 2
u32 s32 s32 s32 u16
ms mm mm mm mm
tow n e d h accuracy
18
2
u16
mm
v accuracy
20 21
1 1
u8 u8
GPS Time of Week Baseline North coordinate Baseline East coordinate Baseline Down coordinate Horizontal position accuracy estimate (not implemented). Defaults to 0. Vertical position accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution Status flags
n sats flags
22
Total Payload Length
R
Fi x
es
er
ve
m od
d
e
(T ab
le
5.
1. 11 )
Table 5.1.10: MSG BASELINE NED 0x0203 message structure
7
3
2
0
Field 5.1.4: Status flags (flags)
Version 0.33, April 15, 2015
Value
Description
0 1
Float RTK Fixed RTK
Table 5.1.11: Fix mode values (flags[0:2])
10
Swift Navigation
Swift Navigation Binary Protocol
MSG VEL ECEF — 0x0204
This message reports the velocity in Earth Centered Earth Fixed (ECEF) coordinates. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 8 12 16
4 4 4 4 2
u32 s32 s32 s32 u16
ms mm/s mm/s mm/s mm/s
tow x y z accuracy
18 19
1 1
u8 u8
GPS Time of Week Velocity ECEF X coordinate Velocity ECEF Y coordinate Velocity ECEF Z coordinate Velocity accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution Status flags (reserved)
20
n sats flags
Total Payload Length Table 5.1.12: MSG VEL ECEF 0x0204 message structure
Version 0.33, April 15, 2015
11
Swift Navigation
Swift Navigation Binary Protocol
MSG VEL NED — 0x0205
This message reports the velocity in local North East Down (NED) coordinates. The full GPS time is given by the preceding MSG GPS TIME with the matching time-of-week (tow).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 8 12 16
4 4 4 4 2
u32 s32 s32 s32 u16
ms mm/s mm/s mm/s mm/s
tow n e d h accuracy
18
2
u16
mm/s
v accuracy
20 21
1 1
u8 u8
GPS Time of Week Velocity North coordinate Velocity East coordinate Velocity Down coordinate Horizontal velocity accuracy estimate (not implemented). Defaults to 0. Vertical velocity accuracy estimate (not implemented). Defaults to 0. Number of satellites used in solution Status flags (reserved)
22
n sats flags
Total Payload Length Table 5.1.13: MSG VEL NED 0x0205 message structure
Version 0.33, April 15, 2015
12
Swift Navigation
5.2
Swift Navigation Binary Protocol
System
Standardized system messages from Swift Navigation devices. MSG STARTUP — 0xFF00
The system start-up message is sent once on system start-up. It notifies the host or other attached devices that the system has started and is now ready to respond to commands or configuration requests.
Offset (bytes)
Size (bytes)
Format
0
4
u32
4
Units
Name
Description
reserved
Reserved Total Payload Length
Table 5.2.1: MSG STARTUP 0xFF00 message structure
Version 0.33, April 15, 2015
13
Swift Navigation
Swift Navigation Binary Protocol
MSG HEARTBEAT — 0xFFFF
The heartbeat message is sent periodically to inform the host or other attached devices that the system is running. It is used to monitor system malfunctions. It also contains status flags that indicate to the host the status of the system and whether it is operating correctly. Currently, the expected heartbeat interval is 1 sec. The system error flag is used to indicate that an error has occurred in the system. To determine the source of the error, the remaining error flags should be inspected.
Offset (bytes)
Size (bytes)
Format
0
4
u32
Units
Name
Description
flags
Status flags
4
Total Payload Length
(T ab
nt se
Sw IO iftN Sy Er AP st ror E em rr Er or ro r Fl a
g
pr e na en nt
ve
d
al a
R es
er
te rn Ex 31
30
Value
Description
0 1
System Healthy An error has occurred
le
(T ab
le
5. 2. 3)
5.
2. 4)
Table 5.2.2: MSG HEARTBEAT 0xFFFF message structure
3
2
1
0
Table 5.2.3: System Error Flag values (flags[0])
Value
Description
0 1
No external antenna detected External antenna is present
Field 5.2.1: Status flags (flags) Table 5.2.4: External antenna present values (flags[31])
Version 0.33, April 15, 2015
14
Swift Navigation
Swift Navigation Binary Protocol
6
Draft Message Definitions
6.1
Acquisition
Satellite acquisition messages from the device. MSG ACQ RESULT — 0x0015
This message describes the results from an attempted GPS signal acquisition search for a satellite PRN over a code phase/carrier frequency range. It contains the parameters of the point in the acquisition search space with the best signal-to-noise (SNR) ratio.
Offset (bytes)
Size (bytes)
Format
0
4
float
4 8 12
4 4 1
float float u8
13
Units
chips hz
Name
Description
snr
SNR of best point. Currently dimensonless, but will have units of dB Hz in the revision of this message. Code phase of best point Carrier frequency of best point PRN-1 identifier of the satellite signal for which acquisition was attempted
cp cf prn
Total Payload Length Table 6.1.1: MSG ACQ RESULT 0x0015 message structure
Version 0.33, April 15, 2015
15
Swift Navigation
6.2
Swift Navigation Binary Protocol
Bootload
Messages for the bootloading configuration on the device. These are in the implementation-defined range (0x0000-0x00FF), and are intended for internal use only. Note that some of these messages share the same message type ID for both the host request and the device response. MSG BOOTLOADER HANDSHAKE — 0x00B0
The handshake message establishes a handshake between the device bootloader and the host. The payload string contains the bootloader version number, but returns an empty string for earlier versions.
Offset (bytes)
Size (bytes)
Format
0
N
string
N
Units
Name
Description
handshake
Version number (NULL terminated) Total Payload Length
Table 6.2.1: MSG BOOTLOADER HANDSHAKE 0x00B0 message structure
Version 0.33, April 15, 2015
16
Swift Navigation
Swift Navigation Binary Protocol
MSG NAP DEVICE DNA — 0x00DD
The device message from the host reads a unique device identifier from the SwiftNAP, an FPGA. The host requests the ID by sending a MSG NAP DEVICE DNA with an empty payload. The device responds with the same message with the device ID in the payload. Note that this ID is tied to the FPGA, and not related to the Piksi’s serial number.
Offset (bytes)
Size (bytes)
Format
0
8
u8[8]
8
Units
Name
Description
dna
57-bit SwiftNAP FPGA Device ID. Remaining bits are padded on the right. Total Payload Length
Table 6.2.2: MSG NAP DEVICE DNA 0x00DD message structure
Version 0.33, April 15, 2015
17
Swift Navigation
6.3
Swift Navigation Binary Protocol
File IO
Messages for using device’s onboard flash filesystem functionality. This allows data to be stored persistently in the device’s program flash with wear-levelling using a simple filesystem interface. The file system interface (CFS) defines an abstract API for reading directories and for reading and writing files. These are in the implementation-defined range (0x0000-0x00FF), and intended for internal-use only. Note that some of these messages share the same message type ID for both the host request and the device response. MSG FILEIO READ — 0x00A8
The file read message reads a certain length (up to 255 bytes) from a given offset into a file, and returns the data in a MSG FILEIO READ message where the message length field indicates how many bytes were succesfully read. If the message is invalid, a followup MSG PRINT message will print ”Invalid fileio read message”.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 5
4 1 20
u32 u8 string
bytes bytes
offset chunk size filename
File offset Chunk size to read Name of the file to read from (NULL padded)
25
Total Payload Length Table 6.3.1: MSG FILEIO READ 0x00A8 message structure
Version 0.33, April 15, 2015
18
Swift Navigation
Swift Navigation Binary Protocol
MSG FILEIO READ DIR — 0x00A9
The read directory message lists the files in a directory on the device’s onboard flash file system. The offset parameter can be used to skip the first n elements of the file list. Returns a MSG FILEIO READ DIR message containing the directory listings as a NULL delimited list. The listing is chunked over multiple SBP packets and the end of the list is identified by an entry containing just the character 0xFF. If message is invalid, a followup MSG PRINT message will print ”Invalid fileio read message”.
Offset (bytes)
Size (bytes)
Format
0
4
4
20 24
Units
Name
Description
u32
offset
string
dirname
The offset to skip the first n elements of the file list Name of the directory to list (NULL padded) Total Payload Length
Table 6.3.2: MSG FILEIO READ DIR 0x00A9 message structure
Version 0.33, April 15, 2015
19
Swift Navigation
Swift Navigation Binary Protocol
MSG FILEIO REMOVE — 0x00AC
The file remove message deletes a file from the file system. If message is invalid, a followup MSG PRINT message will print ”Invalid fileio remove message”.
Offset (bytes)
Size (bytes)
Format
0
20
string
20
Units
Name
Description
filename
Name of the file to delete (NULL padded) Total Payload Length
Table 6.3.3: MSG FILEIO REMOVE 0x00AC message structure
Version 0.33, April 15, 2015
20
Swift Navigation
Swift Navigation Binary Protocol
MSG FILEIO WRITE — 0x00AD
The file write message writes a certain length (up to 255 bytes) of data to a file at a given offset. Returns a copy of the original MSG FILEIO WRITE message to check integrity of the write. If message is invalid, a followup MSG PRINT message will print ”Invalid fileio write message”.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 20
20 4
string u32
bytes
filename offset
24
N
u8[N]
Name of the file to write to (NULL padded) Offset into the file at which to start writing in bytes Variable-length array of data to write
N + 24
data
Total Payload Length Table 6.3.4: MSG FILEIO WRITE 0x00AD message structure
Version 0.33, April 15, 2015
21
Swift Navigation
6.4
Swift Navigation Binary Protocol
Flash
Messages for reading/writing the device’s onboard flash memory. Many of these messages target specific flash memory peripherals used in Swift Navigation devices: the STM32 flash and the M25Pxx FPGA configuration flash. These are in the implementation-defined range (0x0000-0x00FF), and are intended for internal-use only. MSG FLASH PROGRAM — 0x00E0
The flash program message programs a set of addresses of either the STM or M25 flash. The device replies with either a MSG FLASH DONE message containing the return code FLASH OK (0) on success, or FLASH INVALID LEN (2) if the maximum write size is exceeded. Note that the sector-containing addresses must be erased before addresses can be programmed.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 1 4
1 3 1
u8 u8[3] u8
bytes bytes
target addr start addr len
5
N
u8[N]
Target flags Starting address offset to program Length of set of addresses to program, counting up from starting address Data to program addresses with, with length N=addr len
data
N +5
Total Payload Length
R 7
1
0
Field 6.4.1: Target flags (target)
Version 0.33, April 15, 2015
Value
Description
0 1
FLASH STM FLASH M25
h Fl
es
as
er
ve d
ta rg
et
to
re
ad
(T ab
le
6. 4. 2)
Table 6.4.1: MSG FLASH PROGRAM 0x00E0 message structure
Table 6.4.2: Flash target to read values (target[0])
22
Swift Navigation
Swift Navigation Binary Protocol
MSG FLASH DONE — 0x00E0
This message defines success or failure codes for a variety of flash memory requests from the host to the device. Flash read and write messages, such as MSG FLASH READ or MSG FLASH WRITE, may return this message on failure.
Offset (bytes)
Size (bytes)
Format
0
1
u8
Units
1
Name
Description
response
Response flags Total Payload Length
7
3
es R
R
es e
rv
po ns
ed
e
co
de
(T ab
le
6. 4. 4)
Table 6.4.3: MSG FLASH DONE 0x00E0 message structure
2
0
Field 6.4.2: Response flags (response)
Version 0.33, April 15, 2015
Value
Description
0 1 2 3 4 5
FLASH FLASH FLASH FLASH FLASH FLASH
OK INVALID INVALID INVALID INVALID INVALID
FLASH LEN ADDR RANGE SECTOR
Table 6.4.4: Response code values (response[0:2])
23
Swift Navigation
Swift Navigation Binary Protocol
MSG FLASH READ — 0x00E1
The flash read message reads a set of addresses of either the STM or M25 onboard flash. The device replies with a MSG FLASH READ message containing either the read data on success or a MSG FLASH DONE message containing the return code FLASH INVALID LEN (2) if the maximum read size is exceeded or FLASH INVALID ADDR (3) if the address is outside of the allowed range.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 1 4
1 3 1
u8 u8[3] u8
bytes bytes
target addr start addr len
Target flags Starting address offset to read from Length of set of addresses to read, counting up from starting address
5
Total Payload Length
7
1
0
Field 6.4.3: Target flags (target)
Version 0.33, April 15, 2015
Value
Description
0 1
FLASH STM FLASH M25
h Fl as
R
es
er v
ed
ta rg
et
to
re
ad
(T ab
le
6. 4. 6)
Table 6.4.5: MSG FLASH READ 0x00E1 message structure
Table 6.4.6: Flash target to read values (target[0])
24
Swift Navigation
Swift Navigation Binary Protocol
MSG FLASH ERASE — 0x00E2
The flash erase message from the host erases a sector of either the STM or M25 onboard flash memory. The device will reply with a MSG FLASH DONE message containing the return code - FLASH OK (0) on success or FLASH INVALID FLASH (1) if the flash specified is invalid.
Offset (bytes)
Size (bytes)
Format
0 1
1 4
u8 u32
Units
5
Name
Description
target sector num
Target flags Flash sector number to erase (0-11 for the STM, 0-15 for the M25) Total Payload Length
R 7
1
0
Field 6.4.4: Target flags (target)
Version 0.33, April 15, 2015
Value
Description
0 1
FLASH STM FLASH M25
h as Fl
es
er v
ed
ta rg
et
to
re
ad
(T ab
le
6. 4. 8)
Table 6.4.7: MSG FLASH ERASE 0x00E2 message structure
Table 6.4.8: Flash target to read values (target[0])
25
Swift Navigation
Swift Navigation Binary Protocol
MSG STM FLASH LOCK SECTOR — 0x00E3
The flash lock message locks a sector of the STM flash memory. MSG FLASH DONE message.
Offset (bytes)
Size (bytes)
Format
0
4
u32
4
Units
The device replies with a
Name
Description
sector
Flash sector number to lock Total Payload Length
Table 6.4.9: MSG STM FLASH LOCK SECTOR 0x00E3 message structure
Version 0.33, April 15, 2015
26
Swift Navigation
Swift Navigation Binary Protocol
MSG STM FLASH UNLOCK SECTOR — 0x00E4
The flash unlock message unlocks a sector of the STM flash memory. The device replies with a MSG FLASH DONE message.
Offset (bytes)
Size (bytes)
Format
0
4
u32
4
Units
Name
Description
sector
Flash sector number to unlock Total Payload Length
Table 6.4.10: MSG STM FLASH UNLOCK SECTOR 0x00E4 message structure
Version 0.33, April 15, 2015
27
Swift Navigation
Swift Navigation Binary Protocol
MSG STM UNIQUE ID — 0x00E5
This message reads the device’s hardcoded unique ID. The device returns 12-byte unique ID back to host.
Offset (bytes)
Size (bytes)
Format
0
12
u8[12]
12
Units
Name
Description
stm id
Device unique ID Total Payload Length
Table 6.4.11: MSG STM UNIQUE ID 0x00E5 message structure
Version 0.33, April 15, 2015
28
Swift Navigation
6.5
Swift Navigation Binary Protocol
Logging
Logging and debugging messages from the device. These are in the implementation-defined range (0x0000-0x00FF). MSG PRINT — 0x0010
This message contains a human-readable payload string from the device containing errors, warnings and informational messages at ERROR, WARNING, DEBUG, INFO logging levels.
Offset (bytes)
Size (bytes)
Format
0
N
string
N
Units
Name
Description
text
Human-readable string Total Payload Length
Table 6.5.1: MSG PRINT 0x0010 message structure
Version 0.33, April 15, 2015
29
Swift Navigation
6.6
Swift Navigation Binary Protocol
Observation
Satellite observation messages from the device. MSG OBS — 0x0045
The GPS observations message reports all the raw pseudorange and carrier phase observations for the satellites being tracked by the device. Carrier phase observation here is represented as a 40-bit fixed point number with Q32.8 layout (i.e. 32-bits of whole cycles and 8-bits of fractional cycles).
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 4 6
4 2 1
u32 u16 u8
ms week
header.t.tow header.t.wn header.n obs
13N + 7 13N + 11 13N + 15 13N + 16 13N + 17
4 4 1 1 2
u32 s32 u8 u8 u16
cm cycles cycles dB Hz
obs[N].P obs[N].L.i obs[N].L.f obs[N].cn0 obs[N].lock
13N + 19
1
u8
Milliseconds since start of GPS week GPS week number Total number of observations. First nibble is the size of the sequence (n), second nibble is the zero-indexed counter (ith packet of n) Pseudorange observation Carrier phase whole cycles Carrier phase fractional part Carrier-to-Noise density Lock indicator. This value changes whenever a satellite signal has lost and regained lock, indicating that the carrier phase ambiguity may have changed. PRN-1 identifier of the satellite signal
13N + 7
obs[N].prn
Total Payload Length Table 6.6.1: MSG OBS 0x0045 message structure
Version 0.33, April 15, 2015
30
Swift Navigation
Swift Navigation Binary Protocol
MSG BASE POS — 0x0044
The base station position message is the position reported by the base station itself. It is used for pseudo-absolute RTK positioning, and is required to be a high-accuracy surveyed location of the base station. Any error here will result in an error in the pseudo-absolute position output.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 8 16
8 8 8
double double double
deg deg m
lat lon height
Latitude Longitude Height
24
Total Payload Length Table 6.6.2: MSG BASE POS 0x0044 message structure
Version 0.33, April 15, 2015
31
Swift Navigation
6.7
Swift Navigation Binary Protocol
Piksi
System health, configuration, and diagnostic messages specific to the Piksi L1 receiver, including a variety of legacy messages that may no longer be used. These messages are in the implementation-defined range (0x0000-0x00FF), and largely intended for internal-use only. MSG RESET — 0x00B2
This message from the host resets the Piksi back into the bootloader.
Offset (bytes)
Size (bytes) 0
Format
Units
Name
Description Total Payload Length
Table 6.7.1: MSG RESET 0x00B2 message structure
Version 0.33, April 15, 2015
32
Swift Navigation
Swift Navigation Binary Protocol
MSG INIT BASE — 0x0023
This message initializes the integer ambiguity resolution (IAR) process on the Piksi to use an assumed baseline position between the base station and rover receivers. Warns via MSG PRINT if there aren’t a shared minimum number (4) of satellite observations between the two.
Offset (bytes)
Size (bytes) 0
Format
Units
Name
Description Total Payload Length
Table 6.7.2: MSG INIT BASE 0x0023 message structure
Version 0.33, April 15, 2015
33
Swift Navigation
Swift Navigation Binary Protocol
MSG THREAD STATE — 0x0017
The thread usage message from the device reports real-time operating system (RTOS) thread usage statistics for the named thread. The reported percentage values require to be normalized.
Offset (bytes)
Size (bytes)
Format
0 20
20 2
string u16
22
4
u32
26
Units
bytes
Name
Description
name cpu
Thread name (NULL terminated) Percentage cpu use for this thread. Values range from 0 - 1000 and needs to be renormalized to 100 Free stack space for this thread
stack free
Total Payload Length Table 6.7.3: MSG THREAD STATE 0x0017 message structure
Version 0.33, April 15, 2015
34
Swift Navigation
Swift Navigation Binary Protocol
MSG UART STATE — 0x0018
The UART message reports data latency and throughput of the UART channels providing SBP I/O. On the default Piksi configuration, UARTs A and B are used for telemetry radios, but can also be be host access ports for embedded hosts, or other interfaces in future. The reported percentage values require to be normalized.
Offset (bytes)
Size (bytes)
Format
Units
Name
0 4 8 10 12
4 4 2 2 1
float float u16 u16 u8
kB/s kB/s
uart uart uart uart uart
13
1
u8
14 18 22 24 26
4 4 2 2 1
float float u16 u16 u8
27
1
u8
28 32 36 38 40
4 4 2 2 1
float float u16 u16 u8
41
1
u8
42 46 50 54
4 4 4 4
s32 s32 s32 s32
58
Description a.tx throughput a.rx throughput a.crc error count a.io error count a.tx buffer level
uart a.rx buffer level kB/s kB/s
uart uart uart uart uart
b.tx throughput b.rx throughput b.crc error count b.io error count b.tx buffer level
uart b.rx buffer level kB/s kB/s
uart uart uart uart uart
ftdi.tx throughput ftdi.rx throughput ftdi.crc error count ftdi.io error count ftdi.tx buffer level
uart ftdi.rx buffer level ms ms ms ms
latency.avg latency.lmin latency.lmax latency.current
UART transmit throughput UART receive throughput UART CRC error count UART IO error count UART transmit buffer percentage utilization (ranges from 0 - 255) UART receive buffer percentage utilization (ranges from 0 to 255) UART transmit throughput UART receive throughput UART CRC error count UART IO error count UART transmit buffer percentage utilization (ranges from 0 - 255) UART receive buffer percentage utilization (ranges from 0 to 255) UART transmit throughput UART receive throughput UART CRC error count UART IO error count UART transmit buffer percentage utilization (ranges from 0 - 255) UART receive buffer percentage utilization (ranges from 0 to 255) Average latency Minimum latency Maximum latency Smoothed estimate of the current latency Total Payload Length
Table 6.7.4: MSG UART STATE 0x0018 message structure
Version 0.33, April 15, 2015
35
Swift Navigation
6.8
Swift Navigation Binary Protocol
Settings
Messages for reading and writing the device’s device settings. These are in the implementation-defined range (0x0000-0x00FF). Note that some of these messages share the same message type ID for both the host request and the device response. See the accompanying document for descriptions of settings configurations and examples: https://github.com/swiftnav/piksi firmware/blob/master/docs/settings.pdf MSG SETTINGS — 0x00A0
The setting message reads and writes the device’s configuration.
Offset (bytes)
Size (bytes)
Format
0
N
string
N
Units
Name
Description
setting
A NULL-terminated and delimited string with contents [SECTION SETTING, SETTING, VALUE] on writes or a series of such strings on reads. Total Payload Length
Table 6.8.1: MSG SETTINGS 0x00A0 message structure
Version 0.33, April 15, 2015
36
Swift Navigation
Swift Navigation Binary Protocol
MSG SETTINGS SAVE — 0x00A1
The save settings message persists the device’s current settings configuration to its onboard flash memory file system.
Offset (bytes)
Size (bytes) 0
Format
Units
Name
Description Total Payload Length
Table 6.8.2: MSG SETTINGS SAVE 0x00A1 message structure
Version 0.33, April 15, 2015
37
Swift Navigation
6.9
Swift Navigation Binary Protocol
Tracking
Satellite code and carrier-phase tracking messages from the device. MSG TRACKING STATE — 0x0016
The tracking message returns a variable-length array of tracking channel states. It reports status and snr power measurements for all tracked satellites.
Offset (bytes)
Size (bytes)
Format
6N + 0 6N + 1 6N + 2
1 1 4
u8 u8 float
Units
Name
Description
dB Hz
states[N].state states[N].prn states[N].cn0
Status of tracking channel PRN-1 being tracked Carrier-to-noise density
6N
Total Payload Length
7
2
10
Field 6.9.1: Status of tracking channel (state)
Version 0.33, April 15, 2015
Value
Description
0 1
Disabled Running
ck Tr a
R
es
er v
ed
in g
m
od
e
(T ab
le
6. 9. 2)
Table 6.9.1: MSG TRACKING STATE 0x0016 message structure
Table 6.9.2: Tracking mode values (state[0:1])
38
Swift Navigation
Swift Navigation Binary Protocol
MSG EPHEMERIS — 0x001A
The ephemeris message returns a set of satellite orbit parameters that is used to calculate GPS satellite position, velocity, and clock offset (WGS84). Please see the Navstar GPS Space Segment/Navigation user interfaces (ICD-GPS-200, Table 20-III) for more details.
Offset (bytes)
Size (bytes)
Format
Units
Name
Description
0 8
8 8
double double
s m
tgd crs
16
8
double
m
crc
24
8
double
rad
cuc
32
8
double
rad
cus
40
8
double
rad
cic
48
8
double
rad
cis
56 64 72 80 88
8 8 8 8 8
double double double double double
rad/s radians mˆ(1/2) rad
dn m0 ecc sqrta omega0
96 104 112 120 128
8 8 8 8 8
double double double double double
rad/s rad rad rad/s s
omegadot w inc inc dot af0
136
8
double
s/s
af1
144
8
double
s/sˆ2
af2
152 160 162 170 172 173 174
8 2 8 2 1 1 1
double u16 double u16 u8 u8 u8
s week s week
toe tow toe wn toc tow toc wn valid healthy prn
Group delay differential between L1 and L2 Amplitude of the sine harmonic correction term to the orbit radius Amplitude of the cosine harmonic correction term to the orbit radius Amplitude of the cosine harmonic correction term to the argument of latitude Amplitude of the sine harmonic correction term to the argument of latitude Amplitude of the cosine harmonic correction term to the angle of inclination Amplitude of the sine harmonic correction term to the angle of inclination Mean motion difference Mean anomaly at reference time Eccentricity of satellite orbit Square root of the semi-major axis of orbit Longitude of ascending node of orbit plane at weekly epoch Rate of right ascension Argument of perigee Inclination Inclination first derivative Polynomial clock correction coefficient (clock bias) Polynomial clock correction coefficient (clock drift) Polynomial clock correction coefficient (rate of clock drift) Time of week Week number Clock reference time of week Clock reference week number Is valid? Satellite is healthy? PRN being tracked
175
Total Payload Length Table 6.9.3: MSG EPHEMERIS 0x001A message structure
Version 0.33, April 15, 2015
39
