Swift Navigation provides command line utilities both in the form of Python 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
  • Familiarity with command line utilities on your operating system

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:

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.


Installing Piksi Tools from source

If you have interest in modifying or changing the behavior of the scripts, it may be useful to run the scripts from source.  This is only recommended for users familiar with Github and Python development. The best way to do this is to use run the following commands:

git clone https://github.com/swift-nav/piksi_tools.git

cd piksi_tools

pip install -e ./


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:5555 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