Swift Navigation provides command line utilities both in the form of Python 3 scripts or Windows executables for common receiver tasks through its open source “piksi_tools” Python library. This library is available on Github at the following address: https://github.com/swift-nav/piksi_tools.
Prerequisites
- Familiarity with installation of Python 3
- Familiarity with command line utilities on your operating system
Compatibility
Piksi Tools can operate on the following platforms:
- Linux with glibc 2.17 - x86_64, i686 or aarch64
- Linux with musl 1.1 - x86_64, i686 or aarch64
- macOS 10.9 or later for x86_64 or macOS 11 or later for arm64
- Windows 7 or later - i686 or x86_64
Installing Piksi Tools command line utilities
It is necessary to install the Piksi Tools command line utilities through one of the methods described below.
Installing binary tools (Windows only):
The most useful piksi_tools scripts are released as binary tools for users who may be unfamiliar with Python. These tools are distributed on Swift’s website at the following address currently only for Windows users: Piksi Tools Windows Binaries.
The package includes settings.py, fileio.py, bootload_v3.py, serial_link.py, and interpolate_event_positions.py, the function of each of which are described in this document.
To install these tools:
- Download the zip file Piksi Tools Windows Binaries.
- Extract it
- Place the binary .exe files in a logical place in your system path
- Swift suggests placing the tools in a c:/Program Files(x86)/piksi_tools directory and adding this directory to your PATH environment variable. For instructions in appending to the PATH variable, see this article: https://www.howtogeek.com/118594/how-to-edit-your-system-path-for-easy-command-line-access/
Installing Piksi Tools with pip
The easiest way to retrieve piksi_tools functionality from source is to fetch the tools from the Python package repository, pip. For best results, it may be useful to do the installation in a virtual environment if you are familiar with using them. Installation should be as simple as typing
pip install piksi_tools
provided your Python installation supports pip.
Using settings tool
The settings tool (settings.py for those using Python or settings.exe if the executables were installed) can be used to read and write settings messages to configure devices. The command line help is repeated below for completeness:
Usage:
settings.py [-h] [-p PORT] [-b BAUD] [--rtscts] [-v] [-f] [-l] [-r]
[-o LOG_DIRNAME] [--logfilename LOGFILENAME]
[-a APPEND_LOG_FILENAME] [--file] [-d TAGS] [-t]
[--expand-json] [--timeout TIMEOUT] [-s]
{save,reset,read,all,write,read_to_file,write_from_file}
...
Piksi Settings Tool
positional arguments:
{save,reset,read,all,write,read_to_file,write_from_file}
save save all the current settings to flash.
reset reset the device after the action.
read read the current setting.
all read all the settings.
write write the current setting.
read_to_file read the current settings file from device.
write_from_file write settings file to device.
optional arguments:
-h, --help show this help message and exit
-p PORT, --port PORT specify the serial port to use.
-b BAUD, --baud BAUD specify the baud rate to use.
--rtscts Enable Hardware Flow Control (RTS/CTS).
-v, --verbose print extra debugging information.
-f, --ftdi use pylibftdi instead of pyserial.
-l, --log serialize SBP messages to autogenerated log file.
-r, --reset reset device after connection.
-o LOG_DIRNAME, --log-dirname LOG_DIRNAME
directory in which to create logfile.
--logfilename LOGFILENAME
filename to use for log. Default filename with date
and timestamp is used otherwise.
-a APPEND_LOG_FILENAME, --append-log-filename APPEND_LOG_FILENAME
file to append log output to.
--file Read with a filedriver rather than pyserial.
-d TAGS, --tags TAGS tags to decorate logs with.
-t, --tcp Use a TCP connection instead of a local serial port.
If TCP is selected, the port is interpreted as
host:port
--expand-json Expand fields in JSON logs
--timeout TIMEOUT specify the timeout for settings reads.
-s, --save_after_write
Save settings to flash after successful write or
write_from_file
Returns:
0: Upon success
1: Runtime error or invalid settings request.
2: Improper usage
Settings examples:
In the following section, a few examples are shown for using the settings tool. For each example, the first command line string refers to the invocation if running from the distributed executables, while the second shows the the method of invoking from Python.
Read all device settings to standard out from serial COM3
You can invoke the tool to read all the settings to standard output by the following command line strings:
Binary Installation: settings -p COM3 all
Python: python -m piksi_tools.settings -p COM3 all
Read all device settings to a file from default Ethernet address
Binary Installation: settings -t -p 192.168.0.222:5555 read_to_file CONFIG.ini
Python: python -m piksi_tools.settings -t -p 192.168.0.222:55555 read_to_file CONFIG.ini
Write an individual setting from COM3
Binary Installation: settings -p COM3 write ethernet ip_address 192.168.0.223
Python: python -m piksi_tools.settings -p COM3 write ethernet ip_address 192.168.0.223
Write an ini file to device via COM3
Note, the ini file should only contain settings that are intended to be changed and any read-only settings, if the ini file was saved from a different device, should be removed. It is suggested that the “system_info” grouping be removed completely from any .ini file that is to be sent to a device for best results. Similarly, ini files that were saved with different firmware versions may include settings that do not exist on the target firmware version. In that case, the write_from_file command may fail which may require adjustment of the CONFIG.INI file to reflect the target firmware being used. There shall be no silent failures of the write_from_file command.
Binary Installation: settings -p COM3 write_from_file CONFIG.INI
Python: python -m piksi_tools.settings -COM3 write_from_file CONFIG.INI
Save settings to device flash
The individual “save” commands or the write_from_file commands do not write any settings to persistent storage. For settings to persist across device resets, a settings save command must be sent. This is akin to pressing the “save to flash” button in the Swift console.
Binary Installation: settings -p COM3 save
Python: python -m piksi_tools.settings -COM3 save
Using bootload_v3 tool
The bootload_v3 tool allows users to update firmware on a device via the SBP protocol. It is recommended to run this tool through the Ethernet or the micro usb interface to the device. While possible, invoking the tool over a serial port at 115200 baud can take a very long time to complete. The usage string for this tool is below.
Usage:
bootload_v3.py [-h] [-p PORT] [-b BAUD] [--rtscts] [-v] [-f] [-l] [-r]
[-o LOG_DIRNAME] [--logfilename LOGFILENAME]
[-a APPEND_LOG_FILENAME] [--file] [-d TAGS] [-t]
[--expand-json]
file
Piksi Bootloader
positional arguments:
file the image set file to write to flash.
optional arguments:
-h, --help show this help message and exit
-p PORT, --port PORT specify the serial port to use.
-b BAUD, --baud BAUD specify the baud rate to use.
--rtscts Enable Hardware Flow Control (RTS/CTS).
-v, --verbose print extra debugging information.
-f, --ftdi use pylibftdi instead of pyserial.
-l, --log serialize SBP messages to autogenerated log file.
-r, --reset reset device after connection.
-o LOG_DIRNAME, --log-dirname LOG_DIRNAME
directory in which to create logfile.
--logfilename LOGFILENAME
filename to use for log. Default filename with date
and timestamp is used otherwise.
-a APPEND_LOG_FILENAME, --append-log-filename APPEND_LOG_FILENAME
file to append log output to.
--file Read with a filedriver rather than pyserial.
-d TAGS, --tags TAGS tags to decorate logs with.
-t, --tcp Use a TCP connection instead of a local serial port.
If TCP is selected, the port is interpreted as
host:port
--expand-json Expand fields in JSON logs
Upgrade device over Ethernet example
Binary Installation: bootload_v3 -t -p 192.168.0.222:55555 PiksiMulti-v2.1.14.bin
Python: python -m piksi_tools.bootload_v3 -t -p 192.168.0.222:55555 PiksiMulti-v2.1.14.bin
Serial_link utility
The serial link utility allows command line logging with the same methods used by the Swift Console Software. Refer to its command line help utility (by invoking with a -h argument) for more information.
Interpolate_event_positions
The interpolate event positions tool allows users to determine position or velocity when an external event was triggered in a log file. Refer to its command line help utility (by invoking with a -h argument) for more information.
fileio
The fileio tool allows users to write individual files on the Swift Navigation device. In fact, this is used under the hood during the firmware upgrade procedure. One use case for the fileio tool is to write the “config.ini” file to the Swift Navigation Receiver in a one-shot fashion, which can be useful if you would like to change the settings for the communication interface over which you are currently communicating (for instance, if you would like to change the ethernet settings over ethernet). The example below shows how one could write a configuration file to the /persistent partition on the device. Not all portions of the file system will be available to read and write on the device for security reasons.
Note: For the tool to work you may need to add message IDs 168,169,170,173 to the enabled_sbp_messages for the communication port you're using (typically TCP server 0).
Binary Installation: fileio --tcp -p 192.168.0.222:55555 -w config.ini /persistent/config.ini
Python: python -m piksi_tools.fileio --tcp -p 192.168.0.222:55555 -w config.ini /persistent/config.ini