ezWS2812.h

Go to the documentation of this file.

/*
 * ezWS2812.h - Simple WS2812 (NeoPixel) driver for Silicon Labs MGM240/MG24
 *
 * Based on Silicon Labs ezWS2812 library by Tamas Jozsi
 * Copyright (c) 2024 Silicon Laboratories Inc.
 *
 * Integrated into FastLED by FastLED Contributors
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
 
#pragma once
 
#ifndef ezWS2812_h
#define ezWS2812_h
 
#include <Arduino.h>  // ok include - SPI driver hardware abstraction
#include <SPI.h>
 
namespace fl {
namespace third_party {

class ezWS2812 {
private:
    uint16_t num_leds_;
    uint8_t brightness_;
    SPIClass* spi_;
    // 8 SPI bits encode 1 WS2812 bit -> 8 * 1.25us = 10us at 0.125us per bit
    // To hit ~1.25us per WS2812 bit, SPI should be ~6.4MHz (1/6.4MHz = 0.15625us)
    static constexpr uint32_t kSpiClockHz = 6400000;
    static constexpr uint16_t kResetTimeUs = 80;
    static constexpr uint8_t kResetByte = 0x00;
    static constexpr uint8_t kResetBytes = 32;

    inline uint8_t one() const {
        return 0xF8; // 11111000 - ~0.78us high at 6.4MHz
    }

    inline uint8_t zero() const {
        return 0xC0; // 11000000 - ~0.31us high at 6.4MHz
    }

    void color_to_spi(uint8_t color, uint8_t* buffer) const {
        for (int i = 7; i >= 0; i--) {
            buffer[7-i] = (color & (1 << i)) ? one() : zero();
        }
    }
 
public:
    ezWS2812(uint16_t num_leds, SPIClass& spi = SPI)
        : num_leds_(num_leds), brightness_(100), spi_(&spi) {}

    void begin() {
        spi_->begin();
        spi_->beginTransaction(SPISettings(kSpiClockHz, MSBFIRST, SPI_MODE0));
    }

    void end() {
        spi_->endTransaction();
    }

    void set_brightness(uint8_t brightness) {
        brightness_ = (brightness > 100) ? 100 : brightness;
    }

    void set_pixel(uint8_t red, uint8_t green, uint8_t blue, uint16_t count = 1) {
        uint8_t spi_buffer[24]; // 3 colors × 8 bits = 24 SPI bytes per pixel
 
        // Apply brightness
        red = (red * brightness_) / 100;
        green = (green * brightness_) / 100;
        blue = (blue * brightness_) / 100;
 
        // Convert to SPI bit patterns (GRB order for WS2812)
        color_to_spi(green, &spi_buffer[0]);  // Green first
        color_to_spi(red, &spi_buffer[8]);    // Red second
        color_to_spi(blue, &spi_buffer[16]);  // Blue third
 
        // Send pixel data
        for (uint16_t i = 0; i < count && i < num_leds_; i++) {
            for (int j = 0; j < 24; j++) {
                spi_->transfer(spi_buffer[j]);
            }
        }
    }

    void set_all(uint8_t red, uint8_t green, uint8_t blue) {
        set_pixel(red, green, blue, num_leds_);
    }

    void end_transfer() {
        // Force MOSI low long enough to guarantee WS2812 reset/latch.
        // Sending zero bytes ensures low even if the last data bit was high.
        for (uint8_t i = 0; i < kResetBytes; i++) {
            spi_->transfer(kResetByte);
        }
        delayMicroseconds(kResetTimeUs);
    }
};

class ezWS2812gpio {
private:
    uint16_t num_leds_;
    uint8_t pin_;
    uint8_t brightness_;
    uint32_t pin_mask_;
    volatile uint32_t* port_set_;
    volatile uint32_t* port_clear_;

    void send_bit(bool bit_value) const {
        if (F_CPU >= 78000000) {
            // Timing for 78MHz CPU
            if (bit_value) {
                // Send '1' bit: ~0.8µs high, ~0.45µs low
                *port_set_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                );
                *port_clear_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop;"
                );
            } else {
                // Send '0' bit: ~0.4µs high, ~0.85µs low
                *port_set_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop;"
                );
                *port_clear_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                );
            }
        } else {
            // Timing for 39MHz CPU (default)
            if (bit_value) {
                // Send '1' bit: ~0.8µs high, ~0.45µs low
                *port_set_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                );
                *port_clear_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop;"
                );
            } else {
                // Send '0' bit: ~0.4µs high, ~0.85µs low
                *port_set_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop;"
                );
                *port_clear_ = pin_mask_;
                __asm__ volatile(
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                    "nop; nop; nop; nop; nop; nop; nop; nop;"
                );
            }
        }
    }

    void send_byte(uint8_t byte_value) const {
        for (int i = 7; i >= 0; i--) {
            send_bit((byte_value >> i) & 0x01);
        }
    }
 
public:
    ezWS2812gpio(uint16_t num_leds, uint8_t pin)
        : num_leds_(num_leds), pin_(pin), brightness_(100) {}

    void begin() {
        pinMode(pin_, OUTPUT);
        digitalWrite(pin_, LOW);
 
        // Cache port addresses for faster access
        // Note: This is platform-specific and needs proper implementation
        // for Silicon Labs MGM240/MG24
        pin_mask_ = digitalPinToBitMask(pin_);
        uint8_t port = digitalPinToPort(pin_);
        port_set_ = portOutputRegister(port);
        port_clear_ = port_set_ + 1; // Typically clear register is next
    }

    void end() {
        digitalWrite(pin_, LOW);
    }

    void set_brightness(uint8_t brightness) {
        brightness_ = (brightness > 100) ? 100 : brightness;
    }

    void set_pixel(uint8_t red, uint8_t green, uint8_t blue, uint16_t count = 1) {
        // Apply brightness
        red = (red * brightness_) / 100;
        green = (green * brightness_) / 100;
        blue = (blue * brightness_) / 100;
 
        noInterrupts();
        for (uint16_t i = 0; i < count && i < num_leds_; i++) {
            // Send in GRB order for WS2812
            send_byte(green);
            send_byte(red);
            send_byte(blue);
        }
        interrupts();
    }

    void set_all(uint8_t red, uint8_t green, uint8_t blue) {
        set_pixel(red, green, blue, num_leds_);
    }

    void end_transfer() {
        // WS2812 reset time (>50µs low)
        delayMicroseconds(300);
    }
};
 
}  // namespace third_party
}  // namespace fl
 
#endif // ezWS2812_h