Changes

Server-SDO block transfer support is now optional. It can be disabled at compile time with the --disable-ssdo-blk option to configure, or by defining the LELY_NO_CO_SSDO_BLK preprocessor macro.

If Server-SDO block transfer support is enabled, the maximum number of segments per block can now be changed from the default value of 127 by defining the CO_SSDO_MAX_SEQNO preprocessor macro.

Finally, the Client-SDO no longer gives up immediately if the server does not support the requested block size during a block upload request. Instead, the client halves the block size and tries again until the server accepts the request.

Known issues

See v2.3.3.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed in all three versions:

• co_time_of_day_set() now actually stores the result. Previously it would only compute the result but not actually make it available to the caller.

The following additional issues have been addressed in v2.3.4:

• EMCY messages generated by the stack when a heartbeat or life-guarding event occurs are now automatically removed when the event is resolved. This fixes a potential memory usage issue if the application did not remove the EMCY messages manually. To make this fix possible, two other changes were necessary:
• The co_emcy_find() and co_emcy_remove() functions have been added. These functions allow the caller to resolved (and remove) EMCY errors other than the most recent error.
• The error register is now computed on demand. Since EMCY errors can now be resolved in arbitrary order, we cannot rely on the error register value of the most recent EMCY error to remain correct.

Known issues

See v2.3.3.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed in all three versions:

• configure.ac now prepends the default flags to $CFLAGS and $CXXFLAGS. This allows the user to override the default flags.
• During a firmware update, a missing SDO download response message after the “start program” command no longer results in an error. This may happen if a device reboots immediately after receiving the command, before sending an SDO response. While this is non-conforming behavior, the firmware update process is more robust if we ignore the SDO timeout in this case.
• GCC 13 is now supported. All build warnings have been fixed.
• liblely-util and liblely-co no longer rely on the availability of specified-width integer types and macros. These types and macros are optional according to the standard. The least-width types and macros are used instead.
• The previous bug fix, combined with a few other small fixes, enables support for the TI C2000 C/C++ Compiler. This compiler targets the TI C2000 Microcontroller platforms. A distinguishing feature of these platforms is the absence of 8-bit bytes.
• CAN frames with CAN-ID 000h (NMT commands) are now only processed by the NMT service and not by other CAN frame receiver callbacks. This prevents difficult to debug issues with misconfigured CANopen services which accidentally use 000h as the COB-ID. Since those services might be recreated by the NMT service, this could even lead to segmentation faults in the worst case.
• dcfgen now generates an explicit SDO download request to set sub-index 0 of the PDO mapping parameter object to 0 before writing the actual mapping parameters, even when the EDS/DCF file suggests that it might already be 0. The standard is vague on whether this is necessary, but always writing the value is the most robust solution.
• A missing member initializer has been added __frbuf_init().

The following additional issues have been addressed in v2.3.3 and v2.2.9:

• Defining LELY_NO_CO_OBJ_FILE no longer results in a linker error in liblely-coapp.

The following additional issues have been addressed in v2.3.3:

• Padding bytes in MPDO messages are now discarded, like the standard requires.

Known issues

The following known issues are still present:

• When compiling with clang with C17 support, the following error is reported for multiple files:

  error: macro 'ATOMIC_VAR_INIT' has been marked as deprecated [-Werror,-Wdeprecated-pragma]
  

  This cannot be easily fixed, since the ATOMIC_VAR_INIT macro is also used in the <lely/libc/stdatomic.h> compatibility layer for compilers without support for C11 atomics. For now, the error can be fixed by adding -std=c11 to $CFLAGS when compiling with clang.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed in all three versions:

• GCC 12 is now supported. All build warnings have been fixed.
• Several clang warnings have been fixed. And the -Wno-static-in-inline flag has been added to $CFLAGS to suppress warnings about the use of extern inline.
• The r[ead] p[do] and w[rite] p[do] commands in coctl (and the ASCII gateway) mimick RPDO/TPDO access to the local object dictionary. These commands now correctly ignore the AccessType to prevent errors.
• coctl no longer changes tries to change the bitrate if it was already correct, or if retrieving the bitrate fails. This prevents the network interface from being left in a down state after initialization.
• A potential use-after-free in the user-defined destructor of a promise has been fixed.
• Potential race conditions in ev_future_submit() and ev_future_when_all_n() have been fixed.
• The Server-SDO now copies the CRC support flag from the Client-SDO request to its own response. Even though the server supports CRC in SDO block transfers, reporting this when the client does not may result in an error in some clients. To prevent confusion, if the client does not support CRC, we pretend to not support it either.
• The CAN frame receiver now uses strict CAN ID matching and does not mask unused bits before comparison. This prevents situations where a CAN frame is sent to a receiver even though the ID differs from what the receiver expects, which may result in assertion failures.

The following additional issues have been addressed in v2.3.2 and v2.2.8:

• dcfgen now explicitly generates an SDO request to disable the heartbeat consumer, if necessary.
• The EDS/DCF Python tools now accept a LastEDS key in the FileInfo section of EDS/DCF files.
• The CAN network interface in liblely-io2 now correctly reports the read/write error count to the user-defined callback function. Previously, the last error code was supplied to the callback instead of the error count.

The following additional issues have been addressed in v2.3.2:

• --disable-diag (LELY_NO_DIAG) no longer results in build errors.
• SDO/PDO communication parameters and PDO mapping parameter records are now copied explicity instead of with memcpy(). This fixes potential errors when sub-objects are missing from the local object dictionary.
• Receiving an empty string via SDO no longer results in an std::string instance being initialized with a null pointer, which is undefined behavior.

Known issues

The following known issues are still present:

• When compiling with clang with C17 support, the following error is reported for multiple files:

  error: macro 'ATOMIC_VAR_INIT' has been marked as deprecated [-Werror,-Wdeprecated-pragma]
  

  This cannot be easily fixed, since the ATOMIC_VAR_INIT macro is also used in the <lely/libc/stdatomic.h> compatibility layer for compilers without support for C11 atomics. For now, the error can be fixed by adding -std=c11 to $CFLAGS when compiling with clang.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed in all three versions:

• GCC 11 is now supported. All build warnings have been fixed.

The following additional issues have been addressed in v2.3.1 and v2.2.7:

• dcfgen now properly formats INTEGER8 values when creating concise DCF files.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

ECSS compliance

This release contains several changes necessary to make the Lely CANopen stack suitable for use in space, in particular to make it compliant with the ECSS-E-ST-50-15C - CANbus extension protocol. Full ECSS compliance requires breaking changes and will not be achieved until the v3 release (under deleveopment in the ecss branch at https://gitlab.com/n7space/canopen/lely-core.). This release contains the necessary non-breaking changes (with the exception of a few minor changes that should not affect normal users).

Configuration options

An ECSS-compliant build can be generated by specifying the --enable-ecss-compliance option to the configure script. This option disables all functionality not covered by the ECSS-E-ST-50-15C - CANbus extension protocol, which includes the I/O libraries and all C++ APIs. Additionally, it configures the project for a freestanding environment with (almost) no support from the standard C library.

Standard C library support can also be selectively disabled with the following new configure options (or preprocessor macros)

• --disable-errno (LELY_NO_ERRNO): disable support for errno and <errno.h>.
• --disable-malloc (LELY_NO_MALLOC) disable support for dynamic memory allocation.
• --disable-stdio (LELY_NO_STDIO) disable standard I/O support.

Note: LELY_NO_MALLOC support is preliminary and will not yet disable all dynamic memory allocation.

Additionally, --disable-diag (LELY_NO_DIAG) disables the diagnostic functions from liblely-util.

The NMT boot slave and configuration request services are not covered by ECSS. They can be disabled with the new --disable-nmt-boot (LELY_NO_CO_NMT_BOOT) and --disable-nmt-cfg (LELY_NO_CO_NMT_CFG) options, respectively. Node guarding is also out of scope. It can be disabled with the new --disable-ng (LELY_NO_CO_NG) option.

For more information, see the build configuration documentation.

Static object dictionary generator

Disabling dynamic memory allocation prevents the generation of the object dictionary at runtime. It also precludes the use of the static object dictionary generated by dcf2c, since that object dictionary still needs to be converted to the real object dictionary at runtime.

The new dcf2dev tool (part of the EDS/DCF tools) can generate a compile-time object dictionary that is directly usable by the CANopen stack.

Note: Because of the way array values are handled, the generated object dictionary can only be used when LELY_NO_MALLOC is defined.

Unit tests

Part of the ECSS-compliance effort is the development of a test suite that covers 100% of the code that is in scope. This test suite is based on the CppUTest and can be found in the unit-tests directory. It can be disabled with the --disable-unit-tests option.

New features

Stop token

A stop token implementation is now provided by <lely/util/stop.h> and <lely/util/stop.hpp>. The API is based on <stop_token> in C++20. Stop tokens provide a generic mechanism for users to cancel (sequences of) tasks, using (global) timeouts or any other condition. This blog post provides a good overview of why this is useful.

Support for stop tokens will be added to the asynchronous I/O library in a future release.

Transmit-PDO sampling support

CiA 301 allows for a SYNC-driven Transmit-PDO to start sampling after a SYNC message has been received (and before the synchronous window expires). It is now possible to register a callback function with a TPDO (with co_tpdo_set_sample_ind()) that implements the sampling process. Once the process is complete, the user calls co_tpdo_sample_res() to report the result, at which point the PDO is sent.

If the user does not register a sampling callback function, the current value of the mapped object is sent the moment the SYNC message is received.

Multiplex PDO support

Support for Multiplex PDOs (MPDOs) has been added to the Receive-PDO and Transmit-PDO services. Both destination address mode (DAM) and source address mode (SAM) MPDOs are supported.

The object dictionary supports event tracking for SAM-MPDOs. The user can call co_dev_sam_mpdo_event() to indicate that an event occurred for a specific sub-object. If that sub-object is mapped to a SAM-MPDO, the PDO will automatically be sent. The SetEvent() method in the C++ CANopen application library will invoke both co_dev_tpdo_event() and co_dev_sam_mpdo_event(), so the user does not need to know to which type of PDO a sub-object is mapped. DAM-MPDO events can be triggered with co_dam_mpdo_event() and the DamMpdoEvent() method.

The RpdoRead()/RpdoGet() and OnRpdoWrite() methods treat incoming SAM-MPDOs the same as regular PDOs. For DAM-MPDOs the originating node-ID and object (sub-)index are unknown. To respond to an incoming DAM-MPDO, use the OnWrite() callback for the local object dictionary. However, it is impossible to distinguish between an incoming DAM-MPDO and an SDO download request.

dcfgen does not yet create the object scanner and object dispatching lists used by SAM-MPDOs. Support for SAM-MPDOs will be added in a future release.

MPDO support can be disabled by specifying the --disable-mpdo to configure or by defining the LELY_NO_CO_MPDO preprocessor macro.

SDO download DCF requests

It is now possible for the user to issue a series of SDO download requests in the form of a concise DCF, either from a file or a memory region. Concise DCF SDO requests can be generated with dcfgen. They were already supported as part of the NMT configuration request sequence during the boot process, but now it is possible to use them manually from an application.

The co_csdo_dn_dcf_req() and co_dev_dn_dcf_req() function can be used to issue such requests to remote and local object dictionaries, respectively. In the C++ CANopen application library, use the WriteDcf(), SubmitWriteDcf() and AsyncWriteDcf() methods.

As part of the implementation, the co_val_read_file()/co_val_read_frbuf() and co_val_write_file()/co_val_write_fwbuf() helper functions were added to read/write a CANopen value directly to/from a file (buffer).

Other

Utilities library:

• Re-entrant versions of the error string functions (errc2str(), errno2str() and errnum2str()) are now available. Following the glibc convention, the names of the re-entrant versions end in _r.
• The fiber implementations in the utilities library have been unified. Fibers can now also be migrated between threads on platforms that support it.
• A contains() method has been added to all containers in the utilities library. This method allows the user to check if a node is present in a container.
• The pheap_find() and pheap_remove() methods if the pairing heap now have a non-recursive implementation. This prevents potential stack overflows when using those methods with large heaps.
• Several 16-bit Unicode string functions (str16len(), str16ncmp() and str16ncpy()) are now available in <lely/util/ustring.h>. These functions are equivalent to the corresponding standard library functions, except that they operate on strings of type char16_t instead of char.

Asynchronous I/O library:

• Synchronous CAN channel operations no longer require a valid executor in the constructor of the CAN channel. This allows synchronous operations to be used in the absence of an event loop.
• The ENOTSUP error from RTNETLINK is now ignored when creating a CAN controller on Linux. This enables support for SLCAN network interfaces, which do not provide CAN bus attributes.

CANopen and C++ CANopen application libraries:

• All CANopen services now have start(), stop() and is_stopped() methods. This allows the user to explicitly disable or enable a service after it is created. To not break backward compatibility, services are automatically started after they are created.
• SDO block transfers can now be explicitly requested in the C++ CANopen application library. The co_csdo_blk_dn_val_req() has been added to the C API to make block downloads more convenient.
• The new co_nmt_chk_bootup() can be used to check if boot-up messages have been received for a specific node or for all mandatory nodes. This function is available even if LELY_NO_CO_NMT_BOOT is defined.

EDS/DCF tools:

• Bare $NODEID values are now allowed in EDS/DCF files.
• Keys with empty values are now ignored in EDS/DCF files.
• Custom data types are now supported when using the EDS/DCF tools as a Python module. The command-line tools ignore unknown data types.
• dcfgen no longer configures the master to read sub-objects from object 1018h on the slave that do not exist. Only sub-index 1 (Vendor-ID) is mandatory. Sub-indices 2 (Product code), 3 (Revision number) and 4 (Serial number) are all optional.

CI/CD:

• The Docker images used in the CI/CD pipeline are now documented in docker/README.md.
• The C and C++ code style is now checked with clang-format in the CI/CD pipeline.
• Python code style checks have been added using Black and Flake8.

API changes

The C++ interface of liblely-co is deprecated and will be removed in a future version. liblely-coapp now uses the C interface of liblely-co.

• membuf_init() now takes two extra parameters that can be used to initialize the buffer with a pre-existing memory region. This change is necessary to support static memory buffers when LELY_NO_MALLOC is defined. membuf_init(buf, NULL, 0) is equivalent to the original membuf_init(buf).
• can_buf_init() now also takes an extra parameter that can be used to initialize a CAN frame buffer with a pre-existing memory region. The size parameter is now required to be a power of 2, instead of automatically being rounded up. Additionally, the unused can_buf_create() and can_buf_destroy() functions have been removed.
• Due to the new start() and stop() methods of CANopen services, the existing co_time_start() and co_time_stop() functions have been renamed to co_time_start_prod() and co_time_stop_prod(), respectively.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed in all three versions:

• co_val_cmp() now correctly compares TIME_OF_DAY and TIME_DIFF values: the days member is compared before the ms member.
• A potential race condition was fixed in asynchronous I/O functions, which made it possible in a multi-threaded environment for an asynchronous operation to complete and release its promise before the invoking function acquired the corresponding future.
• The Transmit-PDO event timer no longer stops in case of an error.
• co_sdev_load() no longer causes compilation failures when LELY_NO_CO_OBJ_NAME is defined.

The following additional issues have been addressed in v2.2.6:

• Drivers inheriting from canopen::LoopDriver can now use the Join() method in their destructor to ensure the thread running the dedicated event loop finishes its execution before continuing. This is necessary to guarantee that all tasks involving registered logical drivers have finished before those drivers are destroyed. The Join() method is public, so it can also be used to synchronize the destruction of logical drivers that are not owned by the driver inheriting from LoopDriver.
• The USleep() method in canopen::LoopDriver now uses an actual timer instead of relying on the run_for() method of ev::Loop. This makes the implementation consistent with canopen::FiberDriver and removes the 1 ms resolution of the timeout.
• The AsyncWait() operation used by the USleep() method in canopen::LoopDriver and canopen::FiberDriver is now canceled if the event loop is interrupted.
• dcfgen now copies the producer heartbeat time from object 1017h in the slave EDS/DCF if the heartbeat_producer attribute is not explicitly specified.
• dcfgen no longer omits the SDO request to set the number of mapped objects to 0 before changing the PDO mapping.
• The on_can_state() method in io::CanNet now receives the new_state and old_state arguments in the correct order.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Several of their improvements have already found their way back into recent releases. And even more will be part of the upcoming v2.3 release. However, some changes require us to break the backward compatibility of part of the C API. For example, one of the ESA requirements is that the stack can be used with (almost) no support from the standard C library. Supporting such a freestanding environment, with no dynamic memory allocation, affects several public interfaces.

Breaking changes warrant an increase in the major version number. For now, v3 is under development in the ecss branch at https://gitlab.com/n7space/canopen/lely-core. The first releases mark milestones in the ESA project. Once it is finished, the ecss branch will be merged into the official repository and released publicly, probably with version 3.3. Non-breaking changes will continue to be merged into v2.x releases.

Disclaimer: The views expressed here can in no way be taken to reflect the official opinion of the European Space Agency.

Bug fixes

The following bugs have been fixed in all three versions:

• Receive-PDO services now interpret the value of object 1007h (Synchronous window length) as microseconds instead of milliseconds.
• Transmit-PDO (TPDO) services now ignore the value of object 1007h. Proper handling of the synchronous window requires support for a user-defined “sampling” step before transmitting PDOs. This will be added in the next release.
• Acyclic (event-driven) TPDOs (transmission type 00h) now ignore the event-timer, as specified in CiA 301.
• RTR-only (synchronous) TPDOs (transmission type FCh) now ignore RTR frames if no PDO has been buffered by a previous SYNC event.
• An empty UploadFile attribute now results in an empty value instead of a file-not-found error during an SDO upload (read) request.
• The ev::when_all() and ev::when_any() function overloads now distinguish between a pair of ev::Futures and a pair of iterators.

The following additional issues have been addressed in v2.2.5:

• Some non-compliant devices never send a boot-up message, which results in the master never starting the NMT ‘boot slave’ process for those nodes. The user can now manually trigger the boot-up process with the Boot() method of the master and driver classes.
• If a slave restarts during the boot-up process, the Client-SDO now remains available for use by the application (or driver).
• canopen::BasicMaster now has a protected IsConfig() method which can be used to check if a remote node is configuring (i.e., i.e., the ‘update configuration’ step of the NMT ‘boot slave’ process is reached but not yet completed).
• The --disable-cython has been added to the configure script. Using this option will disable the (deprecated) Python bindings while still allowing the DCF tools to be built.
• dcfchk and dcfgen now correctly handle implicitly defined PDOs.
• dcfgen now correctly handles objects mapped to multiple PDOs.
• The configuration_file attribute has been added to the slave section of the YAML file used by dcfgen. This attribute can be used to override the name of the configuration file for the slave as it appears in object 1F22h in master.dcf. Note that it has no effect on the name of the .bin file generated by dcfgen.
• Object 1F22h is omitted from master.dcf by dcfgen if no slaves use a configuration file, either because no .bin files are generated or because the configuration_file attribute is explicitly set to an empty string.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.

Bug fixes

The following bugs have been fixed:

• Following Postel’s law, Client- and Server-SDOs now accept CAN frames less than 8 bytes if they can be interpreted unambiguously. This is necessary to communicate with certain less-than-compliant devices.
• A deadlock when reading CAN frames asynchronously on Linux, introduced in v2.2.3, has been removed.
• An overload issue in the submit_read_error() method of CanRouter, which prevented submitting instances of io_can_rt_read_err, has been fixed.
• The EDS/DCF linter in dcf-tools no longer complains about sub-objects with a ParameterValue attribute without a DefaultValue.

Download

You can download the source from GitLab or the Ubuntu packages from our PPA.