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

Created with Sketch.


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

Windows

Android

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

  1. 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.

  2. Authenticate GitHub CLI:
    gh auth login
    

     

  3. 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:

example.py

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)')

Subscribe and unsubscribe

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