Intel® RealSense™ Cross Platform API
Intel Realsense Cross-platform API
Macros | Functions
rs_device.h File Reference

Exposes RealSense device functionality for C compilers. More...

#include "rs_types.h"
#include "rs_sensor.h"

Go to the source code of this file.

Macros

#define RS2_UNSIGNED_UPDATE_MODE_UPDATE   0
 
#define RS2_UNSIGNED_UPDATE_MODE_READ_ONLY   1
 
#define RS2_UNSIGNED_UPDATE_MODE_FULL   2
 

Functions

int rs2_get_device_count (const rs2_device_list *info_list, rs2_error **error)
 
void rs2_delete_device_list (rs2_device_list *info_list)
 
int rs2_device_list_contains (const rs2_device_list *info_list, const rs2_device *device, rs2_error **error)
 
rs2_devicers2_create_device (const rs2_device_list *info_list, int index, rs2_error **error)
 
void rs2_delete_device (rs2_device *device)
 
const char * rs2_get_device_info (const rs2_device *device, rs2_camera_info info, rs2_error **error)
 
int rs2_supports_device_info (const rs2_device *device, rs2_camera_info info, rs2_error **error)
 
void rs2_hardware_reset (const rs2_device *device, rs2_error **error)
 
const rs2_raw_data_bufferrs2_send_and_receive_raw_data (rs2_device *device, void *raw_data_to_send, unsigned size_of_raw_data_to_send, rs2_error **error)
 
int rs2_is_device_extendable_to (const rs2_device *device, rs2_extension extension, rs2_error **error)
 
rs2_sensor_listrs2_query_sensors (const rs2_device *device, rs2_error **error)
 
void rs2_loopback_enable (const rs2_device *device, const char *from_file, rs2_error **error)
 
void rs2_loopback_disable (const rs2_device *device, rs2_error **error)
 
int rs2_loopback_is_enabled (const rs2_device *device, rs2_error **error)
 
void rs2_connect_tm2_controller (const rs2_device *device, const unsigned char *mac_addr, rs2_error **error)
 
void rs2_disconnect_tm2_controller (const rs2_device *device, int id, rs2_error **error)
 
void rs2_reset_to_factory_calibration (const rs2_device *device, rs2_error **e)
 
void rs2_write_calibration (const rs2_device *device, rs2_error **e)
 
void rs2_update_firmware_cpp (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback *callback, rs2_error **error)
 
void rs2_update_firmware (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
 
const rs2_raw_data_bufferrs2_create_flash_backup_cpp (const rs2_device *device, rs2_update_progress_callback *callback, rs2_error **error)
 
const rs2_raw_data_bufferrs2_create_flash_backup (const rs2_device *device, rs2_update_progress_callback_ptr callback, void *client_data, rs2_error **error)
 
void rs2_update_firmware_unsigned_cpp (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback *callback, int update_mode, rs2_error **error)
 
void rs2_update_firmware_unsigned (const rs2_device *device, const void *fw_image, int fw_image_size, rs2_update_progress_callback_ptr callback, void *client_data, int update_mode, rs2_error **error)
 
void rs2_enter_update_state (const rs2_device *device, rs2_error **error)
 
const rs2_raw_data_bufferrs2_run_on_chip_calibration_cpp (rs2_device *device, const void *json_content, int content_size, float *health, rs2_update_progress_callback *progress_callback, int timeout_ms, rs2_error **error)
 
const rs2_raw_data_bufferrs2_run_on_chip_calibration (rs2_device *device, const void *json_content, int content_size, float *health, rs2_update_progress_callback_ptr callback, void *client_data, int timeout_ms, rs2_error **error)
 
const rs2_raw_data_bufferrs2_run_tare_calibration_cpp (rs2_device *dev, float ground_truth_mm, const void *json_content, int content_size, rs2_update_progress_callback *progress_callback, int timeout_ms, rs2_error **error)
 
const rs2_raw_data_bufferrs2_run_tare_calibration (rs2_device *dev, float ground_truth_mm, const void *json_content, int content_size, rs2_update_progress_callback_ptr callback, void *client_data, int timeout_ms, rs2_error **error)
 
const rs2_raw_data_bufferrs2_get_calibration_table (const rs2_device *dev, rs2_error **error)
 
void rs2_set_calibration_table (const rs2_device *device, const void *calibration, int calibration_size, rs2_error **error)
 
rs2_raw_data_bufferrs2_serialize_json (rs2_device *dev, rs2_error **error)
 
void rs2_load_json (rs2_device *dev, const void *json_content, unsigned content_size, rs2_error **error)
 

Detailed Description

Exposes RealSense device functionality for C compilers.

Macro Definition Documentation

◆ RS2_UNSIGNED_UPDATE_MODE_FULL

#define RS2_UNSIGNED_UPDATE_MODE_FULL   2

◆ RS2_UNSIGNED_UPDATE_MODE_READ_ONLY

#define RS2_UNSIGNED_UPDATE_MODE_READ_ONLY   1

◆ RS2_UNSIGNED_UPDATE_MODE_UPDATE

#define RS2_UNSIGNED_UPDATE_MODE_UPDATE   0

Function Documentation

◆ rs2_connect_tm2_controller()

void rs2_connect_tm2_controller ( const rs2_device device,
const unsigned char *  mac_addr,
rs2_error **  error 
)

Connects to a given tm2 controller

Parameters
[in]deviceDevice to connect to the controller
[in]mac_addrThe MAC address of the desired controller
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_create_device()

rs2_device* rs2_create_device ( const rs2_device_list info_list,
int  index,
rs2_error **  error 
)

Creates a device by index. The device object represents a physical camera and provides the means to manipulate it.

Parameters
[in]info_listthe list containing the device to retrieve
[in]indexThe zero based index of device to retrieve
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
The requested device, should be released by rs2_delete_device

◆ rs2_create_flash_backup()

const rs2_raw_data_buffer* rs2_create_flash_backup ( const rs2_device device,
rs2_update_progress_callback_ptr  callback,
void *  client_data,
rs2_error **  error 
)

Create backup of camera flash memory. Such backup does not constitute valid firmware image, and cannot be loaded back to the device, but it does contain all calibration and device information.

Parameters
[in]deviceDevice to update
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]client_dataOptional client data for the callback
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_create_flash_backup_cpp()

const rs2_raw_data_buffer* rs2_create_flash_backup_cpp ( const rs2_device device,
rs2_update_progress_callback callback,
rs2_error **  error 
)

Create backup of camera flash memory. Such backup does not constitute valid firmware image, and cannot be loaded back to the device, but it does contain all calibration and device information.

Parameters
[in]deviceDevice to update
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_delete_device()

void rs2_delete_device ( rs2_device device)

Delete RealSense device

Parameters
[in]deviceRealsense device to delete

◆ rs2_delete_device_list()

void rs2_delete_device_list ( rs2_device_list info_list)

Deletes device list, any devices created using this list will remain unaffected.

Parameters
[in]info_listList to delete

◆ rs2_device_list_contains()

int rs2_device_list_contains ( const rs2_device_list info_list,
const rs2_device device,
rs2_error **  error 
)

Checks if a specific device is contained inside a device list.

Parameters
[in]info_listThe list of devices to check in
[in]deviceRealSense device to check for
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
True if the device is in the list and false otherwise

◆ rs2_disconnect_tm2_controller()

void rs2_disconnect_tm2_controller ( const rs2_device device,
int  id,
rs2_error **  error 
)

Disconnects a given tm2 controller

Parameters
[in]deviceDevice to disconnect the controller from
[in]idThe ID of the desired controller
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_enter_update_state()

void rs2_enter_update_state ( const rs2_device device,
rs2_error **  error 
)

Enter the device to update state, this will cause the updatable device to disconnect and reconnect as update device.

Parameters
[in]deviceDevice to update
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_get_calibration_table()

const rs2_raw_data_buffer* rs2_get_calibration_table ( const rs2_device dev,
rs2_error **  error 
)

Read current calibration table from flash.

Returns
Calibration table

◆ rs2_get_device_count()

int rs2_get_device_count ( const rs2_device_list info_list,
rs2_error **  error 
)

Determines number of devices in a list.

Parameters
[in]info_listThe list of connected devices captured using rs2_query_devices
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Device count

◆ rs2_get_device_info()

const char* rs2_get_device_info ( const rs2_device device,
rs2_camera_info  info,
rs2_error **  error 
)

Retrieve camera specific information, like versions of various internal components.

Parameters
[in]deviceThe RealSense device
[in]infoCamera info type to retrieve
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
The requested camera info string, in a format specific to the device model

◆ rs2_hardware_reset()

void rs2_hardware_reset ( const rs2_device device,
rs2_error **  error 
)

Send hardware reset request to the device. The actual reset is asynchronous. Note: Invalidates all handles to this device.

Parameters
[in]deviceThe RealSense device to reset
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_is_device_extendable_to()

int rs2_is_device_extendable_to ( const rs2_device device,
rs2_extension  extension,
rs2_error **  error 
)

Test if the given device can be extended to the requested extension.

Parameters
[in]deviceRealsense device
[in]extensionThe extension to which the device should be tested if it is extendable
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Non-zero value iff the device can be extended to the given extension

◆ rs2_load_json()

void rs2_load_json ( rs2_device dev,
const void *  json_content,
unsigned  content_size,
rs2_error **  error 
)

◆ rs2_loopback_disable()

void rs2_loopback_disable ( const rs2_device device,
rs2_error **  error 
)

Restores the given device into normal operation mode

Parameters
[in]deviceDevice to restore to normal operation mode
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_loopback_enable()

void rs2_loopback_enable ( const rs2_device device,
const char *  from_file,
rs2_error **  error 
)

Enter the given device into loopback operation mode that uses the given file as input for raw data

Parameters
[in]deviceDevice to enter into loopback operation mode
[in]from_filePath to bag file with raw data for loopback
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_loopback_is_enabled()

int rs2_loopback_is_enabled ( const rs2_device device,
rs2_error **  error 
)

Checks if the device is in loopback mode or not

Parameters
[in]deviceDevice to check for operation mode
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
true if the device is in loopback operation mode

◆ rs2_query_sensors()

rs2_sensor_list* rs2_query_sensors ( const rs2_device device,
rs2_error **  error 
)

Create a static snapshot of all connected sensors within a specific device.

Parameters
[in]deviceSpecific RealSense device
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
The list of sensors, should be released by rs2_delete_sensor_list

◆ rs2_reset_to_factory_calibration()

void rs2_reset_to_factory_calibration ( const rs2_device device,
rs2_error **  e 
)

Reset device to factory calibration

Parameters
[in]deviceThe RealSense device
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_run_on_chip_calibration()

const rs2_raw_data_buffer* rs2_run_on_chip_calibration ( rs2_device device,
const void *  json_content,
int  content_size,
float *  health,
rs2_update_progress_callback_ptr  callback,
void *  client_data,
int  timeout_ms,
rs2_error **  error 
)

This will improve the depth noise.

Parameters
[in]json_contentJson string to configure speed on chip calibration parameters: { "speed": 3, "scan parameter": 0, "data sampling": 0 } speed - value can be one of: Very fast = 0, Fast = 1, Medium = 2, Slow = 3, White wall = 4, default is Slow scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 if json is nullptr it will be ignored and calibration will use the default parameters
[out]healthCalibration Health-Check captures how far camera calibration is from the optimal one [0, 0.25) - Good [0.25, 0.75) - Can be Improved [0.75, ) - Requires Calibration
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]client_dataOptional client data for the callback
[in]timeout_msTimeout in ms (use 5000 msec unless instructed otherwise)
Returns
New calibration table

◆ rs2_run_on_chip_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_on_chip_calibration_cpp ( rs2_device device,
const void *  json_content,
int  content_size,
float *  health,
rs2_update_progress_callback progress_callback,
int  timeout_ms,
rs2_error **  error 
)

This will improve the depth noise.

Parameters
[in]json_contentJson string to configure speed on chip calibration parameters: { "speed": 3, "scan parameter": 0, "data sampling": 0 } speed - value can be one of: Very fast = 0, Fast = 1, Medium = 2, Slow = 3, White wall = 4, default is Slow scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 if json is nullptr it will be ignored and calibration will use the default parameters
[out]healthCalibration Health-Check captures how far camera calibration is from the optimal one [0, 0.25) - Good [0.25, 0.75) - Can be Improved [0.75, ) - Requires Calibration
[in]callbackOptional callback to get progress notifications
[in]timeout_msTimeout in ms (use 5000 msec unless instructed otherwise)
Returns
New calibration table

◆ rs2_run_tare_calibration()

const rs2_raw_data_buffer* rs2_run_tare_calibration ( rs2_device dev,
float  ground_truth_mm,
const void *  json_content,
int  content_size,
rs2_update_progress_callback_ptr  callback,
void *  client_data,
int  timeout_ms,
rs2_error **  error 
)

This will adjust camera absolute distance to flat target. User needs to enter the known ground truth.

Parameters
[in]ground_truth_mmGround truth in mm must be between 2500 - 2000000
[in]json_contentJson string to configure tare calibration parameters: { "average_step_count": 20, "step count": 20, "accuracy": 2, "scan parameter": 0, "data sampling": 0 } average step count - number of frames to average, must be between 1 - 30, default = 20 step count - max iteration steps, must be between 5 - 30, default = 10 accuracy - Subpixel accuracy level, value can be one of: Very high = 0 (0.025%), High = 1 (0.05%), Medium = 2 (0.1%), Low = 3 (0.2%), Default = Very high (0.025%), default is very high (0.025%) scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 if json is nullptr it will be ignored and calibration will use the default parameters
[in]content_sizeJson string size if its 0 the json will be ignored and calibration will use the default parameters
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]client_dataOptional client data for the callback
[in]timeout_msTimeout in ms (use 5000 msec unless instructed otherwise)
Returns
New calibration table

◆ rs2_run_tare_calibration_cpp()

const rs2_raw_data_buffer* rs2_run_tare_calibration_cpp ( rs2_device dev,
float  ground_truth_mm,
const void *  json_content,
int  content_size,
rs2_update_progress_callback progress_callback,
int  timeout_ms,
rs2_error **  error 
)

This will adjust camera absolute distance to flat target. User needs to enter the known ground truth.

Parameters
[in]ground_truth_mmGround truth in mm must be between 2500 - 2000000
[in]json_contentJson string to configure tare calibration parameters: { "average step count": 20, "step count": 20, "accuracy": 2, "scan parameter": 0, "data sampling": 0 } average step count - number of frames to average, must be between 1 - 30, default = 20 step count - max iteration steps, must be between 5 - 30, default = 10 accuracy - Subpixel accuracy level, value can be one of: Very high = 0 (0.025%), High = 1 (0.05%), Medium = 2 (0.1%), Low = 3 (0.2%), Default = Very high (0.025%), default is very high (0.025%) scan_parameter - value can be one of: Py scan (default) = 0, Rx scan = 1 data_sampling - value can be one of:polling data sampling = 0, interrupt data sampling = 1 if json is nullptr it will be ignored and calibration will use the default parameters
[in]content_sizeJson string size if its 0 the json will be ignored and calibration will use the default parameters
[in]callbackOptional callback to get progress notifications
[in]timeout_msTimeout in ms (use 5000 msec unless instructed otherwise)
Returns
New calibration table

◆ rs2_send_and_receive_raw_data()

const rs2_raw_data_buffer* rs2_send_and_receive_raw_data ( rs2_device device,
void *  raw_data_to_send,
unsigned  size_of_raw_data_to_send,
rs2_error **  error 
)

Send raw data to device

Parameters
[in]deviceRealSense device to send data to
[in]raw_data_to_sendRaw data to be sent to device
[in]size_of_raw_data_to_sendSize of raw_data_to_send in bytes
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
Device's response in a rs2_raw_data_buffer, which should be released by rs2_delete_raw_data

◆ rs2_serialize_json()

rs2_raw_data_buffer* rs2_serialize_json ( rs2_device dev,
rs2_error **  error 
)

◆ rs2_set_calibration_table()

void rs2_set_calibration_table ( const rs2_device device,
const void *  calibration,
int  calibration_size,
rs2_error **  error 
)

Set current table to dynamic area.

Parameters
[in]Calibrationtable

◆ rs2_supports_device_info()

int rs2_supports_device_info ( const rs2_device device,
rs2_camera_info  info,
rs2_error **  error 
)

Check if a camera supports a specific camera info type.

Parameters
[in]deviceThe RealSense device to check
[in]infoThe parameter to check for support
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored
Returns
True if the parameter both exist and well-defined for the specific device

◆ rs2_update_firmware()

void rs2_update_firmware ( const rs2_device device,
const void *  fw_image,
int  fw_image_size,
rs2_update_progress_callback_ptr  callback,
void *  client_data,
rs2_error **  error 
)

Update device to the provided firmware, the device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters
[in]deviceDevice to update
[in]fw_imageFirmware image buffer
[in]fw_image_sizeFirmware image buffer size
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]client_dataOptional client data for the callback
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_update_firmware_cpp()

void rs2_update_firmware_cpp ( const rs2_device device,
const void *  fw_image,
int  fw_image_size,
rs2_update_progress_callback callback,
rs2_error **  error 
)

Update device to the provided firmware, the device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters
[in]deviceDevice to update
[in]fw_imageFirmware image buffer
[in]fw_image_sizeFirmware image buffer size
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_update_firmware_unsigned()

void rs2_update_firmware_unsigned ( const rs2_device device,
const void *  fw_image,
int  fw_image_size,
rs2_update_progress_callback_ptr  callback,
void *  client_data,
int  update_mode,
rs2_error **  error 
)

Update device to the provided firmware by writing raw data directly to the flash, this command can be executed only on unlocked camera. The device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters
[in]deviceDevice to update
[in]fw_imageFirmware image buffer
[in]fw_image_sizeFirmware image buffer size
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]client_dataOptional client data for the callback
[in]update_modeSelect one of RS2_UNSIGNED_UPDATE_MODE, WARNING!!! setting to any option other than RS2_UNSIGNED_UPDATE_MODE_UPDATE will make this call unsafe and might damage the camera
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_update_firmware_unsigned_cpp()

void rs2_update_firmware_unsigned_cpp ( const rs2_device device,
const void *  fw_image,
int  fw_image_size,
rs2_update_progress_callback callback,
int  update_mode,
rs2_error **  error 
)

Update device to the provided firmware by writing raw data directly to the flash, this command can be executed only on unlocked camera. The device must be extendable to RS2_EXTENSION_UPDATABLE. This call is executed on the caller's thread and it supports progress notifications via the optional callback.

Parameters
[in]deviceDevice to update
[in]fw_imageFirmware image buffer
[in]fw_image_sizeFirmware image buffer size
[in]callbackOptional callback for update progress notifications, the progress value is normailzed to 1
[in]update_modeSelect one of RS2_UNSIGNED_UPDATE_MODE, WARNING!!! setting to any option other than RS2_UNSIGNED_UPDATE_MODE_UPDATE will make this call unsafe and might damage the camera
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored

◆ rs2_write_calibration()

void rs2_write_calibration ( const rs2_device device,
rs2_error **  e 
)

Write calibration to device's EEPROM

Parameters
[in]deviceThe RealSense device
[out]errorIf non-null, receives any error that occurs during this call, otherwise, errors are ignored