Create CANopen abstraction layer

[PeterBowman]

Known open-source implementations:

• https://stackoverflow.com/a/46330960
• https://github.com/CANopenNode/CANopenNode
• https://canfestival.org/
• https://github.com/marel-keytech/openCANopen
• https://github.com/ulrikhagstrom/datalinkengineeringcanopen
• https://github.com/christiansandberg/canopen (Python)

Moar links:

• https://en.wikipedia.org/wiki/CANopen
• https://www.can-cia.org/canopen/
• https://www.csselectronics.com/screen/page/canopen-tutorial-simple-intro/language/en
• http://www.byteme.org.uk/canopenparent/canopen/
• https://www.canopensolutions.com/
• https://www.ni.com/en-my/innovations/white-papers/13/the-basics-of-canopen.html
• http://overpof.free.fr/schneider
• O. Pfeiffer et al., Embedded Networking with CAN and CANopen
• http://www.servotronix.com/html/stepIM_Help/HTML/home.htm

Documents:

• Martin Rostan, Configuration Guideline for CANopen Networks
• CANopen application layer and general communication profile
• P091.063.CANopen.iPOS.UM.2019.pdf
• CiA 301 version 4.2.0 (cpc TC1&TC1-B)
• CiA 306 version 1.3.0
• H. Boterenbrood, CANopen: high-level protocol for CAN-bus, v3.0
• Elmo Motion Control CANopen DS 301 Implementation Guide
• Steve Corrigan, Introduction to the Controller Area Network (CAN), Texas Instruments

Also, CiA 402 / IEC / UNE-EN mappings (ref, UC3M access via AENOR):

CiA 402	IEC / UNE-EN 61800-7 (profile type 1)
402-1: General definitions	61800-7-1: Interface definition, Annex A
402-2: Operation modes and application data	61800-7-201: Profile specifications
402-3: PDO mapping	61800-7-301: Mapping of profiles to network technologies

[PeterBowman]

SDO protocol

From 3.2.3, Service Data Objects (SDO):

Service Data Objects are used by CANopen master to access any object from the drive’s Object Dictionary. Both expedited and segmented SDO transfers are supported (see DS301 v4.2.0 for details). The SDOs are typically used for drive configuration after power-on, for PDO mapping and for infrequent low priority communication.

SDO transfers are confirmed services. In case of an error, an Abort SDO message is transmitted with one of the codes listed in Table 3.2.1.

Apparently, iPOS drives do not support block transfers (www.can-cia.org). Comprehensive examples on using both expedited and segmented transfers are given on this site. Again, the object dictionary for iPOS drives is designed in such a way that only expedited transfers are needed, with very little exceptions (see object 1008h, Manufacturer Device Name).

Per www.csselectronics.com:

SDOs are flexible, but carry a lot of overhead - making them less ideal for real-time operational data. This is where the PDO comes in.

We vastly abuse this protocol in terms of querying current drive status: most notably, modes of operation and error registers listed in section 5.4, Error monitoring. Those should be treated in an event-driven manner via TPDOs. For non-frequent, query-like requests (e.g. get current limits, set reference velocity&acceleration, and so on), SDO will prevail.

Implementation notes:

• Attend to SDO abort codes (section 3.2.3).
• Create an abstraction layer around SDO expedited transfers, handle protocol byte (first one, includes the ccs - client command speficier - and others).
• If deemed convenient or necessary, support SDO segmented transfers.
• Attend to acknowledge responses (on read) and queries (on write) in a wait-and-timeout fashion. That is, drop hardcoded delays (example), implement a blocking wait until the response arrives or the request times out.
• Implement an eds.ini and/or dcf.ini file (ref) to describe supported objects and load them into a map in an indexed manner so that interpretMessage() may access them easily? See IO.eds and auto-generated CO_OD sources.
• There will be no support for SDO peer-to-peer communication between two CANopen devices (see object 1280h, SDO client parameter).

[PeterBowman]

SDO abstraction layer ready at ebcfe13. Supports normal (segmented) and expedited transfers for integer types and strings. Expects response/confirmation with timeout (#159), parses abort codes.

I decided to leave the dictionary .ini file thing out. All SDO dictionary data is employed in the code itself, anywhere it is actually necessary. This file would cover much more than we actually need, it requires certain effort to understand and learn the exact format, and I doubt that YARP's .ini parser conforms to it anyway.

[PeterBowman]

Added PDO at 110a9bc and EMCY at cb2a1f7, along with an omnibus CANopen factory class which I'm not quite fond of.

[PeterBowman]

Initial implementation available in libraries/CanBusSharerLib (merged from #229).

I initially intended to follow the null object pattern in the CanOpen class to model optional CAN protocols. For instance, such circumstance could arise when trying to implement a PDO beyond the fourth subindex, e.g. can->rpdo(5). I ultimately dropped this design due to excessive code clutter and little benefit, assuming that most drives will adhere to the pre-defined connection set. Therefore, so does the CanOpen class.

[PeterBowman]

PDO protocol

Useful links: ref1, ref2.

From 3.2.4, Process Data Objects (PDO):

Process Data Objects are used for high priority, real-time data transfers between CANopen master and the drives. The PDOs are unconfirmed services and are performed with no protocol overhead. Transmit PDOs are used to send data from the drive, and receive PDOs are used to receive data. The Technosoft drives have 4 transmit PDOs and 4 receive PDOs. The contents of the PDOs can be set according with the application needs through the dynamic PDO-mapping. This operation can be done during the drive configuration phase using SDOs.

Two objects define a PDO: the communication object and the mapping object. The communication object defines the COB-ID of the PDO, the transmission type and the event triggering the transmission. The mapping object contains the descriptions of the objects mapped into the PDO, i.e. the index, sub-index and size of the mapped objects.

Object mapping is exhaustively described in several places, refer to the linked resources in the issue description and objects 16xxh/1Axxh. Objects 1400h through 1403h and 1800h through 1803h describe communication parameters of default RPDOs and TPDOs, respectively. In this way, the following transmission types can be configured:

• Asynchronous (event driven): the PDO transfer is initiated when the process data changes, e.g. an encoder read is updated. Also, it can occur at a fixed time interval (timer driven).
• Synchronous/asynchronous RTR (remote requested, only TPDO): obsolete or not recommened anymore, occurs on individual polling.
• Acyclic synchronous: triggered on SYNC message iff an internal event occurs (the process data changes).
• Cyclic synchronous (only TPDO): triggered on SYNC message or an iteration thereof (i.e. once every two SYNC messages, every three messages, and so on).

This family of objects also provide access to specific parameters such as inhibit time, event timer and SYNC start value (only cyclic synchronous TPDO). iPOS drives are only permitted to perform event-driven RPDO and TPDO, and acyclic synchronous TPDO; at least, I can tell the user manual omits communication parameters that refer to the remaining transmission types.

[PeterBowman]

iPOS drives are only permitted to perform event-driven RPDO and TPDO, and acyclic synchronous TPDO; at least, I can tell the user manual omits communication parameters that refer to the remaining transmission types.

I can confirm iPOS drives, at least at firmware F508M/F509M, do support cyclic synchronous TPDOs. They don't support subindex 06h in transmission type comms params, i.e. SYNC start value, though.

[PeterBowman]

EMCY protocol

From 4.1.4, Emergency messages:

A drive sends an emergency message (EMCY) when a drive internal error occurs. An emergency message is transmitted only once per ‘error event’. As long as no new errors occur, the drive will not transmit further emergency messages.

From CiA 301, 7.2.7.1, Emergency object usage:

A CANopen device shall be in one of two emergency states (Figure 37). Dependent on the transitions emergency objects shall be transmitted. Links between the error state machine and the NMT state machine are defined by object 1029 h (see sub-clause 7.5.2.32).

0. After initialization the CANopen device enters the error free state if no error is detected. No
   error message is sent.
1. The CANopen device detects an internal error indicated in the first three bytes of the
   emergency message (error code and error register). The CANopen device enters the error
   state. An emergency object with the appropriate error code and error register is transmitted.
   The error code is filled in at the location of object 1003h (pre-defined error field).
2. One, but not all error reasons are gone. An emergency message containing error code 0000h
   (Error reset) may be transmitted together with the remaining errors in the error register and in
   the manufacturer-specific error field.
3. A new error occurs on the CANopen device. The CANopen device remains in error state and
   transmits an emergency object with the appropriate error code. The new error code is filled in
   at the top of the array of error codes (1003h). It shall be guaranteed that the error codes are
   sorted in a timely manner (oldest error - highest sub-index, see object 1003h).
4. All errors are repaired. The CANopen device enters the error free state and transmits an
   emergency object with the error code ‘reset error / no error'.
5. Reset or power-off.

iPOS drives do not define Object 1029h: Error behavior object (concerns the behavior of the NMT state machine on any severe error condition).

[PeterBowman]

NMT protocol

From 4, Network Management:

The Network Management (NMT) services initialize, start, monitor, reset or stop the CANopen nodes. The NMT requires a node in the network (a PC or a PLC) to be designed as a network manager while the Technosoft intelligent drives are the NMT slaves.

From CiA 301, 7.3.2, NMT state machine:

CANopen devices enter the NMT state Pre-operational directly after finishing the CANopen devices initialization. During this NMT state CANopen device parameterization and CAN-ID-allocation via SDO (e.g. using a configuration tool) is possible. Then the CANopen devices may be switched directly into the NMT state Operational.

From CiA 301, 7.3.2.2.1, NMT state initialisation:

The NMT state initialisation shall be divided into three NMT sub-states (specified in Figure 49) in order to enable a complete or partial reset of a CANopen device.

1. Initialising: This is the first NMT sub-state the CANopen device enters after power-on or hardware reset. After finishing the basic CANopen device initialisation the CANopen device enters autonomously into the NMT sub-state reset application.
2. Reset application: In this NMT sub-state the parameters of the manufacturer-specific profile area and of the standardized device profile area are set to their power-on values. After setting of the power-on values the NMT sub-state reset communication is entered autonomously.
3. Reset communication: In this NMT sub-state the parameters of the communication profile area are set to their power-on values. After this the NMT state Initialisation is finished and the CANopen device executes the NMT service boot-up write and enters the NMT state Pre-operational.

Power-on values are the last stored parameters. If storing is not supported or has not been executed or if the reset was preceded by the command restore defaults (see clause 7.5.2.14), the power-on values are the default values according to the communication and device profile specifications.

[PeterBowman]

SYNC protocol

From 4.1.3.4, Synchronization between devices:

There are two ways to synchronize the drive in a network:

1. Send only the sync message with the COB ID 0x80 and Data null at very precise intervals. This method is the most commonly used and its accuracy is based on how precise the master sends the SYNCS and the CAN bus load.
2. (see TIME)

From 7.2.5, Synchronization object (SYNC) in CiA 301:

The SYNC producer broadcasts the synchronization object periodically. This SYNC provides the basic network synchronization mechanism. The time period between the SYNCs is specified by the standard parameter communication cycle period (see sub-clause 7.5.2.6), which may be written by a configuration tool to the CANopen devices during the boot-up process. There may be a time jitter in transmission by the SYNC producer corresponding approximately to the latency due to some other message being transmitted just before the SYNC. The SYNC consumer may use the communication cycle period manufacturer specific.

(...) In order to guarantee timely access to the network the SYNC is given a very high priority CAN-ID (see sub-clause 7.5.2.5). CANopen devices that operate synchronously may use the SYNC object to synchronize their own timing with that of the synchronization object producer. (...)

This CAN feature is very much linked to PDO protocol and, more precisely, to synchronous transmission types (either RTR, cyclic or acyclic).

[PeterBowman]

TIME protocol

From 4.1.3.4, Synchronization between devices:

There are two ways to synchronize the drive in a network:

1. (see SYNC)
2. For time critical applications, which require more accurate synchronization, the Technosoft drives can use the optional high-resolution synchronization protocol, which employs a special form of time stamp message. The High Resolution Time Stamp can be set with the COB ID 0x100 and 4 bytes of data that represent a time stamp with a resolution of 1μs. When the master sends a time stamp with the COB ID 0x100 it has the same effect as writing the same value to all the slaves in the network in object 1013h. With this second method, the master sends the sync message (0x80) followed immediately by the time stamp message with the id 0x100.
   When one of the Technosoft drives is set as synchronization master, the High resolution time stamp is by default sent using the COB ID defined in COB-ID High Resolution Time Stamp object (index 2004h).

From https://www.can-cia.org/can-knowledge/canopen/special-function-protocols#c1947:

The Time-stamp protocol enables the user of CANopen systems to adjust a unique network time. The Time-stamp is mapped to one single CAN frame with a data length code of 6 byte. These six databytes provide the information "Time of Day". This information is given as milliseconds after midnight (Datatype: Unsigned28) and days since January 1, 1984 (Datatype: Unsigned16). The associated CAN frame has by default the CAN-Identifier 100h.

From Elmo Motion Control CANopen DS 301 Implementation Guide, Chapter 8: SYNC and Time STAMP:

The SYNC message has two uses:

• (see SYNC)
• Synchronize the motion clock of the servo drive with a clock in the network master. The synchronization is made in conjunction with the Time Stamp message. The motion clock of the servo drive counts microseconds (regardless of the sampling time of the drive). It is cyclic and has 32 bits, meaning that it completes a full cycle in 4,295 seconds (approximately 72 minutes). When the motion clocks of all connected servo drives are synchronized to the motion clock of the master, multiple servo drives can perform complex synchronized motion with exact timing set by the network master.

The drives are synchronized by the transmission of a SYNC message, whose arrival time is captured by the drive. Upon reception of the SYNC, the drive latches its internal timer.

A Time Stamp is a 32-bit message that contains the master internal clock as generated upon receipt of the client’s own SYNC. The Time Stamp causes a clock synchronization cycle to be executed. The drive uses the Time Stamp as an absolute timer and adjusts its internal time in relation to the time latched in the last SYNC1. To synchronize the master and drive clocks to full precision, the synchronization process is filtered in order to ensure that the timing jitter of the time stamping process does not adversely affect motion smoothness. It takes about 200 SYNC-Time Stamp pairs to ensure that all clocks are fully synchronized.

COB-ID 256 (0x100) is a constant dedicated ID used for this purpose. The master can send Time Stamps at any time.

A Time Stamp always refers to the previous SYNC message and must come no later than 5 seconds after the relevant SYNC.

From O. Pfeiffer et al., Embedded Networking with CAN and CANopen, p. 374 (object 1013h):

This entry contains a high resolution timestamp in microseconds, which may be mapped into a PDO. The high resolution timestamp allows for local clock synchronization with great precision. If only the SYNC signal is used for the synchronization of local clocks, the deviation between the clocks could be several hundreds of microseconds because even the high priority SYNC message can be delayed (for example, because it has to wait until a message currently on the bus is transmitted).

When the SYNC producer finishes transmitting the SYNC object, a local CAN message transmit complete interrupt is generated. In the interrupt service routine, the high resolution timestamp is taken of that moment in time. This timestamp is then transmitted in a PDO after the SYNC object.

When a SYNC consumer receives the SYNC object (recognized by a CAN message received interrrupt), it also takes a high resolution timestamp of that moment in time. Shortly afterwards, the SYNC consumer will receive the PDO containing the high resolution timestamp from the SYNC producer. The SYNC consumer compares the two timestamps, which should be identical if the local clocks of the producer and the consumer are perfectly synchronized. If they are not identical, the SYNC consumer has to start a process of synchronizing itself with the clock of the SYNC producer.

Note however that there is still an error in the synchronization. It takes some time for the SYNC producer to react to the SYNC object transmission complete interrupt and generate the timestamp. Also, it takes some time for the SYNC consumer to react to the SYNC object being received and generate a timestamp. These delays are typically different, however they can be calculated in advance based on the code executed and used to adjust the high resolution timestamps accordingly. This behavior, however, is application specific.

The timestamp allows for a maximum delay of 72 minutes before it is reset back to zero.

[PeterBowman]

Boot-up protocol

From 4.1.3.3, Boot-up protocol:

This protocol is used by the drive to signal to the network master that it has entered the state pre-operational. When the drive is powered on for the time or is reset, it will send a boot-up message with the COB-ID (0x700+ Node Id) and Data 00.

From https://www.can-cia.org/can-knowledge/canopen/error-control-protocols#c2671:

The boot-up protocol represents a special type of an error control protocol. It is transmitted as the final action in NMT FSA state Initialisation, prior to enter the NMT FSA state Pre-operational. The reception of this message indicates that a new device has been registered to the CANopen network. The unintended reception of such a protocol during runtime either indicates a change in the network setup (e.g. due to the addition of a new CANopen device) or is considered a sign for an error condition (e.g. erroneous power supply of related CANopen device). The protocol uses the same identifier as any other error control protocol, such as e.g. the heartbeat protocol. The 1-byte data field has a fixed value of zero.

Note certain hardware supports an "extended boot-up" (H. Boterenbrood, CANopen: high-level protocol for CAN-bus, v3.0). The iPOS drives don't.

[PeterBowman]

Heartbeat protocol

From 4.1.3.2, Heartbeat protocol:

The Heartbeat protocol defines an error control service without the need of remote frames. It implies independent and cyclical transmission of a telegram by the drive (the Heartbeat producer) indicating the drives current state. The time interval between two heartbeat messages is specified through producer heartbeat time (index 1017h). The master (Heartbeat consumer) guards the reception of the heartbeat messages within the Heartbeat Consumer Time. If the value of this object is 0, the heartbeat transmission is disabled. If the master does not receive the heartbeat message this indicates a problem with the drive or with its network connection.

From https://www.can-cia.org/can-knowledge/canopen/error-control-protocols#c2670:

The Heartbeat protocol is a cyclically transmitted message that informs all heartbeat consumers of the availability of the heartbeat producer. In addition to the availability of the heartbeat producer, the heartbeat protocol provides the current NMT FSA state of the heartbeat producer. The cycle time for transmitting the Heartbeat message is configurable in the object dictionary index 1017h.

From https://www.canopensolutions.com/english/about_canopen/Heartbeat-service.shtml:

As a rule of thumb, the consumer time should twice of the producer time.
(...)
The Hearbeat message is mapped to a CAN data frame with a 1-byte data field. This byte provides the NMT status of the CANopen device. It could be in Pre-operational state (7Fh), Operational state (05h), or Stopped state (04h). In Pre-operational state the CANopen device does not process PDOs and in Stopped state it supports just the NMT message and sends its Heartbeat. In Operational state all CANopen functions are provided.

If the CAN data frame contains 00h, it is interpreted as Boot-up message indicating that this CANopen device has just entered the network. This happens after initial power-on, a power-cycle as well as after application and communication reset. The next CAN data frame with the same CAN-ID and content unequal 00h is interpreted as Heartbeat message. The NMT master device uses the Heartbeat message as a confirmation of its NMT commands.

iPOS drives provide the following objects:

• 1017h, Producer Heartbeat Time, defaulted to 0 (i.e. disabled).

• 6007h, Abort connection option code:

  The object sets the action performed by the drive when one of the following events occurs: bus-off, heartbeat and life guarding.

  Defaulted to "no action", also accepts: "fault signal", "disable voltage" and "quick stop".

Also, EMCY message with code 0x8130 reports a "Life guard error or heartbeat error". However, I presume both 6007h and said EMCY are aimed at iPOS nodes configured as heartbeat consumers.

[PeterBowman]

Node- and life-guarding protocols (legacy)

From 4.1.3.1, Node guarding protocol:

The master polls each NMT slave at regular time intervals. This time interval is called the guard time and may be different for each NMT slave. The slaves answer with a node-guarding message containing their state. This allows both the master and the slave to identify a network error if either the remote request or the guarding messages stop.

The node life time is computed as the product between the guard time (index 100Ch) and the life time factor (index 100Dh). If the drive is not accessed within the life time then a Life Time event occurs and an emergency telegram is sent.

From https://www.can-cia.org/can-knowledge/canopen/error-control-protocols#c2672

Guarding is an outdated method of checking whether a guarded CANopen device is still working in the correct network state. As this is an RTR-based service, the Heartbeat protocol is used in new designs. In old-fashioned applications, the host controller triggers the error control information of the monitored CANopen devices via the CAN remote frame (RTR) for example. Each monitored CANopen device has to be triggered individually. The monitored device replies with a CAN data frame that indicates the current NMT FSA state.

From https://www.ni.com/es-es/innovations/white-papers/13/the-basics-of-canopen.html:

In the node guarding protocol, the CANopen master polls the slave nodes for their current state information. If the node does not respond in a specific period of time, the master assumes the node is dead and will take an action.

The heartbeat protocol is the preferred method because it has less overhead than node guarding.

See also 7.2.8.2.2, Error control services in CiA 301.

[PeterBowman]

Commit fbeb6a3 removes the dependency of EMCY and NMT objects on an SDO client instance. So, no more EmcyConsumer::configure(std::uint16_t inhibitTime) and NmtProtocol::setupHeartbeat(std::uint16_t period) methods. I'd rather configure these by hand via direct SDO calls. Also, there are more dictionary objects related to those protocols, some of them not even supported by iPOS drives (the EMCY inhibit time is apparently not), thus it defeats the purpose of supporting the CANopen pre-defined connection set basics. The PDO protocol is somewhat an exception due to the convolute configuration process involved in that case.

[PeterBowman]

I had to take another design decision regarding the ICanBusSharer.hpp header):

• Move it outside CanBusSharerLib into YarpPlugins, rename library, remove CanBusControlboard's dependency on it. I wanted to pick CanOpenNodeLib badly, but it might cause confusion due to https://github.com/CANopenNode/CANopenNode.

• Leave it where it is, but remove dependency on yarp::dev::CanMessage.

Not fully sure about it, but I chose the second option for simplicity's sake: ea9546c.

[PeterBowman]

Not fully sure about it, but I chose the second option for simplicity's sake: ea9546c.

Eventually, I decided to pick the hard way and go for the first option: commit 9182ca2 splits old CanBusSharerLib into itself, StateObserverLib and CanOpenNodeLib. Also, those three targets are now being exported and installed by CMake for casual consumers.

• StateObserverLib: implementation of non-typed and typed (generic) class monitors.
• CanBusSharerLib: mostly interfaces for generic CAN messages and nodes, includes utilities.
• CanOpenNodeLib: CANopen-related stuff, follows the CiA 301 and CiA 402 standards.

So, most of old CanBusSharerLib is now CanOpenNodeLib and the CanOpen class has been renamed to CanOpenNode to stress that all handles relate to a specific CAN node.