sensors/canbus/docs/usecase1.md

Go to the documentation of this file.

# Copyright (c) 2019-2020 NVIDIA CORPORATION.  All rights reserved.

@page canbus_usecase1 Receiving and Sending Data

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

## CAN Bus Sensor Module workflow

### Initialization

Initialization of the CAN bus sensor is achieved as follows:

```{.cpp}
    dwSensorParams params{};
    params.protocol = "can.socket";
    params.parameters = "device=can0";

    dwSensorHandle_t canSensor;
    dwSAL_createSensor(&canSensor, params, ...);
```

#### Protocol
The `dwSensorParams.protocol` expects one of the following can interfaces:

- `can.socket` interface for system CAN bus.

- `can.aurix` interface for CAN over Aurix.

- `can.virtual` interface for reading CAN data from binary logs.

#### Sensor parameters 
The `dwSensorParams.parameters` accepts the following parameters:

##### For all:

`filter=id:mask[+id:mask]`:

- `filter` is a string of `+` seperated filters
- `id` is a hex value
- `mask` is a hex value

Example: `filter=123:FFF+60A:FFF`

See the [Setting message filters](#setting-message-filters) section to see how these values are used. 

##### When using `can.socket`:

`device=can0[,fifo-size=1024]`

- `device` CAN device interface, usually canx, x starting from 0
    - on Linux, use `ifconfig` to list available CAN interfaces
    - on QNX, use `pidin a | grep nvcan` to list available CAN interfaces

- `fifo-size` size of internal buffer, in number of `dwCANMessage` stored.

##### When using `can.aurix` in driveworks 3.5 and above (Aurix version 4.0 and above):

`ip=10.0.0.1,bus={a,b,c,d,e,f}[,aport=50000,bport=60395],[inIDMap=1:0x106+2:0x206][6,outIDMap=0x105:17+0x205:18][,fifo-size=1024]`

- `ip` IP of Aurix (Drive AGX: `10.42.0.146`).
- `aport` port on which CAN messages are sent to Aurix.
- `bport` port on which CAN messages are received from Aurix.
- `fifo-size` see above.
- `inIDMap` a mapping of PDU ID to CAN ID in the format pduID:canID seperated by '+'. This should match the security model compiled onto the Aurix. ID values in decimal or hex format with leading 0x. Messages recieved from Aurix with pduID will be mapped to matched canID.
- `outIDMap` a mapping of CAN ID to PDU ID in the format canID:pduUD seperated by '+'. This should match the security model compiled onto the Aurix. ID values in decimal or hex format with leading 0x. Messages with canID will be send to Aurix mapped to pduID. 

##### When using `can.aurix` in driveworks 3.0 and below (Aurix version 3.X and below)

`ip=10.42.0.146,bus={a,b,c,d,e,f}[,aport=50000,bport=60395],[config-file=/path/to/EasyCanConfigFile.conf][,fifo-size=1024]`

- `ip` IP of Aurix (Drive AGX: `10.42.0.146`).
- `aport` port on which CAN messages are sent to Aurix.
- `bport` port on which CAN messages are received from Aurix.
- `fifo-size` see above.
- `bus` EasyCAN bus.
- `config-file` path to EasyCanConfigFile.conf, when provided, configures
  Aurix EasyCAN message routing when starting sensor. An example is provided
  in the DriveWorks data folder, under /path/to/data/samples/sensors/can.

##### When using `can.virtual`:

`file=/path/to/file.can[,create_seek,default_timeout_us,time-offset=0]`

- `file` path to CAN bus recording
- `create_seek` create seek table
- `default_timeout_us` period after which sensor times out
- `time-offset` offset applied to CAN messages timestamps

The CAN buses are setup with CAN FD if supported. If not supported sending
and receiving CAN FD messages will fail.

### Starting, stopping and releasing sensor

The CAN bus sensor can be started, stopped and released as follows:

```{.cpp}
dwSensor_start(canSensor);
dwSensor_stop(canSensor);
dwSAL_releaseSensor(&canSensor);
```

### Reading CAN messages

CAN messages can be read from the bus as follows:

```{.cpp}
dwCANMessage msg{};
dwStatus status = dwSensorCAN_readMessage(&msg, 10000, canSensor);
```

This will populate a `dwCANMessage` structure with the next CAN message
received on the bus, in this example waiting up to 10000us, or 10ms, for
a message to arrive. Timeout can be set to `::DW_TIMEOUT_INFINITE` to
indicate infinite waiting until new message arrives, or 0 to immediately
return and only read messages already received. The `dwCANMessage`
structure can hold up to 64 bytes to accommodate CAN FD messages.

To only read messages available in the internal queue, without reading
new messages on the CAN bus, the `dwSensorCAN_popMessage()` method can be
used. Together with `dwSensorCAN_processRawData()`, raw binary CAN data
can be read and parsed in `dwCANMessage` format, see @ref canbus_usecase2.

### Sending CAN messages

CAN messages can be sent on the bus as follows:

```{.cpp}
dwCANMessage msg{};

msg.id = 0x123;
msg.data[0] = 0xFF;
msg.size = 1;
msg.timestamp = 0;

dwSensorCAN_sendMessage(&msg, 10000, canSensor);
```

This sends a message over the CAN bus within a specified timeout. A message
is guaranteed to have been sent when this method returns `DW_SUCCESS`.
The method can block for up-to the specified amount of time if a bus is
blocked or previous `dwSensorCAN_readMessage()` operation has not yet
finished.

If the `msg.size` value is from 9 - 64, then the message will be sent as
a CAN FD message.

#### Sending CAN messages over Aurix

As of software version 3.01.3, the Aurix is configured to cyclically send
CAN messages with IDs 0x10f to 0x114 on buses A through F. These message
IDs should be considered as reserved as this behavior cannot be disabled
at run-time. Please refer to the Elektrobit Aurix Software User Guide for
more details.

#### Sending CAN with FD (Flexible Data-Rate) and BRS (Bit Rate Switch)

As of software version 3.05.4, the Aurix can send CAN FD messages with BRS.
Note that this is configured to use timing sample points of 0.8. Devices
on the network must be setup using this timing or bus errors can occur.
Please refer to Drive Developer Guide, Flashing Aurix documentation for more information.

### Setting message filters

CAN messages be filtered by ID as follows:

```{.cpp}
uint32_t ids[2] = {0x100, 0x6AB};
uint32_t masks[2] = {0xF00, 0xFFF};

dwSensorCAN_setMessageFilter(&ids, &masks, 2, canSensor);
```

This function takes an array of IDs and an array of masks to setup filters.
Once the filters are set, only messages with IDs matching the filters
will be read. Each call to the above will reset previously set filters. To
reset all filtering, call the above with 0 as number of filters.

Internally, only messages that meet the following condition for at least
one filter are read:

```{.cpp}
(messageID & mask) == (id & mask)
```

Masks are optional; when passing `NULL`, a default mask of `1FFFFFFF`
is used.

#### Setting message routing on Aurix

A message routing configuration has to be sent to Aurix prior to running
the application in order to receive, over Aurix, select CAN messages on
the desired Xavier device(s). This can be done by providing an EasyCAN
configuration file when creating the CAN bus sensor for `can.aurix` protocol,
by specifying the path to an Aurix EasyCAN configuration file with the
`config-file` argument. The configuration file is a text file containing
the following structures, one per CAN message to be routed:

```
MsgId   : 0x140
CtrlId  : EC_CAN_BUS_E
FrmTyp  : CAN_ID_STANDARD
DestId  : TEGRA_DEVICE_A
DestSwc : SWC_ID_CANDATA
```

Where:
 - `MsgId`   is the message ID to be routed, in hexadecimal
 - `CtrlId`  is the EasyCAN bus on which the message is received, in range
             `EC_CAN_BUS_A` to `EC_CAN_BUS_F`
 - `FrmTyp`  is the CAN ID type selector, either `CAN_ID_STANDARD` or `CAN_ID_EXTENDED`
 - `DestId`  is the destination device, either `TEGRA_DEVICE_A` or `TEGRA_DEVICE_B`
 - `DestSwc` is set to `SWC_ID_CANDATA` for CAN data

Each structure, corresponding to one CAN message to be routed, is separated
by an empty line from the next. An example file is provided in the DriveWorks
data folder, under /path/to/data/samples/sensors/can.

Please refer to the Elektrobit Aurix Software User Guide provided as part of
PDK documentation for more information on the EasyCAN message routing feature
and on how to configure Aurix.

### Setting hardware timestamping

The `dwSensorCAN_setUseHwTimestamps()` function allows the user to enable
or disable hardware timestamping of messages. By default, hardware timestamping
is enabled, but can be turned off if the default behavior is not working properly
with the current hardware stack.


The `dwSensorCAN_readMessage()` function reads the next available CAN message
with a given timeout. The function call is blocking, until a CAN message
is available or the timeout is exceeded. Filters can be set with
`dwSensorCAN_setMessageFilter()` so that only specific messages are read
from the bus. Messages can be sent with `dwSensorCAN_sendMessage()`.

The `dwCANMessage` structure holds a CAN message, consisting of a timestamp,
an ID, message data (payload) and size. The CAN bus module supports the
extended CAN frame format.

## Example

The following code shows the general structure of a program setting up
CAN message filters and receiving/sending messages on the bus. Only messages
with IDs `0x100`-`0x1FF` and `0x6AB` will be read.

```{.cpp}
dwSensorParams params{};
params.protocol = "can.socket";
params.parameters = "device=can0";

dwSensorHandle_t canSensor;
dwSAL_createSensor(&canSensor, params, ...);

uint32_t ids[2] = {0x100, 0x6AB};
uint32_t masks[2] = {0xF00, 0xFFF};

dwSensorCAN_setMessageFilter(&ids, &masks, 2, canSensor);

dwSensor_start(canSensor);

while(loop)
{
    dwCANMessage msg{};

    // read all messages until internal queue is empty
    while(dwSensorCAN_readMessage(&msg, 0, canSensor) == DW_SUCCESS)
    {
        // use received can message
    }

    // send message, e.g. asking for more data
    msg.id = 0xAAA;
    msg.data[0] = 0xFF;
    msg.size = 1;
    msg.timestamp = 0;

    // wait for 10ms at most if bus is busy
    dwSensorCAN_sendMessage(&msg, 10000, canSensor);
}

dwSensor_stop(canSensor);
dwSAL_releaseSensor(&canSensor);

```

For more information, refer to @ref dwx_canbus_logger_sample.