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, 8>> vxsdr::hello()#

Request basic information from the device.

Returns:

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

  • device type identifier

  • FPGA code version

  • MCU code version,

  • device unique identifier,

  • packet version supported,

  • wire sample data format,

  • number of subdevices,

  • maximum sample payload size in bytes

unsigned vxsdr::compute_sample_granularity(const uint32_t wire_format) const#

Helper function to compute the sample granularity from the wire sample data format returned by hello().

Returns:

the sample granularity

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<unsigned> vxsdr::get_num_subdevices()#

Get the number of subdevices.

Returns:

a std::optional with the number of subdevices

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 sample payload size in bytes, reported by the device, not including any transport limits. Note that for UDP transport, the maximum packet size, which must not exceed the network MTU, is the maximum sample payload size plus the size of the VXSDR packet header, plus the stream spec and time spec, plus the size of the UDP and IPv4 headers. The packet header, stream spec, and time spec are 8 bytes each, the UDP header is 8 bytes, and IPv4 header is typically 20 bytes, for a total of 52 bytes.

Returns:

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

bool vxsdr::set_max_payload_bytes(const unsigned max_payload_bytes)#

Set the maximum sample payload size in bytes for transport to and from the device. The sample payload size must be greater than or equal to 1024 and less than or equal to the minimum of (device_maximum_payload, transport_maximum_payload, 16384), and will be adjusted to match the device’s sample granularity. For UDP transport, we strongly recommend using the UDP default of 8192, which is compatible with a typical jumbo packet MTU of 9000; only use a larger value if you are certain your network card supports it. A larger MTU can be specified using the udp_data_transport:mtu_bytes setting. If you use this setting, you are promising the library that your network supports this MTU; the library will check with the device for its maximum, but there is no reliable way for the library to determine network MTUs.

Parameters:

max_payload_bytes – the maximum sample payload size in bytes

Returns:

true if the requested 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::optional<std::string> vxsdr::get_sensor_name(const unsigned sensor_number, const uint8_t subdev = 0)#

Get the name of a sensor.

Parameters:

  • sensor_number – the sensor number

  • subdev – the subdevice number

Returns:

a std::optional with a std:string giving the name

std::optional<double> vxsdr::get_sensor_reading(const unsigned sensor_number, const uint8_t subdev = 0)#

Get the value of a sensor.

Parameters:

  • sensor_number – the desired sensor number

  • 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, so this command may not return for nearly 1 second

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

Get the status of the device timing references, where true means the device detects or is locked to that reference, and false means not present or not locked. Although the external PPS status indicates whether the PPS is present, the set_time_next_pps command must be used to align the internal clock with the external PPS. Note that the first two values returned will be false in normal operation if no external PPS and 10 MHz are connected.

Returns:

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

  • the external PPS 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, clamped to the range [1e-3, 600] seconds

Returns:

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