CANopen Guides

An edge device can interact with Octave by sending and receiving information through an Octave-ready device such as an AirLink FX30S or mangOH Red over CANopen. The Octave-enabled device contains an Octave Datahub which is responsible for communicating with the Octave cloud service.

📘

Note

Your FX30S or mangOH Red must be running firmware 1.0.14+ and must be equipped with an IoT expansion card to use the CANopen functionality in Octave.

This topic provides the following:

• Tutorial for CANopen Communications: a walk through on communications between an edge device and a mangOH Red using CANopen.
• CANopen Reference Guide: contains reference information about the CANopen protocol.

Tutorial for CANopen Communications

📘

Note

This tutorial assumes a working knowledge of CANopen.

Setting up CAN bus on the mangOH Red Through Octave

Follow the steps below to configure Octave to communicate over CANopen:

1. Select your mangOH Red in the Octave dashboard and navigate to Device > Services.
2. Locate the CANopen section, and click Configure.
3. Set Bus name to bus1, set the Bitrate to 125kb/s, and set Mode to spy.
4. In the Configuration section, enter and ID and name for the first node. Click "+" to add additional nodes and enter their information as required.
5. Set the Polling Period under Objects to 1. This specifies that the object at the edge will be polled every second.
6. Define objects for a CANopen object dictionary by setting the ID and name just below the polling period. Click the "+" button on the right hand side to add additional variables to the object dictionary.
7. Click the down arrow to the left of the object ID to view its sub indices, and enter the ID, name, and type for each. Click the "+" button on the right hand side to add additional sub indices to a variable. Note that the Const type is read-only and is the same size as Unsigned32. The other types can be used for service-to-object requests which can involve both reads and writes.
8. Set up the CANopen Process Data Object (PDO) protocol by clicking the PDOS tab. Click the "+" button on the right hand side to add additional PDOS entries.
9. Ensure the arrow to the left of the first PDOS entry points down, and click EntryId to select a variable/subindex combination defined in steps 6 and 7 above. The graph will update to provide a visual indication as to how many bits of the 64-bit data size maximum the entries use. Click the "+" button on the right hand side to add additional PDOS entries.
10. Click Save to save the CANopen configuration.

Verifying Resources

Follow the steps below to identify and verify the resources that have been created for your bus:

1. Navigate to Device > Resources in the Octave dashboard.
2. Locate and expand canopen and verify that the errorlog/value is null. This field will be populated with an error message if an error occurs when configuring CANopen.
3. Expand canopen > bus1 to view the CANopen configuration.

Receiving Data from a CANopen Device

• Navigate to Device > Observations, create a new Observation that sends events to the Cloud Stream, and save it. Wait for Octave to poll the device and then view the Observation's Last Value field to see the raw data that was read.

CANopen Reference Guide

📘

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

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:

Its OD is:

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:

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:

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:

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:

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 thte command byte field alternats 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:

📘

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:

Example of content of object at index 0x1800:

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):

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:

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:

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.