Skip to content

API guide

The driver's API by task, with code that compiles.

Datasheet sections this page relies on
  • NMT master frame (identifier 0, command then node): Wikipedia contributors Wikipedia article (oldid 1373604442) last edited September 2026, Network management (NMT), p. 1
  • Object dictionary and communication objects: CSS Electronics canopen-tutorial-simple-intro 2026 edition, Object dictionary, p. 1
  • Emergency message layout: CANopenNode project CO_Emergency.h master as downloaded, CO_Emergency.h: EMCY frame, p. 1
  • Heartbeat consumer: CANopenNode project CO_HBconsumer.c master as downloaded, CO_HBconsumer.c, p. 1
  • SYNC producer and counter: CANopenNode project CO_SYNC.h master as downloaded, CO_SYNC.h: SYNC frame and counter, p. 1
  • Store and restore parameters: CANopenNode project CO_storage.c master as downloaded, CO_storage.c: signatures and sub-indices, p. 1
  • SDO expedited and segmented transfer: christiansandberg python-canopen sdo/client.py master as downloaded, SdoClient: initiate, upload, download, segments, p. 1
  • SDO command specifiers and abort codes: christiansandberg python-canopen sdo/constants.py master as downloaded, SDO constants, p. 1
  • SDO object access and data types: christiansandberg python-canopen sdo/base.py master as downloaded, SdoBase: variable access, p. 1
  • NMT commands and states: christiansandberg python-canopen nmt.py master as downloaded, NMT commands and state codes, p. 1
  • Node guarding toggle bit: christiansandberg python-canopen nmt.py master as downloaded, NMT guarding reply, p. 1
  • Emergency message consumer: christiansandberg python-canopen emcy.py master as downloaded, EmcyConsumer, p. 1
  • PDO communication and mapping parameters: christiansandberg python-canopen pdo/base.py master as downloaded, PDO map and communication records, p. 1
  • CiA 402 state machine and controlword: christiansandberg python-canopen profiles/p402.py master as downloaded, BaseNode402: states, masks, transitions, p. 1
  • CiA 402 modes of operation: christiansandberg python-canopen profiles/p402.py master as downloaded, Operation modes, p. 1

All of them, with the driver API for each: Datasheet map.

Group Calls
Lifecycle EnsureInitialized(), IsInitialized(), Deinitialize(), SetConfig(), GetConfig(), canopen_client::Validate()
NMT and SYNC (send only) SendNmt(), SendSync(), SendRpdo(), SdoDownloadUnconfirmed()
SDO SdoUpload(), SdoDownload(), SdoReadU8/16/32(), SdoWriteU8/16/32(), GetLastAbort()
Standard objects ReadDeviceType(), ReadErrorRegister(), WriteHeartbeatProducerTime(), StoreParameters(), RestoreDefaults()
Receive path Poll(), MonitorNode(), UnmonitorNode(), GetNodeStatus(), GuardNode(), PopEmcy(), GetStats()
SYNC producer ConfigureSync(), ServiceSync()
PDO ConfigurePdo(), DisablePdo(), ReadPdoConfig(), SubscribeTpdo(), UnsubscribeTpdo(), ReadTpdo()
CiA 402 drive ReadStatusword(), ReadDriveState(), DriveEnable(), DriveDisable(), DriveQuickStop(), DriveResetFault(), SetDriveMode(), ReadDriveMode()

A call that needs a reply exists only on a port with Receive() and NowUs(); the commands in the second row work on a send-only port (Porting). Every call returns Result<T>: check ok() or operator bool, then read .value or .error.

Read and write objects (SDO)

canopen_client::Error ConfigureNode(Client& client) {
  // Expedited for 1 to 4 bytes, segmented for more; the driver picks.
  if (auto r = client.SdoWriteU16(5, 0x2001, 0, 1234); !r) {
    return r.error; // SdoAbort: the node refused, `client.GetLastAbort()` says why
  }
  const auto value = client.SdoReadU32(5, 0x2000, 0);
  if (!value) {
    return value.error;
  }
  std::array<uint8_t, 64> name{};
  const auto n = client.SdoUpload(5, 0x1008, 0, name); // device name: a segmented read
  return n.error; // BufferTooSmall if the node has more than 64 bytes
}

Sizes of 1 to 4 bytes travel as one expedited exchange, larger ones as a segmented transfer; the driver picks. After SdoAbort, GetLastAbort() holds the node, object and the 32-bit abort code, and canopen_client::AbortCodeName() names the common ones.

For diagnosis there is a raw, single-shot path: ReadRawSdo() and WriteRawSdo() send one request and return the node's reply frame as it is; SendRawFrame() and ReadRawFrame() put one frame on the bus or take one from it; GetLastRawFrame() holds the last frame the driver saw. None of them retries or checks more than the framing. They bypass the safety and state guards and do not update the node table, so use SendNmt(), DriveDisable() and DriveQuickStop() to stop a node. A boot-up message leaves bootup_seen set for its node until ClearBootUp(node).

Watch nodes and read emergencies

canopen_client::Error WatchNode(Client& client) {
  if (auto r = client.MonitorNode(5, 3'000'000); !r) { // alive while a heartbeat is under 3 s old
    return r.error;
  }
  const auto frame = client.Poll(100'000); // wait up to 100 ms and route one frame
  if (!frame) {
    return frame.error;
  }
  const auto status = client.GetNodeStatus(5);
  if (status && !status.value.alive) {
    return canopen_client::Error::Timeout; // no heartbeat for 3 s
  }
  canopen_client::EmcyEvent event{};
  while (client.PopEmcy(event)) {
    // event.node, event.code (0x0000 means the error is gone), event.error_register
  }
  return canopen_client::Error::Ok;
}

Poll() is the receive loop: call it from your task with the longest wait you can afford. It routes one frame to the node table, the EMCY queue, a TPDO sample or the SYNC counter and returns which. Heartbeats are consumed only for nodes registered with MonitorNode(); GuardNode() is the polled alternative for nodes that answer node guarding.

Process data

canopen_client::Error SetUpPositionPdo(Client& client) {
  canopen_client::PdoConfig pdo{};
  pdo.cob_id = 0x185;        // TPDO1 of node 5
  pdo.transmission_type = 1; // sent on every SYNC
  pdo.entry_count = 2;
  pdo.entries[0] = {0x6064, 0, 32}; // position actual value
  pdo.entries[1] = {0x6041, 0, 16}; // statusword
  if (auto r = client.ConfigurePdo(5, canopen_client::PdoKind::Transmit, 1, pdo); !r) {
    return r.error; // the PDO is left invalid, never half configured and valid
  }
  if (auto r = client.SubscribeTpdo(0x185, 6); !r) {
    return r.error;
  }
  if (auto r = client.SendNmt(canopen_client::NmtCommand::Start, 5); !r) {
    return r.error;
  }
  return client.SendSync().error; // the node answers with the PDO; `Poll()` then `ReadTpdo(0x185)`
}

ConfigurePdo() writes the node's communication and mapping records in the profile's order, so the PDO is never valid while half written. Configure a node in Pre-operational and start it with SendNmt(Start, node); a node sends its TPDOs only when Operational.

Drive a CiA 402 node

canopen_client::Error RunDrive(Client& client) {
  using canopen_client::OperationMode;
  if (auto r = client.SetDriveMode(5, OperationMode::ProfileVelocity); !r) {
    return r.error;
  }
  if (auto r = client.DriveEnable(5); !r) { // shutdown, switch on, enable operation
    return r.error; // DriveFault: the drive is in Fault; `DriveResetFault()` clears it
  }
  // ... write the target velocity (object 0x60FF) with `SdoWriteU32()` ...
  return client.DriveDisable(5).error; // never refused, sent up to Config::safety_attempts times
}

DriveEnable() walks the state machine one transition at a time, writing the next controlword and reading the statusword until the drive reports Operation enabled or Config::drive_timeout_us of bus time passes, however small the poll period. A drive that maps its objects elsewhere passes a DriveObjects with its indices.

Handle errors

const char* Describe(canopen_client::Error e) {
  switch (e) {
  case canopen_client::Error::Timeout:
    return "no reply in time: node absent, wrong node id or bit rate";
  case canopen_client::Error::SdoAbort:
    return "the node refused the transfer: see GetLastAbort()";
  case canopen_client::Error::NodeState:
    return "the node is Stopped: send NmtCommand::Start or PreOperational first";
  default:
    return canopen_client::ToString(e);
  }
}

Next: Configuration.