docs: Update CANBUS.md

Recommend USB to CAN adapter and no longer recommend using the
waveshare rpi hat.

Recommend using allow-hotplug for all USB adapters.

Note bandwidth limitations when using USB to CAN bridge mode.

Note that a USB to CAN mcu is not a USB serial device.

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

1 files changed, 44 insertions, 37 deletions

diff --git a/docs/CANBUS.md b/docs/CANBUS.md
index c71273d5..651ed4c9 100644
--- a/docs/CANBUS.md
+++ b/docs/CANBUS.md
@@ -4,7 +4,7 @@ This document describes Klipper's CAN bus support.
 
 ## Device Hardware
 
-Klipper currently supports CAN on stm32, same5x, and rp2040 chips. In
+Klipper currently supports CAN on stm32, SAME5x, and rp2040 chips. In
 addition, the micro-controller chip must be on a board that has a CAN
 transceiver.
 
@@ -14,44 +14,35 @@ and flash it to the target board.
 
 ## Host Hardware
 
-In order to use a CAN bus, it is necessary to have a host adapter.
-There are currently two common options:
-
-1. Use a
-   [Waveshare Raspberry Pi CAN hat](https://www.waveshare.com/rs485-can-hat.htm)
-   or one of its many clones.
-
-2. Use a USB CAN adapter (for example
-   [https://hacker-gadgets.com/product/cantact-usb-can-adapter/](https://hacker-gadgets.com/product/cantact-usb-can-adapter/)). There
-   are many different USB to CAN adapters available - when choosing
-   one, we recommend verifying it can run the
-   [candlelight firmware](https://github.com/candle-usb/candleLight_fw).
-   (Unfortunately, we've found some USB adapters run defective
-   firmware and are locked down, so verify before purchasing.)
+In order to use a CAN bus, it is necessary to have a host adapter. It
+is recommended to use a "USB to CAN adapter". There are many different
+USB to CAN adapters available from different manufacturers. When
+choosing one, we recommend verifying that the firmware can be updated
+on it. (Unfortunately, we've found some USB adapters run defective
+firmware and are locked down, so verify before purchasing.) Look for
+adapters that can run Klipper directly (in its "USB to CAN bridge
+mode") or that run the
+[candlelight firmware](https://github.com/candle-usb/candleLight_fw).
 
 It is also necessary to configure the host operating system to use the
 adapter. This is typically done by creating a new file named
 `/etc/network/interfaces.d/can0` with the following contents:
 ```
-auto can0
+allow-hotplug can0
 iface can0 can static
-    bitrate 500000
+    bitrate 1000000
     up ifconfig $IFACE txqueuelen 128
 ```
 
-Note that the "Raspberry Pi CAN hat" also requires
-[changes to config.txt](https://www.waveshare.com/wiki/RS485_CAN_HAT).
-
 ## Terminating Resistors
 
 A CAN bus should have two 120 ohm resistors between the CANH and CANL
 wires. Ideally, one resistor located at each the end of the bus.
 
-Note that some devices have a builtin 120 ohm resistor (for example,
-the "Waveshare Raspberry Pi CAN hat" has a soldered on resistor that
-can not be easily removed). Some devices do not include a resistor at
-all. Other devices have a mechanism to select the resistor (typically
-by connecting a "pin jumper"). Be sure to check the schematics of all
+Note that some devices have a builtin 120 ohm resistor that can not be
+easily removed. Some devices do not include a resistor at all. Other
+devices have a mechanism to select the resistor (typically by
+connecting a "pin jumper"). Be sure to check the schematics of all
 devices on the CAN bus to verify that there are two and only two 120
 Ohm resistors on the bus.
 
@@ -95,22 +86,18 @@ canbus_uuid: 11aa22bb33cc
 ## USB to CAN bus bridge mode
 
 Some micro-controllers support selecting "USB to CAN bus bridge" mode
-during "make menuconfig". This mode may allow one to use a
+during Klipper's "make menuconfig". This mode may allow one to use a
 micro-controller as both a "USB to CAN bus adapter" and as a Klipper
 node.
 
 When Klipper uses this mode the micro-controller appears as a "USB CAN
 bus adapter" under Linux. The "Klipper bridge mcu" itself will appear
-as if was on this CAN bus - it can be identified via `canbus_query.py`
-and configured like other CAN bus Klipper nodes. It will appear
-alongside other devices that are actually on the CAN bus.
+as if it was on this CAN bus - it can be identified via
+`canbus_query.py` and it must be configured like other CAN bus Klipper
+nodes.
 
 Some important notes when using this mode:
 
-* The "bridge mcu" is not actually on the CAN bus. Messages to and
-  from it do not consume bandwidth on the CAN bus. The mcu can not be
-  seen by other adapters that may be on the CAN bus.
-
 * It is necessary to configure the `can0` (or similar) interface in
   Linux in order to communicate with the bus. However, Linux CAN bus
   speed and CAN bus bit-timing options are ignored by Klipper.
@@ -119,12 +106,32 @@ Some important notes when using this mode:
 
 * Whenever the "bridge mcu" is reset, Linux will disable the
   corresponding `can0` interface. To ensure proper handling of
-  FIRMWARE_RESTART and RESTART commands, it is recommended to replace
-  `auto` with `allow-hotplug` in the `/etc/network/interfaces.d/can0`
-  file. For example:
+  FIRMWARE_RESTART and RESTART commands, it is recommended to use
+  `allow-hotplug` in the `/etc/network/interfaces.d/can0` file. For
+  example:
 ```
 allow-hotplug can0
 iface can0 can static
-    bitrate 500000
+    bitrate 1000000
     up ifconfig $IFACE txqueuelen 128
 ```
+
+* The "bridge mcu" is not actually on the CAN bus. Messages to and
+  from the bridge mcu will not be seen by other adapters that may be
+  on the CAN bus.
+
+* The available bandwidth to both the "bridge mcu" itself and all
+  devices on the CAN bus is effectively limited by the CAN bus
+  frequency. As a result, it is recommended to use a CAN bus frequency
+  of 1000000 when using "USB to CAN bus bridge mode".
+
+  Even at a CAN bus frequency of 1000000, there may not be sufficient
+  bandwidth to run a `SHAPER_CALIBRATE` test if both the XY steppers
+  and the accelerometer all communicate via a single "USB to CAN bus"
+  interface.
+
+* A USB to CAN bridge board will not appear as a USB serial device, it
+  will not show up when running `ls /dev/serial/by-id`, and it can not
+  be configured in Klipper's printer.cfg file with a `serial:`
+  parameter. The bridge board appears as a "USB CAN adapter" and it is
+  configured in the printer.cfg as a [CAN node](#configuring-klipper).