# CANbus {% hint style="info" %} **English**: Use your browser's built-in translation — Chrome and Edge detect the language automatically and offer to translate the page. {% endhint %} ## Que es CANbus? CANbus es un estándard utilizado para la comunicación de múltiples dispositivos y que se ha usado en automoción desde los años 90´s. Puedes encontrar más información en la [**Wikipedia**](https://en.wikipedia.org/wiki/CAN_bus) **o revisar el siguiente video y esquema general de como funciona CANbux:** {% tabs %} {% tab title="Video" %} {% embed url="" %} {% endtab %} {% tab title="Esquema" %} Esquema simplificado del cableado de un CANbus: ![](/files/RDeCtlNnw0VvopmKCZHu) {% endtab %} {% endtabs %} ## Que mejoras puede aportar a las impresoras 3D? El uso de CANbus puede aportar algunos beneficios en nuestras impresoras 3D: * **Solo necesitas 4 cables hasta el cabezal de impresión**, (2 para 24v y 2 para datos) lo cual reduce el coste en cableado. * Estos 4 cables solo llevan voltaje, por canbus la comunicación se hace por diferencia de potencial, se **evita cualquier tipo de interferencia o perdida por conexiones o campos electromagnéticos**, etc. * Por ejemplo, si montas cualquier impresora, tipo Voron, Rat Rig **en vez de estar cableando 20 hilos al cabezal pasas esos 4, reduciendo peso en el gantry y problemas de falsos contactos a la larga y simplificando el mantenimiento/expansiones futuras a nivel de cableado**. * El uso del **firmware/bootloader Katapult/CANboot simplifica el proceso de actualización de nuestros componentes CAN,** explicaremos más adelante esto. Con todo esto si sumas los costes de cables que soporten altas temperaturas (PTFE), pcbs de conexión y tiempo de cableado, **merece la pena montar canbus sobretodo en según que tipo de máquinas o para expandir otras que están limitadas en el número de drivers o de pines de expansión**. ![](/files/80H4b9GxKdDxDQ9bJEv7) ![](/files/PIoHXllpUlAtghpGduzO) ### Katapult (antiguamente CANboot) Aunque ya lo adelantabamos antes el **uso de Katapult/CANboot puede simplificarnos más la gestión/actualización de nuestros componentes CAN**. **Kataput/CANboot es un firmware/bootloader que nos va a permitir actualizar el firmware Klipper de nuestros componentes/toolheads desde el propio cableado CAN** sin necesidad de tener que usar cables USB. En cualquier caso no es algo estrictamente necesario pero si al final optamos por utilizar CANbus en nuestra impresora es aconsejable implementarlo ya que nos va a facilitar la vida en la gestión de los dispositivos CAN. ## Necesito un CAN en mi máquina? Aunque en el punto anterior os pusimos brevemente pros y contras del uso de CAN en nuestras máquinas me gustaría dar algunas explicaciones por las que creo que CAN NO es aconsejable en muchas situaciones. Los **fabricantes como siempre quieren vender y los maker como nosotros en 3D probar cosas nuevas y el caso de las conexiones CAN bus es un claro ejemplo de ambas cosas**. Para entender los siguientes razonamientos sobre CAN vs usar USB para expandir el sistema en la siguiente tabla podéis ver los puntos fuertes de cada tecnología: | USB | CAN | | --------------------------------------- | --------------------------- | | Plug\&Play (dependiendo del componente) | Redundancia | | Baja latencia | Tolerancia a interferencias | | Alto ancho de banda | Largas distancias | Algunas de las ventajas comentadas por parte de CANbus es su arquitectura donde mediante su cableado (bus, 2 cables) podemos crear una red de dispositivos pero... verdaderamente eso me beneficia en algo? * normalmente en las electrónicas de nuestras impresoras no contamos con conectores T para crear estas conexiones * la mayoría de electrónicas están pensadas para actuar como nodos terminales, no disponen de la opción de continuar el bus * está pensado para solamente tener el toolhead. En **impresoras con un host Klipper este es el cerebro y donde los beneficios de redundancia de CAN no van a aplicar además en esta arquitectura la latencia es crítica** por lo que la comunicación USB en lugar de CAN nos va a aportar más beneficios eliminando cuellos de botella que puedan limitar el funcionamiento de nuestra máquina. Además **el uso de CAN require de un mayor uso de recursos de sistema para su gestión y un extra de complejidad en su configuración/mantenimiento dependiendo de como se implemente**. En este escenario lo que **queremos diferenciar es el uso de CAN para su uso al conectar nuestra electrónica principal** y que esta pueda estar controlando el resto de componentes del bus como por ejemplo uno o más toolhead **o solo para la gestión de partes satélite de nuestra impresora dejando las controladoras principales usando USB/USART**. Por otro lado estas expansiones de nuestra electrónica, como los toolhead, podemos utilizarlos en modo USB y cuando se discute entre CANbus y USB suelen salir los siguientes puntos de discusión: * **Con USB necesitas más cables que con CANbus, si y no**... lo ideal y aconsejable desde nuestro punto de vista es el uso de un cable USB acorde con el uso y 2 cables de alimentación, algo que tampoco hace complicada la instalación ya que al final acaban siendo 3 cables vs 4 de CANbus dependiendo del tipo de cable que usemos. En cualquier caso con el uso de determinados cables se podría incluso llevar la alimentación a través de este mismo cable USB, algo que de nuevo no aconsejamos. * **Los cables USB no están preparados para un sistema móvil como las impresoras 3D, rotundamente falso**... existen cables USB preparados sin problemas para entornos de este tipo además de aguantar la temperatura. Además que puedes montar cualquier cable que sea adecuado que disponga de 4 hilos y adaptar en cada extremo unos conectores USB de calidad DIY. Lo curioso de esta afirmación por parte de mucha gente que usa CANbus es que cuando les preguntas por las características del cable que usan en su instalación en la mayoría de casos estos cuentan con cables que tampoco están preparados para este uso en un entorno de impresora 3D. * **Los cables USB no permiten cables largos o son proclives a interferencias, algo que no es cierto**... claro está usando cables de calidad y con unas longitudes conformes al estándar que dan sobradamente para cualquier impresora 3D Creo que **CAN es una buena solución para determinadas máquinas donde, principalmente por su tamaño, reducir el cableado al toolhead supone una ventaja, si disponemos de multi tool, o aquellas que queramos ampliar las funciones de la electronica sin invertir en una nueva** tenemos otra opción a explorar aunque a veces puede ser más complicada de montar/mantener aunque sea muy "cool" decir que usamos CAN :smile: Así que antes de aventuraros al mundo CAN me gustaría que pensarais el porqué verdaderamente necesitais CAN o no además de entender los pros y contras del uso del mismo. ## CAN en nuestra impresora Si hemos llegado hasta aquí es porque tenemos claro que queremos implementar CAN a nuestra impresora. Para simplificar el proceso lo hemos dividido en 2 partes... una nueva instalación o si queremos actualizar nuestro CANbus.
Nueva Instalación CAN/files/uXmGMP7r2HRTTcgR8TLJ#instalacion-can-desde-0
Actualizar CAN/files/SrG3y38Qv6W2nO094n9H#actualizando-firmware-en-nuestros-dispositivos-can
## Comandos de referencia rápida Los comandos más usados en el día a día con CANbus en Klipper: ```bash # Verificar que la interfaz CAN está activa ip -s -d link show can0 # Buscar dispositivos CAN sin configurar (obtener UUID) ~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0 # Poner un dispositivo en modo bootloader via CAN (para actualizar firmware) ~/klippy-env/bin/python ~/katapult/scripts/flashtool.py -i can0 -u -r # Flashear Klipper a un dispositivo via CAN (requiere Katapult en el dispositivo) ~/klippy-env/bin/python ~/katapult/scripts/flashtool.py -i can0 -u -f ~/klipper/out/klipper.bin ``` | Comando | Cuándo usarlo | | --------------------------------- | --------------------------------------------------------------------------------- | | `canbus_query.py can0` | Primera puesta en marcha, tras resetear un dispositivo, cuando un UUID desaparece | | `flashtool.py ... -r` | Antes de actualizar Klipper en un dispositivo que ya tiene Katapult activo | | `flashtool.py ... -f klipper.bin` | Actualizar Klipper via CAN sin desmontar nada | | `ip -s -d link show can0` | Verificar bitrate, estado y errores del bus CAN | *** ## Instalación CAN desde 0 Si es la primera vez que instalamos CAN en nuestra máquina deberemos seguir los siguientes pasos. ### Red CAN Para poder utilizar CAN en nuestra máquina y que nuestros dispositivos CAN puedan interactuar necesitamos habilitar un interfaz CAN en nuestro host Klipper. Dependiendo del sistema operativo de nuestro host puede que la gestión de redes de este utilice los comandos de servicios de red ifupdown (es el "de toda la vida") o systemd-networkd... en nuestro caso os sugerimos realizar el proceso en ambos para asegurarnos que no tenemos problemas. {% tabs %} {% tab title="ifupdown" %} Nos conectaremos a nuestro host por SSH y lanzaremos el siguiente comando para crear un fichero de configuración para nuestro interfaz `can0`, en nuestro caso usamos el editor de texto `nano` que suele venir instalado normalmente pero puedes utilizar el que te sea más cómodo: ```bash sudo nano /etc/network/interfaces.d/can0 ``` Ya en el editor copiaremos esta configuración: 
  allow-hotplug can0
  iface can0 can static
    bitrate 1000000
    up ip link set can0 txqueuelen 1024
Os intentamos explicar para que sirve algunas partes de esta configuración: * `allow-hotplug`, permite que ante un restart o reinicio de servicios los dispositivos CAN puedan volver a conectarse de forma automática * `bitrate`, indica la velocidad de comunicación del interfaz CAN lo normal y aconsejable es utilizar 1000000 (1M) siempre que nuestros dispositivos CAN lo soporten y nos aseguraremos que a la hora de crear el firmware establezcamos este bitrate en sus opciones. De no hacerlo deberemos ajustar este valor al del dispositivo con el valor más bajo. Como veremos más adelante ajustar este parámetro correctamente es crucial para evitar cuellos de botella (por ejemplo si usamos acelerómetros o tiras led gestionadas por un dispositivo CAN) y problemas de comunicación. * `txqueuelen`, se sugiere 1024 y básicamente permite crear una cola/buffer de gestión de mensajes que en caso de saturación permita evitar problemas de cuellos de botella con el típico error "Timer too close". Una vez ya tenemos nuestro fichero de configuración para nuestra interfaz `can0` podemos reiniciar nuestro host con un `sudo reboot` {% endtab %} {% tab title="systemd-networkd" %} En el caso que contemos con un sistema operativo para nuestro host, normalmente reciente, que funcione utilizando systemd-networkd (o netplan) el procedimiento es similar. Nos conectaremos a nuestro host por SSH y lanzaremos el siguiente comando para crear un fichero de configuración para nuestro interfaz `10-can-link`, en nuestro caso usamos el editor de texto `nano` que suele venir instalado normalmente pero puedes utilizar el que te sea más cómodo: ```bash sudo nano /etc/systemd/network/10-can.link ``` Ya en el editor copiaremos esta configuración: {% code title="/etc/systemd/network/10-can.link" %} ```bash [Match] Type=can [Link] TransmitQueueLength=1024 ``` {% endcode %} En este fichero de configuración estableceremos el tipo de interfaz y el tamaño de la cola/buffer de mensajes tal como explicamos anteriormente en el proceso ifupdown. De nuevo crearemos otro fichero de configuracion, en este caso llamado 25-can.network donde indiacremos el bitrate: ```bash sudo nano /etc/systemd/network/25-can.network ``` {% code title="/etc/systemd/network/25-can.network" %} ```bash [Match] Name=can* [CAN] BitRate=1M ``` {% endcode %} {% endtab %} {% endtabs %} ### Componentes CAN Antes de continuar con los siguientes pasos os vamos a explicar de forma general los componentes de un CANbus. #### Adaptador/Electrónica bridge CAN Para que nuestro host pueda tener acceso a nuestra interfaz/red CAN necesitamos un dispositivo que haga de "puente" entre los dispositivos CAN y nuestro host. Normalmente disponemos de dos opciones: * **Adaptadores CAN**, normalmente estos son unas pequeñas controladoras que disponen de conexión para cableado CAN y un interfaz USB para conectar a nuestro host Klipper.\ Por ejemplo tenemos el Bigtreetech U2C que es uno de los que solemos aconsejar por la compatibilidad con diferentes tipos de conexiones, comunidad/soporte/documantación y calidad/precio.

Diagrama de conexión CAN utilizando un adaptador USB CAN (Bigtreetech U2C)

* **Electrónicas con CAN/bridge**, también recientemente se ha extendido por parte de los fabricantes añadir conexiones CAN en las electrónicas. En este caso tenemos que distinguir aquellas que disponen CAN para ser utilizadas como un dispositivo o aquellas que disponen CAN bridge con un transceiver CAN que nos va a hacer de "puente" entre los dispositivos CAN y nuestro host Klipper.\ En este caso las electrónicas Bigtreetech de nuevo dan soporte en muchos de sus modelos (Octopus/Manta/Kraken) a CAN/bridge.\ En este caso si queremos habilitar CAN en nuestra instalación y nuestra electrónica dispone de opciones de CAN/bridge con transceiver no será necesario del uso de un adaptador CAN extra.

Diagrama de conexión CAN utilizando una electrónica como CAN bridge (Bigtreetech Octopus)

#### Toolheads Normalmente el uso de CAN en las impresoras 3D tiene sentido para colocar una electrónica en el cabezal de impresión para reducir la cantidad de cableado. En este caso disponemos de controladoras/electrónicas específicamente diseñadas para ello de diferentes marcas como Bigtreetech, Fysetc, Mellow y que con los diferentes modelos y versiones se acaptan a practicamente cualquier cabezal de impresión ### Adaptador CAN Ahora que explicamos los diferentes componetes CAN y en especial los adaptadores CAN vamos a continuar con la configuración de estos donde tenemo dos opciones:
Adaptador CAN USB/files/i8OwhhNzhYm9GL5dQ3ZZ#adaptador-can-usb-como-interfaz-can
Electrónica CAN/bridge/files/0PmL6CAtJDp6cBvB9m3z#electronica-can-bridge-como-interfaz-can
#### Adaptador CAN USB como interfaz CAN Tal como os hemos comentado estos adaptadores se suelen conectar por USB a nuestro host y nos permiten que este pueda "hablar" con los dispositivos CAN a través de nuestra red CAN que montamos en pasos anteriores. Al conectarse estos mediante USB una forma sencilla para detectar si estos fueron detectados por el sistema es lanzando el comando `lsusb` desde SSH y veremos un dispositivo con una descripción `OpenMoko, Ink`, `Geschwister Schneider CAN adapter` o similares.
Si vemos que nuestro adaptador CAN fué detectado el siguiente paso será configurar que nuestro interfaz CAN, el cual configuramos previamente está levantado y funcionando correctamente, mediante el siguiente comando: ```bash ip -s -d link show can0 ``` Deberemos ver algo similar a la siguiente captura donde podremos ver los parámetros de bitrate y cola/buffer que configuramos en el interfaz:
{% hint style="warning" %} Si no detectamos nuestro adaptador USB CAN o tenemos problemas con el interfaz: * es posible que el firmware del adaptador no sea el correcto, este dañado o falle el dispositivo. En este caso os aconsejamos ir al Github o repositorio del fabricante del mismo para aplicar de nuevo el firmware actualizado. * en algunos casos podemos ver fallow del interfaz arriba o abajo, normalmente también suele estar relacionado con problemas de firmware en el adaptador {% endhint %} A continuación os damos información de algunos de los adaptadores USB más comunes: {% tabs %} {% tab title="Bigtreetech U2C" %} Dependiendo del modelo de U2C contamos con opciones de varios buses CAN usando USB los cuales podéis ver en el siguiente esquema, es importante recordar que cada uno de ellos tienen su propio terminador en forma de jumper y sus jumpers VUSB1 y 2 para el control de la alimentacion reversa en esos USB. ![](/files/sJnnIIJk7yJ2RbPm1d7D) En la siguiente imagen os aconsejamos prestar especial atención a los jumpers de terminación CAN (120R) y su ubicación dependiendo del o los buses que utilicemos en nuestro caso. ![](/files/2PEaTdp16UCuD0tzJUlE) También en el caso de utilizar los buses USB (VBUS1-2) disponemos unos jumpers para evitar la retroalimentación de 5V ![](/files/1eO8ECs0XpjJLhyXQKXO) En el siguiente esquema podéis ver mejor a que conexión corresponde cada uno de los conectores CAN disponibles en nuestra U2C. ![](/files/7yVgfk6EuuAgrWgeWXRN) **Firmware,** módulo U2C de Bigtreetech usa CandeLight que es un firmware open source que podéis encontrar [**aquí**](https://github.com/candle-usb/candleLight_fw). Os recordamos el el U2C usa una MCU STM32F072C8. ![](/files/wgj0BVp2duSjQLycRbbB) Para actualizar el firmware con el módulo sin alimentación pulsaremos el botón BOOT y conectaremos el cable USB C para entrar en modo DFU. Con STM32CubeProgrammer actualizaremos el firmware. {% hint style="info" %} También tenéis una forma alternativa para actualizar usando esta web que, si os funciona, es una forma bastante sencilla: {% endhint %} {% hint style="warning" %} **U2C v2.1!!!!** Para poder usar correctamente esta versión de U2C es aconsejable utilizar el firmware que podéis encontrar [**aquí**](https://github.com/Esoterical/voron_canbus/tree/main/can_adapter/BigTreeTech%20U2C%20v2.1) ya que aparentemente el **proporcionado por el fabricante con las versiones de Klipper actuales no funciona correctamente**. El proceso es el mismo para poner el U2C en modo DFU y comprobar con `dfu-util -l` Aplicamos el firmware con `dfu-util -D ~/G0B1_U2C_V2.bin -a 0 -s 0x08000000:leave` El error de `get-status` no suele afectar. Una vez aplicado desconectamos y volvemos a conectar el U2C y ya deberiamos tener visible nuestro interfaz `can0` (si hemos configurado correctamente el interfaz `/etc/network/interfaces.d/can0`) {% endhint %} {% endtab %} {% tab title="Mellow UTC" %} Otro adaptador USB popular es el Mellow UTC. En este caso cuenta con la resistencia de terminación (120R) directamente soldada por lo que no es necesario ningún jumper. Aunque el adaptador viene con el firmware pre-instalado puede ser útil tener el siguiente procedimiento a mano para actualizar o restaurar el firmware. Tenéis el [proceso descrito en detalle en la Wiki de Mellow ](https://mellow-3d.github.io/fly-utoc_firmware.html#flashing-utoc-firmware)y podéis descargar la última versión del firmware desde [aquí](https://mellow-3d.github.io/files/utoc_firmware.bin). Para actualizar el firmware, y con todas las conexiones retiradas, pondremos el jumper DFU tal como podeis ver en la siguiene imagen:
Conectaremos el adaptador Mellow UTC a nuestro host Klipper con un cable USB-C y lanzaremos el comando `lsusb` que dentro de la lista de dispositivos debería listarnos uno con las siguientes características: ``` Bus 001 Device 004: ID 0483:df11 STMicroelectronics STM Device in DFU Mode ``` A continuación y con el firmware descargado del link que os facilitamos anteriormente copiado en nuestro host Klipper actualizaremos con el siguiente comando: ```bash sudo dfu-util --dfuse-address -d 0483:df11 -c 1 -i 0 -a 0 -s 0x08000000 -D ~/utoc_firmware.bin ``` **Conexión de nuestra controladora UTOC:** * USB de nuestra PI a nuestra controladora UTOC * H en UTOC a H en nuestra SHT o Toolhead * L en UTOC a L en nuestra SHT o Toolhead * 24V de nuestra fuente a nuestra UTOC * GND de nuestra fuente a nuestra UTOC * 24 de nuestra UTOC a 24 en nuestra SHT o Toolhead * GND de nuestra UTOC a GND en nuestra SHT o Toolhead ![](/files/wx0Z9qSbIJWN9kts6jOw) {% endtab %} {% tab title="Waveshare Raspberry Pi CAN" %} El adaptador Waveshare Raspberry Pi CAN hat conectable directamente al gpio o mediante cableado a través de los puertos SPI y UART. ![](/files/lI2rFsnVBFpLzYOkW7v5) El puerto en la Raspberry Pi se utiliza para la salida de la consola de Linux de forma predeterminada, por lo que necesitamos desactivarlo primero: * Ejecute Comando para abrir RASPI-CONFIG: ```bash sudo raspi-config ``` ![](/files/L4SQLKEdimmt0MvKdNIN) * Elija Interfacing Options -> Serial -> No ![](/files/eZsWjqw49g73NBwxXzO3) ![](/files/ctVHEinWK8HbF0t7M2To) * Abra el archivo /boot/config.txt, agregue la siguiente línea: ```bash enable_uart=1 ``` * Para Raspberry PI, el puerto serie se utiliza para Bluetooth, está línea tiene que estar comentada: ```bash #dtoverlay=pi-minuart-b ``` * Definimos la configuración del puerto CAN bus. Añadimos la siguiente línea en el archivo /boot/config.txt según las dos versiones disponibles. La única diferencia entre estas versiones es la frecuencia del oscilador de cristal. ![](/files/CpAdGLOhWhcNfCQC1UHe) ```bash // Si tenemos el cristal de 8Mhz dtoverlay=mcp2515- can0,oscillator=8000000,interrupt=25,spimax frequency=1000000 // Si tenemos el cristal de 12Mhz dtoverlay=mcp2515- can0,oscillator=12000000,interrupt=25,spi maxfrequency=2000000 ``` {% endtab %} {% endtabs %} Una vez tenemos detectado nuestro adaptador y el interfaz está levantado podemos continuar con la [configuración de nuestro toolhead.](#toolheads-hotend-canbus) #### Electrónica CAN/bridge como interfaz CAN Tal como os comentamos anteriormente podemos utilizar nuestra electrónica de control de la impresora como adaptador CAN siempre que esta lo soporte, en concreto hemos de fijarnos en electrónicas que soporten CAN/bridge e integren un transceptor CAN. Antes de comenzar con el proceso es aconsejable asegurarnos que nuestro sistema instalado en el host disponga de todas las dependencias instaladas, para ello lanzaremos: ```bash sudo apt update sudo apt upgrade sudo apt install python3 python3-pip python3-can pip3 install pyserial ``` **Instalación de Katapult/CANboot en electrónica de control** Aunque no es algo obligatorio si que es algo que os aconsejamos el uso de Katapult si optáis por montar CAN en vuestra máquina... os va a facilitar mucho algunos procesos. El primer paso será clonar el repositorio de Katapult: ```bash test -e ~/katapult && (cd ~/katapult && git pull) || (cd ~ && git clone https://github.com/Arksine/katapult) ; cd ~ ``` El siguiente paso será crear nuestro firmware Katapult para nuestra electrónica, lanzaremos los siguientes comandos: ```bash cd ~/katapult make menuconfig ``` {% hint style="warning" %} **Los siguientes pasos son un ejemplo, deberás de ajustar las opciones dependiendo de tu electrónica. A modo de ejemplo al finalizar esta sección os facilitamos las configuraciones para las electrónicas más comunes.** **Recuerda que no nos hacemos responsables de ningún problema o daño que se pueda ocasionar a tu electrónica... tú eres el único responsable de lo que haces.** {% endhint %} Y ajustaremos las opciones para nuestra electrónica, en nuestro caso:
Saldremos (Q) guardando cambios (Y), **pondremos nuestra electrónica en modo DFU** y con el comando sudo `dfu-util -l`del resultado del comando anterior prestaremos especial atención al **ID del dispositivo (0483:df11) y al valor de Internal Flash (0x08000000)** ya que los vamos a necesitar en pasos siguientes:
Ahora ya tenemos todo para compilar y aplicar lanzando los siguientes comandos ajustando el valor de -s al valor de Internal Flash obtenido anteriormente, y el valor de -d al ID del dispositivo también del paso anterior: ```bash cd ~/katapult make sudo dfu-util -R -a 0 -s 0x08000000:leave -D ~/katapult/out/katapult.bin -d 0483:df11 ``` {% hint style="info" %} Dependiendo del entorno o estado de la electrónica puede ser necesario aplicar el firmware forzando que se aplique: `sudo dfu-util -a 0 -D ~/katapult/out/katapult.bin --dfuse-address 0x08000000:force:mass-erase -d 0483:df11` {% endhint %} Puede que al final del proceso veamos un error en la linea dfu-util, no pasa nada mientras que File downloaded sea **successfully**.
Para verificar que todo ha ido correctamente saldremos del modo DFU de la electronica, mediante un reset de esta o retirando un jumper dependiendo de cada electrónica, y lanzaremos el comando `ls /dev/serial/by-id` que nos debería retornar un dispositivo conectado que el inicio del nombre sea `usb-katapult`...
Ahora que ya tenemos nuestro bootloader Katapult aplicado en nuestra electrónica el siguiente paso es **generar y aplicar el firmware Klipper** a esta. Para ello no nos vamos a extender en esta parte y os aconsejamos seguir las instrucciones normales de Klipper para vuestra electrónica pero muy importante asegurarnos que indicamos como `Communication interface` a `USB to CAN bus bridge` en los pines correctos (en nuestro ejemplo USB on PA11/PA12) de esta y ajustar `CAM bus speed` a la velocidad que ajustamos en la configuración de nuestro interfaz CAN, en nuestro caso 1000000 (1M).
También podremos reallizar este proceso utilizando Katapult, una vez configurado y compilado el firmware tal como explicamos en el paso antrior, para ello y por seguridad vamos a detener el servicio Klipper con el comando `sudo service klipper stop` y seguidamente `ls /dev/serial/by-id/` para obtener el ID de nuestro dispositivo Katapult, nuestra electrónica en este caso:
Y con el siguiente comando, donde usaremos nuestro ID obtenido en el paso anterior, podremos aplicar el firmware Klipper de forma directa: ```bash python3 ~/katapult/scripts/flashtool.py -f ~/klipper/out/klipper.bin -d /dev/serial/by-id/usb-katapult_rp2040_E6613893F5D7224-if00 ``` El siguiente paso a realizar sería obtener el UUID de nuestra electrónica que tenéis explicado [aquí](#encontrar-el-canbus_uuid-para-nuevas-mcus) y continuar con el siguiente paso que es preparar nuestro [toolhead](#toolheads-can). A continuación os facilitamos información de las más comunes/usadas: {% hint style="danger" %} **IMPORTANTE!!!** * **no nos hacemos responsables de ningún problema o daño que se pueda ocasionar a tu electrónica... tú eres el único responsable de lo que haces** * **antes de aplicar ninguna configuración descrita en los siguientes pasos verifica con la documentación del fabricante que los valores/configuraciones son correctas para tu caso** {% endhint %} {% tabs %} {% tab title="BTT Kraken" %} * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* DFU, mientras presionamos el boton BOOT0 pulsamos una vez el botón RESET y soltamos el boton BOOT0 a los 5s
* 120R, resistencia de terminador CAN
{% endtab %} {% tab title="BTT Manta" %} **Bigtreetech Manta M8P v2.0** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* 120R, resistencia de terminador CAN
**Bigtreetech Manta M8P v1.1** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* 120R, resistencia de terminador CAN
**Bigtreetech Manta M5P v1.0** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* DFU, mientras presionamos el boton BOOT0 pulsamos una vez el botón RESET y soltamos el boton BOOT0 a los 5s
* 120R, resistencia de terminador CAN
**Bigtreetech Manta E3EZ** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* 120R, resistencia de terminador CAN
{% endtab %} {% tab title="BTT Octopus" %} **Bigtreetech Octopus Max EZ** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* 120R, resistencia de terminador CAN
**Bigtreetech Octopus** * Configuración para Katapult/Canboot

MCU STM32F446

MCU STM32F429

MCU STM32F407

MCU STM32H723

* Configuración CAN/bridge

MCU STM32F446

MCU STM32F429

MCU STM32F407

MCU STM32H723

* DFU, en este caso necesitaremos colocar un jumper en el pin marcado en púrpura/morado y presionaremos el botón de RESET (verde). Usaremos el jumper marcado en azul para indicar si la electrónica se alimenta por USB o la fuente de la impresora.
{% endtab %} {% tab title="SKR 3" %} **Bigtreetech SKR 3 / 3 EZ** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
{% endtab %} {% tab title="Fysetc Spider" %} **Fysetc Spicer v3.0** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* DFU, pulsaremos el boton BT0 y con este pulsado haremos una pulsacion en el RST esperando 5s hasta soltar el BT0
{% hint style="warning" %} Los **siguientes modelos de Fysetc Spider no incorporan un transceptor** **CAN** por lo que ha de añadirse de forma externa como un TJA1050. Os daremos una sugerencia en cada caso de como conectarlo a la electrónica. {% endhint %} **Fysetc Spicer v2.3** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* Transceptor externo, TJA1050, conectaremos el CAN Rx/Tx a los pines PD0/PD1 del conector CAN que cuenta la electrónica y 5v/GND para alimentar el transceptor
**Fysetc Spicer v2.2** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* Transceptor externo, TJA1050, conectaremos el CAN Rx/Tx a los pines PD0/PD1 del conector CAN que cuenta la electrónica y 5v/GND para alimentar el transceptor
**Fysetc Spicer v1.0** * Configuración para Katapult/Canboot
* Configuración CAN/bridge
* Transceptor externo, TJA1050, conectaremos el CAN Rx/Tx a los pines PD0/PD1 del conector CAN que cuenta la electrónica y 5v/GND para alimentar el transceptor
{% endtab %} {% endtabs %} ### Dónde conseguir los componentes CAN {% tabs %} {% tab title="BTT EBB36 / EBB42 CAN toolboard" %} {% embed url="" %} {% endtab %} {% tab title="BTT U2C v2.1 (adaptador USB-CAN)" %} {% embed url="" %} {% endtab %} {% endtabs %} {% hint style="info" %} Si utilizas los links de compra, el precio del producto será el mismo que si accedes de manera habitual, pero a 3DWork le quedará una pequeña comisión. Algo que nos ayudará a soportar el proyecto y continuar generando contenido. {% endhint %} ### ToolHeads CAN Antes de comenzar con el proceso es aconsejable asegurarnos que nuestro sistema instalado en el host disponga de todas las dependencias instaladas, para ello lanzaremos: ```bash sudo apt update sudo apt upgrade sudo apt install python3 python3-pip python3-can pip3 install pyserial ``` **Instalación de Katapult/CANboot en Toolhead** Aunque no es algo obligatorio si que es algo que os aconsejamos el uso de Katapult si optáis por montar CAN en vuestra máquina... os va a facilitar mucho algunos procesos. El primer paso será clonar el repositorio de Katapult: ```bash test -e ~/katapult && (cd ~/katapult && git pull) || (cd ~ && git clone https://github.com/Arksine/katapult) ; cd ~ ``` {% hint style="info" %} Los pasos anteriores no son necesarios si ya los hemos previamente al utilizar nuestra electrónica como adaptador CAN ya que durante los pasos de puesta en marcha explicados anteriormente ya se han realizado. {% endhint %} El siguiente paso será crear nuestro firmware Katapult para nuestra electrónica, lanzaremos los siguientes comandos: ```bash cd ~/katapult make menuconfig ``` {% hint style="warning" %} **Los siguientes pasos son un ejemplo, deberás de ajustar las opciones dependiendo de tu toolhead. A modo de ejemplo al finalizar esta sección os facilitamos las configuraciones para los toolhead más comunes.** **Recuerda que no nos hacemos responsables de ningún problema o daño que se pueda ocasionar a tu electrónica... tú eres el único responsable de lo que haces.** {% endhint %} Y ajustaremos las opciones para nuestro toolhead, en nuestro caso:

Ejemplo configuración toolhead

Saldremos (Q) guardando cambios (Y). Normalmente los toolhead cuentan con MCU STM32xxx o con RP2040, en este caso los siguientes pasos varían dependiendo de esto: {% tabs %} {% tab title="STM32xxx" %} P**ondremos nuestra electrónica en modo DFU** y con el comando sudo `dfu-util -l`del resultado del comando anterior prestaremos especial atención al **ID del dispositivo (0483:df11) y al valor de Internal Flash (0x08000000)** ya que los vamos a necesitar en pasos siguientes:
Ahora ya tenemos todo para compilar y aplicar lanzando los siguientes comandos ajustando el valor de -s al valor de Internal Flash obtenido anteriormente, y el valor de -d al ID del dispositivo también del paso anterior: ```bash cd ~/katapult make sudo dfu-util -R -a 0 -s 0x08000000:force:mass-erase:leave -D ~/katapult/out/katapult.bin -d 0483:df11 ``` Puede que al final del proceso veamos un error en la linea dfu-util, no pasa nada mientras que File downloaded sea **successfully**.
Para verificar que todo ha ido correctamente saldremos del modo DFU del toolhead, mediante un reset de esta o retirando un jumper dependiendo de cada toolhead, y lanzaremos el comando `ls /dev/serial/by-id` que nos debería retornar un dispositivo conectado que el inicio del nombre sea `usb-katapult`...
{% endtab %} {% tab title="RP2040" %} Siguiendo las instrucciones del fabricante del toolhead pondremos esta en modo BOOT, y ejecutaremos el comando `lsusb` para listar los dispositivos conectados donde tendremos que ver uno con el nombre `Raspberry Pi boot`.
Y donde nos anotaremos el ID del dispositivo (2e8a:003 en nuestro ejemplo). El cual usaremos para aplicar el firmware/bootloader Katapult a nuestro toolhead: ```bash cd ~/katapult make flash FLASH_DEVICE=2e8a:0003 ```
{% hint style="info" %} Si tenemos problemas para aplicar el firmware katapult.uf2 mediante comandos siempre podemos utilizar el método manual, básicamente es poner el toolhead en modo BOOT conectarlo a nuestro host/ordenador donde veremos una unidad y copiaremos el katapult.uf2 dentro. {% endhint %} {% endtab %} {% endtabs %} Ahora que ya tenemos nuestro bootloader Katapult aplicado en nuestro toolhead el siguiente paso es verificar que este está funcionando correctamente. Para ello apagaremos con sudo shutdown now nuestro host y la impresora en el caso que usen alimentación separada. Dependiendo del toolhead, si este utiliza jumpers para entrar en modo DFU, retiraremos los jumpers, retiraremos el cable USB del toolhead a nuestro host y conectaremos los cables CAN (CANL/H) y los de alimentación al toolhead (Vin/GND). Volveremos a iniciar/encender nuestro host y después nuestra impresora y volveremos a conectar por SSH revisando que nuestra interfaz CAN esté levantada y revisando los dispositivos en esta con los siguientes comandos: ```bash ip -s -d link show can0 python3 ~/katapult/scripts/flashtool.py -i can0 -q ``` Nos debería de aparecer un dispositivo `Application: Katapult` en el listado que es nuestro toolhead y tomaremos nota del UUID de este (en nuestro ejemplo 66f03f24c715):
Ahora toca **generar y aplicar el firmware Klipper** a nuestro toolhead una vez aplicado el bootloader Katapult. Lanzaremos los siguientes comandos para configurar las opciones del firmware Klipper: ```bash cd ~/klipper make menuconfig ``` Para ello no nos vamos a extender en esta parte y os aconsejamos seguir las instrucciones normales de Klipper para vuestro toolhead pero muy importante asegurarnos que indicamos como `CAN Bus` donde pondremos los pines correctos de esta y ajustar `CAM bus speed` a la velocidad que ajustamos en la configuración de nuestro interfaz CAN, en nuestro caso 1000000 (1M). Ejecutaremos los siguientes comandos para compilar nuestro firmware Klipper que se guardará, el la extensión dependerá de la MCU que monte nuestro toolhead, en \~/klipper/out/klipper.bin y aplicaremos siguiendo las intrucciones normales de nuestro fabricante: ```bash make clean make ``` También podremos reallizar este proceso utilizando Katapult, una vez configurado y compilado el firmware tal como explicamos en el paso antrior, para ello y por seguridad vamos a detener el servicio Klipper con el comando `sudo service klipper stop` y seguidamente utilizaremos el siguiente comando para aplicar el firmware en nuestro toolhead usando como parámetro `-d` el UUID obtenido en pasos anteriores: 
python3 ~/katapult/scripts/flashtool.py -i can0 -u b6d9de35f24f -f ~/klipper/out/klipper.bin
Para verificar que todo se aplicó correctamente volveremos a ejecutar `python3 ~/katapult/scripts/flashtool.py -i can0 -q` para listar los dispositivos CAN donde deberiamos de ver nuestro UUID con la descipción `Application: Klipper`:
Arrancaremos de nuevo Klipper con el comando `sudo service klipper start`. También podemos lanzar el comando de Klipper `~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0` donde veremos el UUID que usaremos posteriormente en nuestro printer.cfg como cadena de conexión CAN (en nuestro ejemplo 66f03f24c715):
A continuación os facilitamos información de las más comunes/usadas: {% hint style="danger" %} **IMPORTANTE!!!** * **no nos hacemos responsables de ningún problema o daño que se pueda ocasionar a tu electrónica... tú eres el único responsable de lo que haces** * **antes de aplicar ninguna configuración descrita en los siguientes pasos verifica con la documentación del fabricante que los valores/configuraciones son correctas para tu caso** {% endhint %} {% hint style="warning" %} **Resistencias de terminación** Un CAN bus debe tener dos resistencias de 120 ohmios entre los cables CANH y CANL. Preferiblemente,una resistencia ubicada en cada extremo del bus. Tenga en cuenta que algunos dispositivos tienen una resistencia integrada de 120 ohmios (por ejemplo, el "Waveshare Raspberry Pi CAN hat" tiene una resistencia soldada en la pcb). Algunos dispositivos no incluyen ninguna resistencia. Otros dispositivos tienen un mecanismo para seleccionar la resistencia (normalmente conectando un "jumper"). Asegúrese de revisar los esquemas de todos los dispositivos en el bus CAN para verificar que haya dos y solo dos resistencias de 120 ohmios en el bus. Para probar que las resistencias son correctas, se puede desconectar la alimentación de la impresora y usar un multímetro para verificar la resistencia entre los cables CANH y CANL; debería medir \~60 ohmios en un CAN bus cableado correctamente. {% endhint %} {% tabs %} {% tab title="BTT EBB v1.x" %} * Configuración para Katapult/Canboot

EBB36 v1.2

EBB42 v1.2

* Configuración firmware Klipper para CAN/bridge

EBB36 v1.2

EBB42 v1.2

* DFU, colocar el jumper... conectamos a nuestro host por USB... pulsamos RESET/BOOT... lanzando un `lsusb` deberiamos obtener : `Bus 001 Device 005: ID 0483:df11 STMicroelectronics STM Device in DFU Mode`

EBB36 v1.2

EBB42 v1.2

* 120R, resistencia de terminador CAN

EBB36 v1.2

EBB42 v1.2

{% endtab %} {% tab title="BTT MMB CAN" %} * Configuración para Katapult/Canboot
* Configuración firmware Klipper para CAN/bridge
* DFU, colocar el jumper... conectamos a nuestro host por USB... pulsamos RESET/BOOT... lanzando un `lsusb` deberiamos obtener : `Bus 001 Device 005: ID 0483:df11 STMicroelectronics STM Device in DFU Mode`
* 120R, resistencia de terminador CAN
{% endtab %} {% tab title="BTT SB22XX" %} * Configuración para Katapult/Canboot

SB2240 / SB2209

SB2209 RP2240 MCU

* Configuración firmware Klipper para CAN/bridge

SB2240 / SB2209

SB2209 RP2240 MCU

* DFU, * SB2240 / SB2209...colocar el jumper... conectamos a nuestro host por USB... pulsamos RESET/BOOT... lanzando un `lsusb` deberiamos obtener : `Bus 001 Device 005: ID 0483:df11 STMicroelectronics STM Device in DFU Mode` * SB2209 RP2240 MCU...sin ningún cable conectado pondremos el jumper en USB\_5V... conectaremos el cable USB de nuestro host a la SBB2209... pulsaremos BOOT, y con este pulsado, haremos lo mismo pero brevemente con el RST... continuamos unos segundos con el BOOT pulsado y al soltarlo ya deberiamos estar en modo DFU que podemos verificar con un `lsusb`
* 120R, resistencia de terminador CAN
{% endtab %} {% endtabs %} ## Encontrar el canbus\_uuid para nuevas MCUs A cada MCU se le asigna un UUID único para ser identificado en el CAN bus, este identificador está codificado en el chip de la MCU. {% hint style="warning" %} Para encontrar el identificador de cada MCU, asegúrese de que el hardware esté encendido, con sus terminadores y cableado correctamente {% endhint %} Y luego ejecutaremos: ```bash ~/klippy-env/bin/python ~/klipper/scripts/canbus_query.py can0 ``` {% hint style="warning" %} Podemos levantar el interfaz **can0** manualmente ejecutando: > **sudo ip link set up can0 type can bitrate 1000000** En el caso que nuestro interfaz CAN no se levante automáticamente: * Editaremos el fichero nano /etc/rc0.d/K01klipper\_mcu * Añadiremos esta linea al final:\ PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin\ ip link set up can0 type can bitrate 1000000 {% endhint %} Solo se detectan dispositivos CAN bus que estén disponibles para ser activados, el comando anterior informará con líneas como las siguientes: ``` Found canbus_uuid = 11aa22bb33cc ``` Cada dispositivo tendrá un identificador único. En el ejemplo anterior, 11aa22bb33cc es el "canbus\_uuid" de un dispositivo que no está en funcionamiento y puede ser activado. Tenga en cuenta que la herramienta canbus\_query.py solo informará sobre dispositivos no activados: si Klipper (o una herramienta similar) activa un dispositivo, ya no aparecerá en dicha lista. ## Configuración de Klipper Actualice su configuración de mcu en Klipper para conectar a través del puerto CAN bus a dicho dispositivo, un ejemplo utilizando nuestra electrónica utilizando CAN ejemplo: ``` [mcu] canbus_uuid: 11aa22bb33cc ``` En el caso de la configuración de un toolhead CAN hemos de dar un nombre/ID a la mcu: ``` [mcu] canbus_uuid: 11aa22bb33cc ``` Os aconsejamos para tener un printer.cfg ordenado, simplificado y aprovechar las funciones de Klipper... el tener las configuraciones relacionadas con vuestro toolhead en un fichero toolboard-config.cfg que crearemos a la misma altura de nuetro printer.cfg y en este último añadiremos como include: ``` [include toolboard-config.cfg] ``` En la siguiente tabla tenéis configuraciones de ejemplo para los toolhead más comunes: | Toolhead | toolboard-config.cfg | | ----------------------------- | ------------------------------------------------------------------------------- | | BigTreeTech EBB36 V1.2 | | | BigTreeTech EBB42 V1.2 | | | BigTreeTech MMB CAN V1.0 | | | BigTreeTech SB2209 (RP2040) | | | BigTreeTech SB2209 and SB2240 | | | Fysetc SB-CAN-TH | | | Mellow Fly ERCF | | | Mellow Fly SB2040 | | | Mellow Fly SHT36 and SHT42 | | | Mellow Fly SHT36v2 | | ## Actualizando firmware en nuestros dispositivos CAN En ocasiones Klipper puede eliminar soporte para versiones antiguas de su firmware, cuando esto sucede veremos que después de actualizar Klipper nos reporta un error que la versión de Klipper en nuestros dispositivos esta desactualizada. Dado que hemos aconsejado el uso de Katapult esto va a facilitar enormemente el proceso de actualización en estos casos ya que no va a ser necesario desmontar parcialmente vuestra máquina, conectar cables USB de nuevo ni nada parecido... vamos a poder actualizar nuestros dispositivos a través del CANbus y gracias a Katapult. El primer paso que haremos en cualquier caso será asegurarnos que tenemos la última revisión de Katapult en nuestro sistema ejecutando el siguiente comando por SSH: ```bash test -e ~/katapult && (cd ~/katapult && git pull) || (cd ~ && git clone https://github.com/Arksine/katapult) ; cd ~ ``` El siguiente paso, y dependiendo de cual sea el dispositivo que se tenga que actualizar, deberemos de seguir los siguientes pasos: {% tabs %} {% tab title="Electrónica CAN" %} En el caso que tengamos que actualizar el firmware Klipper de nuestra electrónica deberemos de realizar los siguientes pasos que a rasgos generales serán los mismos que realizamos durante la [instalación de 0](#instalacion-can-desde-0). **Actualización del firmware/bootloader Katapult** En el caso que hayamos actualizado nuestra versión de Katapult, lo cual aconsejamos en el punto anterior, lo primero a hacer es volver a aplicar la versión actualizada de Katapult en nuestra electrónica. Para ello ejecutaremos los siguientes comandos por SSH: ```bash cd ~/katapult make menuconfig ``` Tal como hicimos en pasos anteriores ajustaremos las opciones para nuestra electrónica y que ya os dimos algunos ejemplos en los pasos anteriores, en nuestro caso os ponemos un ejemplo:
Una vez ajustado salimos (Q) y guardamos los cambios (Y) y lanzaremos un comando `make` a continuación. Una vez finalizada la compilación se nos generará el firmware katapult.bin y un deployer.bin el cual va a contener la actualización de Katapult. Para poder aplicar estos cambios lo primero será poner nuestra electrónica en modo bootloader Katapult con el siguiente comando utilizando nuestro UUID que ya obtuvimos previamente (como parámetro -u, b6d9de35f24f en nuestro ejemplo): ```bash python3 ~/katapult/scripts/flashtool.py -i can0 -u b6d9de35f24f -r ``` Con nuestra electrónica en el modo bootloader Katapult ya podremos lanzar el comando `ls /dev/serial/by-id` para verificar que nuestra electronica tiene el identificador como `usb-katapult-xxx` (usb-katapult\_rp2040\_E66138935F5D7224-if00 en nuestro ejemplo) y nos anotaremos este valor:
Si todo ha ido bien lanzaremos el siguiente comando para actualizar nuestro firmware/bootloader Katapult (deployer.bin) : ```bash python3 ~/katapult/scripts/flashtool.py -f ~/katapult/out/deployer.bin -d /dev/serial/by-id/usb-katapult_rp2040_E66138935F5D7224-if00 ``` **Actualización del firmware Klipper** Ahora nos toca generar el firmware Klipper de nuestra electrónica deberemos de realizar los siguientes pasos que a rasgos generales serán los mismos que realizamos durante la [instalación de 0](#instalacion-can-desde-0). No entraremos en detalles ya que se explicó ya en pasos anteriores, básicamente ejecutaremos `cd ~/klipper` y lanzaremos el configurador de firmware Klipper con `make menuconfig` donde configuraremos los parámetros para nuestra electrónica prestando atanción a `Communication interface` a `USB to CAN bus bridge`, `CAN Bus interface` donde ajustaremos los pines de nuestra electrónica donde esté conectado nuestro CAN y por último `CAN bus speed` que coincida con la configuación de nuestro interfaz CAN (can0). Saldremos (Q) y guardamos (Y), y lanzaremos un `make clean` y seguido un `make`, si todo ha ido bien nos va a generar nuestro firmware Klipper `~/klipper/out/klipper.bin`. Por seguridad pararemos el servicio Klipper con `sudo service klipper stop` y para poder aplicar estos cambios lo primero será poner nuestra electrónica en modo bootloader Katapult con el siguiente comando utilizando nuestro UUID que ya obtuvimos previamente (como parámetro -u, b6d9de35f24f en nuestro ejemplo): ```bash python3 ~/katapult/scripts/flashtool.py -i can0 -u b6d9de35f24f -r ```
Con nuestra electrónica en el modo bootloader Katapult ya podremos lanzar el comando `ls /dev/serial/by-id` para verificar que nuestra electronica tiene el identificador como `usb-katapult-xxx` (usb-katapult\_rp2040\_E66138935F5D7224-if00 en nuestro ejemplo) y nos anotaremos este valor:
Si todo ha ido bien lanzaremos el siguiente comando para actualizar nuestro firmware Klipper (klipper.bin) : ``` python3 ~/katapult/scripts/flashtool.py -f ~/klipper/out/klipper.bin -d /dev/serial/by-id/usb-katapult_rp2040_E66138935F5D7224 ``` {% endtab %} {% tab title="Toolhead CAN" %} {% endtab %} {% endtabs %}
Bibliografia Klipper > Bigtreetech Wiki > Mellow Wiki > Esoterical CANbus guide >
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://klipper.3dwork.io/klipper/mejoras/canbus.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.