#include <uhd/cal/database.hpp>

Detailed Description

Calibration Data Storage/Retrieval Class

UHD can store calibration data on disk or compiled within UHD. This class provides access to both locations.

Format of binary data

This class can read and write binary data, but it does not verify the data or expect any kind of format. It simply manages BLOBs (binary large objects). It is up to the consumers and producers of this data to agree on a format. Typically, since this class stores calibration data, it will be consuming data that was produced by uhd::usrp::cal::container::serialize().

Serial number and key

Calibration data is indexed by two keys: An arbitrary key that describes the type of calibration data (e.g., "rx_iq") and a serial number. The serial number has to uniquely identify the device for which the calibration data was obtained. This can either be the serial number of the daughterboard (if the calibration data only relates to the daughterboard), the motherboard (for example, if there is no such thing as a daughterboard, or the data only relates to the motherboard), it can be combination of both daughterboard and motherboard serial (if the calibration data is only valid for a combination), or it can be a combination of a device serial number and a channel index (if a device with single serial has different channels that have separate characteristics).

It is up to the individual device drivers which value they use for the serial numbers and keys.

Note that the serial number is irrelevant when the data is pulled out of the resource compiler. By definition, it is not permitted to store data in the resource compiler that is specific to a certain serial number, only data that applies to an entire family of devices is permitted.

Public Types
using	has_data_fn_type = std::function< bool(const std::string &, const std::string &)>
	Function type to look up if there is cal data given a key and serial. More...

using	get_data_fn_type = std::function< std::vector< uint8_t >(const std::string &, const std::string &)>
	Function type to return serialized cal data key and serial. More...

Static Public Member Functions
static std::vector< uint8_t >	read_cal_data (const std::string &key, const std::string &serial, const source source_type=source::ANY)
	Return a calibration data set as a serialized string. More...

static bool	has_cal_data (const std::string &key, const std::string &serial, const source source_type=source::ANY)
	Check if calibration data exists for a given source type. More...

static void	write_cal_data (const std::string &key, const std::string &serial, const std::vector< uint8_t > &cal_data, const std::string &backup_ext="")
	Store calibration data to the local filesystem database. More...

static void	register_lookup (has_data_fn_type has_cal_data, get_data_fn_type get_cal_data, const source source_type=source::FLASH)
	Register a lookup function for cal data. More...

Member Typedef Documentation

◆ get_data_fn_type

using uhd::usrp::cal::database::get_data_fn_type = std::function<std::vector<uint8_t>(const std::string&, const std::string&)>

Function type to return serialized cal data key and serial.

These functions should throw a uhd::runtime_error if called with invalid key/serial pairs, although database will internally always call the corresponding 'has' function before calling this.

◆ has_data_fn_type

using uhd::usrp::cal::database::has_data_fn_type = std::function<bool(const std::string&, const std::string&)>

Function type to look up if there is cal data given a key and serial.

Member Function Documentation

◆ has_cal_data()

static bool uhd::usrp::cal::database::has_cal_data	(	const std::string &	key,
		const std::string &	serial,
		const source	source_type = `source::ANY`
	)

static

Check if calibration data exists for a given source type.

This can be called before calling read_cal_data() to avoid having to catch an exception. If source_type is FILESYSTEM, then it will only return true if a file is found with the appropriate cal data. The same is true for RC. If is ANY, then having either RC or FILESYSTEM data will yield true.

Parameters

key	The calibration type key (e.g., "rx_iq")
serial	The serial number of the device this data is for. See also Serial number and key
source_type	Where to read the calibration data from. For anything other than RC, FILESYSTEM, or ANY, this will always return false because this class does not have access to user data or EEPROM data.

Returns: true if calibration data is available that matches this key/serial pair.

◆ read_cal_data()

static std::vector<uint8_t> uhd::usrp::cal::database::read_cal_data	(	const std::string &	key,
		const std::string &	serial,
		const source	source_type = `source::ANY`
	)

static

Return a calibration data set as a serialized string.

Note: the source_type parameter can be used to specify where to read cal data from. However, this class only has access to RC and FILESYSTEM type cal data. ANY will pick FILESYSTEM data if both are available, and RC data if only RC data is available.

Parameters

key	The calibration type key (e.g., "rx_iq")
serial	The serial number of the device this data is for. See also Serial number and key
source_type	Where to read the calibration data from. See comments above. For anything other than RC, FILESYSTEM, or ANY, this will always throw a uhd::key_error because this class does not have access to user data or EEPROM data.

Exceptions

uhd::key_error if no calibration data is found matching the source type.

◆ register_lookup()

static void uhd::usrp::cal::database::register_lookup	(	has_data_fn_type	has_cal_data,
		get_data_fn_type	get_cal_data,
		const source	source_type = `source::FLASH`
	)

static

Register a lookup function for cal data.

Parameters

has_cal_data	A function object to a function that returns true if cal data is available
get_cal_data	A function object to a function that returns serialized cal data
source_type	Reserved. Must be source::FLASH.

◆ write_cal_data()

static void uhd::usrp::cal::database::write_cal_data	(	const std::string &	key,
		const std::string &	serial,
		const std::vector< uint8_t > &	cal_data,
		const std::string &	backup_ext = `""`
	)

static

Store calibration data to the local filesystem database.

This implies a source type of FILESYSTEM. Note that writing the data does not apply it to a currently running UHD session. Devices will typically load calibration data at initialization time, and thus this call will take effect only for future UHD sessions.

If calibration data for this key/serial pair already exists in the database, the original data will be backed up by renaming the original file from filename.cal to filename.cal.$TIMESTAMP. Alternatively, a custom extension can be chosen instead of $TIMESTAMP.

Parameters

key	The calibration type key (e.g., "rx_iq")
serial	The serial number of the device this data is for. See also Serial number and key
cal_data	The calibration data to be written
backup_ext	A custom extension for backing up calibration data. If left empty, a POSIX timestamp is used.

The documentation for this class was generated from the following file:

database.hpp

Detailed Description

Format of binary data

Serial number and key

Public Types

Static Public Member Functions

Member Typedef Documentation

◆ get_data_fn_type

◆ has_data_fn_type

Member Function Documentation

◆ has_cal_data()

◆ read_cal_data()

◆ register_lookup()

◆ write_cal_data()