neopixel: Support using SPI to send data

This change allows the use of a SPI bus to send correctly timed data to
a string of neopixels.

The current bitbang approach cannot be used directly from a Raspberry Pi
secondary MCU as the bitbang timing is not precise enough. Using the SPI
bus to send data to neopixels is a commonly used technique among other
open source projects, and seems to work well in Kalico, too.

On the devices I have tested (Raspberry Pi 5 and STM32F427) the
available SPI speeds work with the data patterns that I have hardcoded,
but it is conceivable that it may be necessary to make the data
configurable or automatically generated based on requested bus speed in
order to support some devices.

Signed-off-by: Russell Cloran <rcloran@gmail.com>

Author: rcloran

docs/Config_Reference.md

@@ -3886,17 +3886,41 @@ Neopixel (aka WS2812) LED support (one may define any number of
 sections with a "neopixel" prefix). See the
 [command reference](G-Codes.md#led) for more information.
 
-Note that the [linux mcu](RPi_microcontroller.md) implementation does
-not currently support directly connected neopixels. The current design
-using the Linux kernel interface does not allow this scenario because
-the kernel GPIO interface is not fast enough to provide the required
-pulse rates.
+A SPI bus may optionally be used to generate the data to send to the
+neopixels. They aren't really SPI devices, but this allows offloading
+the timing required to hardware. By default a SPI speed of 6MHz (6000000)
+is requested -- not all hardware supports arbitrary speeds, and you may
+need to specify an exact speed that is supported by your hardware. Speeds
+between about 4Mhz and about 8MHz should be tolerated by most neopixels.
+
+Note that the [linux mcu](RPi_microcontroller.md) implementation only
+supports directly connected neopixels using SPI, as the GPIO interface
+is not fast enough to provide the required pulse rates.
 
 ```
 [neopixel my_neopixel]
 pin:
 #   The pin connected to the neopixel. This parameter must be
-#   provided.
+#   provided if not using SPI bus.
+spi_bus:
+spi_speed:
+#   See the "common SPI settings" section for a description of the
+#   above parameters. Changing `spi_speed` will change the timing of
+#   pulses sent to the neopixel chain; the voltage high time for a 0 is
+#   represented by 2 SPI bits, and a 1 by 5 SPI bits, with the remaining
+#   bits in each SPI byte being low. At the default `spi_speed` of 6MHz
+#   this results in 2/6e6 = 333ns high time and 1000ns low time for a 0,
+#   and 6/6e6 = 833ns high time and 500ns low time for a 1. Experimenting
+#   with slightly different `spi_speed` (usually between 4MHz and 8MHz)
+#   may resolve compatibility problems with different neopixel chips.
+#   On Raspberry Pi 4 and older the actual SPI bus speed is a fraction
+#   of the current core clock speed, which can vary, so you may need to
+#   set the core clock to a fixed speed. See
+#   https://github.com/raspberrypi/linux/issues/3381 for more.
+cs_pin:
+#   If using a SPI bus this is required in order to determine which
+#   MCU the SPI bus is on, but may be specified as "mcu:None" if no
+#   actual CS pin needs to be set.
 #chain_count:
 #   The number of Neopixel chips that are "daisy chained" to the
 #   provided pin. The default is 1 (which indicates only a single

klippy/extras/neopixel.py

@@ -4,6 +4,7 @@
 #
 # This file may be distributed under the terms of the GNU GPLv3 license.
 import logging
+from . import bus
 
 BACKGROUND_PRIORITY_CLOCK = 0x7FFFFFFF00000000
 
@@ -18,12 +19,20 @@ def __init__(self, config):
         self.printer = printer = config.get_printer()
         self.mutex = printer.get_reactor().mutex()
         # Configure neopixel
-        ppins = printer.lookup_object("pins")
-        pin_params = ppins.lookup_pin(config.get("pin"))
-        self.mcu = pin_params["chip"]
+        if config.get("pin", None) is not None:
+            ppins = printer.lookup_object("pins")
+            pin_params = ppins.lookup_pin(config.get("pin"))
+            self.mcu = pin_params["chip"]
+            self.pin = pin_params["pin"]
+            self.mcu.register_config_callback(self.build_config_bitbang)
+        else:
+            self.spi = bus.MCU_SPI_from_config(
+                config, 0, default_speed=6_000_000
+            )
+            self.mcu = self.spi.mcu
+            self.mcu.register_config_callback(self.build_config_spi)
+
         self.oid = self.mcu.create_oid()
-        self.pin = pin_params["pin"]
-        self.mcu.register_config_callback(self.build_config)
         self.neopixel_update_cmd = self.neopixel_send_cmd = None
         # Build color map
         chain_count = config.getint("chain_count", 1, minval=1)
@@ -54,7 +63,7 @@ def __init__(self, config):
             self.mcu.get_non_critical_reconnect_event_name(), self.send_data
         )
 
-    def build_config(self):
+    def build_config_bitbang(self):
         bmt = self.mcu.seconds_to_clock(BIT_MAX_TIME)
         rmt = self.mcu.seconds_to_clock(RESET_MIN_TIME)
         self.mcu.add_config_cmd(
@@ -73,6 +82,24 @@ def build_config(self):
             cq=cmd_queue,
         )
 
+    def build_config_spi(self):
+        rmt = self.mcu.seconds_to_clock(RESET_MIN_TIME)
+        self.mcu.add_config_cmd(
+            "config_neopixel_spi oid=%d bus_oid=%s data_size=%d"
+            " reset_min_ticks=%d"
+            % (self.oid, self.spi.oid, len(self.color_data), rmt)
+        )
+        cmd_queue = self.mcu.alloc_command_queue()
+        self.neopixel_update_cmd = self.mcu.lookup_command(
+            "neopixel_update_spi oid=%c pos=%hu data=%*s", cq=cmd_queue
+        )
+        self.neopixel_send_cmd = self.mcu.lookup_query_command(
+            "neopixel_send_spi oid=%c",
+            "neopixel_result oid=%c success=%c",
+            oid=self.oid,
+            cq=cmd_queue,
+        )
+
     def update_color_data(self, led_state):
         color_data = self.color_data
         for cdidx, (lidx, cidx) in self.color_map:

src/Kconfig

@@ -138,6 +138,10 @@ config WANT_NEOPIXEL
     bool
     depends on HAVE_GPIO
     default y
+config WANT_NEOPIXEL_SPI
+    bool
+    depends on WANT_SPI
+    default y
 config WANT_PULSE_COUNTER
     bool
     depends on HAVE_GPIO
@@ -236,8 +240,11 @@ config WANT_TMCUART
     bool "Support Trinamic stepper motor driver UART communication"
     depends on HAVE_GPIO
 config WANT_NEOPIXEL
-    bool "Support 'neopixel' type LED control"
+    bool "Support 'neopixel' type LED control using bitbang"
     depends on HAVE_GPIO
+config WANT_NEOPIXEL_SPI
+    bool "Support 'neopixel' type LED control using SPI"
+    depends on WANT_SPI
 config WANT_PULSE_COUNTER
     bool "Support measuring fan tachometer GPIO pins"
     depends on HAVE_GPIO

src/Makefile

@@ -12,6 +12,7 @@ src-$(CONFIG_HAVE_GPIO_SDIO) += sdiocmds.c
 src-$(CONFIG_WANT_BUTTONS) += buttons.c
 src-$(CONFIG_WANT_TMCUART) += tmcuart.c
 src-$(CONFIG_WANT_NEOPIXEL) += neopixel.c
+src-$(CONFIG_WANT_NEOPIXEL_SPI) += neopixel_spi.c
 src-$(CONFIG_WANT_PULSE_COUNTER) += pulse_counter.c
 src-$(CONFIG_WANT_ST7920) += lcd_st7920.c
 src-$(CONFIG_WANT_HD44780) += lcd_hd44780.c

src/neopixel_spi.c

@@ -0,0 +1,129 @@
+// Support for WS2812 type "neopixel" LEDs using SPI hardware for timing
+//
+// Copyright (C) 2025  Russell Cloran <rcloran@gmail.com>
+//
+// This file may be distributed under the terms of the GNU GPLv3 license.
+
+#include "basecmd.h" // oid_alloc
+#include "board/irq.h" // irq_poll
+#include "board/misc.h" // timer_read_time
+#include "command.h" // DECL_COMMAND
+#include "sched.h" // shutdown
+#include <string.h> // memcpy
+#include "spicmds.h" // spidev_transfer
+
+// This code uses a SPI bus to generate neopixel-compatible data by sending
+// different bytes on the SPI bus, each of which represents a bit in the 
+// neopixel data.
+//
+// According to one source, a neopixel 0 can be represented by holding the line
+// high for anywhere between 200 and 500 ns, and a 1 for at least 550ns. The
+// amount of time the line must then be held low is actually fairly tolerant:
+// https://wp.josh.com/2014/05/13/ws2812-neopixels-are-not-so-finicky-once-you-get-to-know-them/
+//
+// Another source shows that high times as short as 62.5ns are valid 0s:
+// https://cpldcpu.com/2014/01/14/light_ws2812-library-v2-0-part-i-understanding-the-ws2812/
+//
+// Some LEDs may require as much as 800ns high time for a 1:
+// https://github.com/Klipper3d/klipper/pull/7113
+//
+// 2 bits of SPI data take 200ns at 10MHz and 500ns at 4MHz
+// 5 bits of SPI data take 550ns at 9.09MHz, or longer at slower rates
+// 5 bits of SPI data take 800ns at 6.25MHz
+
+#define ONE_BIT 0b01111100
+#define ZERO_BIT 0b01100000
+
+#define NP_BYTES_PER_TRANSFER 3
+
+/****************************************************************
+ * Neopixel interface
+ ****************************************************************/
+
+struct neopixel_spi_s {
+    struct spidev_s *spi;
+    uint32_t last_req_time, reset_min_ticks;
+    uint16_t data_size;
+    uint8_t data[0];
+};
+
+void
+command_config_neopixel_spi(uint32_t *args)
+{
+    uint16_t data_size = args[2];
+    if (data_size & 0x8000)
+        shutdown("Invalid neopixel data_size");
+    struct neopixel_spi_s *n = oid_alloc(args[0], command_config_neopixel_spi
+                                     , sizeof(*n) + data_size);
+
+    n->spi = spidev_oid_lookup(args[1]);
+
+    n->data_size = data_size;
+    n->reset_min_ticks = args[3];
+}
+DECL_COMMAND(command_config_neopixel_spi, "config_neopixel_spi oid=%c"
+             " bus_oid=%u data_size=%hu reset_min_ticks=%u");
+
+static int
+send_data_spi(struct neopixel_spi_s *n)
+{
+    // Make sure the reset time has elapsed since last request
+    uint32_t last_req_time = n->last_req_time, rmt = n->reset_min_ticks;
+    uint32_t cur = timer_read_time();
+    while (cur - last_req_time < rmt) {
+        irq_poll();
+        cur = timer_read_time();
+    }
+
+    // Transmit data
+    uint8_t *data = n->data;
+    uint_fast16_t data_len = n->data_size;
+    uint8_t msg[NP_BYTES_PER_TRANSFER * 8] = {0};
+
+    while (data_len) {
+        uint_fast8_t i;
+        for (i = 0; i < NP_BYTES_PER_TRANSFER && data_len; i++) {
+            uint_fast8_t byte = *data++;
+            data_len--;
+            for (uint_fast8_t bit = 0; bit < 8; bit++) {
+                if (byte & 0x80) {
+                    msg[i * 8 + bit] = ONE_BIT;
+                } else {
+                    msg[i * 8 + bit] = ZERO_BIT;
+                }
+                byte <<= 1;
+            }
+        }
+        uint_fast8_t msg_len = i * 8;
+        spidev_transfer(n->spi, 0, msg_len, msg);
+    }
+
+    n->last_req_time = timer_read_time();  // + transfer time?
+    return 0;
+}
+
+void
+command_neopixel_update_spi(uint32_t *args)
+{
+    uint8_t oid = args[0];
+    struct neopixel_spi_s *n = oid_lookup(oid, command_config_neopixel_spi);
+    uint_fast16_t pos = args[1];
+    uint_fast8_t data_len = args[2];
+    uint8_t *data = command_decode_ptr(args[3]);
+    if (pos & 0x8000 || pos + data_len > n->data_size)
+        shutdown("Invalid neopixel update command");
+    memcpy(&n->data[pos], data, data_len);
+}
+DECL_COMMAND(command_neopixel_update_spi,
+             "neopixel_update_spi oid=%c pos=%hu data=%*s");
+
+void
+command_neopixel_send_spi(uint32_t *args)
+{
+    uint8_t oid = args[0];
+    struct neopixel_spi_s *n = oid_lookup(oid, command_config_neopixel_spi);
+    int ret = 1;
+    ret = send_data_spi(n);
+    sendf("neopixel_result oid=%c success=%c", oid, ret ? 0 : 1);
+}
+DECL_COMMAND(command_neopixel_send_spi, "neopixel_send_spi oid=%c");