/builds/driveav/dw/sdk/tools/recorder/libs/dwrecorder/README.md

Go to the documentation of this file.

# Copyright (c) 2016-2017, NVIDIA CORPORATION.  All rights reserved.

@page dwx_recording_library DriveWorks Recording Library

The DriveWorks recording library provides functionality to easily record multiple
sensors. The library is configurable with a JSON file. The
JSON file syntax is described as below.

Currently, there are 6 types of sensors supported (camera, CAN, GPS, IMU, Lidar, Radar)
and the JSON file is written this way.

@code
{
    "version": "0.8",
@endcode

This is the version number. If this version number mismatches the in code
version number, the recorder will throw an exception.

@code
    "path": ".",
@endcode

This is where the recording library stores its captured data. Each time a new
capture session is invoked, a new folder is created at this path with the time
and location (if available) in the folder name.

@code
    "log-level": "verbose",
@endcode

This is log level used within DriveWorks. Valid values are `verbose`, `debug`, `warn`, or `error`.
@code
    "file-buffer-size": 2097152,
@endcode

This is the size of the buffer for file writing.

@code
    "camera": {
        "separate-thread": true,
        "write-file-pattern": "video_*",
        "sensors": [
          {
                "protocol": "camera.gmsl",
                "params": "camera-type=ar0231-rccb,csi-port=ef,camera-count=4,fifo-size=12",
                "channel-names": [
                                    "first",
                                    "second",
                                    "third",
                                    "fourth"
                                 ]
          }
        ]
    },
@endcode

Each sensor group is set up the same way. Multiple sensors are added by creating
a new object in the `sensors` array section of each group. 
For example to connect four cameras to each of the "ab" and "cd" interfaces the
code above can be replaced with:

@code
   "camera": {
       "separate-thread": true,
       "write-file-pattern": "video_*",
       "sensors": [
         {
               "protocol": "camera.gmsl",
               "params": "camera-type=ar0231-rccb,csi-port=ab,camera-count=4,fifo-size=12",
               "channel-names": [
                                   "ab_first",
                                   "ab_second",
                                   "ab_third",
                                   "ab_fourth"
                                ]
         },
         {
               "protocol": "camera.gmsl",
               "params": "camera-type=ar0231-rccb,csi-port=cd,camera-count=4,fifo-size=12",
               "channel-names": [
                                   "cd_first",
                                   "cd_second",
                                   "cd_third",
                                   "cd_fourth"
                                ]
         }
       ]
   },
@endcode

`write-file-pattern`must contain an asterisk, which is replaced by the channel number 
or channel-name of the sensor being recorded. The `write-file-pattern` needs no extension 
for any of the sensors, as this is automatically inferred based on the sensor params.
Each sensor group can share a capture thread with the other sensor groups by using
`separate-thread=false`. If `separate-thread=true`, a new thread spawns for
this sensor group to capture and record data separately from the other sensor groups.
If `separate-thread` is not present, it defaults to `false`.

The `protocol` for camera can be `camera.gmsl` only.

The `params` must follow the params given to a Driveworks sensor at initialization.
In order to record in other formats besides h264, add
`output-format=[raw,lraw,h264,raw+h264,lraw+h264]` with one of the listed output
formats to the `params`.
In order to record camera frames at a lower rate than the default, use
`frame-skip-count` in the `params`. 

For example, a value of
`frame-skip-count=1` records at 15 FPS if the camera hardware
runs at 30 FPS. Setting `record-frame-count=2` with `frame-skip-count=1`
records two (2) frames and skips 1, and then repeats.

For sensors that control multiple sources (such as camera), `channel-names` array
can be specified. This replaces the `*` in the `write-file-pattern` when
the file is saved to disk. If no `channel-names` array is specified, the `*` in
`write-file-pattern` is replaced with the channel number. Specific GMSL
cameras can be selected by using the `camera-mask=1111` where a `0` represents
off and a `1` represents on. This is an alternative to the `camera-count` 
option in the `params`.

In order to record asyncronously, add `async-record=1` to the `params`. The default
is `async-record=0`, which writes to disk on the same thread where the camera is
read.

For certain kinds of camera, e.g., ar0231-rccb, the camera framerate can be
controlled by the `required-framerate` option. Valid values for now are 20, 30, and 36.

@note It is not possible to intermix cameras of different type on the same CSI port.

@code
    "can" : {
        "separate-thread": false,
        "write-file-pattern": "can_*",
        "sensors" : [
            {
                "protocol": "can.socket",
                "params": "device=can0",
                "channel-name": "0"
            }
        ]
    },
@endcode

The CAN `protocol` supports both `can.socket` and `can.aurix`. In general, it
follows the same rules as camera. To add multiple CAN sensors, add another
object literal in the `sensors` array. `channel-name` specifies the replacement
for the `*` in `write-file-pattern` and is optional. If none is specified, it
defaults to a numeric system.

For gps.uart:
@code
    "gps" : {
        "separate-thread": false,
        "write-file-pattern": "gps_*",
        "sensors" : [
            {
              "protocol": "gps.uart",
              "params": "device=/dev/ttyACM0,baud=115200",
              "channel-name": "0"
            }
        ]
    },
@endcode

For gps.xsens:
@code
    "gps" : {
        "separate-thread": false,
        "write-file-pattern": "gps_*",
        "sensors" : [
            {
              "protocol": "gps.xsens",
              "params": "device=0,frequency=100",
              "channel-name": "0"
            }
        ]
    },
@endcode

GPS `protocol` supports `gps.uart` and `gps.xsens`. In general, it
follows the same rules as camera. To add multiple GPS sensors, add another
object literal in the `sensors` array. `channel-name` specifies the replacement
for the `*` in `write-file-pattern` and is optional. If none is specified, it
defaults to a numeric system.

For imu.uart
@code
    "imu" : {
        "separate-thread": false,
        "write-file-pattern": "imu_*",
        "sensors" : [
            {
                "protocol": "imu.uart",
                "params": "device=/dev/ttyUSB0,baud=115200",
                "channel-name": "0"
            }
        ]
    },
@endcode

For imu.xsens:
@code
    "imu" : {
        "separate-thread": false,
        "write-file-pattern": "imu_*",
        "sensors" : [
            {
              "protocol": "imu.xsens",
              "params": "device=0,frequency=100",
              "channel-name": "0"
            }
        ]
    },
@endcode

IMU `protocol` supports `imu.uart` and `imu.xsens`. In general, it
follows the same rules as camera. To add multiple IMU sensors, add another
object literal in the `sensors` array. `channel-name` specifies the replacement
for the `*` in `write-file-pattern` and is optional. If none is specified, it
defaults to a numeric system.

@code
    "lidar" : {
        "separate-thread": false,
        "write-file-pattern": "lidar_*",
        "sensors" : [
            {
                "protocol": "lidar.socket",
                "params": "ip=192.168.1.201,port=2368,device=VELO_VLP16,scan-frequency=10",
                "channel-name": "0"
            }
        ]
    },
@endcode

Lidar `protocol` supports `lidar.socket`. In general,
it follows the same rules as camera. To add multiple Lidar sensors, add
another object literal in the `sensors` array. `channel-name` specifies the replacement
for the `*` in `write-file-pattern` and is optional. If none is specified, it
defaults to a numeric system.

@code
    "radar" : {
        "separate-thread": false,
        "write-file-pattern": "radar_*",
        "sensors" : [
            {
                "protocol": "radar.socket",
                "params": "ip=192.168.1.201,port=2368,device=DELPHI_ESR2_5",
                "channel-name": "0"
            }
        ]
    },
@endcode

Radar `protocol` supports `radar.socket`. In general,
it follows the same rules as camera. To add multiple Radar sensors, add
another object literal in the `sensors` array. `channel-name` specifies the replacement
for the `*` in `write-file-pattern` and is optional. If none is specified, it
defaults to a numeric system.

@code
}
@endcode