Sensor configuration file

The configuration file is used to identify the cameras and sensors to use on your system. You can have multiple sensors and cameras physically connected to the board, but your system only uses the ones identified in this configuration file.

You can configure as few as one camera or sensor. For testing purposes, you can simulate a camera or sensor by specifying a file. The file can contain sensor information, such as lidar data or compressed/uncompressed video for playback.

The configuration for sensors and cameras is specified in a section enclosed by begin SENSUNIT and end SENSUNIT, where SENSUNIT is a enumerator from sensor_unit_t (Sensor library), such as SENSOR_UNIT_1. For more information about sensor_unit_t, see the “sensor_unit_t” section in the Sensor Library chapter of the Sensor Library Developer's Guide. If you are using the Camera Library API, you map the enumerator for the camera_unit_t to the corresponding enumerator from the sensor_unit_t data type. For example, for CAMERA_UNIT_1, you would map it to SENSOR_UNIT_1. The identifiers you use must follow these rules:

one sensor must be named SENSOR_UNIT_1
the name can appear only once in the file
there are no gaps between the numeric part of the identifiers you use

For example, you can't name your second sensor SENSOR_UNIT_5, it should be named SENSOR_UNIT_2. Though it isn't necessary to order your definitions in numeric order within the file, it is recommended that you do so to make it easier to read and maintain the file. For example, the following is valid configuration for three sensors, which follow the rules mentioned previously:

begin SENSOR_UNIT_3
    type = file_camera
    name = left
    address = /accounts/1000/shared/videos/frontviewvideo1.mp4
    default_video_format = rgb8888
    default_video_resolution = 640, 480
end SENSOR_UNIT_3
begin SENSOR_UNIT_1
    type = file_data
    name = vlp-16
    address = /accounts/1000/shared/videos/capture_data.mp4
    playback_group = 1
    direction = 0,0,0
    position = 1000,0,1100
end SENSOR_UNIT_1
begin SENSOR_UNIT_2
    type = radar
    name = front
    direction = 0,0,0
    position = 3760,0,0
    address = /dev/usb/io-usb-otg, -1, -1, -1, -1, 0, delphi_esr
    packet_size = 64
    data_format = SENSOR_FORMAT_RADAR_POLAR
end SENSOR_UNIT_2

Parameters:

There are required and optional parameters that you can use to configure a camera or sensor for your system. The required parameters you need depend on the type you choose. The name, position, and direction specified for each are useful when an application wants to know more information about the camera or sensor. To get this information, an application can call sensor_get_location_property() (Sensor library) or camera_get_location_property() (Camera library) to retrieve the values.

type

(Required) The type of sensor or camera. The values for the supported sensors are as follows:

usb_camera — Indicates that the camera is connected to the system via a USB interface. Cameras must be compliant to the USB Video Class (UVC) or USB3 Vision standard.
sensor_camera — Indicates that the camera sensor is directly connected to a native video port on the board, such as CSI2 or parallel port.
ip_camera — Indicates that the camera is connected to the system via an Ethernet interface.
file_camera — Simulates a camera connected to the board. The video file that's created comes from recorded data from the Camera or Sensor library. This is useful for testing purposes during the development phase of your project. The specified video file plays in a loop. The supported formats are uncompressed (RAW), LZ4, a GZIP-compressed format (GZ), MOV, UCV (UnCompressed Video), and MP4. UCV is a propriety format. The recorded video can be uncompressed video in MOV format, UCV file format, or H.264-encoded video in the MP4 format.
file_data — Simulates a sensor (non-camera) connected to the board. The file that's provided is recorded data from a sensor (e.g., GPS, radar, lidar) using the Sensor library and loops continuously when played. The data from the sensor can be an uncompressed format (RAW) or lossless compression formats, such as a GZIP (GZ) or a LZ4 file. This parameter is useful for testing purposes.
radar — Indicates that radar is connected to the board.
lidar — Indicates that lidar is connected to the board.
gps — Indicates that a GPS is connected to the board.
imu — Indicates that a IMU is connected to the board.
external_camera — Indicates that an external camera is being used. Specify the library (external camera driver) that you provide to support this camera in the address parameter in this configuration file.
external_sensor — Indicates that an external sensor is being used. Specify the library (external sensor driver) that you provide to support this sensor in the address parameter in this configuration file.

address

(Required) Depending on the type of sensor that's connected, this parameter is used to refine the identity of the sensor, especially in systems where you have more than one sensor of the same type connected to your system. For example, if you have more than one USB camera connected, this parameter can help to identify which one is currently in use.

Based on the sensor configured for the type, here are the formats you should use:

Type	Format for address
`usb_camera`	`driver_path, bus, device, vendorID, deviceID`	This format is necessary to identify the camera when you have more than one USB camera connected to your system. You can use a wild card (-1) to accept any USB camera found on the system. If you have only one USB camera connected, using a wild card value of `-1` for all fields correctly works, however, if you have more than one USB camera, you must specify non-wild card values for at least the `bus`/`device` parameter pair or `vendorID`/`deviceID`. For example, if you have more than one camera of the same make or model, you must specify the `bus` and `device` because specifying `vendorID`/`deviceID` parameter doesn't uniquely identify the camera. The `driver_path` specifies the path of the driver that's used for cameras on the system. You must specify this parameter (e.g., /dev/usb/io-usb-otg). The `bus` and `device` values are unique and are dependent on which port you use to connect the cable on your hardware. These values are useful to describe the position of the device on the bus. It's up to you to determine how this is relevant to your system. `vendorID` and `deviceID` identify the device's vendor and identifier. The numbers are USB-standard identifiers that specify the USB camera to use.
`sensor_camera`	`cameraId, input`	This format is necessary to identify a specific sensor camera when you have more than one camera connected to the system. The format that's used to identify the sensor camera is as follows: `cameraId` — A string that identifies the sensor camera. You can use the value of `rdacm21_max9286` (for a RDACM21 camera that's connected to a Maxim 9286 deserializer). `input` — A number that specifies the camera to use for deserializer boards. Set this value to 0 for the first camera, 1 for the second camera, etc.
`file_camera`	`/path/to/file/video.mp4`	This format can be a RAW, LZ4, GZ, MP4 (H.264 encoded video), UCV, or MOV (uncompressed video) file. The prerecorded file can be created using APIs from the Camera or Sensor library.
`file_data`	`/path/to/file/data.lz4`	Prerecorded file containing sensor data, which can be raw binary (RAW). It can be also encoded (lossless compression) as a GZIP (GZ) or LZ4 file.
`imu`	`driver_path`, `bus, device, vendorID, deviceID, model` or `driver_path`, `model`	You can use a wild card (-1) to accept any IMU found on the system. If you have only one IMU connected, using a wild card value of `-1` for all fields correctly works, however, if you have more than one IMU connected, you must specify non-wild card values for at least the `vendorID`/`deviceID` parameter pair or `vendorID`/`deviceID`. For example, if you have more than one sensor of the same make or model, you must specify the `bus` and `device` because specifying `vendorID`/`deviceID` parameter doesn't uniquely identify the sensor. The `driver_path` specifies the path of the driver that's used for sensors on the system. You must specify this parameter (e.g., /dev/usb/io-usb-otg. /dev/serusb1). The `bus` and `device` values are unique and are dependent on which port you use to connect the cable on your hardware. These values are useful to describe the position of the device on the bus. The values are hardware-specific. `vendorID` and `deviceID` identify the device's vendor and identifier. The `model` specifies the specific make and model of the sensor (e.g., `xsens_mti-g-710`, `novatel_oem6`).
`ip_camera`	`ip_address`, `type_of_camera`, `[serial_num]`	The `ip_address` segment represents the IP address of the camera. If you don't know the IP address, use `0.0.0.0` to use auto-discovery. When you use auto-discovery, the optional `serial_num` segment isn't required. When you use a valid IP address, you don't need to specify a value in the `serial_num` segment. The `type_of_camera` segment specifies the camera type, which can be `onvif` for an ONVIF-compliant camera or `gige_vision` for a GigE vision-compliant camera. The `serial_num` is an optional segment. It represents the serial number of the camera. When you use auto-discovery (i.e., you had configured the `ip_address` segment to `0.0.0.0`), it matches the specified serial number. If this segment is left blank when using auto-discovery, the first camera that's found on the system is used, which is typical when you have one camera connected to your system.
`lidar`	`ip_address`, `ip_based_lidar_model` or `serial_driver_path`, `device_address`, `serial_based_lidar_model`	When you want to configure an IP-based lidar, the `ip_address` segment must be a valid IP address because it broadcasts the data over UDP. For the `ip_based_lidar_model` segment, you can use the string `velodyne_vlp-16` or `velodyne_vlp-16-high-res` to the IP-based lidar from Velodyne. Ensure that you use the string to match the model that you have connected to your target. When you want to configure serial-based lidar, the `serial_driver_path` segment is specified as a /dev/ser`X` (where `X` is the prt and depends on your configuration). For the `device_address` segment, specify the device address assigned to the lidar. For the `lidar_model` segment, you can use `leddartech_vu8` to specify a serial-based lidar from Leddartech.
`radar`	`driver_path`, `bus, device, vendorID, deviceID, channelID, model`	This format is necessary to identify the radar system when you have more than one radar sensor to your system. You can use a wild card (`-1`) to accept any radar system connected to the system. If you have only one radar sensor connected, using a wild card value of `-1` for all fields correctly works, however, if you have more than one radar sensor, you must specify non-wild card values for at least the `bus`/`device` parameter pair or `deviceID`. For example, if you have more than one radar sensor of the same make/model, you must specify the `bus` and `device` because specifying the `deviceID` parameter doesn't uniquely identify the radar. The `driver_path` specifies the path of the driver that's used for sensors on the system. You must specify this parameter (e.g., /dev/usb/io-usb-otg). The `bus` and `device` values are unique and are dependent on where you connect the USB cable on your board. The values are useful to describe the position of the radar on the USB bus. It's up to you to determine how this is relevant to your system. The `channelID` identifies the channel on the USB to CAN adapter to which the sensor is connected. For example, in the case of the Kvaser USB to CAN adapter, channel 0 or 1 can be specified. The `vendorID` and `deviceID` identifies the Kvaser cable.. The `model` specifies the specific make and model of the sensor (e.g., `delphi_esr`, `delphi_srr2_right`, `delphi_srr2_left`).
`gps`	`driver_path`, `bus, device, vendorID, deviceID, model` or `driver_path`, `model`	You can use a wild card (-1) to accept any GPS system found on the system. If you have only one GPS system connected, using a wild card value of `-1` for all fields correctly works, however, if you have more than one GPS unit connected, you must specify non-wild card values for at least the `vendorID`/`deviceID` parameter pair or `vendorID`/`deviceID`. For example, if you have more than one sensor of the same make or model, you must specify the `bus` and `device` because specifying `vendorID`/`deviceID` parameter doesn't uniquely identify the sensor. The `driver_path` specifies the path of the driver that's used for sensors on the system. You must specify this parameter (e.g., /dev/usb/io-usb-otg, /dev/serusb1). The `bus` and `device` values are unique and are dependent on which port you use to connect the cable on your hardware. These values are useful to describe the position of the device on the bus. It's up to you to determine how this is relevant to your system. `vendorID` and `deviceID` identify the device's vendor and identifier. The `model` specifies the specific make and model of the sensor (e.g., `xsens_mti-g-710`, `novatel_oem6`). .
`external_camera`	`driver_path`, `input`	The `driver_path` specifies the path of the user-provided library that's used for the external cameras on the system. This library must provide implementation according to the functions defined in external_camera_api.h. See “Using external camera drivers” in the Camera Developer's Guide. The `input` specifies the value that the Sensor service passes to open_external_camera() as the input parameter to identify the camera to use when your driver supports multiple cameras.
`external_sensor`	`driver_path`	The `driver_path` specifies the path of the user-provided library that's used for external sensors on the system. This library must provide implementation according to the functions defined in external_sensor_api.h. See “Using external sensor drivers” in the Sensor Developer's Guide.

coordinate_system

(Optional for sensors whose type are gps, imu, lidar, or radar) The indication of whether the sensor data you receive through the Sensor library is transformed to your reference coordinate system based on each sensor's position and direction. Valid values are:

car — Indicates that the sensor data is transformed using position and direction
sensor — (Default) Indicates that no transformation is applied.

The coordinate_system parameter isn't applicable to cameras.

data_format

(Required for lidar, radar, or GPS systems) Based on sensor configured for type, here are the formats you should use:

Type	Format
lidar	SENSOR_FORMAT_LIDAR_POLAR to indicate that data is in polar coordinates SENSOR_FORMAT_LIDAR_SPHERICAL to indicate that data is in spherical coordinates SENSOR_FORMAT_POINT_CLOUD to indicate that data is in point cloud format (Cartesian coordinates, which are X, Y, and Z coordinates)
radar	SENSOR_FORMAT_RADAR_POLAR to indicate that data is in polar coordinates SENSOR_FORMAT_RADAR_SPHERICAL to indicate that data is in spherical coordinates
gps, imu	SENSOR_FORMAT_GPS for GPS SENSOR_FORMAT_IMU for inertial measure unit (IMU)

default_video_format

(Optional for cameras) The default resolution format the camera starts up with. This is useful when you want to change the system provided video format that's provided for the camera and you don't want to use the API calls from the Camera library to change the video format. You must know the video formats supported by your camera. Based on the supported format, you can use these corresponding values to configure the default video format, such as rbg8888 for the RBG8888 video format:

nv12 — The format is NV12 formatted data
rgb8888 — The format is 32-bit ARGB data.
rgb888 — The format is 24-bit RGB data.
gray8 — The format is 8-bit gray-scale image data.
bayer — The format is a 10-bit Bayer frame type.
cbycry — The format is a YCbCr 4:2:2 packed frame type.
rgb565 — is 16-bit RGB data (5-bit red component, 6-bit green component, 5-bit blue component).
ycbcr420p — The format is frame type is a 4:2:0 YCbCr formats where Y, Cb and Cr are stored in separate planes.
ycbycr — The format is YCbCr 4:2:2 packed frame type where the pixel order is Y, Cb, Y, Cr.
ycrycb — The format is a YCbCr 4:2:2 packed frame type where the pixel order is Y, Cr, Y, Cb.
crycby — The format is a YCbCr 4:2:2 packed frame type where the pixel order is Cr, Y, Cb, Y.
bayer14_rggb_padlo16 — The format is 14-bit Bayer data in a 16-bit buffer.

default_video_framerate

(Optional; for cameras and file cameras only) The default resolution format the camera starts up with. This is useful when you want to change the system provided video format that's provided for the camera and you don't want to use the API calls from the Camera library to change the video format. You can provide a rate using numeric value, such as 60 to indicate 60 frames per second (fps). You must know the framerates that are supported by your camera.

default_video_resolution

(For cameras and file cameras) The default resolution to show on the display. This is useful when you want to change the provided resolution that's provided for the camera. It's also useful when you don't want to use the API calls from the Camera library to dynamically change the video resolution on the camera. For example, you can provide a value of 640,480 to indicate a 640 x 480 resolution. You must know the resolutions that are supported by your camera.

direction

(Optional) A comma-separated list of angles (in degrees counter-clockwise) that indicates the orientation of the sensor. List the angles in the order of yaw, pitch, and roll as you would in a right-handed, three-dimentional cartesian coordinate system where:

yaw is the angle about the z-axis
pitch is the angle about the y-axis
roll is the angle about the x-axis (direction of travel)

Figure 1. Direction of travel.

If the x-axis isn't the direction of travel in your reference coordinate system, then adjust the values of the angles for direction accordingly. The coordinate system that you use to specify the direction must be the same as that with which you specify the position.

flicker_cancel_mode

(Optional for cameras only) This parameter is for cameras that support 50 or 60 Hz flicker-cancellation algorithms. The can be one of the following:

off — (Default) Flicker-cancellation algorithm is off.
on_auto — Flicker-cancellation algorithm is on and automatically detects whether 50 or 60 Hz frequency is used.
on_50Hz: Flicker-cancellation algorithm is turned on to filter out 50 Hz flicker.
on_60Hz — Flicker-cancellation algorithm is turned on to filter out 60 Hz flicker.

filter_profile

(Required for GPS systems only) The GPS filter to apply.

For a XSens MTi 100-series GPS, these are the values you can use. For more information, see the XSesns MTi 100-series GPS documentation on the XSens website (https://www.xsens.com/):

general — The default setting, which makes a few assumptions about movements. Yaw is referenced by comparing GNSS accelerators with on-board accelerators.
general_nobaro — Similar to the general setting, but it doesn't use the barometer for height estimation.
general_mag — Similar to the general setting, but the yaw is based mainly on magnetic heading, together with comparison of GNSS acceleration and the accelerometers.
automotive — Yaw is determined using the GNSS. If GNSS is lost, yaw is determined using the velocity estimation algorithm for the first 60 seconds and then yaw is determined using only gyroscope integration. If a GNSS outage occurs regularly or GNSS availability is poor (e.g., in urban canyons), consider using high_performance_edr. this filter uses holonomic constraints and requires that the GPS is mounted according to the settings specified in the XSens User Manual.
high_performance_edr — This filter is specially designed for ground-based navigation applications where deteriorated GNSS conditions and GNSS outages occur regularly. This filter doesn't use holonomic constraints, therefore doesn't require GPS mounting considerations. It's ideal for slow moving ground vehicles.

horizontal_fov

(Optional) The horizontal field of view of the sensor. This value is specified in degrees. If two fields of view are supported, you can specify the both delimited by a comma. The horizontal axis is defined as the axis running from left to right of the board.

i2c_addr

(Optional) This parameter is for sensor cameras only. It specifies the 7-bit I2C address used to communicate with the sensor camera. If this parameter isn't specified, the default value for that sensor camera is used.

i2c_path

(Optional) This parameter is for sensor cameras only. It specifies the path of the I2C driver used to communicate with this camera. For example, /dev/i2c1.

lidar_fov

(Optional) The horizontal rotation (azimuth, in degrees) of interest from the lidar sensor.

For Velodyne lidar sensors, lidar_fov specifies the horizontal rotation (i.e., the difference between FOV End and FOV Start) that you configured by using the Velodyne webserver user interface. Valid rotations are in the range [1..360].

For Leddartech lidar sensors, lidar_fov specifies the horizontal rotation that's supported by the sensor. For example, Leddartech's Vu8 is available in different configurations that can support 20, 48, or 100.

name

(Required) A unique string to identify the camera.

num_user_buffers

(Optional) The number of buffers required for processing. If this value isn't specified, the default is 2.

packet_size

(Required for GPS, IMU, lidar, or radar systems) The number of data entries in each packet. A minimum of 384 (which represents approximately 20 degrees of data) should be specified for the Velodyne lidar sensor.

playback_group

(Required for file cameras only) Permits synchronized playback of the specified video file. You can configure multiple cameras to be part of the same group. A value of 0 indicates that the camera isn't part of a group, a value of 1 indicates that the camera is part of group 1, etc. Up to four groups are supported.

position

(Optional) A comma-separated list of distances (in millimetres) from an origin of your choice (the center of the vehicle's rear axle is commonly used) to the sensor's installation point. Specify the distances in the order of: x, y, and z as you would in a right-handed, three-dimentional cartesian coordinate system where:

X is the distance on the x-axis (direction of travel)
Y is the distance on the y-axis
Z is in distance on the z-axis

Figure 2. Direction of travel.

If the x-axis isn't the direction of travel in your reference coordinate system, then adjust the values of the distances for position accordingly. The coordinate system that you use to specify the position must be the same as that with which you specify the direction.

password

(Required for IP cameras only) The password to access the IP camera. This parameter also requires that you use the username parameter.

range_fov

(Optional) The sensor range, in millimeters. If two fields of view are supported, you can specify the both delimited by a comma. The horizontal axis is defined as the axis running from left to right of the board.

reference_clock

(Optional) The type of clock used to to generate the timestamps of the sensors. The valid values are as follows:

external — Dynamically load and use the user-provided library that's specified by reference_clock_library to generate sensor timestamps. If you specify external as your reference clock, you must also specify reference_clock_library to indicate the external clock library for the Sensor service to use.
monotonic — Use CLOCK_MONOTONIC (default). The sensor service generates the timestamps for the sensors based on its own monotonic clock.
ptp — Use the Precision Time Protocol daemon to synchronize sensor timestamps when sensors are across multiple targets.
real_time — Use CLOCK_REALTIME. The sensor service generates the timestamps for the sensors based on the "current time of day" clock.

reference_clock_library

(Required if external is specified for reference_clock) The path to the library that you provide to the Sensor service to use as the reference time for sensor timestamps. For example:

...
reference_clock = external
reference_clock_library = /usr/lib/libexternal_clock_example.so
...

You can configure each sensor to use a different external clock library, or multiple sensors can share one external clock library. You may provide multiple external clock libraries.

See “Using external clocks” in the Sensor Developer's Guide.

return_mode

(Required for lidar systems only) The type of reflection mode to use. The valid values are as follows:

strongest — The strongest reflection data.
last — Use the last or farther reflection data.
dual — Use both the strongest and last reflection data. This doubles the data that's received by the Sensor service.

rotations_per_minute

(For lidar systems only) The number of 360-degree rotations that occur each minute.

sample_frequency

(Required for GPS and IMU systems only) The frequency at which new data is received from the GPS, in microseconds.

udp_data_port

(Required for lidar systems only) The UDP port to use for data from the lidar system.

udp_position_port

(Required for lidar systems only) The UDP port to use for position information from the lidar system, which is 8308. For the UDP ports, the port is typically 2368.

username

(Required for IP cameras only) The user ID to use to log into an IP camera. This parameter also requires that you use the password parameter.

vertical_fov

(Optional) The vertical field of view of the sensor. This value is specified in degrees. If two fields of view are supported, you can specify the both delimited by a comma. The vertical axis is defined as the axis running from top to bottom of the board.