The Octave Developer Hub

Welcome to the Octave developer hub. You'll find comprehensive guides and documentation to help you start working with Octave as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

CANopen Reference Guide

This reference guide provides detailed CANopen protocol information for developers who are connecting their devices using CANopen.

📘

Note

Octave complies with the CIA 301 specification.

Object Dictionary

Each node contains a dictionary (i.e., an array of items) composed of the following elements:

  • Index: 16 bits @ in the table
  • Object Name (Type/Size) example: array, record, simple variable.
  • Name: string
  • Attribute: Access right RW, RO, WO, ? CONST ?
  • Boolean indicating if the object is mandatory or optional

The index range indicates the type of the item, and a sub index (or entry) indicates the field in the data type stored within the dictionary at a specific index. In practice, the Object Dictionary (OD) is a hash table where the main index is the key to a "C-like" structure composed of bitfields, where each bitfield is accessed via a sub index.

Example 1: No sub index; the OD is directly accessing the dictionary without a sub index

Main index (16bits)Variable NameData Type
0x1000Device typeUnsigned 32

Example 2: Multiple fields in the object

The following object is composed of two fields: one is a const and the other is an 16-bit unsigned number:

Main index (16bits)Variable NameData Type
0x2005Max discharge CurrentArray

Its OD is:

Main IndexSub IndexVariable AccessData Type
20050x00Highest sub-Index supportedCONST
20050x01Max Regen currentUnsigned 16

High sub-index supported and Max Regen current are part of the Max discharge current object.

Message Format

A standard CAN frame is composed as follows:

SoFCOB-idRTRReservedDLCData FieldCRCACKEOF
1 bit4 + 7 bits1 bit2 bits4 bits

Where:

  • SoF (Start of Frame) (1 bit): 0
  • COB-id (11 bits): 4 bits Operation selection | 7 bits node ID (127 possible nodes)
    • 000 -> NMT node control
    • 080 -> Sync (see heartbeat/Timer)
    • 080 + NodeID -> Emergency
    • 100 -> Timestamp
    • 180 - 500 + NodeID -> PDO transmit/PDO receive
    • 580-600 + NodeID -> SDO transmit/receive (works in pre-operational State)
    • 700 + NodeID -> NMT node monitoring
    • 7E4-7E5 -> Layer Setting Service (LSS)
  • RTR (Remote transmission request) (1 bit)
  • DLC Data Length Code (4 bits): the number of bytes transmitted
  • Data field (64 bits): the data to transmit

SDO Service Data Object:

The first method to edit a node's dictionary is to use an SDO frame. Communication is from node to nodei, and the targeted node contains in the frame. The channel used is referred to as an SDO Channel.

There are two types of SDO frames:

  • Reading frame or upload.
  • Writing frame or download. The node that initiates an SDO frame is named the client and the node that is addressed by this node is the server. Determining whether the frame is reading or writing is done from the point of view of the server. Therefore, to read a node you must send a Download request, and to write a node it is a Download request.

SDO Client Dictionary @ range from 0x1200-0x127F -> 128 SDO. SDO Server Dictionary @ range from 0x1280-0x12FF -> 128 SDO.

SDO Specific Frame Format

Note: all fields are in little endian.

The SDO client always initiates communication. Every request is answered even if it cannot be fulfilled (in which case an abort code is sent). The format of an SDO frame is as follows:

Can HeaderCommand ByteOD Main IndexOD Sub IndexDATA
2 byte1 byte2 bytes1 bytemaximum 4 bytes

The CAN header is 16 bits and consists of the COB ID (Function + Node), the RTR bit, and 4 bits representing the packet length (0-8).

The CAN COB ID for a transmit SDO is formatted as 0x580 + <node Id> and the result of this addition cannot be greater than 0x600. The can COB ID for a receive SDO is formatted as 0x600 + <node Id> and the result of this addition cannot be greater than 0x700.

The OD main index and sub index refers to the object addressed by the SDO request, and data refers to that transmitted by the SDO. Notice that the data length sent by one SDO frame is only 4 bytes. If the data size is greater than 4 bytes, the SDO transfer is segmented into multiple SDOs.

The Command byte is composed as follow:

ccs=1Toggle Bitnes
3 bits1 bit2 bits1 bit1 bit

Notation:

  • ccs:
  • 0 Download Segment
  • 1 Initiate Download
  • 2 Initiate Upload
  • 3 Upload Segment
  • 4 Abort
  • 5 Block Upload
  • 6 Block Download
  • Toggle bit used in segmented mode
  • n: ( e & s ) number of data bytes which do not contain data (i.e., useless bytes).
  • e: (e) expedited transfer: (segment data > frame data capacity).
  • s: (s) see n: the number of data bytes stored in the frame's data region.

Example: 0x23: 0b0010011 means initiate a download, with the expedited transfer size set.

The response for reading the Vendor ID is in subindex 1 of the identity object 1018:

0x60OD Main IndexOD Sub IndexEmpty (0 padding)
43181001ID

Error codes:

  • 0x05030000: Toggle bit not alternated.
  • 0x05040001: Invalid SDO Command specifier.
  • 0x0601000x: Unsupported access to an object.
  • 0x06010002: Attempt to write a read only object.
  • 0x06020000: Object does not exist in the object dictionary.
  • 0x0607001x: Data type does not match.
  • 0x06090011: Subindex does not exist.
  • 0x08000000: General error.

Examples

Frames/segments are always 8 bytes long. If more than 8 bytes are required, send the message using multiple segments.

Download Request Expedited:

Frame example:

612.27.05.20.01.11.22.33.00 means request to node 12 object 2005 and sub index 01.

ccs: 0b001.0.0111:
    + 001 -> 1 so Initiate download
    + 0 fixed
    + 01 11 (from left to right) 1 bytes not used, expedited (one frame) and size set.

Answer:
592.60.05.20.01.00.00.00.00  means request to node 12 object 2005 and sub index 01.
ccs: 0b011.0.000
    0b11 is the identifier for Server response to upload request.

Upload request Expedited:

612.40.05.20.01.00.00.00.00  means request to node 12 object 2005 and sub index 01.

ccs: 0b010.0.0111:
    + 010 -> 2 so Initiate upload
    + 0 fixed
    + 0011 (from left to right) 0 bytes not used, expedited (one frame) and size set.

Answer :
592.47.05.20.01.data[8]  means request to node 12 object 2005 and sub index 01.
ccs: 0b11.0.000
    0b11 is the identifier for Server response to upload request.

Download request segmented:

612.40.05.20.01.00.00.00.00 Initiate Download Object 2005 sub object 1. ccs: 0b010.0.0000: 010 -> initiate an upload

592.41.05.20.01.1A.00.00.00 Initiate resp: Fine. It's 26 bytes long ccs: 41 -> 1 data size is set and segmented so size is in data field.

612.60.00.00.00.00.00.00.00  Upload segment req, Toggle = 0
592.00.54.69.6E.79.20.4E.6F  Upload segment resp, Toggle = 0
612.70.00.00.00.00.00.00.00  Upload segment req, Toggle = 1
592.10.64.65.20.2D.20.4D.65  Upload segment resp, Toggle = 1
612.60.00.00.00.00.00.00.00  Upload segment req, Toggle = 0
592.00.67.61.20.44.6F.6D.61  Upload segment resp, Toggle = 0
612.70.00.00.00.00.00.00.00  Upload segment req, Toggle = 1
592.15.69.6E.73.20.21.00.00  Last segment, 2 bytes free, Toggle = 1

Remarks:

  • When segmented, the size is greater than the maximum 8 bytes of the SDO format, so it cannot be encoded in 2 bits as in expedited case. This is why the size is sent in the data field on a read initiate response or in a write initiate frame.
  • When the initiate is finished, the forth bit of the command byte field alternates between 0 and 1 and starts at 0.
  • The last frame containing data always has its size bits on.

PDO Frame

PDO is another way to send an object sub entry to another other node. As in SDO, a sub entry is sent, but the PDO frame is configured to send multiple sub entries at once. Moreover, the event that triggers the PDO frame can be configured.

There are two kinds of PDO: TxPDO and RxPDO (sometimes the x is not used).

To configure those PDO, SDO are used to write at object 0x1Axx (TxPDO) and 0x16xx (RxPDO). This configures the data sent by PDO where the maximum is 0x1Axx to 0x1FFF for TxPDO, and 0x16xx to 0x18xx for Rx. To configure the event, write at (T/R)xPDO object - 0x200.

The PDO frame follows this scheme:

CAN headerrtrlendata
0x180 + node1bit1 byte (1-8)7 bytes

📘

Note

The number of monitored sub entries can be greater than 7 bytes.

PDO Mapping

PDO mapping can be done in three different ways:

  • Static: SDO can't change the value of the mapping.
  • Variable: can be modified only during the NMT (Network Management) pre-operational state.
  • Dynamic: same as variable but modifications can also occur in post-operational state.

PDO mapping procedure:

  1. Set PDO invalid by switching Bit 31 in the related COB-ID entry.
  2. Set PDO mapping invalid by writing 00h to sub-index 00h of the related mapping entries.
  3. Adjust the desired PDO mapping.
  4. Set sub-index 00h of the related mapping index to the number of mapped objects.
  5. Switch PDO valid by means of Bit 31 in the related COB-ID entry.

Content of the TxPDO map

The following is at object 0x1Axx sub object Y:

IndexSub IndexLength
2 bytes1 byte1 byte

Example of content of object at index 0x1800:

IndexNbr of Sub indexEntry1Entry2Entry3...Entry 7
0x1800220050110200503100...0

Where 20050110 is mapped to object 2005 sub object 01, and has a size of 2 bytes (u16) (refers to an object of the current node).

Content of the RxPDO

The consumer of a PDO should map its RxPDO according to the monitored TxPDO, 0x16xx (where xx match TxPDO xx):

IndexSub IndexLength
2 bytes1 byte1 byte

The object index and sub index can be different. For example, consider a node that wants to monitor the PDO set in the previous TxPDO section. This could be achieved with the following configuration:

IndexNbr of Sub indexEntry1Entry2Entry3...Entry 7
0x1600210050110100503100...0

Event configuration:

PDO's for both Rx and Tx can be configured to be sent on a specific event using the object at 0x18xx and 0x16xx.

Both objects are formatted as follows:

Nbr of Sub indexCOB IDTypeInhibit TimeEvent Timer
1 byte4 bytes1 byte2 bytes2 bytes

The type field values are as follows::

  • 0 Acyclic synchronous: PDO sent if a value changes.
  • 1-240 Cyclic synchronous: PDO sent if a value changes and SYNC has been received.
  • 241-251 Reserved.
  • Synchronous RTR: send PDO on RTR and SYNC packet.
  • Asynchronous RTR only.
  • 254-255 Asynchronous.

The remainder are as follows: COB-ID COB-id: 11 bits: 4 bits Operation selection | 7 bits node ID (127 possible nodes) + 000 -> NMT node control + 080 -> Sync (see heartbeat/Timer) + 080 + NodeID -> Emergency + 100 -> timestamp + 180 - 500 + NodeID -> PDO transmit/PDO receive + 580-600 + NodeID -> SDO transmit/receive (works in pre-operational State) + 700 + NodeID -> NMT node monitoring + 7E4-7E5 -> Layer Setting Service (LSS)

Node Resources

Data Resource

/app/canbus/node_name/value

{
     "objectName": {
         "entryName": {
             "value": number,
             "error": {
                 "code": "str",
                 "class": "str"
             }
         }, ... // other entry
     }, ... // other object
 }

Where errorCode and errorClass are define by the CANopen standard as follows:

  • ErrorCode:
    • Service Error
    • Access Error
    • Other Error
    • Invalid signature
  • ErrorClass:
    • Parameter Inconsistent
    • Illegal Parameter
    • Object non-existent
    • Object access unsupported
    • Invalid address
    • Hardware fault
    • Object attribute inconsistent
    • Type conflict
    • Invalid address

Network Management Resource (nmt):

/app/canbus/node_name/nmt/value

{
  "NMT state": "str"
}

Where the state can be set to the following values:

  • Enter Operational
  • Enter Stop
  • Enter Pre-operational
  • Reset Mode
  • Reset Communication

Emergency Message:

/app/canbus/node_name/value

{
  "errorCode": "str",
  "errorClass": "str",
  "vendor data": number
}

Where errorCode and errorClass are also specified by the standard:

  • ErrorCode:
    • Generic error
    • Current
    • Voltage
    • Temperature
    • Communication error (overrun error state)
    • Device profile specific
    • Reserved
    • Manufacturer specific
    • Generic error
    • Current
    • Voltage
    • Temperature
    • Communication error (overrun error state)
    • Device profile specific
    • Reserved
    • Manufacturer specific
  • ErrorClass:
    • Error Reset or No Error
    • Generic Error
    • Current
    • Current device input side
    • Current inside the device
    • Current device output side
    • Voltage
    • Mains Voltage
    • Voltage inside the device
    • Output Voltage
    • Temperature
    • Ambient Temperature
    • Device Temperature
    • Device Hardware
    • Device Software
    • Internal Software
    • User Software
    • Data Set
    • Additional Modules
    • Monitoring
    • Communication
    • CAN Overrun (Objects lost)
    • CAN in Error Passive Mode
    • Life Guard Error or Heartbeat Error
    • recovered from bus off
    • CAN-ID collision
    • Protocol Error
    • PDO not processed due to length error
    • PDO length exceeded
    • DAM MPDO not processed destination object not available
    • Unexpected SYNC data length
    • RPDO timeout
    • External Error
    • Additional Functions
    • Device specific

Request:

Per-node Config:

Triggers an SDO request:

/app/canopen/bus_name/node_name/sdo/send

Send

{
    "action": "R",
    "objects": {
      // first request
      "Temperature": { //object name same as config name
        "Temperature": true // entry name
      }, // second request :
      "TemperatureMin": {
        "TemperatureMin": true
      }
      ...
    }
}

Supported Features:

  • Sniffing mode: reports all data changes seen on the bus with no implicit user interaction. Both SDO and PDO are sniffed.
  • Reading data by explicitly by sending an SDO from Fx/mangoh to a node using the Request resource. Only expedited.
  • Standard type for entries up to 48-bit integers (signed and unsigned); Note that const is a 32-bit integer.

Updated about a month ago

CANopen Reference Guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.