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
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
On Windows, using CMD
On Windows, using PowerShell
On Windows’ UNIX-like shells (e.g. Git Bash CLI)
Authenticating with GitHub
- Install GitHub CLI:In Linux debian-based systems:
In Windows:
Or go to the GitHub CLI download page.
- Authenticate GitHub CLI:
- Follow the prompts to authenticate:
- Select
GitHub.com
. - Choose
HTTPS
as the preferred protocol. - Authenticate with your preferred method (browser or token).
- Select
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:
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:
Usage
Here’s a basic example to get started. You can use this as a template:
Basic integration
Import the SDK
Setup the connection to the drone’s queue
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:
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:
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
Sending instructions to the drone operator via the instructions topic
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:
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
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 beOnline
.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 beOnline
.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 beOnline
.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 beOnline
.
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:
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: