Repository files navigation

• Specification and Bindings for Swift Binary Protocol
  • Installing sbp2json, json2sbp, json2json and related tools
  • Building / installing
    • Using Docker
      • Fetching the prebuilt image from DockerHub
      • Creating your own image
      • Using the docker image
    • Installing from package managers
    • Installing development Python versions
    • Adding development version as a pip dependency
    • Installing from source
  • SBP Development Procedures
  • SBP Protocol Specification
  • JSON Schema Definitions
  • Kaitai Struct Format Descriptions
    • Notes on python bindings
  • LICENSE

The Swift Navigation Binary Protocol (SBP) is a fast, simple, and minimalbinary protocol for communicating with Swift devices. It is the native binaryprotocol used by thePiksi GPS receiver totransmit solutions, observations, status and debugging messages, as well asreceive messages from the host operating system, such as differentialcorrections and the almanac.

This project provides language-agnostic specification and documentation formessages used with SBP, a compiler for generating message bindings, and clientlibraries in a variety of languages. This repository is organized into thefollowing directory structure:

• docs: Protocol documentation and message definitions.
• spec: Machine readable protocol specification inYAML.
• generator: Simple, template-based generator fordifferent languages.
• python: Python client and examples.
• c: C client library and examples.
• haskell: Haskell client and examples.
• java: Java client library and examples.
• javascript: JavaScript client library and examples.
• rust: Rust client library and examples.
• sbpjson: Tools for parsing SBP-JSON.
• kaitai: Kaitai Struct Format Description and generated code.

Except for thegenerator, all of the above are generated and should not be modified directly.

This repository also provides the following utilities for comprehending andinspecting SBP data:

• sbp2json: converts SBP binary into a JSON representation, in which fieldnames and values are expanded into JSON objects, common fields such as"message type" and "payload" are included as well.

• json2sbp: uses the "message type", "payload" and related fields from an SBPJSON stream to reconstruct the binary representation.

• json2json: some tools (notably the Swift GUI Console) produce abbreviatedJSON logs with only common fields such as "message type" and "payload", thejson2json tool expands these JSON objects to include fields specific theindividual message.

To install a released version of these tools, visit thereleasespage and download an archive foryour platform.

To install from source, you can use Rust's cargo tool (firstinstallRust), then run:

cargo install --git https://github.com/swift-nav/libsbp.git --bins

There's also aHaskell version available which can be installed byrunningstack install in the./haskell directory of a checkoutof this repo (afterinstallingstack) or by visiting thereleases by and downloading ansbp_tools_haskell archive. This variant ofthe tools predate the Rust and Python versions, and also includes ansbp2yamltool as well as asbp2prettyjson tool.

Finally, a Python version of thesbp2json tool exists, which is installableon any platform that supports Python via pip, e.g.:

pip3 install sbp

The tool can then be invoked as follows:

python3 -m sbp2json<sbp.bin

The performance of the Python version is significantly slower than Rust and Haskell,but works on all platforms that Python itself supports.

Before you start, run

git pull --tags

in you local libsbp repository to pull the tags. This will ensure the correctversion number is generated.

Before you begin, make sure you haveDocker installed.StartDocker desktop.

The quickest method to get going is to just pull a prebuilt copy from DockerHub(no guarantees on freshness) by running the following on your command line:

docker run --rm -v$PWD:/mnt/workspace -i -t swiftnav/libsbp-build:2025-02-10 /bin/bash

This will mount your local copy of the libsbp repository onto the image.

Check libsbp-builddockerhub page for newer tags.Alternatively, you could run

docker run --rm -v$PWD:/mnt/workspace -i -t swiftnav/libsbp-build:latest-master /bin/bash

if you are facing issues with compilation and the tags are out of date as well.

Otherwise, theDockerfile will create a docker image that contains all thenecessary dependencies to build libsbp. You can make a local image fresh fromthis file by runningdocker build as such:

docker build -t libsbp-build -<Dockerfile

Reading the Dockerfile from STDIN prevents docker from pulling in the wholerepostory into the build context (which is then immediately discarded anyway).You can customize the UID of the user that's created with the docker imageby passing the desiredUID value to the build:

    docker build -t libsbp-build --build-arg UID=1234 -<Dockerfile

You can then make this image operate on your local workspace like this:

docker run --rm -v$PWD:/mnt/workspace -i -t libsbp-build:latest /bin/bash

Once in the image, to overcome issues with git trying to determine ownership ofthe repository, rungit config --global --add safe.directory /mnt/workspace.Then, simply typemake all to generate all the libsbp bindings.This could take several hours to run. Alternately, the docker image will runthemake all command by default, so you can kick off themake all processby simply running the following command:

docker run --rm -v$PWD:/mnt/workspace -i -t libsbp-build:2025-02-10

To speed up this process you can attempt to run Python environment tests inparalell with:

docker run --rm -v$PWD:/mnt/workspace -i -t -e SBP_TOX_PARALLEL=auto libsbp-build:2025-02-10

When you are finished, quit Docker so that it would not unnecessarily use upresources on your machine.

If you run into issues during the generation process, try runningmake clean.Alternatively, you could recompile from a clean, newly-cloned libsbp repositoryon your machine, which would minimize the chance of running into compilationissues from an old build.

Some bindings are available on package managers:

• python: available on pip
• haskell: available on Hackage
• javascript: available on NPM

To install the Python binding from source (using pip) run the following command:

pip install'file:///path/to/libsbp#subdirectory=python'

Or via setuptools directly:

cd /path/to/libsbpcd pythonpython setup.py

Run the following command:

pip install"git+https://github.com/swift-nav/libsbp@<GIT_REVISION>#egg=sbp&subdirectory=python"

Or add this torequirements.txt:

git+https://github.com/swift-nav/libsbp@<GIT_REVISION>#egg=sbp&subdirectory=python

You can build one binding at a time or update all at once:

make python

or

make all

are both valid. To see a list of all valid targets, runmake help.

Python version notes:

1. By default the Python targetsmake python andmake test-python (as wellasmake all) run tests on all Python versions officially supported bythelibsbp Python bindings, currently3.6-3.9, skipping any versions notinstalled. To run tests on just specific Python version(s), specify theTOXENV environment variable, e.g.,TOXENV=py37 make python. Travis runsPython tests on all supported versions.
2. By defaultthe code generators are run on the system's (or virtual env's)default Python interpreter. Currently Python versions2.7, 3.5, and 3.7are officially supported, other versions may or may not work. The generatedlibsbp bindings should be the same on all supported Python versions. To usea different version than your default Python interpreter, specify theGENENV environment variable, e.g.,GENENV=py27 make all (you must havethat version of Python installed beforehand).
3. To run both the generator and the Python tests on specific Python versions,specify both envs, e.g.,GENENV=py37 TOXENV=py37 make python

See the"how to" page for instructions on adding new messages,updating thedocumentation, and releasing new versions of thislibrary.

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 ofa 6-byte binary header section, a variable-sized payload field, and a 16-bitCRC value. SBP uses the CCITT CRC16 (XMODEM implementation) for errordetection.

Please seethe docs for a full description of the packetstructure and the message types. Developer documentation for thelanguage-specific sbp libraries is available athttp://swift-nav.github.io/libsbp/.Please refer tothe changelog for more information about theevolution of the library and its messages.

For web clients processing SBP in JSON form, JSON schema definitions areprovided. Libraries for JavaScript, TypeScript, and Elm generated by theQuickType tool are provided. See theHOWTO for instructions on updating these schemas.

Kaitai Struct is a declarative language used to describebinary data structures. KSY files containing format specifications for allsupported SBP messages can be generated using thekaitai target. Theresulting files can be found in thekaitai/ksy directory.This target also runs the Kaitai Struct compiler to generate bindings forperl and python. These bindings (along with test cases) can be found in thekaitai/perl andkaitai/python subdirectoriesrespectively.

The Kaitai Struct format description files can also potentially be used togenerate bindings for the following targets:

• graphviz
• csharp
• rust
• java
• go
• cpp_stl
• php
• lua
• nim
• html
• ruby
• construct
• javascript

The python bindings generated by the Kaitai Struct compiler allow forsignificantly faster parsing in comparison to the construct-based bindingsincluded in libsbp. However, due to the nature of Kaitai Struct, thesebindings do not allow for serialisation (i.e. construction of SBP objects).Serialisation for java and python targets is supported as an experimentalfeature in the development version of Kaitai Struct (> 0.10) so thisrestriction should hopefully be removed in the future.

It should also be noted that the names used by the KSY bindings are not 1:1identical to the construct bindings due constraints which Kaitai Struct placeson various token types (e.g. it is forbidden to use upper case characters infield names). The test cases in thekaitai/ksy/tests directory(particularly those intest_parsers.py) can be used as a starting point forworking with these bindings, as well as demonstrating the minor differencesbetween the output generated by each set of bindings.

Copyright © 2015-2023 Swift Navigation

Distributed under theMIT open source license.