Документация Engee

Пакет поддержки для управления аппаратной платформой РИТМ SDR USRP

В статье содержатся сведения, необходимые для использования в Engee библиотеки Targets.RITM_SDR_API, предназначенной для дистанционного управления аппаратной платформой РИТМ SDR[1] USRP[2] и обмена данными по сети Ethernet. Приведены требования к среде выполнения, порядок подключения, описание интерфейса прикладного программирования (API) и регистровая карта основных IP-ядер[3].

Назначение и условия применения

Библиотека Targets.RITM_SDR_API предназначена для управления аппаратной платформой РИТМ SDR USRP на базе системы-на-кристалле Xilinx Zynq UltraScale+ и радиочастотного трансивера ADRV9009. Управление осуществляется посредством сетевого взаимодействия с управляющим модулем РИТМ SDR USRP. РИТМ SDR USRP обеспечивает работу в диапазоне 75 МГц – 6 ГГц при мгновенной полосе до 450 МГц. Библиотека Targets.RITM_SDR_API применяется при разработке, отладке и испытаниях беспроводных систем связи и радиолокации.

Общие сведения

Библиотека Targets.RITM_SDR_API реализует набор строго типизированных методов и макросов языка Julia для выполнения следующих операций:

  • установление и завершение TCP-соединения с управляющим модулем РИТМ SDR USRP;

  • установка радиочастотных параметров и параметров тракта (частота, аттенюация, режимы TX / RX[4]);

  • выполнение процедур сброса и управления IP-ядрами;

  • передача и прием выборок I/Q и служебных данных.

Взаимодействие с РИТМ SDR USRP выполняется через Engee Device Manager. Схема взаимодействия компонентов приведена на рисунке.

ritm sdr usrp

Условия выполнения

Для работы библиотеки Targets.RITM_SDR_API требуется:

  • доступ РИТМ SDR USRP к сети Ethernet;

  • наличие Engee Device Manager на стороне управляющего компьютера (при применении согласно принятой архитектуре).

Сетевые параметры по умолчанию:

  • IP-адрес РИТМ SDR USRP — 192.168.2.70;

  • TCP-порт — 12345.

Быстрый старт

  1. Установите или подключите подсистему Engee.Интеграции как показано в статье.

    engee.package.install("Engee-Device-Manager")
    Ссылка для подключения: engee.com/prod/user/demo1234-user
Установите клиентскую программу:
https://dl.kpm-ritm.ru/repo/Host-Device-Manager-v1.57-Windows.zip - Для Windows
https://dl.kpm-ritm.ru/repo/Host-Device-Manager-v1.57-Linux.zip - Для Linux
Для получения примеров выполните: engee.package.getdemos("Engee-Device-Manager")
Для запуска серверной программы выполните: engee.package.start("Engee-Device-Manager")
Пакет поддержки 'Engee-Device-Manager' версии 'v1.57' успешно установлен.
    engee.package.start("Engee-Device-Manager")
    "engee.com/prod/user/demo1234-user"

  2. Используйте команды:

    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("Ошибка подключения")
    return
end
println("Версия сервера: $(RITM_SDR_API.get_version(client))")
RITM_SDR_API.disconnect(client)

    Пример ожидаемого вывода в консоль:

    Подключено к 192.168.2.70:12345
Версия сервера: v5.1.5
Соединение закрыто

Подробнее см. в статье Начало работы с РИТМ SDR USRP

Интерфейс прикладного программирования (API)

В разделе приведено описание макросов и функций библиотеки. Для каждой позиции указаны наименование, прототип (при наличии в исходном тексте) и назначение.

Группа ведения журнала

Наименование Прототип Назначение

@log

macro log(expr)

Макрос для «тихого» ведения журнала без вывода в консоль. Записывает данные, только если LOG_ENABLED[] = true.

@log_on

macro log_on()

Главный переключатель системы ведения журнала. Устанавливает глобальную переменную LOG_ENABLED[] = true. При первом вызове функций @logmsg или @log автоматически запускается _ensure_log_file(), которая создает папку logs (если ее нет) и инициализирует файл с временной меткой в имени. В консоль выводится подтверждение.

@logmsg

macro logmsg(expr)

Основной макрос для комбинированного вывода. Преобразует выражение в строку, очищает ее, печатает в консоль и, если ведение журнала активно, записывает в файл журнала с временной меткой.

Пример: @logmsg "Температура: $(temp)°C"

@logprint

macro logprint(expr)

Печатает сообщение в консоль без перевода строки. Используется для интерактивных прогресс-баров или вывода частичных результатов в одной строке.

close_log()

function close_log()

Корректное завершение сессии ведения журнала. Добавляет финальную запись, создает очищенную версию файла журнала и сбрасывает глобальные переменные.

Служебные функции

Наименование Прототип Назначение

RITMClient()

RITMClient(server_ip::String="192.168.2.70")

Конструктор основного объекта библиотеки. Создает структуру с полями: IP-адрес управляющего модуля, дескриптор TCP-соединения и частота дискретизации (по умолчанию).

_clean_string()

_clean_string(s::String)::String

Очистка строковых ответов от управляющего модуля от управляющих и непечатаемых символов.

_clear_socket_buffer()

_clear_socket_buffer(socket::SOCKET.Socket)

Очистка входного буфера сетевого сокета.

_get_data()

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

Прием бинарных данных с управляющего модуля по установленному протоколу.

_put_data()

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

Отправка бинарных данных на управляющий модуль по установленному протоколу.

_send_command()

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

Ключевая низкоуровневая функция для отправки команд управляющему модулю. Отправляет команду, ожидает обработки, читает и анализирует ответ.

disconnect()

disconnect(client::RITMClient)

Безопасный разрыв соединения.

connect()

connect(client::RITMClient)::Bool

Установка TCP-соединения с управляющим модулем. Порт фиксирован — SDR_PORT = 12345.

Управление основными параметрами

Наименование Прототип Назначение

get_calibrate_status()

get_calibrate_status(client::RITMClient)::String

Запрос статуса калибровки системы.

get_frequency()

get_frequency(client::RITMClient)::Float64

Запрос текущей частоты.

get_rx_attenuation()

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

Запрос табличного значения аттенюации приемника.

get_rx_power()

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

Измерение мощности на входе приемника.

get_transceiver_state()

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

Запрос текущего состояния трансивера.

get_tx_attenuation()

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

Запрос аттенюации передатчика.

set_frequency()

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

Установка несущей частоты передатчика и приемника. Проверяет диапазон, отправляет команду COMMAND: SET_TX_CARR_FREQ_HZ.

set_param()

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

Универсальная установка параметра.

set_rx_attenuation()

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

Установка табличного значения аттенюации приемника.

set_transceiver()

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

Конфигурация каналов передатчика и приемника с помощью битовых масок.

set_tx_attenuation()

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

Установка аттенюации передатчика.

set_tx_carrier_freq_hz()

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

Альтернативная установка частоты в Гц.

stop_transmission()

stop_transmission(client::RITMClient)::Bool

Остановка передачи.

Функции расширенного управления и сбросов

Наименование Назначение

get_ip_core()

Чтение регистра функционального модуля (IP-ядра).

reset_DFE_system_FIFO_TX491()

Целевой сброс FIFO[5] в системе DFE.

reset_KG()

Сброс блока вспомогательного генератора шума.

reset_RX_DMA()

Сброс DMA-контроллеров[6] приема и передачи.

reset_TX_DMA()

Сброс DMA-контроллеров приема и передачи.

reset_buffers()

Комплексный сброс FIFO-буферов.

set_ip_core()

Запись в регистр функционального модуля (IP-ядра).

RF-переключатели

Наименование Прототип Назначение

manual_calibrate_orx()

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

Ручная калибровка канала обратной связи.

rf_switch_set_trx_sw1()

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

Управление RF-коммутацией на аппаратной платформе.

rf_switch_set_trx_sw2()

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

Управление RF-коммутацией на аппаратной платформе.

rf_switch_set_tx_bandsel_a()

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

Управление RF-коммутацией на аппаратной платформе.

rf_switch_set_tx_bandsel_b()

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

Управление RF-коммутацией на аппаратной платформе.

rf_switch_set_tx_fddtdd_sw1()

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

Управление RF-коммутацией на аппаратной платформе.

rf_switch_set_tx_fddtdd_sw2()

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

Управление RF-коммутацией на аппаратной платформе.

set_tx_data_duplicate()

set_tx_data_duplicate(client::RITMClient, enable::Bool)::Bool

Включение/выключение дублирования данных передатчика для MIMO-режимов.

Управление приемом и передачей данных

Наименование Назначение

get_orx_attenuation()

Управление ослаблением каналов ORX[7].

is_ORX_DMA_transfer_end()

Проверка завершения DMA-передачи для основного приема (RX) и каналов обратной связи (ORX).

is_dma_transfer_end()

Проверка завершения DMA-передачи для основного приема (RX) и каналов обратной связи (ORX).

parse_rx_data()

Форматирование принятых данных из uint32 в массив комплексных чисел.

prepare_tx_data()

Подготовка комплексных данных к передаче: масштабирование и интерливинг компонентов.

receive_file_ORX_to_RAM()

Прием данных с канала обратной связи (ORX) в ОЗУ.

receive_to_ram()

Инициация приема данных с приемника в ОЗУ.

receiver_RX_ORX_ONOFF()

Прямое включение/выключение приемных каналов.

send_to_ram()

Команда на передачу данных из ОЗУ в передатчик.

set_orx_attenuation()

Управление ослаблением каналов ORX.

Дополнительные сервисные функции

Наименование Назначение

get_temperatures()

Мониторинг температур различных компонентов аппаратной платформы.

get_version()

Запрос версии программного обеспечения управляющего модуля.

Функции автоматической регулировки усиления

Наименование Прототип Назначение

agc_set_mode()

agc_set_mode(client, mode)

Конфигурация автоматической регулировки усиления (0 — выкл, 1 — медленный, 2 — быстрый, 3 — гибридный).

agc_parse_config()

agc_parse_config(client)

Принудительное применение настроек автоматической регулировки усиления после их изменения.

agc_reset()

agc_reset(client)

Возврат настроек автоматической регулировки усиления к значениям по умолчанию.

set_tx_data_duplicate()

set_tx_data_duplicate(client, enable)

Включение/выключение дублирования данных передатчика для MIMO-режимов.

Сетевое взаимодействие и обмен данными

Соединение с управляющим модулем изделия устанавливается по протоколу TCP. Номер порта фиксирован (12345). Функция connect() должна вызываться до выполнения любых команд управления и обмена данными. Разрыв соединения выполняется функцией disconnect() (или close(), если используется синоним). Отправка команд управления реализуется через низкоуровневую функцию _send_command(), осуществляющую передачу строковой команды и анализ ответа. Передача и прием бинарных массивов данных выполняются функциями _put_data() и _get_data() по установленному протоколу обмена.

Регистры SDR

В таблице приведена регистровая карта IP-ядер, доступных через механизм set_ip_core()/get_ip_core(). Адреса указаны в шестнадцатеричном виде. Типы данных приведены в соответствии с обозначениями, применяемыми в проекте ПЛИС.

IP-ядро Адрес (hex) Название регистра Тип данных Описание

DUCex[8]

0x30108

IPCore_Reset

boolean

Сброс ядра: запись 0x1 сбрасывает IP-ядро.

DUCex

0x30008

IPCore_Timestamp

uint32

Уникальный временной штамп ядра (формат yymmddHHMM).

DUCex

0x30100

rate_axi_Data

ufix12

Регистр данных для настройки коэффициента интерполяции.

DUCex

0x30104

rate_enb_axi_Data

boolean

Включение / выключение интерполятора.

DUCex

0x30108

rst_axi_Data

boolean

Асинхронный сброс ядра через AXI.

DUCex

0x3010C

enb_axi_Data

boolean

Глобальное включение ядра.

DUCex

0x30110

gain_0_correct_axi_Data

ufix12_En10

Коэффициент усиления канала 0 (коррекция).

DUCex

0x30114

gain_0_enb_axi_Data

boolean

Включение усиления канала 0.

DUCex

0x30118

gain_1_correct_axi_Data

ufix12_En10

Коэффициент усиления канала 1 (коррекция).

DUCex

0x3011C

gain_1_enb_axi_Data

boolean

Включение усиления канала 1.

DUCex

0x30120

nco_0_enb_axi_Data

boolean

Включение NCO[9] канала 0.

DUCex

0x30124

nco_0_phase_inc_Data

DUC_phase_inc

Инкремент фазы NCO канала 0 (int32).

DUCex

0x30128

nco_0_phase_offset_Data

DUC_phase_offset

Смещение фазы NCO канала 0 (int32).

DUCex

0x3012C

nco_0_reset_accum_Data

boolean

Сброс накопителя фазы NCO канала 0.

DUCex

0x30130

nco_1_phase_inc_Data

DUC_phase_inc

Инкремент фазы NCO канала 1 (int32).

DUCex

0x30134

nco_1_phase_offset_Data

DUC_phase_offset

Смещение фазы NCO канала 1 (int32).

DUCex

0x30138

nco_1_reset_accum_Data

boolean

Сброс накопителя фазы NCO канала 1.

DUCex

0x3013C

nco_1_enb_axi_Data

boolean

Включение NCO канала 1.

DUCex

0x30140

DDS_0_on_Data

boolean

Включение DDS[10] канала 0.

DUCex

0x30144

DDS_1_on_Data

boolean

Включение DDS канала 1.

DDCex

0x50108

IPCore_Reset

boolean

Сброс ядра: запись 0x1 сбрасывает IP-ядро.

DDCex

0x50008

IPCore_Timestamp

uint32

Уникальный временной штамп ядра (формат yymmddHHMM).

DDCex

0x50100

rate_axi_Data

ufix12

Регистр данных для настройки коэффициента децимации.

DDCex

0x50104

rate_enb_axi_Data

boolean

Включение / выключение дециматора.

DDCex

0x50108

rst_axi_Data

boolean

Асинхронный сброс ядра через AXI[11].

DDCex

0x50110

gain_0_correct_axi_Data

ufix12_En10

Коэффициент усиления канала 0 (коррекция).

DDCex

0x5010C

gain_1_correct_axi_Data

ufix12_En10

Коэффициент усиления канала 1 (коррекция).

DDCex

0x50114

gain_0_enb_axi_Data

boolean

Включение усиления канала 0.

DDCex

0x50118

gain_1_enb_axi_Data

boolean

Включение усиления канала 1.

DDCex

0x50124

nco_0_phase_inc_Data

DDC_phase_inc

Инкремент фазы NCO канала 0.

DDCex

0x50128

nco_0_phase_offset_Data

DDC_phase_offset

Смещение фазы NCO канала 0.

DDCex

0x5012C

nco_0_reset_accum_Data

boolean

Сброс накопителя фазы NCO канала 0.

DDCex

0x50130

nco_1_phase_inc_Data

DDC_phase_inc

Инкремент фазы NCO канала 1.

DDCex

0x50134

nco_1_phase_offset_Data

DDC_phase_offset

Смещение фазы NCO канала 1.

DDCex

0x50138

nco_1_reset_accum_Data

boolean

Сброс накопителя фазы NCO канала 1.

DDCex

0x50120

nco_0_enb_axi_Data

boolean

Включение NCO общего выхода.

DDCex

0x5013C

nco_1_enb_axi_Data

boolean

Включение NCO канала 1.

DDCex

0x50154

DDS_0_on_Data

boolean

Включение DDS канала 0.

DDCex

0x50158

DDS_1_on_Data

boolean

Включение DDS канала 1.

DDCex

0x5011C

high_level_0_Data

int16

DDCex

0x50140

inc_val_0_Data

sfix16_En15

DDCex

0x50144

dec_val_0_Data

sfix16_En15

DDCex

0x50148

low_level_0_Data

int16

DDCex

0x5014C

enb_dc_correct_0_Data

boolean

DDCex

0x50150

high_level_1_Data

int16

DDCex

0x5015C

inc_val_1_Data

sfix16_En15

DDCex

0x50160

dec_val_1_Data

sfix16_En15

DDCex

0x50164

low_level_1_Data

int16

DDCex

0x50168

enb_dc_correct_1_Data

boolean

DDCex

0x5016C

integrate_0_out_Data

int32

DDCex

0x50170

integrate_1_out_Data

int32

AGCex[12]

0x80120000

IPCore_Reset

boolean

Сброс ядра: запись 0x1 сбрасывает IP-ядро.

AGCex

0x80120004

IPCore_Enable

boolean

Включение ядра (по умолчанию включено, когда бит 0 равен 0x1).

AGCex

0x80120008

IPCore_Timestamp

uint32

Уникальный временной штамп ядра (формат yymmddHHMM): 2509100147.

AGCex

0x80120100

time_out_Data

ufix25

Регистр данных для входного порта time_out.

AGCex

0x80120104

thrshld_Data

sfix18_En17

Регистр данных для входного порта thrshld.

AGCex

0x80120108

target_avg_delta_high_Data

ufix18_En17

Регистр данных для входного порта target_avg_delta_high.

AGCex

0x8012010C

target_avg_Data

ufix18_En17

Регистр данных для входного порта target_avg.

AGCex

0x80120110

prg_rst_Data

boolean

Регистр данных для входного порта prg_rst.

AGCex

0x80120114

avg_timer_pow2_Data

uint8

Регистр данных для входного порта avg_timer_pow2.

AGCex

0x80120118

over_hi_dec_step_Data

sfix18_En17

Регистр данных для входного порта over_hi_dec_step.

AGCex

0x8012011C

normal_dec_step_Data

sfix18_En17

Регистр данных для входного порта normal_dec_step.

AGCex

0x80120120

normal_inc_step_Data

sfix18_En17

Регистр данных для входного порта normal_inc_step.

AGCex

0x80120124

normal_gain_Data

ufix18_En12

Регистр данных для входного порта normal_gain.

AGCex

0x80120128

hi_criteria_Data

ufix17_En17

Регистр данных для входного порта hi_criteria.

AGCex

0x8012012C

hi_criteria_timer_Data

uint8

Регистр данных для входного порта hi_criteria_timer.

AGCex

0x80120130

agc_enb_Data

boolean

Регистр данных для входного порта agc_enb.

AGCex

0x80120134

b_in_Data

ufix18_En18

Регистр данных для входного порта b_in.

AGCex

0x80120138

max_detected_Data

sfix16_En15

Регистр данных для выходного порта max_detected.

AGCex

0x8012013C

avg_data_clear_Data

ufix12_En7

Регистр данных для выходного порта avg_data_clear.

AGCex

0x80120140

avg_data_iir_Data

ufix18_En17

Регистр данных для выходного порта avg_data_iir.

AGCex

0x80120144

current_ku_Data

ufix18_En12

Регистр данных для выходного порта current_ku.

AGCex

0x80120148

overhi_enb_valid_out_Data

boolean

Регистр данных для выходного порта.

Полезные ссылки

1. SDR (Software Defined Radio) — программно-определяемое радио.
2. USRP (Universal Software Radio Peripheral) — универсальная платформа SDR.
3. IP-ядро — аппаратный функциональный модуль в составе ПЛИС/СнК, доступный по адресному пространству.
4. TX / RX — каналы передачи/приема.
5. FIFO — очередь типа First In, First Out.
6. DMA (Direct Memory Access) — контроллер прямого доступа к памяти.
7. ORX (Observation Receiver) — канал обратной связи.
8. DUC/DDC (Digital Up/Down Converter) — цифровой преобразователь вверх/вниз.
9. NCO (Numerically Controlled Oscillator) — числовой управляемый генератор.
10. DDS (Direct Digital Synthesis) — цифровой синтезатор.
11. AXI — шинный интерфейс AMBA AXI.
12. AGC (Automatic Gain Control) — автоматическая регулировка усиления.