Using an MQTT Client

Any MQTT client can be used to receive messages with signal quality measurements as they are generated. This is useful for verifying that the system is working properly before starting a measurement session.

Below are some recommended MQTT clients for different platforms:

Linux

Mosquitto — command-line client.
MQTT Explorer — graphical user interface.

Windows

MQTT Explorer — graphical user interface.

Android

My MQTT

iPhone

Do you have a favorite? Let us know and we’ll include it!

Using the SorusBoxScan SDK

The SorusBoxScan Python SDK provides tools and libraries to help you develop applications for 5G-enabled drones.

Features

Easy integration with 5G drones
Real-time data streaming
Advanced drone control APIs
Comprehensive documentation (in progress)

Prerequisites

A system with Python installed
A virtual environment is recommended for running your project
The SDK is hosted in a private repository, so you need an authenticated Git session. Username/password prompts will not work on GitHub.

Setting up a Virtual Environment

On Linux, Mac OS or similar

python -m venv .venv
source .venv/bin/activate

On Windows, using CMD

python -m venv .venv
.\.venv\Scripts\activate.bat

On Windows, using PowerShell

python -m venv .venv
.\.venv\Scripts\activate.ps1

On Windows’ UNIX-like shells (e.g. Git Bash CLI)

python -m venv .venv
source .venv/Scripts/activate

Authenticating with GitHub

Install GitHub CLI:In Linux debian-based systems:
```
sudo apt-get update
sudo apt-get install gh
```
In Windows:
```
winget install --id GitHub.cli
```
Or go to the GitHub CLI download page.
Authenticate GitHub CLI:
```
gh auth login
```
Follow the prompts to authenticate:
- Select GitHub.com.
- Choose HTTPS as the preferred protocol.
- Authenticate with your preferred method (browser or token).

Now your Git session is authenticated for GitHub on both Linux and Windows using the GitHub CLI.

You can now use git on GitHub’s private repositories you have access to just like if they were public.

Installation

To install the SDK:

pip install git+https://github.com/aferre88/5gdrone-sdk

If your project has a requirements.txt, you can run pip freeze > requirements.txt to pin the dependency.

Update

To upgrade the SDK to the latest version:

pip install git+https://github.com/aferre88/5gdrone-sdk -U

Usage

Here’s a basic example to get started. You can use this as a template:

"""
This is an example of how to use the FiveGDroneSDK class to subscribe to the signals topic.
"""

from fivegdrone_sdk import FiveGDroneSDK

# Environment variables
MQTT_BROKER = "mqtt.eclipse.org"
MQTT_USERNAME = "username"
MQTT_PASSWORD = "password"
MQTT_PORT = 1883

# Create a new instance of the SDK
hat = FiveGDroneSDK(MQTT_BROKER, MQTT_PORT, MQTT_USERNAME, MQTT_PASSWORD)


# The @hat.signals decorator is used to subscribe to the signals topic
# The signal_printer function will be called every time a signal is received
# The signal object is passed as an argument to the function
@hat.signals
def signal_printer(signal):
    """
    In this example, all the attributes of the signal object are printed,
    but you can modify the function to do whatever you want with the signal.

    E.g. if you only need the rssi attribute, you can modify the function like this:

    @hat.signals
    def print_only_rssi(signal):
        print(f"Received signal: {signal.rssi}")
    """
    print("Received signal:")
    for attr, value in signal.__dict__.items():
        if attr == "position":
            print(f"  {attr}:")
            for attr_val, value_val in value.__dict__.items():
                print(f"    {attr_val}: {value_val}")
            print(f"    decimal degrees: {value.get_decimal_position()}")
            print(f"    degrees, minutes, seconds: {value.get_dms_position()}")
        else:
            print(f"  {attr}: {value}")


# Starts the MQTT session and blocks the main thread so the program doesn't end
# If you want the program to end, you can substitute the start_blocking method
# with the hat.start_async() method.
hat.start_blocking()

Basic integration

Import the SDK

from fivegdrone_sdk import FiveGDroneSDK

Setup the connection to the drone’s queue

hat = FiveGDroneSDK(MQTT_BROKER, MQTT_PORT, MQTT_USERNAME, MQTT_PASSWORD)

Create a signal’s handling function

@hat.signals
def signal_handling_function(signal):
    print(f"Signal received in band {signal.frequency_band}")

Your function will be called for every signal received from the drone.

Check the list of attributes for the Signal class.

Instead of the @hat.signals decorator, you can use the @hat.raw_signals decorator to receive all the information in a single string rather than a Signal object.

Loop the connection

You need to trigger the connection loop in order for the MQTT handler to process the messages.

Typically you will need to block the execution of the script to avoid the program exiting rather than keeping the connection open indefinitelly, for doing this, you can use this sentence:

hat.start_blocking()

Asyncronous loop

If you don’t want to block the execution of the script (e.g. you are handling your own threads), you can use the non-blocking alternative:

hat.start_async()

Sending messages to the queue

Messages can be passed to the queue in order to control the drone or to return information that might be useful for other consumers connected to the queue.

Sending an AT command to the hat

E.g. to send the AT message to turn on the GPS module

hat.send('control/command', 'AT+CGPS=1')

Sending instructions to the drone operator via the instructions topic

hat.send('instructions', 'Go to (53,47)')

You can subscribe yourself to arbitrary topics in the MQTT server. This allows you to exchange information between different related systems.

Example subscription to the instructions queue

def do_for_each_instructions_message(client, userdata, message):
    print(f"Instructions message: {message.payload.decode()}")

hat.subscribe('instructions', 2, do_for_each_instructions_message) # Topic, QOS, callback

You can later undo the subscription with:

hat.unsubscribe('instructions', do_for_each_instructions_message)

Other functions

To ask the hat to pause sending signals

hat.pause()

To ask the hat to resume sending signals

hat.resume()

To stop the loop and disconnect from the MQTT server

hat.stop()

The Signal class

The Signal class represents signals received from the drone. It is designed to handle various types of signals and provides methods to access and represent these signals.

Attributes

position (GPSPosition): The GPS position data.
system_mode (str): The type of network used by the drone.
operation_mode (str): The mode of operation of the hat. It will usually be Online.
mcc (str): The Mobile Country Code.
mnc (str): The Mobile Network Code.
tac (str): The Tracking Area Code.
scell_id (str): The serving cell ID.
pcell_id (str): The primary cell ID.
frequency_band (str): The frequency band.
earfcn (str): The E-UTRA Absolute Radio Frequency Channel Number.
dlbw (str): The downlink bandwidth.
ulbw (str): The uplink bandwidth.
rsrq (str): The Reference Signal Received Quality.
rsrp (str): The Reference Signal Received Power.
rssi (str): The Received Signal Strength Indicator.
rssnr (str): The Reference Signal Signal-to-Noise Ratio.
snr (str): The Signal-to-Noise Ratio.
scs (str): The Subcarrier Spacing.
nr_dl_bw (str): The NR downlink bandwidth.

Note that not all attributes will be set in all signals, as the device might be connected to multiple bands.

When connected to a LTE network

You will receive one signal with the following attributes:

position (GPSPosition): The GPS position data.
system_mode (str): The type of network used by the drone.
operation_mode (str): The mode of operation of the hat. It will usually be Online.
mcc (str): The Mobile Country Code.
mnc (str): The Mobile Network Code.
tac (str): The Tracking Area Code.
scell_id (str): The serving cell ID.
pcell_id (str): The primary cell ID.
frequency_band (str): The frequency band.
earfcn (str): The E-UTRA Absolute Radio Frequency Channel Number.
dlbw (str): The downlink bandwidth.
ulbw (str): The uplink bandwidth.
rsrq (str): The Reference Signal Received Quality.
rsrp (str): The Reference Signal Received Power.
rssi (str): The Received Signal Strength Indicator.
rssnr (str): The Reference Signal Signal-to-Noise Ratio.

system_node will be LTE.

When connected to a 5G NSA network

You will receive a LTE signal following the previous definition, and one or more signals with system_mode set to NR5G_NSA and the following attributes:

position (GPSPosition): The GPS position data.
system_mode (str): The type of network used by the drone.
pcell_id (str): The primary cell ID.
frequency_band (str): The frequency band.
earfcn (str): The E-UTRA Absolute Radio Frequency Channel Number.
rsrp (str): The Reference Signal Received Power.
rsrq (str): The Reference Signal Received Quality.
snr (str): The Signal-to-Noise Ratio.
scs (str): The Subcarrier Spacing.
nr_dl_bw (str): The NR downlink bandwidth.

When connected to a 5G SA network

You will receive signals with the system_mode set to NR5G_SA, and the following attributes:

position (GPSPosition): The GPS position data.
system_mode (str): The type of network used by the drone.
operation_mode (str): The mode of operation of the hat. It will usually be Online.
mcc (str): The Mobile Country Code.
mnc (str): The Mobile Network Code.
tac (str): The Tracking Area Code.
scell_id (str): The serving cell ID.
pcell_id (str): The primary cell ID.
frequency_band (str): The frequency band.
earfcn (str): The E-UTRA Absolute Radio Frequency Channel Number.
rsrp (str): The Reference Signal Received Power.
rsrq (str): The Reference Signal Received Quality.
snr (str): The Signal-to-Noise Ratio.

When not connected to a network

You will receive signals with the system_mode set to NO SERVICE, and the following attributes:

position (GPSPosition): The GPS position data.
system_mode (str): The type of network used by the drone.
operation_mode (str): The mode of operation of the hat. It will usually be Online.

Nested Class: GPSPosition

The GPSPosition class represents GPS position data.

Methods

`get_datetime(self)`

Returns the date and time reported by the GPS service.

Returns: – datetime: Date and time reported by the GPS service.

`get_position(self)`

Returns the GPS position in DDMM.MMMMMM format (decimal minutes).

Returns: – tuple: A tuple containing the latitude and longitude of the GPS position. – float: Latitude in DDMM.MMMMMM format. – str: Latitude direction (N or S). – float: Longitude in DDMM.MMMMMM format. – str: Longitude direction (E or W).

`get_decimal_position(self)`

Returns the GPS position in decimal degrees.

Returns: – tuple: A tuple containing the latitude and longitude of the GPS position. – float: Latitude in decimal degrees. – float: Longitude in decimal degrees.

`get_dms_position(self)`

Returns the GPS position in sexagesimal format.

Returns: – tuple: A tuple containing the latitude and longitude of the GPS position. – tuple: A tuple containing the latitude in sexagesimal format. – int: Degrees. – int: Minutes. – float: Seconds. – str: Direction (N or S). – tuple: A tuple containing the longitude in sexagesimal format. – int: Degrees. – int: Minutes. – float: Seconds. – str: Direction (E or W).

`get_altitude_meters(self)`

Returns the altitude of the GPS position in meters.

Returns: – float: The altitude of the GPS in meters.

`get_speed_knots(self)`

Returns the speed of the GPS position in knots.

Returns: – float: The speed of the GPS in knots.

`get_speed_kmh(self)`

Returns the speed of the GPS position in km/h.

Returns: – float: The speed of the GPS in km/h.

`get_course(self)`

Returns the course of the GPS position.

Returns: – float: The course of the GPS position.

Using the Database Connector

The SorusBoxScan DB Connector is a tool based on the SorusBoxScan Python SDK that stores each received signal in a MariaDB database.

Prerequisites

Python 3.8+
If you’re using Linux, install the MariaDB binary libraries:
```
sudo apt install libmariadb3 libmariadb-dev
```

Create the database structure

Run the following SQL script in your MariaDB instance:

CREATE TABLE signals (
    id INT(11) NOT NULL AUTO_INCREMENT,
    lat DECIMAL(10,6) DEFAULT NULL,
    lon DECIMAL(10,6) DEFAULT NULL,
    datetime DATETIME DEFAULT NULL,
    alt DECIMAL(10,2) DEFAULT NULL,
    speed DECIMAL(10,2) DEFAULT NULL,
    course DECIMAL(10,2) DEFAULT NULL,
    system_mode VARCHAR(50) DEFAULT NULL,
    operation_mode VARCHAR(50) DEFAULT NULL,
    mcc VARCHAR(10) DEFAULT NULL,
    mnc VARCHAR(10) DEFAULT NULL,
    tac VARCHAR(10) DEFAULT NULL,
    scell_id VARCHAR(50) DEFAULT NULL,
    pcell_id VARCHAR(50) DEFAULT NULL,
    frequency_band VARCHAR(50) DEFAULT NULL,
    earfcn VARCHAR(50) DEFAULT NULL,
    dlbw VARCHAR(50) DEFAULT NULL,
    ulbw VARCHAR(50) DEFAULT NULL,
    rsrq VARCHAR(50) DEFAULT NULL,
    rsrp VARCHAR(50) DEFAULT NULL,
    rssi VARCHAR(50) DEFAULT NULL,
    rssnr VARCHAR(50) DEFAULT NULL,
    snr VARCHAR(50) DEFAULT NULL,
    scs VARCHAR(50) DEFAULT NULL,
    nr_dl_bw VARCHAR(50) DEFAULT NULL,
    PRIMARY KEY (id)
);

Configure Environment Variables

Create a .env file in the project root. You can use .env.example as a template.

Run the Project

Use the following command to start the connector:

python -m fivegdrone_db

6G-SORUS | SorusBoxScan > How to exploit the data

Using an MQTT Client

Linux

Windows

Android

iPhone

Using the SorusBoxScan SDK

Features

Prerequisites

Setting up a Virtual Environment

On Linux, Mac OS or similar

On Windows, using CMD

On Windows, using PowerShell

On Windows’ UNIX-like shells (e.g. Git Bash CLI)

Authenticating with GitHub

Installation

Update

Usage

Basic integration

Import the SDK

Setup the connection to the drone’s queue

Create a signal’s handling function

Loop the connection

Asyncronous loop

Sending messages to the queue

Sending an AT command to the hat

Sending instructions to the drone operator via the instructions topic

Subscribe and unsubscribe

Example subscription to the instructions queue

Other functions

To ask the hat to pause sending signals

To ask the hat to resume sending signals

To stop the loop and disconnect from the MQTT server

The Signal class

Attributes

When connected to a LTE network

When connected to a 5G NSA network

When connected to a 5G SA network

When not connected to a network

Nested Class: GPSPosition

Methods

get_datetime(self)

get_position(self)

get_decimal_position(self)

get_dms_position(self)

get_altitude_meters(self)

get_speed_knots(self)

get_speed_kmh(self)

get_course(self)

Using the Database Connector

Prerequisites

Create the database structure

Configure Environment Variables

Run the Project

UNICA 6G

`get_datetime(self)`

`get_position(self)`

`get_decimal_position(self)`

`get_dms_position(self)`

`get_altitude_meters(self)`

`get_speed_knots(self)`

`get_speed_kmh(self)`

`get_course(self)`