Engee documentation

Software management of RITM SDR cards

This page describes the software management functions. EngeeDeviceManager.Targets.RITM_API.SDR: type BoardConfig and methods for managing and reading parameters. The preparation of the environment and the interaction scheme of the components are given in the article. RITM SDR card management in Engee.

To work with software control functions EngeeDeviceManager.Targets.RITM_API.SDR in Engee. install the hardware support package as specified in article. After installation, import the module and select the RITM machine:

using Main.EngeeDeviceManager.Targets: RITM_API

SDR = RITM_API.SDR
ritm = "RITM 1"
if !RITM_API.isMachineExists(ritm)
    RITM_API.addMachine(ritm, "192.168.56.3")
end

boards = SDR.listBoards(ritm)
isempty(boards) && error("SDR-платы не обнаружены")
board = first(boards)["id"]

Replace the name and IP address in the example with the values of your machine, or use an already registered machine. Examples of individual methods suggest that ritm, SDR and board already defined. Examples of parameter changes require an initialized board, unless otherwise specified in the method description.

Types and methods SDR

Group Types and methods

Configuration

BoardConfig

Detection and status

listBoards, getStatus, isInitialized

Initialization

initialize, deinitialize

Frequency and FHM

setFrequency, getFrequency, isFhmEnabled, getFhmMinMhz, getFhmMaxMhz

Synchronization

getSyncTopology, getSlaveFallback

Radio path and calibration

calibrate, setRadioState, radioOn, radioOff

TX and RX

setTxAttenuation, getTxAttenuation, setRxGain, getRxGain

DDS

setDds, getDdsChannel, getDdsFrequency, getDdsScale

JESD

getJesdGood, getJesdRx, getJesdTx, getJesdRxOs

SDR.BoardConfig(;
    id,
    frequency_hz,
    fhm_min_mhz=nothing,
    fhm_max_mhz=nothing,
    topology="internal",
)

Configuration type for a single SDR board.

Named arguments

  • id::Int: the SDR board identifier.

  • frequency_hz::Int: initial carrier frequency, Hz.

  • fhm_min_mhz::Union{Nothing,Int}=nothing: Lower limit of FHM, MHz. By default nothing.

  • fhm_max_mhz::Union{Nothing,Int}=nothing: upper limit of FHM, MHz. By default, nothing.

    Both limits nothing define a fixed frequency. For FHM, specify both limits; the initial carrier must fall within the selected range. For RFMC9000, set positive limits using fhm_min_mhz < fhm_max_mhz. The driver additionally checks the compatibility of the range with the transceiver profile.

  • topology::String="internal": the synchronisation topology, specified as '` "internal" ' (by default), ' "master" ' or ' "slave" '. `"internal" specifies the internal synchronisation: "master" — master board, "slave" — slave board.

    For general synchronisation, transfer the master/slave configurations using a single call to initialize.

Return value

The object BoardConfig is to be passed to initialize. Creating the object does not trigger a payment. Topology checks and the joint definition of FHM boundaries are carried out when the initialisation command is prepared.

Examples

config = SDR.BoardConfig(
    id=board,
    frequency_hz=300_000_000,
    fhm_min_mhz=300,
    fhm_max_mhz=5500,
    topology="internal",
)
SDR.calibrate(ritm, board::Integer; channel::Integer=0)

Calibrates the transmission path of the initialised board.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Named arguments

  • channel::Integer=0: TX channel, 0 (by default) or 1.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the reason if an error occurs.

Features

In the RFMC9000, calibration is common to both transmission paths, regardless of the transmitted value ( channel). If successful, the current driver leaves the RF switched on. The previous RF state is not restored. The full status is not automatically queried.

Examples

try
    result = SDR.calibrate(ritm, board; channel=0)
    result["success"] || error(string(result["msg"]))
finally
    result = SDR.radioOff(ritm, board)
    result["success"] || error(string(result["msg"]))
end
SDR.deinitialize(ritm, board::Integer)
SDR.deinitialize(ritm, boards::AbstractVector{<:Integer})

This shuts down one or more boards by disabling the radio circuit and performing hardware de-initialisation. A hardware shutdown is not performed again on a board that has already been de-initialised.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier for a single circuit board.

  • boards::AbstractVector{<:Integer}: a non-empty array of identifiers.

Return value

success dictionary /msg:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

If a group call error occurs, check the status of the boards individually: the result does not indicate that each one has stopped.

Examples

result = SDR.deinitialize(ritm, board)
result["success"] || error(string(result["msg"]))

# Alternative group call:
# result = SDR.deinitialize(ritm, [0, 1])
SDR.getDdsChannel(ritm, board::Integer)

Reads the last DDS index used from the driver cache.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

An integer — the DDS index. This method does not switch the generator and does not return a list of all configured generators.

Examples

dds_channel = SDR.getDdsChannel(ritm, board)
println(dds_channel)
SDR.getDdsFrequency(ritm, board::Integer)

Reads the frequency of the most recently applied DDS setting from the driver cache.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

An integer representing the DDS frequency in Hz. This is a stored parameter, not a reading of the registers of all components, nor a measurement of the output frequency.

Examples

dds_frequency_hz = SDR.getDdsFrequency(ritm, board)
println(dds_frequency_hz)
SDR.getDdsScale(ritm, board::Integer)

Reads the scale of the most recently applied DDS setting from the driver cache.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

An integer — a scale of one millionth. The value 1_000_000 corresponds to the amplitude 1.0 in digital form; The RF signal strength cannot be determined directly from it.

Examples

dds_scale = SDR.getDdsScale(ritm, board)
println("Относительный масштаб: ", dds_scale / 1_000_000)
SDR.getFhmMaxMhz(ritm, board::Integer)

Reads the upper limit of the FHM range.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

The integer represents the upper limit in MHz. FHM activity is checked separately via isFhmEnabled.

Examples

max_mhz = SDR.getFhmMaxMhz(ritm, board)
println("Верхняя граница: ", max_mhz, " МГц")
SDR.getFhmMinMhz(ritm, board::Integer)

Reads the lower limit of the FHM range.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

An integer represents the lower limit in MHz. Use this in conjunction with isFhmEnabled: the saved limit value alone does not confirm that FHM is active.

Examples

min_mhz = SDR.getFhmMinMhz(ritm, board)
println("Нижняя граница: ", min_mhz, " МГц")
SDR.getFrequency(ritm, board::Integer)

Reads the carrier value provided by the driver.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

An integer — frequency in Hz. This value does not represent a measurement of the output RF signal’s frequency.

Examples

frequency_hz = SDR.getFrequency(ritm, board)
println("Несущая: ", frequency_hz / 1_000_000, " МГц")
SDR.getJesdGood(ritm, board::Integer)

Reads the summary status indicator for JESD digital lines.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

Bool. In the current driver, true requires the status DATA for three lines: RX, TX and observation RX (observation receiver). This value characterises the digital lines between the FPGA and the transceiver. It does not confirm the presence of a valid RF signal or the phase coherence of signals across multiple boards.

Examples

jesd_good = SDR.getJesdGood(ritm, board)
println("JESD: ", jesd_good)
SDR.getJesdRx(ritm, board::Integer)

Reads the status of the JESD digital input line and the driver’s initial diagnostics.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

Glossary of single-line diagrams:

Field: Value

"enabled"

Bool, indicator showing whether the diagnostic line is active

"good"

Bool, the line is active and in the status DATA

"state"

Status string or nothing if the status has not been retrieved

"raw"

Source text for diagnostics

Examples

rx = SDR.getJesdRx(ritm, board)
println("Состояние RX JESD: ", rx["state"])
println(rx["raw"])
SDR.getJesdRxOs(ritm, board::Integer)

Reads the status of the JESD bus on the observation receiver (observation RX) and the driver diagnostics.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

A dictionary containing "enabled", "good", "state" and "raw" in getJesdRx format.

Examples

rx_os = SDR.getJesdRxOs(ritm, board)
println("Observation RX JESD: ", rx_os["state"])
println(rx_os["raw"])
SDR.getJesdTx(ritm, board::Integer)

Reads the status of the JESD digital transmission line and the driver diagnostics.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

A dictionary from "enabled", "good", "state" and "raw" in the getJesdRx format.

Examples

tx = SDR.getJesdTx(ritm, board)
println("Состояние TX JESD: ", tx["state"])
println(tx["raw"])
SDR.getRxGain(ritm, board::Integer, channel::Integer)

Reads the gain table index for a single receive channel.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer : identifier of the initialised board.

  • channel::Integer : RX channel, 0 or 1.

Return value

An integer — the gain table index. The value is not expressed in dB. If the driver cannot read the parameter, including when RF is disabled, the method throws an exception. To obtain the full status with the readback_error field, use getStatus.

Examples

gain_index = SDR.getRxGain(ritm, board, 0)
println("Индекс усиления RX0: ", gain_index)
getRxMode(name, board::Integer)

Read the configured receive path without changing RF state.

  • name: RITM machine name, its saved IP/URL, or a RITM_API.Ritm handle.

  • board::Integer: SDR board ID, as returned by listBoards.

The receive mode string: "rx", "orx1", or "orx2". Failed reads raise an exception.

SDR.getSlaveFallback(ritm, board::Integer)

Reads the authorisation for the dependent load to switch to the local reference source.

Arguments

  • ritm: the name of the RITM machine from the machine repository (for example, "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

Bool: true, if fallback is permitted. The method reports the configuration, not whether the transition has actually occurred. There is no separate method in this API for reading the actual synchronisation source.

Examples

fallback_allowed = SDR.getSlaveFallback(ritm, board)
println("Локальная опора разрешена: ", fallback_allowed)
SDR.getStatus(ritm, board::Integer)

Reads the full status of a single board. This is the only high-level method that requests the full status; it does not include RF.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

Glossary of board status terms:

Field '` ’ Content

"id"

Board ID

"device"

Device type, current value "rfmc9000"

"initialized"

Initialisation flag

"frequency_hz"

Carrier frequency provided by the driver, Hz

"fhm"

Dictionary from "enabled", "min_mhz", "max_mhz"

"sync"

Dictionary from "topology" and "slave_fallback"

"mcs"

Information about MCS during initialisation or nothing

"jesd"

A dictionary from "good", "rx", "tx", "rx_os" or nothing

"rx"

Array of RX channel states

"tx"

Array of TX channel states

"dds"

A dictionary from "channel", "frequency_hz", "scale" or nothing

For an uninitialised board, mcs, jesd and dds are equal to nothing, whilst rx and tx are empty arrays. The presence of a saved frequency or synchronisation parameters does not necessarily mean that the equipment is ready: check initialized.

The element rx contains "channel", "gain_index" and "readback_error". The element tx contains "channel", "attenuation_mdb" and "readback_error". If a reading is unavailable, the value is nothing, whilst readback_error contains a diagnostic message. Errors when reading other mandatory fields may cause the entire query to terminate with an exception.

For an initialised board, mcs contains "source" => "driver_initialization" and "status_available" => false. This describes the MCS execution point, not the result of the phase synchronisation check.

The internal synchronisation settings ibert_prbs_window_ms, resync_sysref, jesd_lmfc_offset and lmk_sysref_delay are removed from the result by the Julia wrapper. The state structure of a single JESD line is shown at getJesdRx. DDS contains a cache of the last setting applied.

Examples

state = SDR.getStatus(ritm, board)
println("Инициализирована: ", state["initialized"])
println("Топология: ", state["sync"]["topology"])

for rx in state["rx"]
    if isnothing(rx["gain_index"])
        println("RX", rx["channel"], ": ", rx["readback_error"])
    else
        println("RX", rx["channel"], ": индекс ", rx["gain_index"])
    end
end
SDR.getSyncTopology(ritm, board::Integer)

Reads the configured synchronisation topology.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

The string '` "internal" ', ' "master" ' or ' "slave" ', provided by the driver. This reflects the topology configuration. For a slave board, the value ' "slave" ’ does not confirm that the board is actually operating from an external reference following a possible fallback.

Examples

topology = SDR.getSyncTopology(ritm, board)
println(topology)
SDR.getTxAttenuation(ritm, board::Integer, channel::Integer)

Reads the attenuation of a single transmit channel.

Arguments

  • ritm : the name of a RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or descriptor is also accepted RITM_API.Ritm.

  • board::Integer : the identifier of the initialised board.

  • channel::Integer : TX channel, 0 or 1.

Return value

An integer representing attenuation in millidecibels. If the hardware read operation is unavailable, the method throws an exception; RF is not automatically enabled for reading.

Examples

attenuation_mdb = SDR.getTxAttenuation(ritm, board, 1)
println("Затухание TX1: ", attenuation_mdb / 1000, " дБ")
SDR.initialize(ritm, config::BoardConfig; slave_fallback::Bool=true)
SDR.initialize(ritm, configs::AbstractVector{BoardConfig}; slave_fallback::Bool=true)

Initialises a single board or a group of boards in a single function call.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • config::BoardConfig: single-board configuration.

  • configs::AbstractVector{BoardConfig}: a non-empty array of configurations.

Named arguments

  • slave_fallback::Bool=true: Allow the driven plates to switch to the local reference source if an external reference is not acquired. When false is set, such a switch is not permitted. This parameter applies to the entire call.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Features

FHM mode is set individually for each board based on the presence of boundaries in its BoardConfig. MCS synchronisation is performed automatically during initialisation.

Before the configuration is applied, the selected boards are de-initialised. The group operation is not atomic. In the event of an error, an attempt is made to stop the boards already initialised in this call, but a return to all previous settings is not guaranteed. After an error, check the status of each affected board.

Successful initialisation of the RFMC9000 leaves the RF switched on.

Examples

config = SDR.BoardConfig(id=board, frequency_hz=300_000_000)
result = SDR.initialize(ritm, config)
result["success"] || error(string(result["msg"]))

result = SDR.radioOff(ritm, board)
result["success"] || error(string(result["msg"]))

Group option; replace the identifiers with the values from listBoards:

configs = [
    SDR.BoardConfig(id=0, frequency_hz=300_000_000, topology="master"),
    SDR.BoardConfig(id=1, frequency_hz=300_000_000, topology="slave"),
]
result = SDR.initialize(ritm, configs; slave_fallback=false)
result["success"] || error(string(result["msg"]))
SDR.isFhmEnabled(ritm, board::Integer)

Reads the FHM mode initialisation flag.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

Bool: whether FHM mode is enabled. For an uninitialised board, '` false ' is returned. The value ' true ' does not mean that the frequency changes automatically; software tuning is carried out using the ' setFrequency ’ method.

Examples

println("FHM: ", SDR.isFhmEnabled(ritm, board))
SDR.isInitialized(ritm, board::Integer)

Reads the board initialisation flag.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

Return value

Bool: true if the board has been initialised, otherwise false. This flag does not indicate whether the RF is currently enabled.

Examples

initialized = SDR.isInitialized(ritm, board)
println(initialized)
SDR.listBoards(ritm)

Returns a list of detected SDR boards. No hardware initialisation is required.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

Return value

An array of dictionaries containing the fields "id" and "device". For supported boards, the value of "device" is "rfmc9000". If there are no supported boards, the array is empty.

Examples

boards = SDR.listBoards(ritm)
for descriptor in boards
    println("Плата ", descriptor["id"], ": ", descriptor["device"])
end
SDR.radioOff(ritm, board::Integer)

Disables the radio path. Equivalent to setRadioState(ritm, board, false).

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Examples

result = SDR.radioOff(ritm, board)
result["success"] || error(string(result["msg"]))
SDR.radioOn(ritm, board::Integer)

Includes the radio path. Equivalent to setRadioState(ritm, board, true).

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Examples

# RF- the connections and board parameters have been prepared in advance.
result = SDR.radioOn(ritm, board)
result["success"] || error(string(result["msg"]))
SDR.setDds(
    ritm, board::Integer, channel::Integer, frequency_hz::Integer, scale::Integer,
)

Configures a single DDS digital oscillator using the low-level index.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

  • channel::Integer: DDS index from 0 to 3.

  • frequency_hz::Integer: DDS frequency in Hz, an integer between 0 and 4_294_967_295 inclusive. Select the operating frequency taking into account the sampling rate and the equipment profile.

  • scale::Integer: scale in parts per million, from 0 to 1_999_000; 50_000 corresponds to 0.05, 1_000_000 corresponds to 1.0.

Return value

success dictionary /msg:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Features

The RFMC9000 has two RF transmit channels. The DDS index does not correspond to the RF transmitter number. The current interface does not provide a one-to-one correspondence between 0…3 and the components TX1 I, TX1 Q, TX2 I, TX2 Q; to configure a specific I/Q path, the implementation of DDS in the driver and the FPGA firmware must be taken into account. The carrier is set via BoardConfig or setFrequency, separately from the DDS frequency.

The method applies the frequency and scale to the selected generator. The subsequent calls to getDdsChannel, getDdsFrequency and getDdsScale read the cache for this latest setting; they do not check the registers of all components or the signal waveform.

Examples

result = SDR.setDds(ritm, board, 0, 20_000_000, 50_000)
result["success"] || error(string(result["msg"]))

println("Индекс DDS: ", SDR.getDdsChannel(ritm, board))
println("Частота, Гц: ", SDR.getDdsFrequency(ritm, board))
println("Масштаб: ", SDR.getDdsScale(ritm, board))
SDR.setFrequency(ritm, board::Integer, frequency_hz::Integer)

Changes the base board initialised with FHM enabled.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

  • frequency_hz::Integer: a new positive frequency in Hz, within the tuned FHM band.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Features

This method cannot be used for a board with a fixed frequency. To change this frequency, use initialize with the new BoardConfig. This method does not return the actual frequency set; use getFrequency instead.

Examples

# The board has already been initialised with FHM, which includes 400 MHz.
result = SDR.setFrequency(ritm, board, 400_000_000)
result["success"] || error(string(result["msg"]))
println(SDR.getFrequency(ritm, board))
SDR.setRadioState(ritm, board::Integer, enabled::Bool)

Enables or disables the radio path of the initialised board.

Arguments

  • ritm: the name of the RITM machine from the machine repository (for example, "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: board identifier.

  • enabled::Bool: true to enable, false to disable.

    The value false preserves the board’s initialisation. To complete the operation, use deinitialize. The parameter enabled requires Bool: pass true or false, not 1 or 0. There is no separate function for reading the RF status in the driver.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Examples

result = SDR.setRadioState(ritm, board, false)
result["success"] || error(string(result["msg"]))
SDR.setRxGain(ritm, board::Integer, channel::Integer, index::Integer)

Sets the index of the receive channel gain table.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g., "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

  • channel::Integer: RX Channel, 0 or 1.

  • index::Integer: the gain table index, an integer ranging from 0 to 255, which is valid for the table and driver mode in use.

Return value

success/msg dictionary:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Features

The index argument does not specify the gain in dB. The correspondence between the indices and the gain is defined by the transceiver table; whether this works depends on the driver. To read the values, use getRxGain.

Examples

result = SDR.setRxGain(ritm, board, 0, 255)
result["success"] || error(string(result["msg"]))
SDR.setTxAttenuation(
    ritm, board::Integer, channel::Integer, attenuation_mdb::Integer,
)

Sets the attenuation of the transmission channel.

Arguments

  • ritm: the name of the RITM machine from the machine repository (e.g. "RITM 1"); a saved IP address/URL or the descriptor RITM_API.Ritm is also accepted.

  • board::Integer: the identifier of the initialised board.

  • channel::Integer: TX channel, 0 or 1.

  • attenuation_mdb::Integer: attenuation in millidecibels, ranging from 0 to 41_950 inclusive.

Return value

success/msg:

  • "success": true if successful, false if the operation fails.

  • "msg": nothing if successful; a description of the cause if an error occurs.

Features

Once installed, the RFMC9000 driver initiates a general TX calibration; if successful, the RF remains switched on. The attenuation may be quantised in steps specified by the transceiver profile. Read the actual value via getTxAttenuation.

Examples

try
    result = SDR.setTxAttenuation(ritm, board, 1, 32_000) # 32 dB
    result["success"] || error(string(result["msg"]))
    println(SDR.getTxAttenuation(ritm, board, 1))
finally
    result = SDR.radioOff(ritm, board)
    result["success"] || error(string(result["msg"]))
end

General calling rules

  • ritm::String — the name of the registered car (for example "RITM 1"), its saved IP address or full URL. The name and IP address must be added to Engee; the full URL can be passed directly.

  • board::Integer — ID from listBoards, not the Julia array index.

  • The TX and RX channels are numbered from scratch: 0 and 1.

  • Indexes of DDS generators: from 0 before 3.

  • The carrier and DDS frequency are transmitted in Hz; the FHM boundaries are in MHz.

  • TX attenuation is transmitted in millidecibels: 1000 respond 1 dB.

  • The RX gain is set by the index of the table, not by the dB value.

  • The DDS scale is set in millionths: 1_000_000 respond 1.0.

The numerical limits given apply to DA-AX-FMC-RF9. If the value falls within the acceptable range, it does not guarantee the applicability of the setting for a specific transceiver profile and sampling rate.

In arguments of methods of the type Integer You can’t use Bool instead of a number: this value is rejected by the software control. When performing the operation, the validity of the configuration for the equipment is additionally checked.

Results of operations changes

Methods initialize, deinitialize, setFrequency, calibrate, setRadioState, radioOn, radioOff, setTxAttenuation, setRxGain and setDds They are returning Dict{String,Any} with two fields:

Field Meaning

"success"

true on success, false in case of an operation error

"msg"

nothing if successful, a description of the reason for the error

Every call must be checked:

result = SDR.radioOff(ritm, board)
result["success"] || error(string(result["msg"]))

The success response does not contain the full status and the actual applied parameter values. To check, use a separate reading function or getStatus.

Julia type and argument errors, RPC/HTTP failures, and incorrect response structure can lead to exceptions. The operation may also partially change the state of the equipment before the error or timeout. Before repeating, read the status of the affected boards; there is no automatic repeat in the program control.

Results of reading operations

The read methods return the requested value directly, a dictionary or an array of dictionaries. If the request fails, they throw an exception. The reading functions do not include a radio trace — the parameters can be read at any time.

Method getStatus returns nothing for inaccessible hardware readings and saves the diagnosis of a reading error. Individual functions for reading such parameters end with an exception if the value cannot be read.

Available before initialization isInitialized, getFrequency, isFhmEnabled, getFhmMinMhz, getFhmMaxMhz, getSyncTopology and getSlaveFallback. They read the signs and saved settings. The individual JESD, DDS, RX gain, and TX attenuation functions require an initialized board.

The methods output additional diagnostic messages via @warn.

Effect on RF status

Method Behavior of the current DA-AX-FMC-RF9 driver on success

initialize

Initializes the board and leaves the RF enabled

calibrate

Calibrates both TX paths and leaves RF enabled

setTxAttenuation

Sets the attenuation, performs calibration, and leaves the RF on.

radioOn / setRadioState(…​, true)

Enables RF

radioOff / setRadioState(…​, false)

Turns off RF, saving initialization

deinitialize

Shuts down the board by turning off the RF

There is no separate function for reading the current RF status (on/off). If the command requires the RF to be turned off later, call radioOff clearly. This call does not prevent the radio path from being switched on during the previous initialization or calibration.