Device Control Functions¶

Device Information¶

The hello function provides device information, including the packet version used by the device (which may be checked against the version supported by the library)

std::optional<std::array<uint32_t, 6>> vxsdr::hello()¶

Request basic information from the device.

Returns

a std::optional with a std::array containing the

device identifier
FPGA code version
MCU code version,
device serial number,
packet version supported
device status

The reset function performs a hard reset of the device.

bool vxsdr::reset()¶

Reset the device.

Returns: true if the command succeeds, false otherwise

std::optional<std::array<uint32_t, 8>> vxsdr::get_status(const uint8_t subdev = 0)¶

Get the device status.

Parameters: subdev – the subdevice number
Returns: a std::optional with a std::array containing device-dependent status information

bool vxsdr::clear_status(const uint8_t subdev = 0)¶

Clear the device status.

Parameters: subdev – the subdevice number
Returns: true if the command succeeds, false otherwise

std::optional<std::array<uint32_t, 2>> vxsdr::get_buffer_info(const uint8_t subdev = 0)¶

Get the size of the device transmit and receive buffers.

Parameters: subdev – the subdevice number
Returns: a std::optional with a std::array containing the transmit and receive buffer sizes in bytes, in that order

std::optional<std::array<uint32_t, 2>> vxsdr::get_buffer_use(const uint8_t subdev = 0)¶

Get the current number of bytes used in the device transmit and receive buffers.

Parameters: subdev – the subdevice number
Returns: a std::optional with a std::array containing the transmit and receive buffer usage in bytes, in that order

std::optional<unsigned> vxsdr::get_max_payload_bytes()¶

Get the maximum payload size in bytes for transport to and from the device. Note that the maximum packet size (which must not exceed the network MTU) is the maximum payload size plus the size of the packet header, plus the stream spec and time spec, if those are used, plus the size of the IPv4 header. The packet header, stream spec, and time spec are 8 bytes each, and the IPv4 header is typically 20 bytes.

Returns: a std::optional with the maximum payload in bytes

bool vxsdr::set_max_payload_bytes(const unsigned max_payload_bytes)¶

Set the maximum payload size in bytes for transport to and from the device. The payload size must be a multiple of 8 bytes (2 samples) and 1024 <= max_payload_bytes <= 16384. We strongly recommend using the default of 8192, which is compatible with a typical jumbo packet MTU of 9000, or a larger value if you are certain your network cards support it.

Parameters: max_payload_bytes – the maximum payload size in bytes
Returns: true if the size is set, false otherwise

Sensors¶

A subdevice may have sensors to report measurements like temperature, voltage, current, or RF power levels. These functions provide information on any available sensors, and read the sensors.

std::optional<unsigned> vxsdr::get_num_sensors(const uint8_t subdev = 0)¶

Get the number of available sensors.

Parameters: subdev – the subdevice number
Returns: a std::optional with the number of available sensors

std::vector<std::string> vxsdr::get_sensor_names(const uint8_t subdev = 0)¶

Get the names of available sensors.

Parameters: subdev – the subdevice number
Returns: a std::vector of std:strings giving the names

std::optional<double> vxsdr::get_sensor_reading(const std::string &sensor_name, const uint8_t subdev = 0)¶

Get the value of a sensor.

Parameters

sensor_name – the desired sensor name
subdev – the subdevice number

Returns

a std::optional with a double giving the sensor reading

Timing¶

A device maintains time and frequency references for all its subdevices. These are queried and controlled by the functions below.

std::optional<vxsdr::time_point> vxsdr::get_time_now()¶

Get the device time immediately.

Returns: a std::optional with a vxsdr::time_point containing the device time

bool vxsdr::set_time_now(const vxsdr::time_point &t)¶

Set the device time immediately.

Parameters: t – the time to set
Returns: true if the command succeeds, false otherwise

bool vxsdr::set_time_next_pps(const vxsdr::time_point &t)¶

Set the device time at the next PPS received by the device.

Parameters: t – the time to set
Returns: true if the command succeeds, false otherwise; note that the device waits for the next PPS to respond

std::optional<std::array<bool, 3>> vxsdr::get_timing_status()¶

Get the status of the device timing references.

Note that the first two will be false if no external PPS and 10 MHz are connected.

Returns

a std::optional with a std::array containing

the external PPS lock status
external 10 MHz lock status
internal reference oscillator lock status

std::optional<double> vxsdr::get_timing_resolution()¶

Get the resolution of the device’s clock.

Returns: a std::optional with a double containing the resolution in seconds

IP Addressing¶

The device API provides functions to discover devices on a network, and to change a device’s IP address. These functions are not used in normal operation; standalone programs are provided to perform these operations.

bool vxsdr::set_ipv4_address(const std::string &device_address)¶

Set the IPv4 address of the device. This will disconnect the device if the given address is different from its current address. The IP address is not saved to nonvolatile memory in the device by this command.

Parameters: device_address – the device address to set
Returns: true if the address is set, false otherwise

bool vxsdr::save_ipv4_address(const std::string &device_address)¶

Save the IPv4 address of the device to nonvolatile memory in the device. The IP address provided must be the same as the device’s current IP address. A special-purpose program is required to change and save a device’s IP address.

Parameters: device_address – the device address to save
Returns: true if the address is saved, false otherwise

std::vector<std::string> vxsdr::discover_ipv4_addresses(const std::string &local_addr, const std::string &broadcast_addr, const double timeout_s = 10)¶

Broadcast a device discovery packet to the given IPv4 broadcast address, and return the IPv4 addresses of the devices which respond.

Parameters

local_addr – the local address to send from
broadcast_addr – the broadcast address
timeout_s – the time in seconds to wait for responses

Returns

a std::vector containing the IPv4 addresses of discovered devices (which may have zero length if no devices are found)