Support package for managing the RITM SDR USRP hardware platform

The article contains information necessary for use in Engee libraries Targets.RITM_SDR_API designed for remote control of the RITM SDRfootnote hardware platform:[SDR (Software Defined Radio) is a software—defined radio.] USRP^[1] and data exchange over an Ethernet network. The requirements for the runtime environment, the connection procedure, the description of the application programming interface (API) and the register map of the main IP cores are given. note:[IP core is a hardware functional module within the FPGA/SNC, accessible by address space.].

Purpose and conditions of use

Library Targets.RITM_SDR_API It is designed to control the RITM SDR USRP hardware platform based on the Xilinx Zynq UltraScale+ system-on-chip and the ADRV9009 RF transceiver. Management is carried out through network interaction with the RITM SDR USRP control module. The SDR USRP RITM provides operation in the range of 75 MHz – 6 GHz with an instantaneous band up to 450 MHz. Library Targets.RITM_SDR_API It is used in the development, debugging and testing of wireless communication and radar systems.

General information

Library Targets.RITM_SDR_API implements a set of strongly typed Julia language methods and macros for performing the following operations:

establishing and terminating a TCP connection with the RITM SDR USRP control module;
setting radio frequency and path parameters (frequency, attenuation, TX/RXfootnote modes:[TX /RX — transmission/reception channels.]);
performing IP core reset and management procedures;
transmission and reception of I/Q samples and service data.

Interaction with the RITM SDR USRP is performed through Engee Device Manager. The diagram of the component interaction is shown in the figure.

ritm sdr usrp

Execution conditions

For the library to work Targets.RITM_SDR_API required:

RITM SDR USRP access to an Ethernet network;
availability Engee Device Manager on the side of the control computer (when used according to the accepted architecture).

Default Network settings:

IP address: SDR USRP — 192.168.2.70;
TCP port — 12345.

Quick start

Install or connect the Engee subsystem.Integration as shown in article.

engee.package.install("Engee-Device-Manager")

Connection link: engee.com/prod/user/demo1234-user
Install the client program:
https://dl.kpm-ritm.ru/repo/Host-Device-Manager-v1.57-Windows.zip - For Windows
https://dl.kpm-ritm.ru/repo/Host-Device-Manager-v1.57-Linux.zip - For Linux
To get examples, run: engee.package.getdemos("Engee-Device-Manager")
To run the server program, run: engee.package.start("Engee-Device-Manager")
The 'Engee-Device-Manager' support package, version 'v1.57', has been successfully installed.

engee.package.start("Engee-Device-Manager")

"engee.com/prod/user/demo1234-user"

Use the commands:

using Main.EngeeDeviceManager.Targets.RITM_SDR_API
import Main.EngeeDeviceManager.Targets.RITM_SDR_API

client = RITM_SDR_API.RITMClient("192.168.2.70")
if !RITM_SDR_API.connect(client)
    println("Connection error")
    return
end
println("Server version: $(RITM_SDR_API.get_version(client))")
RITM_SDR_API.disconnect(client)

An example of the expected output to the console:

Connected to 192.168.2.70:12345
Server version: v5.1.5
Connection closed

For more information, see the article Getting started with the RITM SDR USRP

Application Programming Interface (API)

This section describes the macros and functions of the library. For each item, the name, prototype (if available in the source text) and purpose are indicated.

Logging Group

Name The prototype Appointment

Name	The prototype	Appointment
`@log`	`macro log(expr)`	A macro for «quiet» logging without output to the console. Records data only if `LOG_ENABLED[] = true`.
`@log_on`	`macro log_on()`	The main switch of the logging system. Sets a global variable `LOG_ENABLED[] = true`. When calling functions for the first time `@logmsg` or `@log` It starts automatically `_ensure_log_file()`, which creates a folder `logs` (if there is none) and initializes the file with a timestamp in the name. A confirmation is displayed in the console.
`@logmsg`	`macro logmsg(expr)`	The main macro for combined output. Converts the expression to a string, clears it, prints it to the console, and if logging is active, writes it to a timestamped log file. Example: `@logmsg "Temperature: $(temp)°C"`
`@logprint`	`macro logprint(expr)`	Prints a message to the console without a newline. It is used for interactive progress bars or displaying partial results in one line.
`close_log()`	`function close_log()`	Logging session ends correctly. Adds a final entry, creates a cleaned-up version of the log file, and resets global variables.

@log

macro log(expr)

A macro for «quiet» logging without output to the console. Records data only if LOG_ENABLED[] = true.

@log_on

macro log_on()

The main switch of the logging system. Sets a global variable LOG_ENABLED[] = true. When calling functions for the first time @logmsg or @log It starts automatically _ensure_log_file(), which creates a folder logs (if there is none) and initializes the file with a timestamp in the name. A confirmation is displayed in the console.

@logmsg

macro logmsg(expr)

The main macro for combined output. Converts the expression to a string, clears it, prints it to the console, and if logging is active, writes it to a timestamped log file.

Example: @logmsg "Temperature: $(temp)°C"

@logprint

macro logprint(expr)

Prints a message to the console without a newline. It is used for interactive progress bars or displaying partial results in one line.

close_log()

function close_log()

Logging session ends correctly. Adds a final entry, creates a cleaned-up version of the log file, and resets global variables.

Service functions

Name The prototype Appointment

Name	The prototype	Appointment
`RITMClient()`	`RITMClient(server_ip::String="192.168.2.70")`	Constructor of the main library object. Creates a structure with the following fields: the IP address of the control module, the TCP connection descriptor, and the sampling rate (by default).
`_clean_string()`	`_clean_string(s::String)::String`	Clearing string responses from the control module of control and non-printable characters.
`_clear_socket_buffer()`	`_clear_socket_buffer(socket::SOCKET.Socket)`	Clearing the input buffer of the network socket.
`_get_data()`	`_get_data(client::RITMClient)::Union{Vector{UInt8}, Nothing}`	Receiving binary data from the control module according to the established protocol.
`_put_data()`	`_put_data(client::RITMClient, data::Vector{UInt8})::Bool`	Sending binary data to the control module using the established protocol.
`_send_command()`	`_send_command(client::RITMClient, command::String)::Tuple{Bool, Union{String, Nothing}}`	A key low-level function for sending commands to the control module. Sends a command, waits for processing, reads and analyzes the response.
`disconnect()`	`disconnect(client::RITMClient)`	Secure disconnection.
`connect()`	`connect(client::RITMClient)::Bool`	Establishing a TCP connection with the control module. The port is fixed — `SDR_PORT = 12345`.

RITMClient()

RITMClient(server_ip::String="192.168.2.70")

Constructor of the main library object. Creates a structure with the following fields: the IP address of the control module, the TCP connection descriptor, and the sampling rate (by default).

_clean_string()

_clean_string(s::String)::String

Clearing string responses from the control module of control and non-printable characters.

_clear_socket_buffer()

_clear_socket_buffer(socket::SOCKET.Socket)

Clearing the input buffer of the network socket.

_get_data()

_get_data(client::RITMClient)::Union{Vector{UInt8}, Nothing}

Receiving binary data from the control module according to the established protocol.

_put_data()

_put_data(client::RITMClient, data::Vector{UInt8})::Bool

Sending binary data to the control module using the established protocol.

_send_command()

_send_command(client::RITMClient, command::String)::Tuple{Bool, Union{String, Nothing}}

A key low-level function for sending commands to the control module. Sends a command, waits for processing, reads and analyzes the response.

disconnect()

disconnect(client::RITMClient)

Secure disconnection.

connect()

connect(client::RITMClient)::Bool

Establishing a TCP connection with the control module. The port is fixed — SDR_PORT = 12345.

Managing basic parameters

Name The prototype Appointment

Name	The prototype	Appointment
`get_calibrate_status()`	`get_calibrate_status(client::RITMClient)::String`	Request the calibration status of the system.
`get_frequency()`	`get_frequency(client::RITMClient)::Float64`	Request for the current frequency.
`get_rx_attenuation()`	`get_rx_attenuation(client::RITMClient, rx::String)::Union{Int, Nothing}`	Request for a tabular value of receiver attenuation.
`get_rx_power()`	`get_rx_power(client::RITMClient, rx::String)::Union{Float64, Nothing}`	Measuring the power at the receiver input.
`get_transceiver_state()`	`get_transceiver_state(client::RITMClient)::Tuple{Int, Int}`	Request for the current status of the transceiver.
`get_tx_attenuation()`	`get_tx_attenuation(client::RITMClient, tx::String)::Union{Float64, Nothing}`	Request for transmitter attenuation.
`set_frequency()`	`set_frequency(client::RITMClient, freq_mhz::Float64)::Bool`	Setting the carrier frequency of the transmitter and receiver. Checks the range, sends a command `COMMAND: SET_TX_CARR_FREQ_HZ`.
`set_param()`	`set_param(client::RITMClient, param::String)::Bool`	Universal parameter setting.
`set_rx_attenuation()`	`set_rx_attenuation(client::RITMClient, rx::String, value::Int)::Bool`	Setting the tabular value of receiver attenuation.
`set_transceiver()`	`set_transceiver(client::RITMClient, tx_cmd::Int, rx_cmd::Int)::Bool`	Configuration of the transmitter and receiver channels using bit masks.
`set_tx_attenuation()`	`set_tx_attenuation(client::RITMClient, tx::String, atten_db::Float64)::Bool`	Setting the attenuation of the transmitter.
`set_tx_carrier_freq_hz()`	`set_tx_carrier_freq_hz(client::RITMClient, freq_hz::Int)::Bool`	Alternative frequency setting in Hz.
`stop_transmission()`	`stop_transmission(client::RITMClient)::Bool`	Stopping the transmission.

get_calibrate_status()

get_calibrate_status(client::RITMClient)::String

Request the calibration status of the system.

get_frequency()

get_frequency(client::RITMClient)::Float64

Request for the current frequency.

get_rx_attenuation()

get_rx_attenuation(client::RITMClient, rx::String)::Union{Int, Nothing}

Request for a tabular value of receiver attenuation.

get_rx_power()

get_rx_power(client::RITMClient, rx::String)::Union{Float64, Nothing}

Measuring the power at the receiver input.

get_transceiver_state()

get_transceiver_state(client::RITMClient)::Tuple{Int, Int}

Request for the current status of the transceiver.

get_tx_attenuation()

get_tx_attenuation(client::RITMClient, tx::String)::Union{Float64, Nothing}

Request for transmitter attenuation.

set_frequency()

set_frequency(client::RITMClient, freq_mhz::Float64)::Bool

Setting the carrier frequency of the transmitter and receiver. Checks the range, sends a command COMMAND: SET_TX_CARR_FREQ_HZ.

set_param()

set_param(client::RITMClient, param::String)::Bool

Universal parameter setting.

set_rx_attenuation()

set_rx_attenuation(client::RITMClient, rx::String, value::Int)::Bool

Setting the tabular value of receiver attenuation.

set_transceiver()

set_transceiver(client::RITMClient, tx_cmd::Int, rx_cmd::Int)::Bool

Configuration of the transmitter and receiver channels using bit masks.

set_tx_attenuation()

set_tx_attenuation(client::RITMClient, tx::String, atten_db::Float64)::Bool

Setting the attenuation of the transmitter.

set_tx_carrier_freq_hz()

set_tx_carrier_freq_hz(client::RITMClient, freq_hz::Int)::Bool

Alternative frequency setting in Hz.

stop_transmission()

stop_transmission(client::RITMClient)::Bool

Stopping the transmission.

Advanced control and reset functions

Name Appointment

Name	Appointment
`get_ip_core()`	Reading the register of the functional module (IP core).
`reset_DFE_system_FIFO_TX491()`	FIFOfootnote Target reset:[FIFO is a First In, First Out queue.] in the DFE system.
`reset_KG()`	Resetting the auxiliary noise generator unit.
`reset_RX_DMA()`	Resetting DMA Controllers note:[DMA (Direct Memory Access) — Direct memory access controller.] reception and transmission.
`reset_TX_DMA()`	Resetting the receiving and transmitting DMA controllers.
`reset_buffers()`	Comprehensive FIFO buffer reset.
`set_ip_core()`	Writing to the register of the functional module (IP core).

get_ip_core()

Reading the register of the functional module (IP core).

reset_DFE_system_FIFO_TX491()

FIFOfootnote Target reset:[FIFO is a First In, First Out queue.] in the DFE system.

reset_KG()

Resetting the auxiliary noise generator unit.

reset_RX_DMA()

Resetting DMA Controllers note:[DMA (Direct Memory Access) — Direct memory access controller.] reception and transmission.

reset_TX_DMA()

Resetting the receiving and transmitting DMA controllers.

reset_buffers()

Comprehensive FIFO buffer reset.

set_ip_core()

Writing to the register of the functional module (IP core).

RF switches

Name The prototype Appointment

Name	The prototype	Appointment
`manual_calibrate_orx()`	`manual_calibrate_orx(client::RITMClient, orx::String)::Bool`	Manual calibration of the feedback channel.
`rf_switch_set_trx_sw1()`	`rf_switch_set_trx_sw1(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`rf_switch_set_trx_sw2()`	`rf_switch_set_trx_sw2(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`rf_switch_set_tx_bandsel_a()`	`rf_switch_set_tx_bandsel_a(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`rf_switch_set_tx_bandsel_b()`	`rf_switch_set_tx_bandsel_b(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`rf_switch_set_tx_fddtdd_sw1()`	`rf_switch_set_tx_fddtdd_sw1(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`rf_switch_set_tx_fddtdd_sw2()`	`rf_switch_set_tx_fddtdd_sw2(client::RITMClient, value::Bool)::Bool`	RF switching control on a hardware platform.
`set_tx_data_duplicate()`	`set_tx_data_duplicate(client::RITMClient, enable::Bool)::Bool`	Enabling/disabling the duplication of transmitter data for MIMO modes.

manual_calibrate_orx()

manual_calibrate_orx(client::RITMClient, orx::String)::Bool

Manual calibration of the feedback channel.

rf_switch_set_trx_sw1()

rf_switch_set_trx_sw1(client::RITMClient, value::Bool)::Bool