CANopen API Usage

Synchronous API

The synchronous use is very simple, all you need is a CANopenClient instance.

On creation the client automatically connects to the active CANopen worker or starts a new worker instance if necessary.

The CANopenClient methods will block until the job is done (or has failed). Job results and/or error details are returned in the caller provided job.

Caution

Do not make synchronous calls from code that may run in a restricted context, e.g. within a metric update handler. Avoid using synchronous calls from time critical code, e.g. a CAN or event handler.

Example

#include "canopen.h"

// find CAN interface:
canbus* bus = (canbus*) MyPcpApp.FindDeviceByName("can1");
// …or simply use m_can1 if you're a vehicle subclass

// create CANopen client:
CANopenClient client(bus);

// a CANopen job holds request and response data:
CANopenJob job;

// read value from node #1 SDO 0x1008.00:
uint32_t value;
if (client.ReadSDO(&job, 1, 0x1008, 0x00, (uint8_t)&value, sizeof(value)) == COR_OK) {
  // read result is now in value
}

// start node #2, wait for presence:
if (client.SendNMT(&job, 2, CONC_Start, true) == COR_OK) {
  // node #2 is now started
}

// write value into node #3 SDO 0x2345.18:
if (client.WriteSDO(&job, 3, 0x2345, 0x18, (uint8_t)&value, 0) == COR_OK) {
  // value has now been written into register 0x2345.18
}

Main API methods

/**
* SendNMT: send NMT request and optionally wait for NMT state change
*  a.k.a. heartbeat message.
*
* Note: NMT responses are not a part of the CANopen NMT protocol, and
*  sending "heartbeat" NMT state updates is optional for CANopen nodes.
*  If the node sends no state info, waiting for it will result in timeout
*  even though the state has in fact changed -- there's no way to know
*  if the node doesn't tell.
*/
CANopenResult_t SendNMT(CANopenJob& job,
    uint8_t nodeid, CANopenNMTCommand_t command,
    bool wait_for_state=false, int resp_timeout_ms=1000, int max_tries=3);

/**
 * ReceiveHB: wait for next heartbeat message of a node,
 *  return state received.
 *
 * Use this to read the current state or synchronize to the heartbeat.
 * Note: heartbeats are optional in CANopen.
 */
CANopenResult_t ReceiveHB(CANopenJob& job,
    uint8_t nodeid, CANopenNMTState_t* statebuf=NULL,
    int recv_timeout_ms=1000, int max_tries=1);

/**
 * ReadSDO: read bytes from SDO server into buffer
 *   - reads data into buf (up to bufsize bytes)
 *   - returns data length read in job.sdo.xfersize
 *   - … and data length available in job.sdo.contsize (if known)
 *   - remaining buffer space will be zeroed
 *   - on result COR_ERR_BufferTooSmall, the buffer has been filled up to bufsize
 *   - on abort, the CANopen error code can be retrieved from job.sdo.error
 *
 * Note: result interpretation is up to caller (check device object dictionary
 *   for data types & sizes). As CANopen is little endian as ESP32, we don't
 *   need to check lengths on numerical results, i.e. anything from int8_t to
 *   uint32_t can simply be read into a uint32_t buffer.
 */
CANopenResult_t ReadSDO(CANopenJob& job,
    uint8_t nodeid, uint16_t index, uint8_t subindex, uint8_t* buf, size_t bufsize,
    int resp_timeout_ms=50, int max_tries=3);

/**
 * WriteSDO: write bytes from buffer into SDO server
 *   - sends bufsize bytes from buf
 *   - … or 4 bytes from buf if bufsize is 0 (use for integer SDOs of unknown type)
 *   - returns data length sent in job.sdo.xfersize
 *   - on abort, the CANopen error code can be retrieved from job.sdo.error
 *
 * Note: the caller needs to know data type & size of the SDO register (check
 *   device object dictionary). As CANopen servers normally are intelligent,
 *   anything from int8_t to uint32_t can simply be sent as a uint32_t with
 *   bufsize=0, the server will know how to convert it.
 */
CANopenResult_t WriteSDO(CANopenJob& job,
    uint8_t nodeid, uint16_t index, uint8_t subindex, uint8_t* buf, size_t bufsize,
    int resp_timeout_ms=50, int max_tries=3);

If you want to create custom jobs, use the low level method ExecuteJob() to execute them.

Asynchronous API

The CANopenAsyncClient class provides the asynchronous interface and the response queue.

To use the asynchronous API you need to handle asynchronous responses, which normally means adding a dedicated task for this. A minimal handling would be to simply discard the responses (just empty the queue), if you don’t need to care about the results.

Example

Instantiate the async client for a CAN bus and a queue size like this:

CANopenAsyncClient m_async(m_can1, 50);

Example response handler task:

void MyAsyncTask()
{
  CANopenJob job;
  while (true) {
    if (m_async.ReceiveDone(job, portMAX_DELAY) != COR_ERR_QueueEmpty) {
      // …process job results…
    }
  }
}

Sending requests is following the same scheme as with the synchronous API. Standard result code is COR_WAIT, an error may occur if the queue is full.

if (m_async.WriteSDO(m_nodeid, index, subindex, (uint8_t*)value, 0) != COR_WAIT) {
  // …handle error…
}

Main API methods

The API methods are similar to the synchronous methods (see above).

CANopenResult_t SendNMT(uint8_t nodeid, CANopenNMTCommand_t command,
  bool wait_for_state=false, int resp_timeout_ms=1000, int max_tries=3);

CANopenResult_t ReceiveHB(uint8_t nodeid, CANopenNMTState_t* statebuf=NULL,
  int recv_timeout_ms=1000, int max_tries=1);

CANopenResult_t ReadSDO(uint8_t nodeid, uint16_t index, uint8_t subindex,
  uint8_t* buf, size_t bufsize,
  int resp_timeout_ms=100, int max_tries=3);

CANopenResult_t WriteSDO(uint8_t nodeid, uint16_t index, uint8_t subindex,
  uint8_t* buf, size_t bufsize,
  int resp_timeout_ms=100, int max_tries=3);

CANopenJob objects are created automatically by these methods. Jobs done need to be fetched by looping ReceiveDone() until it returns COR_ERR_QueueEmpty.

If you want to create custom jobs, use the low level method SubmitJob() to add them to the worker queue.

Error Handling

If an error occurs, it will be given as a CANopenResult_t other than COR_OK or COR_WAIT, either by a method result or by the CANopenJob.result field.

Result codes are:

COR_OK = 0,

// API level:
COR_WAIT,                   // job waiting to be processed
COR_ERR_UnknownJobType,
COR_ERR_QueueFull,
COR_ERR_QueueEmpty,
COR_ERR_NoCANWrite,
COR_ERR_ParamRange,
COR_ERR_BufferTooSmall,

// Protocol level:
COR_ERR_Timeout,
COR_ERR_SDO_Access,
COR_ERR_SDO_SegMismatch,

// General purpose application level:
COR_ERR_DeviceOffline = 0x80,
COR_ERR_UnknownDevice,
COR_ERR_LoginFailed,
COR_ERR_StateChangeFailed

Additionally, if an SDO read/write error occurs, an abortion error code may be given by the slave. These codes follow the CANopen standard and may be extended by device specific codes.

To translate a CANopenResult_t and/or a known SDO abort code into a string, use the CANopen class utility methods:

std::string GetAbortCodeName(const uint32_t abortcode);
std::string GetResultString(const CANopenResult_t result);
std::string GetResultString(const CANopenResult_t result, const uint32_t abortcode);
std::string GetResultString(const CANopenJob& job);

Example

if (job.result != COR_OK) {
  ESP_LOGE(TAG, "Result for %s: %s",
    CANopen::GetJobName(job).c_str(),
    CANopen::GetResultString(job).c_str());
}

Custom Address Schemes

The standard clients use the CiA DS301 default IDs for node addressing, i.e.:

NMT request     → 0x000
NMT response    → 0x700 + nodeid
SDO request     → 0x600 + nodeid
SDO response    → 0x580 + nodeid

If you need another address scheme, create a sub class of CANopenAsyncClient or CANopenClient and override the Init…() methods as necessary.

More Code Examples

See shell commands in canopen_shell.cpp
See classes SevconClient and SevconJob in the Twizy SEVCON module