The Sora Device Client provides a set of tools to connect your GNSS device to Sora.
The Sora Device Client consists of:
- A command-line client - the simplest way to connect to Sora
- A Python client library - for deeper integration and customization
You should only need to follow these steps once per machine you are setting up to run the sora-device-client on.
You will most likely need a package manager to install the other dependencies. Use the one that is canonical for your distribution, for example: apt
, dnf
, yum
, pacman
.
For macOS, it is recommend to use homebrew. For windows, something like chocolately will do.
You need to install Python. Versions 3.8 - 3.11 are supported. See https://www.python.org/downloads/ for download instructions. On macOS, you can use homebrew as well:
brew install [email protected]
pip install sora-device-client
See DEVELOPMENT.md for info on installing from source / CI build.
Copy the default config file to the appropriate location. sora
will tell you where it should go:
sora paths
# Example output:
# Configuration folder: (your config.toml needs to go in here)
# /home/jwhitaker/.config/sora-device-client
#
# Data folder: (other runtime data gets stored in here)
# /home/jwhitaker/.local/share/sora-device-client
sora
will also give you an example configuration:
sora example-config
# ==============================================================================
# Sora Device Client configuration
# ==============================================================================
#
# ...
#
Putting them together, you can set up a config file in the right location, and edit it:
mkdir -p /home/jwhitaker/.config/sora-device-client/ # (configuration folder from `sora paths`)
sora example-config > /home/jwhitaker/.config/sora-device-client/config.toml
notepad /home/jwhitaker/.config/sora-device-client/config.toml # or whatever
You will most likely have to edit the [location.driver]
section to work with the location source for your system.
If you are connecting to a GNSS location source over the network, it will be something like:
[location.driver.tcp]
host = "localhost"
port = 55555
However if you are connecting over a serial or USB port:
[location.driver.serial]
port = "/dev/tty.usbmodem14401"
baud = 115200
The value of port
will be highly hardware specific. Some values that are known to have worked are: /dev/ttyACM0
, /dev/ttyUSB0
, /dev/tty.usbmodem14401
.
If you have Swift hardware and have installed the Swift Console: https://support.swiftnav.com/support/solutions/articles/44001903699-installing-swift-console, the value used to connect it to your swift device will work.
Also note that sometimes non privileged users do not have permission to read and write to the device. The easiest way to obtain these permissions is to add your user to the group of the device. For example if it is /dev/ttyACM0
, the group to add yourself to may be obtained with:
stat -c "%G" /dev/ttyACM0
See here for how to add a user to a group on Linux. You may need to log out of and log in to the operating system session again. On macOS and Windows, the instructions are too varied to list here. Please research how to do this for your combination of OS and OS version.
Once installed, the `sora` command will be in the path:
```bash
sora --help
To authenticate with a sora server, run
sora login
and follow the interactive procedure. You will need access to a web browser.
After authentication, you can stream data to the sora server with
sora --verbose start
If you wish to use a difference set of credentials on the same hardware, you can clear them with
sora logout
There is also a data file called data.toml
that is used to store data that is generated by sora login
. Typically, running sora logout
will clear this file.
If you need to manually remove it, its location is is the Data path
location from the output of
sora paths
The Sora Device Client works with Swift Navigation receivers and Starling Position Engine software using data in SBP protocol. Refer to the receiver-specific manual to configure your receiver:
The device client uses the following SBP messages:
Message Name | Message ID (decimal) | Description |
---|---|---|
POS LLH |
522 | Position (latitude, longitude, altitude) |
ORIENT EULER |
545 | Orientation (roll, pitch, yaw) Using this message is optional Message is available only in products with inertial fusion enabled |
Download Swift Binary Protocol Specification
Piksi Multi and Duro configuration can be changed using Swift Console program. TCP Server 1
settings example:
Note: Click SAVE TO DEVICE button to memorize settings over the power cycle.
Starling configuration is saved in the yaml configuration file. TCP server
output example:
...
outputs:
- name: sbp-sora
protocol: sbp
type: tcp-server
port: 55556
max-conns: 4
sbp:
enabled-messages: [ 522,545 ]
...
Support requests can be made by filling the Support Request Form on the Swift Navigation Support page (Support Request Form button is at the bottom of the page). A simple login is required to confirm your email address.