canbus_stats: Periodically report canbus interface statistics

Add support for a new get_canbus_status command to canserial.c .

Add new canbus_stats.py module that will periodically query canbus
mcus for connection status information.

Signed-off-by: Kevin O'Connor <kevin@koconnor.net>

4 files changed, 110 insertions, 1 deletions

diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md
index 66d840d1..ee809902 100644
--- a/docs/Status_Reference.md
+++ b/docs/Status_Reference.md
@@ -39,6 +39,27 @@ the following strings: "adjust", "fine".
 - `current_screw`: The index for the current screw being adjusted.
 - `accepted_screws`: The number of accepted screws.
 
+## canbus_stats
+
+The following information is available in the `canbus_stats
+some_mcu_name` object (this object is automatically available if an
+mcu is configured to use canbus):
+- `rx_error`: The number of receive errors detected by the
+  micro-controller canbus hardware.
+- `tx_error`: The number of transmit errors detected by the
+  micro-controller canbus hardware.
+- `tx_retries`: The number of transmit attempts that were retried due
+  to bus contention or errors.
+- `bus_state`: The status of the interface (typically "active" for a
+  bus in normal operation, "warn" for a bus with recent errors,
+  "passive" for a bus that will no longer transmit canbus error
+  frames, or "off" for a bus that will no longer transmit or receive
+  messages).
+
+Note that only the rp2XXX micro-controllers report a non-zero
+`tx_retries` field and the rp2XXX micro-controllers always report
+`tx_error` as zero and `bus_state` as "active".
+
 ## configfile
 
 The following information is available in the `configfile` object
diff --git a/klippy/extras/canbus_stats.py b/klippy/extras/canbus_stats.py
new file mode 100644
index 00000000..b9ee3102
--- /dev/null
+++ b/klippy/extras/canbus_stats.py
@@ -0,0 +1,68 @@
+# Report canbus connection status
+#
+# Copyright (C) 2025  Kevin O'Connor <kevin@koconnor.net>
+#
+# This file may be distributed under the terms of the GNU GPLv3 license.
+
+class PrinterCANBusStats:
+    def __init__(self, config):
+        self.printer = config.get_printer()
+        self.reactor = self.printer.get_reactor()
+        self.name = config.get_name().split()[-1]
+        self.mcu = None
+        self.get_canbus_status_cmd = None
+        self.status = {'rx_error': None, 'tx_error': None, 'tx_retries': None,
+                       'bus_state': None}
+        self.printer.register_event_handler("klippy:connect",
+                                            self.handle_connect)
+        self.printer.register_event_handler("klippy:shutdown",
+                                            self.handle_shutdown)
+    def handle_shutdown(self):
+        status = self.status.copy()
+        if status['bus_state'] is not None:
+            # Clear bus_state on shutdown to note that the values may be stale
+            status['bus_state'] = 'unknown'
+            self.status = status
+    def handle_connect(self):
+        # Lookup mcu
+        mcu_name = self.name
+        if mcu_name != 'mcu':
+            mcu_name = 'mcu ' + mcu_name
+        self.mcu = self.printer.lookup_object(mcu_name)
+        # Lookup status query command
+        if self.mcu.try_lookup_command("get_canbus_status") is None:
+            return
+        self.get_canbus_status_cmd = self.mcu.lookup_query_command(
+            "get_canbus_status",
+            "canbus_status rx_error=%u tx_error=%u tx_retries=%u"
+            " canbus_bus_state=%u")
+        # Register periodic query timer
+        self.reactor.register_timer(self.query_event, self.reactor.NOW)
+    def query_event(self, eventtime):
+        prev_rx = self.status['rx_error']
+        prev_tx = self.status['tx_error']
+        prev_retries = self.status['tx_retries']
+        if prev_rx is None:
+            prev_rx = prev_tx = prev_retries = 0
+        params = self.get_canbus_status_cmd.send()
+        rx = prev_rx + ((params['rx_error'] - prev_rx) & 0xffffffff)
+        tx = prev_tx + ((params['tx_error'] - prev_tx) & 0xffffffff)
+        retries = prev_retries + ((params['tx_retries'] - prev_retries)
+                                  & 0xffffffff)
+        state = params['canbus_bus_state']
+        self.status = {'rx_error': rx, 'tx_error': tx, 'tx_retries': retries,
+                       'bus_state': state}
+        return self.reactor.monotonic() + 1.
+    def stats(self, eventtime):
+        status = self.status
+        if status['rx_error'] is None:
+            return (False, '')
+        return (False, 'canstat_%s: bus_state=%s rx_error=%d'
+                ' tx_error=%d tx_retries=%d'
+                % (self.name, status['bus_state'], status['rx_error'],
+                   status['tx_error'], status['tx_retries']))
+    def get_status(self, eventtime):
+        return self.status
+
+def load_config_prefix(config):
+    return PrinterCANBusStats(config)
diff --git a/klippy/mcu.py b/klippy/mcu.py
index eb71e6bc..b12888f8 100644
--- a/klippy/mcu.py
+++ b/klippy/mcu.py
@@ -565,6 +565,7 @@ class MCU:
             self._canbus_iface = config.get('canbus_interface', 'can0')
             cbid = self._printer.load_object(config, 'canbus_ids')
             cbid.add_uuid(config, canbus_uuid, self._canbus_iface)
+            self._printer.load_object(config, 'canbus_stats %s' % (self._name,))
         else:
             self._serialport = config.get('serial')
             if not (self._serialport.startswith("/dev/rpmsg_")
diff --git a/src/generic/canserial.c b/src/generic/canserial.c
index d56235f5..b90eb659 100644
--- a/src/generic/canserial.c
+++ b/src/generic/canserial.c
@@ -2,7 +2,7 @@
 //
 // Copyright (C) 2019 Eug Krashtan <eug.krashtan@gmail.com>
 // Copyright (C) 2020 Pontus Borg <glpontus@gmail.com>
-// Copyright (C) 2021  Kevin O'Connor <kevin@koconnor.net>
+// Copyright (C) 2021-2025  Kevin O'Connor <kevin@koconnor.net>
 //
 // This file may be distributed under the terms of the GNU GPLv3 license.
 
@@ -318,6 +318,25 @@ DECL_TASK(canserial_rx_task);
  * Setup and shutdown
  ****************************************************************/
 
+DECL_ENUMERATION("canbus_bus_state", "active", CANBUS_STATE_ACTIVE);
+DECL_ENUMERATION("canbus_bus_state", "warn", CANBUS_STATE_WARN);
+DECL_ENUMERATION("canbus_bus_state", "passive", CANBUS_STATE_PASSIVE);
+DECL_ENUMERATION("canbus_bus_state", "off", CANBUS_STATE_OFF);
+
+void
+command_get_canbus_status(uint32_t *args)
+{
+    struct canbus_status status;
+    memset(&status, 0, sizeof(status));
+    canhw_get_status(&status);
+    sendf("canbus_status rx_error=%u tx_error=%u tx_retries=%u"
+          " canbus_bus_state=%u"
+          , status.rx_error, status.tx_error, status.tx_retries
+          , status.bus_state);
+}
+DECL_COMMAND_FLAGS(command_get_canbus_status, HF_IN_SHUTDOWN
+                   , "get_canbus_status");
+
 void
 command_get_canbus_id(uint32_t *args)
 {