Metadata-Version: 2.4
Name: gse-gsatmicro-mgr
Version: 5.5.1
Summary: Tools for interacting with GSatMicro Core products
Project-URL: homepage, https://www.gsat.us
Author-email: Bogdan Marinescu <bogdan@gsat.us>
License-File: LICENSE.md
Requires-Python: >=3.10
Requires-Dist: cbor2>=5.6.5
Requires-Dist: click>=8.1.0
Requires-Dist: crc>=7.0.0
Requires-Dist: flask>=3.1.0
Requires-Dist: gse-gsatmicro-utils>=3.1.0
Requires-Dist: prettytable>=3.11.0
Requires-Dist: pyftpdlib>=2.0.1
Requires-Dist: python-minifier>=2.11.3
Requires-Dist: tqdm>=4.66.6
Description-Content-Type: text/markdown

- [Overview](#overview)
- [Supported operating systems](#supported-operating-systems)
- [Installation](#installation)
- [Updating gsemgr](#updating-gsemgr)
- [gsemgr commands](#gsemgr-commands)
  - [gsemgr list](#gsemgr-list)
  - [gsemgr reset](#gsemgr-reset)
  - [gsemgr version](#gsemgr-version)
  - [gsemgr file](#gsemgr-file)
    - [gsemgr file upload](#gsemgr-file-upload)
    - [gsemgr file download](#gsemgr-file-download)
    - [gsemgr file rm](#gsemgr-file-rm)
    - [gsemgr file cat](#gsemgr-file-cat)
  - [gsemgr image](#gsemgr-image)
  - [gsemgr logs](#gsemgr-logs)
  - [gsemgr console](#gsemgr-console)
  - [gsemgr prop get](#gsemgr-prop-get)
  - [gsemgr prop set](#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](https://www.gsat.us):

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

Support is available at support@gsat.us

# 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](https://pypi.org/project/pip/) and [virtualenv](https://virtualenv.pypa.io/en/latest/) before installing `gsemgr`.

Python can be be installed from [python.org](https://www.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](https://brew.sh/) 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-commands).

## 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
```