Optimized for Arduino Library

Author: Tuet

README.md

@@ -5,9 +5,14 @@ Library that provides the simple function ws2812Write(pin, color) to set the col
 ## Features
 - No initalization of library or ws2812 LED required
 - Simple api: `ws2812Write(uint8_t pin, uint32_t color_rgb)` Color 0xRRGGBB
-- Extended api: `ws2812Write(uint8_t pin, uint32_t color, ws2812_write_led_type_t led_type)` if you need other color orders
-- Minimal Footprint but time sensitive, works only for certain MCUs and clock frequencies
+- Extended api: `ws2812Write(uint8_t pin, uint32_t color, uint8_t led_count, ws2812_write_led_type_t led_type)` if you want to set color of more than one LED or need other color orders
+- Minimal Footprint but time sensitive, works only for certain MCUs (tested on ESP8266, ESP32 and ESP32S3) and clock frequencies
+
+## Info
+- Blocks interrupts while pushing out data to LED (around 30us per LED)
+- Data latching pause is not generated by this library, so wait at least 50us between ws2812Write calls to same port (usually no need to do something here as you don't update the LED that often and the start of the function takes quite some time to calculate timing and resort color values). In extreme case add `delayMicroseconds(50);` manually to allow latching of data into LEDs.
+- With the third argument more than one LED can be set if you are using LED stripes, but all will be set to the same color.
 
 ## API
 ```c
-void ws2812Write(uint8_t pin, uint32_t color_rgb, ws2812_write_led_type_t led_type = WS2812WRITE_GRB);
+void ws2812Write(uint8_t pin, uint32_t color_rgb, uint8_t led_count = 1, ws2812_write_led_type_t led_type = WS2812WRITE_GRB);

examples/BlockWS2812Blink/.gitignore

@@ -0,0 +1,5 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch

examples/BlockWS2812Blink/BlockWS2812Blink.ino

@@ -0,0 +1,37 @@
+/*
+  BlockWS2812Blink.ino - Example sketch to blink a line of 8 WS2812 LEDs
+  Created by Lutz Lisseck, December 2025.
+
+  Colors the WS2812 LEDs in pink for one second,
+  then turns it green for one second in an endless loop. 
+
+  LEDs should be a WS2812 or WS2812B type.
+  
+  Add a fourth argument to ws2812Write() if your LED uses a 
+  different color order then GRB (as most WS2812 types do).
+
+  This example code is in the public domain.
+*/
+
+#include <WS2812Write.h>
+#ifndef WS2812_LED_PIN    // can be defined in platformio.ini
+#define WS2812_LED_PIN 6  // Pin where the WS2812 LED is connected
+#endif
+
+#define LED_BLOCK_COUNT 8  // Number of WS2812 LEDs in the block
+
+
+// the setup function runs once when you press reset or power the board
+void setup() {
+  // no need to initialize the ws2812 library or pin before :-)
+  //Serial.begin(74880); // Start serial for debugging (optional)
+  //Serial.println("Single WS2812 Blink Example");
+}
+
+// the loop function runs over and over again forever
+void loop() {
+  ws2812Write(WS2812_LED_PIN, 0xFF00FF, LED_BLOCK_COUNT);  // turn the LEDs pink (RGB: 255, 0, 255)
+  delay(1000);                            // wait for a second
+  ws2812Write(WS2812_LED_PIN, 0x00FF00, LED_BLOCK_COUNT);  // turn the LEDs green (RGB: 0, 255, 0)
+  delay(1000);                            // wait for a second
+}

examples/BlockWS2812Blink/idf_component.yml

@@ -0,0 +1,2 @@
+dependencies:
+  idf: '>=5.1'

examples/SingleWS2812Blink/SingleWS2812Blink.ino

@@ -7,14 +7,15 @@
 
   LED should be a WS2812 or WS2812B type.
   
-  Add a third argument to ws2812Write() if your LED uses a 
+  Add a third argument if you want to set more than one LED - all will get the same color.
+  Add a fourth argument to ws2812Write() if your LED uses a 
   different color order then GRB (as most WS2812 types do).
 
   This example code is in the public domain.
 */
 
 #include "WS2812Write.h"
-#ifndef WS2812_LED_PIN
+#ifndef WS2812_LED_PIN    // can be defined in platformio.ini
 #define WS2812_LED_PIN 6  // Pin where the WS2812 LED is connected
 #endif
 

keywords.txt

@@ -0,0 +1,9 @@
+# Syntax Coloring Map
+# Datatypes (KEYWORD1)
+
+# Methods and Functions (KEYWORD2)
+ws2812Write KEYWORD2
+
+# Instances (KEYWORD2)
+
+# Constants (LITERAL1)

library.properties

@@ -1,9 +1,10 @@
 name=Single_WS2812_Bitbang_Write
 version=0.1.0
 author=Lutz Lisseck (Hackerspace FFM e.V.)
-maintainer=Lutz Lisseck (Hackerspace FFM e.V.)
-sentence=Single WS2812 LED driver using bitbang (no MCU peripheral).
-paragraph=Minimal library to control a single WS2812 LED using bitbanged GPIO.
+maintainer=Lutz Lisseck <tutgit@ikmail.com>
+sentence=Single WS2812 LED driver using bitbang (no MCU peripheral) for ESP MCUs.
+paragraph=Minimal library that provides a ws2812Write(pin, color) to control single WS2812 LEDs using bitbanged GPIO without using any MCU peripheral like RMT, SPI, etc. Works on ESP8266 and ESP32.
+license=MIT
 category=Display
 url=https://github.com/hackffm/Single_WS2812_Bitbang_Write
-architectures=*
+architectures=espressif8266, espressif32

platformio.ini

@@ -1,16 +1,17 @@
-; PlatformIO Project Configuration File
+; PlatformIO Project Configuration File, open in PlatformIO and select src_dir to run different examples
 [platformio]
+lib_dir = .
 src_dir = examples/SingleWS2812Blink
-;src_dir = examples/MultiWS2812Blink
+;src_dir = examples/BlockWS2812Blink
 
 [env]
 ; Special pioarduino cores
 ;platform = https://github.com/pioarduino/platform-espressif32.git#develop
 ;platform = https://github.com/pioarduino/platform-espressif32/releases/download/stable/platform-espressif32.zip
 platform = espressif32
 framework = arduino
-;board = esp32dev
-board = esp32-s3-devkitc-1
+board = esp32dev
+;board = esp32-s3-devkitc-1
 monitor_speed = 115200
 
 build_flags = 
@@ -28,6 +29,7 @@ upload_speed = 230400
 ;upload_speed = 57600
 board_build.flash_mode = dout
 upload_resetmethod = nodemcu
+; F_CPU is 80 MHz by default, enable line below to set to 160 MHz
 ;board_build.f_cpu = 160000000L
 build_flags = ${env.build_flags}
               -DWS2812_LED_PIN=13
@@ -36,7 +38,8 @@ build_flags = ${env.build_flags}
 platform = espressif32
 board = esp32dev
 monitor_filters = esp32_exception_decoder
-board_build.f_cpu = 80000000L
+; 80 / 160 / 240 MHz supported, default is 240 MHz
+;board_build.f_cpu = 16000000L
 build_flags = ${env.build_flags}
               -DWS2812_LED_PIN=33
 
@@ -45,7 +48,7 @@ build_flags = ${env.build_flags}
 platform = espressif32
 board = esp32-s3-devkitc-1
 build_type = debug
-board_build.f_cpu = 80000000L
+board_build.f_cpu = 240000000L
 board_build.arduino.memory_type = qio_qspi
 board_build.flash_mode = qio
 board_build.psram_type = qio

…gle_WS2812_Bitbang_Write/WS2812Write.cpp src/WS2812Write.cpplib/Single_WS2812_Bitbang_Write/WS2812Write.cpp renamed to src/WS2812Write.cpp lib/Single_WS2812_Bitbang_Write/WS2812Write.cpp renamed to src/WS2812Write.cpp

@@ -21,13 +21,9 @@
 
   portMUX_TYPE mySpinlock = portMUX_INITIALIZER_UNLOCKED;
 
-  void IRAM_ATTR setColor(uint32_t color, uint8_t pin, uint8_t time1H, uint8_t time1L, uint8_t time0H, uint8_t time0L) {
-    uint32_t bitmask = 0x800000;
-    volatile uint8_t count = 24;
-    uint32_t start;
+  void IRAM_ATTR setColor(uint32_t color, uint8_t pin, uint8_t time1H, uint8_t time1L, uint8_t time0H, uint8_t time0L, uint8_t count) {
     uint32_t tc_reg = GPIO_OUT_W1TC_REG;
     uint32_t ts_reg = GPIO_OUT_W1TS_REG;
-    uint32_t cycles;
 
     if(pin > 32) {
       tc_reg = GPIO_OUT1_W1TC_REG;
@@ -37,20 +33,23 @@
     uint32_t reg_val = (1UL << (pin));
 
     vPortEnterCritical(&mySpinlock);  // Interrupts off on current core
-
     while(count--) {
-      cycles = (color & bitmask) ? time1H : time0H;
-      WRITE_PERI_REG(ts_reg, reg_val);
-      start = GET_CPU_CYCLES();
-      while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
-
-      cycles = (color & bitmask) ? time1L : time0L;
-      bitmask = bitmask >> 1;
-      WRITE_PERI_REG(tc_reg, reg_val); 
-      start = GET_CPU_CYCLES();
-      while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+      uint32_t bitmask = 0x800000;
+      uint32_t start;
+      uint32_t cycles;
+      while(bitmask) {
+        cycles = (color & bitmask) ? time1H : time0H;
+        WRITE_PERI_REG(ts_reg, reg_val);
+        start = GET_CPU_CYCLES();
+        while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+
+        cycles = (color & bitmask) ? time1L : time0L;
+        bitmask = bitmask >> 1;
+        WRITE_PERI_REG(tc_reg, reg_val); 
+        start = GET_CPU_CYCLES();
+        while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+      }
     }
-
     vPortExitCritical(&mySpinlock);   // Interrupts on
 
   }
@@ -63,41 +62,39 @@
 
   #define GET_CPU_CYCLES() esp_get_cycle_count()
 
-  void IRAM_ATTR setColor(uint32_t color, uint8_t pin, uint8_t time1H, uint8_t time1L, uint8_t time0H, uint8_t time0L) {
-    uint32_t bitmask = 0x800000;
-    volatile uint8_t count = 24;
-    uint32_t start;
-    uint32_t cycles;
-
+  void IRAM_ATTR setColor(uint32_t color, uint8_t pin, uint8_t time1H, uint8_t time1L, uint8_t time0H, uint8_t time0L, uint8_t count) {
     if(pin > 32) return;
     uint32_t reg_val = (1UL << (pin));
 
     ETS_INTR_LOCK();  // Interrupts off
-
     while(count--) {
-      cycles = (color & bitmask) ? time1H : time0H;
-      GPIO_REG_WRITE(GPIO_OUT_W1TS_ADDRESS, reg_val);
-      start = GET_CPU_CYCLES();
-      while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
-
-      cycles = (color & bitmask) ? time1L : time0L;
-      bitmask = bitmask >> 1;
-      GPIO_REG_WRITE(GPIO_OUT_W1TC_ADDRESS, reg_val); 
-      start = GET_CPU_CYCLES();
-      while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+      uint32_t bitmask = 0x800000;
+      uint32_t start;
+      uint32_t cycles;
+      while(bitmask) {
+        cycles = (color & bitmask) ? time1H : time0H;
+        GPIO_REG_WRITE(GPIO_OUT_W1TS_ADDRESS, reg_val);
+        start = GET_CPU_CYCLES();
+        while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+
+        cycles = (color & bitmask) ? time1L : time0L;
+        bitmask = bitmask >> 1;
+        GPIO_REG_WRITE(GPIO_OUT_W1TC_ADDRESS, reg_val); 
+        start = GET_CPU_CYCLES();
+        while (GET_CPU_CYCLES() - start < cycles) { __asm__ __volatile__("nop");  } 
+      }
     }
-
     ETS_INTR_UNLOCK();   // Interrupts on
   }
 
 #else
-  #error Target CONFIG_IDF_TARGET is not supported
+  #error Target is not yet supported
 #endif
 
 
 
 
-void ws2812Write(uint8_t pin, uint32_t color_rgb, ws2812_write_led_type_t led_type)
+void ws2812Write(uint8_t pin, uint32_t color_rgb, uint8_t led_count, ws2812_write_led_type_t led_type)
 {
   pinMode(pin, OUTPUT);
 
@@ -129,44 +126,44 @@ void ws2812Write(uint8_t pin, uint32_t color_rgb, ws2812_write_led_type_t led_ty
   uint32_t Freq;
   uint8_t time1H, time1L, time0H, time0L;
 
-  // WS2812B: 1: H_800ns L_450ns (Send a '1' bit)
-  //          0: H_400ns L_850ns (Send a '0' bit)
+  // WS2812B: 1: H_800ns L_450ns (Send a '1' bit) +/-150ns
+  //          0: H_400ns L_850ns (Send a '0' bit) +/-150ns
 
   #ifdef ARDUINO_ARCH_ESP32
   Freq = getCpuFrequencyMhz();  
     #if defined(CONFIG_IDF_TARGET_ESP32) 
-    // Tested for ESP32
-    time1H = (800 * Freq) / 1000 - 11; 
-    time0H = (400 * Freq) / 1000 - 15; 
-    time1L = (450 * Freq) / 1000 - 25; 
-    time0L = (850 * Freq) / 1000 - 28; 
+    // Tested for ESP32         ns @ MHz  240 160 80
+    time1H = (800 * Freq) / 1000 - 15; // 800 774 836
+    time0H = (400 * Freq) / 1000 - 15; // 400 424 312
+    time1L = (450 * Freq) / 1000 - 25; // 426 464 402
+    time0L = (850 * Freq) / 1000 - 28; // 838 812 920
     if(Freq <= 80) {
       // Adjust timing for 80 MHz
-      time1L -= 4;
-      time0L -= 4;
+      time0H -= 2;
+      time0L += 4;
     } 
     #else
-    // Tested for ESP32-S3 80/160/240 MHz
-    time1H = (800 * Freq) / 1000 - 11; 
-    time0H = (400 * Freq) / 1000 - 15; 
-    time1L = (450 * Freq) / 1000 - 18; 
-    time0L = (850 * Freq) / 1000 - 26; 
+    // Tested for ESP32-S3      ns @ MHz  240 160 80
+    time1H = (800 * Freq) / 1000 - 11; // 812 824 774
+    time0H = (400 * Freq) / 1000 - 15; // 400 412 400
+    time1L = (450 * Freq) / 1000 - 15; // 450 438 450
+    time0L = (850 * Freq) / 1000 - 24; // 814 838 788
     #endif
   #elif defined(ARDUINO_ARCH_ESP8266)
     Freq = (uint32_t)system_get_cpu_freq();  
     // Tested ESP8266 at 80 and 160 MHz
-    time1H = (800 * Freq) / 1000 - 11; 
-    time0H = (400 * Freq) / 1000 - 15; 
-    time1L = (450 * Freq) / 1000 - 21; 
-    time0L = (850 * Freq) / 1000 - 24; 
+    time1H = (800 * Freq) / 1000 - 13; // 850 824
+    time0H = (400 * Freq) / 1000 - 15; // 350 374
+    time1L = (450 * Freq) / 1000 - 21; // 424 438
+    time0L = (850 * Freq) / 1000 - 21; // 876 830
   #else
     return; // Unsupported architecture
   #endif
 
  //Serial.printf("ws2812Write: %u MHz, time1H=%u, time1L=%u, time0H=%u, time0L=%u\r\n", 
  //   (unsigned int)Freq, (unsigned int)time1H, (unsigned int)time1L, 
  //   (unsigned int)time0H, (unsigned int)time0L);
- setColor(tx_color, pin, time1H, time1L, time0H, time0L);
+ setColor(tx_color, pin, time1H, time1L, time0H, time0L, led_count);
 
 
 

…ingle_WS2812_Bitbang_Write/WS2812Write.h src/WS2812Write.hlib/Single_WS2812_Bitbang_Write/WS2812Write.h renamed to src/WS2812Write.h lib/Single_WS2812_Bitbang_Write/WS2812Write.h renamed to src/WS2812Write.h

@@ -11,6 +11,8 @@
  *
  * @param pin GPIO number 
  * @param color_rgb 24-bit color format 0xRRGGBB
+ * @param led_count Number of LEDs to write the same color to (default: 1)
+ * @param led_type Color order type (default: WS2812WRITE_GRB)
  */
 
 
@@ -24,5 +26,4 @@ typedef enum {
   WS2812WRITE_GRB   /* Most WS2812 types */
 } ws2812_write_led_type_t;
 
-void ws2812Write(uint8_t pin, uint32_t color_rgb, ws2812_write_led_type_t led_type = WS2812WRITE_GRB);
-
+void ws2812Write(uint8_t pin, uint32_t color_rgb, uint8_t led_count = 1, ws2812_write_led_type_t led_type = WS2812WRITE_GRB);