Lib.rs

Swift二进制协议规范和绑定

• 安装sbp2json，json2sbp，json2json和相关工具
• 构建/安装
  • 使用Docker
    • 从DockerHub获取预构建镜像
    • 创建自己的镜像
    • 使用docker镜像
  • 通过包管理器安装
  • 安装开发Python版本
  • 将开发版本作为pip依赖项添加
  • 从源码安装
• SBP开发流程
• SBP协议规范
• JSON模式定义
• Kaitai结构格式描述
• 许可协议

Swift Navigation二进制协议（SBP）是一种快速、简单、最小化的二进制协议，用于与Swift设备通信。它是Piksi GPS接收器使用的本地二进制协议，用于传输解决方案、观测值、状态和调试消息，以及从主机操作系统接收消息，如差分校正和星历。

此项目为SBP使用的消息提供语言无关的规范和文档、用于生成消息绑定的编译器以及各种语言的客户端库。此存储库的组织结构如下：

• docs：协议文档和消息定义。
• spec：机器可读的YAML协议规范。
• generator：简单、基于模板的多种语言生成器。
• python：Python客户端和示例。
• c：C客户端库和示例。
• haskell：Haskell客户端和示例。
• java：Java客户端库和示例。
• javascript：JavaScript客户端库和示例。
• rust：Rust客户端库和示例。
• sbpjson：SBP-JSON解析工具。
• kaitai：Kaitai Struct格式描述和生成的代码。

除了generator之外，上述所有内容都是自动生成的，不应直接修改。

安装sbp2json，json2sbp，json2json和相关工具

此存储库还提供了以下工具，用于理解和检查SBP数据

• sbp2json：将SBP二进制数据转换为JSON表示，其中字段名称和值扩展为JSON对象，还包括常见的字段，如“消息类型”和“有效载荷”。

• json2sbp：使用SBP JSON流中的“消息类型”、“有效载荷”和相关字段来重建二进制表示。

• json2json：一些工具（特别是Swift GUI控制台）产生简化的JSON日志，只包含常见的字段，如“消息类型”和“有效载荷”，而json2json工具将这些JSON对象扩展以包括特定于单个消息的字段。

要安装这些工具的发布版本，请访问发布页面并下载适用于您平台的存档。

要从源代码安装，您可以使用Rust的cargo工具（首先安装Rust），然后运行

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

还有一个Haskell版本可用，可以通过在./haskell目录中运行stack install来安装（在安装stack之后）或通过访问发布页面下载一个sbp_tools_haskell存档。此工具版本的工具早于Rust和Python版本，还包括一个sbp2yaml工具以及一个sbp2prettyjson工具。

最后，存在一个Python版本的sbp2json工具，可以通过pip安装在任何支持Python的平台上。

pip3 install sbp

然后可以通过以下方式调用工具

python3 -m sbp2json <sbp.bin

Python版本的性能明显低于Rust和Haskell，但可以在Python本身支持的所有平台上运行。

构建/安装

开始之前，请在您的本地libsbp存储库中运行

git pull --tags

以获取标签。这将确保生成正确的版本号。

使用Docker

在开始之前，请确保您已安装Docker。启动Docker桌面。

从DockerHub获取预构建镜像

最快的方法是从DockerHub（无新鲜度保证）拉取预构建版本，只需在您的命令行中运行以下命令：

docker run --rm -v $PWD:/mnt/workspace -i -t swiftnav/libsbp-build:2023-12-19 /bin/bash

这将把您本地的libsbp仓库副本挂载到镜像上。

查看此链接获取较新的标签。或者，您也可以运行：

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

如果您在编译时遇到问题，并且标签已经过时。

创建自己的镜像

否则，Dockerfile将创建一个包含构建libsbp所需所有依赖项的Docker镜像。您可以通过运行以下docker build命令从该文件创建一个本地镜像：

docker build -t libsbp-build - <Dockerfile

从标准输入读取Dockerfile可以防止Docker将整个仓库拖入构建上下文（然后立即丢弃）。您可以通过将期望的UID值传递给构建来自定义由Docker镜像创建的用户UID。

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

然后您可以像这样使这个镜像在您的本地工作区上运行：

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

使用docker镜像

一旦进入镜像，只需键入make all即可生成所有libsbp绑定。这可能需要几个小时才能运行。或者，默认情况下，Docker镜像会运行make all命令，因此您只需运行以下命令即可启动make all过程：

docker run --rm -v $PWD:/mnt/workspace -i -t libsbp-build:2023-12-19

为了加快此过程，您可以在并行运行Python环境测试的同时尝试运行

docker run --rm -v $PWD:/mnt/workspace -i -t -e SBP_TOX_PARALLEL=auto libsbp-build:2023-12-19

完成工作后，请退出Docker，以便它不会不必要地占用您的机器资源。

如果在生成过程中遇到问题，请尝试运行make clean。或者，您可以在机器上从干净的、新克隆的libsbp仓库重新编译，这样可以最大限度地减少遇到旧构建的编译问题的可能性。

通过包管理器安装

一些绑定可以在包管理器上获得

• python：可在pip上获得
• haskell：可在Hackage上获得
• javascript：可在NPM上获得

安装开发Python版本

要从源代码安装Python绑定（使用pip），请运行以下命令

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

或通过setuptools直接运行

cd /path/to/libsbp
cd python
python setup.py

将开发版本作为pip依赖项添加

运行以下命令

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

或将此添加到requirements.txt

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

从源码安装

您可以一次构建一个绑定，或一次更新所有绑定

make python

或

make all

都是有效的。要查看所有有效目标的列表，请运行make help。

Python版本说明

1. 默认情况下，Python 目标 make python 和 make test-python（以及 make all）在由 libsbp Python 绑定官方支持的 3.6-3.9 所有 Python 版本上运行测试，跳过未安装的版本。要仅针对特定 Python 版本运行测试，请指定 TOXENV 环境变量，例如 TOXENV=py37 make python。Travis 在所有支持的版本上运行 Python 测试。
2. 默认情况下，代码生成器在系统（或虚拟环境）的默认 Python 解释器上运行。目前官方支持 Python 版本 2.7、3.5 和 3.7，其他版本可能无法正常工作。生成的 libsbp 绑定应在所有支持的 Python 版本上保持一致。要使用不同于默认 Python 解释器的不同版本，请指定 GENENV 环境变量，例如 GENENV=py27 make all（您必须先安装该版本的 Python）。
3. 要在特定 Python 版本上同时运行生成器和 Python 测试，请指定两个环境，例如 GENENV=py37 TOXENV=py37 make python

SBP开发流程

有关添加新消息、更新 文档 和发布此库新版本的说明，请参阅 “如何” 页面。

SBP协议规范

SBP 包含两部分：（i）一种基于网络的报文封装格式；（ii）结构化有效载荷定义。截至版本 1.0，数据包由一个 6 字节二进制头部部分、一个可变大小的有效载荷字段和一个 16 位 CRC 值组成。SBP 使用 CCITT CRC16（XMODEM 实现）进行错误检测。

有关数据包结构和消息类型的完整描述，请参阅 文档。特定于语言的 sbp 库的开发者文档在此 处。有关库及其消息演变情况的更多信息，请参阅 变更日志。

JSON模式定义

对于以 JSON 格式处理 SBP 的网络客户端，提供了 JSON 架构定义。由 QuickType 工具生成的 JavaScript、TypeScript 和 Elm 库。有关更新这些架构的说明，请参阅 HOWTO。

Kaitai结构格式描述

Kaitai Struct 是一种声明性语言，用于描述二进制数据结构。可以使用 kaitai 目标生成包含所有支持的 SBP 消息格式规范的 KSY 文件。生成的文件可以在 kaitai/ksy 目录中找到。此目标还运行 Kaitai Struct 编译器以生成 perl 和 python 的绑定。这些绑定（以及测试用例）可以在 kaitai/perl 和 kaitai/python 子目录中找到。

Kaitai Struct 格式描述文件还可能用于生成以下目标的绑定

• graphviz
• csharp
• rust
• java
• go
• cpp_stl
• php
• lua
• nim
• html
• ruby
• 构建
• JavaScript

Python 绑定说明

由 Kaitai Struct 编译器生成的 Python 绑定与 libsbp 中包含的基于 construct 的绑定相比，可以显著提高解析速度。然而，由于 Kaitai Struct 的特性，这些绑定不支持序列化（即构建 SBP 对象）。Java 和 Python 目标支持序列化作为 Kaitai Struct 开发版本中的实验性功能（> 0.10），因此希望将来能够取消此限制。

还应注意的是，KSY 绑定使用的名称与 construct 绑定不完全一致，这是由于 Kaitai Struct 对各种令牌类型施加的限制造成的（例如，字段名称中不允许使用大写字母）。可以在 kaitai/ksy/tests 目录中的测试用例（尤其是 test_parsers.py 中的测试用例）用作使用这些绑定以及展示每对绑定生成的输出之间微小差异的起点。

许可协议

版权所有 © 2015-2023 Swift Navigation

在 MIT 开源许可证下分发。