docs: Update CAN bus documents

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

1 files changed, 74 insertions, 0 deletions

diff --git a/docs/CANBUS.md b/docs/CANBUS.md
new file mode 100644
index 00000000..07569205
--- /dev/null
+++ b/docs/CANBUS.md
@@ -0,0 +1,74 @@
+This document describes Klipper's CAN bus support.
+
+# Device Hardware
+
+Klipper currently only supports CAN on stm32 chips. In addition, the
+micro-controller chip must support CAN and it must be on a board that
+has a CAN transceiver.
+
+To compile for CAN, run "make menuconfig", unselect "Use USB for
+communication (instead of serial)" and then select "Use CAN for
+communication (instead of serial)". Finally, compile the
+micro-controller code 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.)
+
+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
+iface can0 can static
+    bitrate 500000
+    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).
+
+# Finding the canbus_uuid for new micro-controllers
+
+Each micro-controller on the CAN bus is assigned a unique id based on
+the factory chip identifier encoded into each micro-controller. To
+find each micro-controller device id, make sure the hardware is
+powered and wired correctly, and then run:
+```
+~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0
+```
+
+If uninitialized CAN devices are detected the above command will
+report lines like the following:
+```
+Found canbus_uuid=11aa22bb33cc
+```
+
+Each device will have a unique identifier. In the above example,
+`11aa22bb33cc` is the micro-controller's "canbus_uuid".
+
+Note that the `canbus_query.py` tool will only report uninitialized
+devices - if Klipper (or a similar tool) configures the device then it
+will no longer appear in the list.
+
+# Configuring Klipper
+
+Update the Klipper [mcu configuration](Config_Reference.md#mcu) to use
+the CAN bus to communicate with the device - for example:
+```
+[mcu my_can_mcu]
+canbus_uuid: 11aa22bb33cc
+```