gse-gsatmicro-mgr 5.5.1

Tools for interacting with GSatMicro Core products

• Overview
• Supported operating systems
• Installation
• Updating gsemgr
• gsemgr commands
  • gsemgr list
  • gsemgr reset
  • gsemgr version
  • gsemgr file
    • gsemgr file upload
    • gsemgr file download
    • gsemgr file rm
    • gsemgr file cat
  • gsemgr image
  • gsemgr logs
  • gsemgr console
  • gsemgr prop get
  • gsemgr prop set

Overview

This package provides the gsemgr command line tool. gsemgr is a tool for interacting with GSatMicro Core series of products from GSE:

• Multi-core firmware updates.
• Remote file management.
• Read/write properties.

Support is available at [e-mail]

Supported operating systems

To use gsemgr, you need to connect your GSatMicro to a computer with an USB cable. The computer should run one of the supported operating systems:

• Windows 10 or 11.
• macOS 15 or 26.
• Linux: Ubuntu 24.04 or newer.

Older or newer versions of Windows, nacOS or Linux (including other distros) are likely to work too, but only the versions above were tested.

Installation

You need to install [Python][https://www.python.org/] 3.10 or higher, pip and virtualenv before installing gsemgr.

Python can be be installed from python.org. This is the recommended installation method in Windows. For Linux, using the distro's package manager might be preferable because it also provides upgrades, but only if the distro has a compatible Python version. On macOS, Homebrew is a popular option. Note that Homebrew works in Linux too and can generally install newer Python versions than the ones in the distro's package repository.

No matter what installation method you choose, make sure that the Python executable is in your system path. To check this:

• Open a shell (cmd or powershell in Windows, bash or similar in Linux/macOS).
• Type python3 --version. Python should display its version.
• Check if the reported version is at least 3.10.

Since pip is bundled with Python, the procedure above will also install pip.

To check if virtualenv is installed, run python3 -c "import venv". If the command finishes without errors, virtualenv is installed. Otherwise, install it using python3 -m pip install virtualenv.

After all the prerequisites above are installed, install gsemgr in a virtual environment from your shell:

$ python3 -m venv v-gsemgr

# If you're using Linux or macOS, run the command below to activate the virtual environment
$ source ./v-gsemgr/bin/activate

# If you're using Windows with cmd.exe, run the command below to activate the virtual environment
> .\v-gsemgr\Scripts\activate.bat

# If you're using Windows with PowerShell, run the command below to activate the virtual environment
> .\v-gsemgr\Scripts\Activate.ps1

# Install gsemgr after the virtual environment is activated
$ pip install gse-gsatmicro-mgr

# Check that the installation succeeded
$ gsemgr version

You will have to activate this virtual environment each time you need to use gsemgr from a new shell.

Note that v-gsemgr above is just an example, you can give the virtual environment any name you want.

Updating gsemgr

Follow the procedure below to update gsemgr to the latest version:

• Activate the virtual environment (as explained in the previous paragraph).
• Run pip install -U gse-gsatmicro-mgr

gsemgr commands

gsemgr implements a number of subcommands for various interactions with GSatCore devices:

• gsemsg --help lists all the available commands and other command line options.
• gsemgr <command> runs the specified commad.
• gsemgr --wait <command> waits for a GSatCore device to be connected to the PC and then runs the specified commad.
• gsemgr --sernum <serial> <command> executes the command on the GSatCore device with the given serial number (see also gsemgr devices below).
• gsemgr <command> --help displays specific usage instructions for the given command.

The command line options above can be combined. For example, use gsemgr --sernum <serial> --wait to wait for a specific device to be connected to the PC.

gsemgr list

This command lists all the GSatCore devices connected to the PC and their respective serial ports. Each GSatCore device enumerates 3 serial ports on USB:

• The logs port: all device logs are sent to this port (see also gsemgr logs below).
• The console port: this port can be used to interact with the MicroPython REPL on the device (see also gsemgr console below).
• The management (mgmt) port: used by gsemgr to communicate with the device.

Each GSatCore device has its own unique serial number, which is also displayed by this command. To limit command execution to a device with a specific serial number, use the --sernum command line option as explained above.

gsemgr reset

Resets the GSatMicro device. Note that this command executes a soft (firmware only) reset, not a full reset. For a full reset, press and release the dedicated reset switch or disconnect and reconnect power to the device.

gsemgr version

Displays the installed version of gsemgr.

gsemgr file

This command is used to manipulate files on the device and is divided into further subcommands.

NOTE: keep in mind that the total size of the file system is around 4MB-6MB, so you won't be able to upload very large files to the device.

gsemgr file upload

Use this command to upload a file from the PC to the device:

$ gsemgr file upload -o /lfs/<name_on_device> <path_to_local_file>

• /lfs is the root path of the file system mounted on the device. It is a mandatory prefix for all device-relative paths.
• name_on_device is the name of the uploaded file on the device (which might be different from its local name).
• path_to_local_file is the path to the local (uploaded) file.

For example, to upload a file named hello.py in the current directory on the PC to the device and rename it main.py, run this command:

$ gsemgr file upload -o /lfs/main.py hello.py

The main purpose of upload is to send Python code to the device, but you can upload any kind of file.

There are two "special" device file names:

• /lfs/main.py: if found and if it is a valid Python source file, the code in the main function from this file will be executed automatically on startup.
• /lfs/runonce.py: if found and if it is a valid Python source file, the code in the main function from this file will be executed automatically on startup and the file will be automatically deleted after main() returns.

If both files are present in the file system, main from /lfs/runonce.py is executed first (and then /lfs/runonce.py is removed), followed by the main from /lfs/main.py.

gsemgr file download

Use this command to download a file from the device to the PC:

$ gsemgr file download -o <path_to_local_file> /lfs/<name_on_device>

• /lfs is the root path of the file system mounted on the device. It is a mandatory prefix for all device-relative paths.
• path_to_local_file is the path to the local (downloaded) file.
• name_on_device is the name of the downloaded file (which might be different from its local name).

For example, to download /lfs/main.py from the device to the PC and rename it to hello.py, run this command:

$ gsemgr file download -o hello.py /lfs/main.py

Note that this command will fail if a file with the same name as <path_to_local_file> exists on the PC. To overwrite existing files on the PC, add the --overwrite flag to the command.

gsemgr file rm

Use this command to remove files or emptry directories from the device:

$ gsemgr file rm /lfs/<name_on_device>

• /lfs is the root path of the file system mounted on the device. It is a mandatory prefix for all device-relative paths.
• name_on_device is the name of the file or empty directory that will be deleted on the device.

gsemgr file cat

Use this command to display the content of a file on the device. Since the file content is displaed on the console, the command should be used only for text files.

$ gsemgr file cat /lfs/<name_on_device>

• /lfs is the root path of the file system mounted on the device. It is a mandatory prefix for all device-relative paths.
• name_on_device is the name of the file on the device.

The command is equivalent to running gsemgr file download -o <downloaded_file> /lfs/<name_on_device> followed by cat <downloaded_file>.

gsemgr image

Use this command to manage firmware images. This command also has a number of subcommands. The most important one is gsemgr image upload, which is used for updating the device firmware:

$ gsemgr image upload -a <app_core_image> -n <net_core_image> --reset

• app_core_image is the binary firmware image of the application core.
• net_core_image is the binary firmware image of the network core.
• --reset is optional, but a reset is required to activate a firmware image that was uploaded with gsemgr image upload, so using --reset with this command is recommended.

Either app_core_image or net_core_image can be omitted, but not both.

After the device resets, the bootloader needs to update the firmware image(s), a process that takes a few tens of seconds. Use gsemgr --wait list to wait for the device to reboot into the new firmware.

gsemgr logs

Use this command to observe the logging output of the device in real time.

Use either CTRL+D or CTRL+Z as instructed to terminate the command.

If the device is reset or disconnected, the command terminates automatically. If this is not the desired behavior, use the --watch-serial flag to instruct gsemgr to wait for the logs port to become available again and connect to it automatically when it does.

gsemgr console

Use this command to connect to the console port of the device. You can use this port to interact with the integrated MicroPython REPL (type and execute Python code directly on the device). This port also displays the output of print and other similar non-logging console output functions.

Use either CTRL+D or CTRL+Z as instructed to terminate the command.

If the device is reset or disconnected, the command terminates automatically. If this is not the desired behavior, use the --watch-serial flag to instruct gsemgr to wait for the console port to become available again and connect to it automatically when it does.

NOTE: the device manages serial ports dynamically. If you run gsemgr console witout also running gsemgr logs, the device automatically redirects logging output to the console port, since this is the only port visible to the user. To keep console output and logging output separate, run gsemgr logs in a separate shell.

gsemgr prop get

Use this command to retrieve the properties of one or mode modules. A property is a configuration option for a module (for example the GPS driver or the GSM driver). It has a type (string, integer or floating point number), a default value, a current value and optional type specific constraints for the value (for example minimum and maximum values for an integer property).

gsemgr prop get can be invoked in 3 ways:

• gsemgr prop get reads and displays the properties of all modules.
• gsemgr prop get <module> reads and displays only the properties of the given module.
• gsemgr prop get <module> <property> reads and display only the value of the given property of the given module.

For example, to return all properties of the user module (which is by convention used by the user application running on the device):

$ gsemgr prop get user
+--------+--------------------+------+-----+-----+---------+-------+
| Module | Name               | Type | Min | Max | Default | Value |
+--------+--------------------+------+-----+-----+---------+-------+
| user   | max_fix_time       | int  | 5   | -   | 600     | 600   |
| user   | min_accuracy       | int  | 1   | 100 | 20      | 20    |
| user   | reporting_interval | int  | 5   | -   | 30      | 600   |
+--------+--------------------+------+-----+-----+---------+-------+

gsemgr prop set

Use this command to set the value of a property in a module:

$ gsemgr prop set <module> <property> <value>

Note that the value must match the type of the property and its optional value constraints.

For example, to change the value of the reporting_interval property in the user module to 120, use this command:

$ gsemgr prop set user reporting_interval 120