Add asyncio support

LICENSE.txt

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2016 Christian Sandberg
+Copyright (c) 2025 Svein Seldal
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -1,5 +1,5 @@
-CANopen for Python
-==================
+CANopen for Python, asyncio port
+================================
 
 A Python implementation of the CANopen_ standard.
 The aim of the project is to support the most common parts of the CiA 301
@@ -8,6 +8,84 @@ automation tasks rather than a standard compliant master implementation.
 
 The library supports Python 3.8 or newer.
 
+This library is the asyncio port of CANopen. See below for code example.
+
+
+Asyncio port
+------------
+
+The objective of the library is to provide a canopen implementation in
+either async or non-async environment, with suitable API for both.
+
+To minimize the impact of the async changes, this port is designed to use the
+existing synchronous backend of the library. This means that the library
+uses :code:`asyncio.to_thread()` for many asynchronous operations.
+
+This port remains compatible with using it in a regular non-asyncio
+environment. This is selected with the `loop` parameter in the
+:code:`Network` constructor. If you pass a valid asyncio event loop, the
+library will run in async mode. If you pass `loop=None`, it will run in
+regular blocking mode. It cannot be used in both modes at the same time.
+
+
+Difference between async and non-async version
+----------------------------------------------
+
+This port have some differences with the upstream non-async version of canopen.
+
+* Minimum python version is 3.9, while the upstream version supports 3.8.
+
+* The :code:`Network` accepts additional parameters than upstream. It accepts
+  :code:`loop` which selects the mode of operation. If :code:`None` it will
+  run in blocking mode, otherwise it will run in async mode. It supports
+  providing a custom CAN :code:`notifier` if the CAN bus will be shared by
+  multiple protocols.
+
+* The :code:`Network` class can be (and should be) used in an async context
+  manager. This will ensure the network will be automatically disconnected when
+  exiting the context. See the example below.
+
+* Most async functions follow an "a" prefix naming scheme.
+  E.g. the async variant for :code:`SdoClient.download()` is available
+  as :code:`SdoClient.adownload()`.
+
+* Variables in the regular canopen library uses properties for getting and
+  setting. This is replaced with awaitable methods in the async version.
+
+      var = sdo['Variable'].raw  # synchronous
+      sdo['Variable'].raw = 12   # synchronous
+
+      var = await sdo['Variable'].get_raw()  # async
+      await sdo['Variable'].set_raw(12)      # async
+
+* Installed :code:`ensure_not_async()` sentinel guard in functions which
+  prevents calling blocking functions in async context. It will raise the
+  exception :code:`RuntimeError` "Calling a blocking function" when this
+  happen. If this is encountered, it is likely that the code is not using the
+  async variants of the library.
+
+* The mechanism for CAN bus callbacks have been changed. Callbacks might be
+  async, which means they cannot be called immediately. This affects how
+  error handling is done in the library.
+
+* The callbacks to the message handlers have been changed to be handled by
+  :code:`Network.dispatch_callbacks()`. They are no longer called with any
+  locks held, as this would not work with async. This affects:
+    * :code:`PdoMaps.on_message`
+    * :code:`EmcyConsumer.on_emcy`
+    * :code:`NtmMaster.on_heartbaet`
+
+* SDO block upload and download is not yet supported in async mode.
+
+* :code:`ODVariable.__len__()` returns 64 bits instead of 8 bits to support
+  truncated 24-bits integers, see #436
+
+* :code:`BaseNode402` does not work with async
+
+* :code:`LssMaster` does not work with async, except :code:`LssMaster.fast_scan()`
+
+* :code:`Bits` is not working in async
+
 
 Features
 --------
@@ -156,6 +234,70 @@ The :code:`n` is the PDO index (normally 1 to 4). The second form of access is f
     network.disconnect()
 
 
+Asyncio
+-------
+
+This is the same example as above, but using asyncio
+
+.. code-block:: python
+
+    import asyncio
+    import canopen
+    import can
+
+    async def my_node(network, nodeid, od):
+
+        # Create the node object and load the OD
+        node = network.add_node(nodeid, od)
+
+        # Read the PDOs from the remote
+        await node.tpdo.aread()
+        await node.rpdo.aread()
+
+        # Set the module state
+        node.nmt.set_state('OPERATIONAL')
+
+        # Set motor speed via SDO
+        await node.sdo['MotorSpeed'].aset_raw(2)
+
+        while True:
+
+            # Wait for TPDO 1
+            t = await node.tpdo[1].await_for_reception(1)
+            if not t:
+                continue
+
+            # Get the TPDO 1 value
+            rpm = node.tpdo[1]['MotorSpeed Actual'].get_raw()
+            print(f'SPEED on motor {nodeid}:', rpm)
+
+            # Sleep a little
+            await asyncio.sleep(0.2)
+
+            # Send RPDO 1 with some data
+            node.rpdo[1]['Some variable'].set_phys(42)
+            node.rpdo[1].transmit()
+
+    async def main():
+
+        # Connect to the CAN bus
+        # Arguments are passed to python-can's can.Bus() constructor
+        # (see https://python-can.readthedocs.io/en/latest/bus.html).
+        # Note the loop parameter to enable asyncio operation
+        loop = asyncio.get_running_loop()
+        async with canopen.Network(loop=loop).connect(
+                interface='pcan', bitrate=1000000) as network:
+
+            # Create two independent tasks for two nodes 51 and 52 which will run concurrently
+            task1 = asyncio.create_task(my_node(network, 51, '/path/to/object_dictionary.eds'))
+            task2 = asyncio.create_task(my_node(network, 52, '/path/to/object_dictionary.eds'))
+
+            # Wait for both to complete (which will never happen)
+            await asyncio.gather((task1, task2))
+
+    asyncio.run(main())
+
+
 Debugging
 ---------
 

canopen/async_guard.py

@@ -0,0 +1,43 @@
+""" Utils for async """
+import functools
+import logging
+import threading
+import traceback
+
+# NOTE: Global, but needed to be able to use ensure_not_async() in
+#       decorator context.
+_ASYNC_SENTINELS: dict[int, bool] = {}
+
+logger = logging.getLogger(__name__)
+
+
+def set_async_sentinel(enable: bool):
+    """ Register a function to validate if async is running """
+    _ASYNC_SENTINELS[threading.get_ident()] = enable
+
+
+def ensure_not_async(fn):
+    """ Decorator that will ensure that the function is not called if async
+        is running.
+    """
+    @functools.wraps(fn)
+    def async_guard_wrap(*args, **kwargs):
+        if _ASYNC_SENTINELS.get(threading.get_ident(), False):
+            st = "".join(traceback.format_stack())
+            logger.debug("Traceback:\n%s", st.rstrip())
+            raise RuntimeError(f"Calling a blocking function, {fn.__qualname__}() in {fn.__code__.co_filename}:{fn.__code__.co_firstlineno}, while running async")
+        return fn(*args, **kwargs)
+    return async_guard_wrap
+
+
+class AllowBlocking:
+    """ Context manager to pause async guard """
+    def __init__(self):
+        self._enabled = _ASYNC_SENTINELS.get(threading.get_ident(), False)
+
+    def __enter__(self):
+        set_async_sentinel(False)
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        set_async_sentinel(self._enabled)

canopen/emcy.py

@@ -1,9 +1,12 @@
+from __future__ import annotations
+import asyncio
 import logging
 import struct
 import threading
 import time
 from typing import Callable, List, Optional
 
+from canopen.async_guard import ensure_not_async
 import canopen.network
 
 
@@ -22,11 +25,15 @@
         self.active: List["EmcyError"] = []
         self.callbacks = []
         self.emcy_received = threading.Condition()
+        self.network: canopen.network.Network = canopen.network._UNINITIALIZED_NETWORK
 
+    # @callback  # NOTE: called from another thread
+    @ensure_not_async  # NOTE: Safeguard for accidental async use
     def on_emcy(self, can_id, data, timestamp):
         code, register, data = EMCY_STRUCT.unpack(data)
         entry = EmcyError(code, register, data, timestamp)
 
+        # NOTE: Blocking lock
         with self.emcy_received:
             if code & 0xFF00 == 0:
                 # Error reset
@@ -36,8 +43,8 @@
             self.log.append(entry)
             self.emcy_received.notify_all()
 
-        for callback in self.callbacks:
-            callback(entry)
+        # Call all registered callbacks
+        self.network.dispatch_callbacks(self.callbacks, entry)
 
     def add_callback(self, callback: Callable[["EmcyError"], None]):
         """Get notified on EMCY messages from this node.
@@ -53,6 +60,7 @@
         self.log = []
         self.active = []
 
+    @ensure_not_async  # NOTE: Safeguard for accidental async use
     def wait(
         self, emcy_code: Optional[int] = None, timeout: float = 10
     ) -> "EmcyError":
@@ -65,8 +73,10 @@
         """
         end_time = time.time() + timeout
         while True:
+            # NOTE: Blocking lock
             with self.emcy_received:
                 prev_log_size = len(self.log)
+                # NOTE: Blocking call
                 self.emcy_received.wait(timeout)
                 if len(self.log) == prev_log_size:
                     # Resumed due to timeout
@@ -81,6 +91,18 @@
                     # This is the one we're interested in
                     return emcy
 
+    async def async_wait(
+        self, emcy_code: Optional[int] = None, timeout: float = 10
+    ) -> EmcyError:
+        """Wait for a new EMCY to arrive.
+
+        :param emcy_code: EMCY code to wait for
+        :param timeout: Max time in seconds to wait
+
+        :return: The EMCY exception object or None if timeout
+        """
+        return await asyncio.to_thread(self.wait, emcy_code, timeout)
+
 
 class EmcyProducer: