apa102.h File Reference

APA102 control interface for AVR microcontrollers using SPI. More...

#include "../../../core_types/gfx/color.h"
#include "../../../utils/macros/stringify.h"
#include "../../../hal/avr0/spi/spi.h"

Include dependency graph for apa102.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	APA102_HAL_PLATFORM   avr0
	Sets the target platform for the APA102 hardware abstraction layer (HAL), e.g., avr or avr0.
#define	APA102_NUMBER_OF_LEDS   1
	Defines the total number of LEDs controlled by the driver.
#define	APA102_FRAME_SIZE   4
	Defines the size of the LED start/stop and data frame in bytes.
#define	APA102_START_FLAG   0xE0
	Defines the start-of-frame flag value for LED data transmission.
#define	APA102_SOF_VALUE   0x00
	Defines the start-of-frame marker value for LED data transmission.
#define	APA102_EOF_VALUE   0xFF
	Defines the end-of-frame marker value for LED data transmission.
#define	APA102_MIN_INTENSITY   0x01
	The minimum intensity value for LED brightness.
#define	APA102_MAX_INTENSITY   0x1F
	The maximum intensity value for LED brightness.
#define	APA102_POWER_SAVING_AVAILABLE
	Flag indicating whether power-saving mode is supported by the LED hardware.
#define	APA102_ENABLE_FLAG   0xE0
	Flag used to enable LED operation.
#define	APA102_SLEEP_FLAG   0xA0
	Flag used to set the LED device into sleep mode.
#define	APA102_SOF()
	Sends the Start-of-Frame (SOF) signal to the LED strip.
#define	APA102_EOF()
	Sends the End-of-Frame (EOF) signal to the LED strip.

Typedefs
typedef enum APA102_Transmission_t	APA102_Transmission
	Alias for enum APA102_Transmission_t representing possible APA102 transmission types.

Enumerations
enum	APA102_Transmission_t { APA102_Transmission_SOF = 0x00 , APA102_Transmission_EOF = 0xFF }
	Enumerates possible LED frame types for APA102 LED strips. More...

Functions
void	apa102_init (void)
	Initialize the LED control interface and hardware.
void	apa102_xof (APA102_Transmission type)
	Transmit a specified value repeatedly over SPI to form a data frame.
void	apa102_led (const GFX_RGBA_Color *color)
	Send an LED data frame with specified color and intensity.
void	apa102_leds (const GFX_RGBA_Color *color)
	Send an LED data frame to all LEDs with specified color and intensity.
void	apa102_led_off (void)
	Send an LED data frame to a single LED to turn it off.
void	apa102_leds_off (void)
	Disable all LEDs by sending sleep commands (if supported) and turning off the SPI peripheral.

Detailed Description

APA102 control interface for AVR microcontrollers using SPI.

This header file defines the interface for controlling LEDs, including configuration macros and data structures for LED color and intensity. Functions are provided to initialize LED hardware, send data frames via SPI and control LED colors. The LED driver supports multiple LEDs with configurable frame sizes and intensity limits.

Author

g.raf

Date

2026-02-20

Version

1.0 Release

Copyright

Copyright (c) 2026 g.raf Released under the GPLv3 License. (see LICENSE in repository)

Note

This file is part of a larger embedded systems project and subject to the license specified in the repository. For updates and the complete revision history, see the GitHub repository.

See also

https://github.com/0x007e/drivers-led-apa102 "APA102 LED Driver GitHub Repository"

Macro Definition Documentation

APA102_ENABLE_FLAG

#define APA102_ENABLE_FLAG   0xE0

Flag used to enable LED operation.

This flag value, default 0xE0, is used in communication settings to signal enabling the LED device or functionality.

APA102_EOF

#define APA102_EOF

(

)

Value:

{ apa102_xof(APA102_Transmission_EOF); }

Sends the End-of-Frame (EOF) signal to the LED strip.

This macro transmits the predefined APA102_STOP_VALUE as an end frame delimiter using the function apa102_xof(). It inserts a short delay of 10 microseconds to ensure proper timing after LED data transmission ends. The EOF indicates the completion of the current LED data sequence.

APA102_EOF_VALUE

#define APA102_EOF_VALUE   0xFF

Defines the end-of-frame marker value for LED data transmission.

This value is sent to mark the end of a LED data frame sequence. The default stop value is 0xFF.

APA102_FRAME_SIZE

#define APA102_FRAME_SIZE   4

Defines the size of the LED start/stop and data frame in bytes.

This macro indicates how many bytes make up a start/stop and data frame sent via SPI to the LED. The default frame size is 4 bytes.

Note

Modify this value if the LED hardware protocol requires a different start/stop and data frame size.

APA102_HAL_PLATFORM

#define APA102_HAL_PLATFORM   avr0

Sets the target platform for the APA102 hardware abstraction layer (HAL), e.g., avr or avr0.

Define this macro with the name of the target platform to select the corresponding platform-specific HAL implementation (such as TWI communication functions) for the APA102 LED driver. Common values are avr (classic AVR architecture) or avr0 (AVR0/1 series).

Note

Set this macro as a global compiler symbol to ensure that the correct HAL implementation is used across the entire project.

APA102_MAX_INTENSITY

#define APA102_MAX_INTENSITY   0x1F

The maximum intensity value for LED brightness.

This macro defines the highest valid intensity level for LED brightness. The default maximum is 0x1F.

APA102_MIN_INTENSITY

#define APA102_MIN_INTENSITY   0x01

The minimum intensity value for LED brightness.

This macro defines the lowest valid intensity level for LED brightness. The default minimum is 0x01.

APA102_NUMBER_OF_LEDS

#define APA102_NUMBER_OF_LEDS   1

Defines the total number of LEDs controlled by the driver.

This macro specifies how many individual LEDs are connected and managed. The default is 2 LEDs.

Note

Override as needed for the actual number of LEDs in the hardware configuration.

APA102_POWER_SAVING_AVAILABLE

#define APA102_POWER_SAVING_AVAILABLE

Flag indicating whether power-saving mode is supported by the LED hardware.

This macro should be defined as 1 if the LED hardware supports a power-saving mode that can be activated via software commands. If set to 0, the driver will not attempt to use power-saving features. The Harvatak RGB LED (https://mm.digikey.com/Volume0/opasdata/d220001/medias/docus/6794/3147_T3A33BRG-H9C0002X1U1930.pdf) supports a sleep mode.

APA102_SLEEP_FLAG

#define APA102_SLEEP_FLAG   0xA0

Flag used to set the LED device into sleep mode.

The value 0xA0 is used to command the LED device to enter a low power or sleep state.

APA102_SOF

#define APA102_SOF

(

)

Value:

{ apa102_xof(APA102_Transmission_SOF); }

Sends the Start-of-Frame (SOF) signal to the LED strip.

This macro transmits the predefined APA102_START_VALUE as a start frame delimiter using the function apa102_xof(). It inserts a short delay of 10 microseconds to ensure proper timing before subsequent LED data transmission begins. The SOF marks the beginning of a new LED data sequence.

APA102_SOF_VALUE

#define APA102_SOF_VALUE   0x00

Defines the start-of-frame marker value for LED data transmission.

This value is sent to indicate the start of a LED data frame sequence. The default start value is 0x00.

APA102_START_FLAG

#define APA102_START_FLAG   0xE0

Defines the start-of-frame flag value for LED data transmission.

This macro defines the highest valid intensity level for LED brightness. The default maximum is 0x1F.

Typedef Documentation

APA102_Transmission

typedef enum APA102_Transmission_t APA102_Transmission

Alias for enum APA102_Transmission_t representing possible APA102 transmission types.

Enumeration Type Documentation

APA102_Transmission_t

enum APA102_Transmission_t

Enumerates possible LED frame types for APA102 LED strips.

This enumeration defines the different frame types that can be used in APA102 LED strip communication It includes Start-of-Frame (SOF) and End-of-Frame (EOF) markers.

Enumerator
APA102_Transmission_SOF
APA102_Transmission_EOF

Function Documentation

apa102_init()

void apa102_init

(

void

)

Initialize the LED control interface and hardware.

This function initializes the SPI peripheral to communicate with the LEDs using most significant bit (MSB) first, with clock polarity and phase set to rising edges. After SPI initialization, it sends a start-of-frame (SOF) signal followed by initializing all configured LEDs with the enable flag and zero color data (LEDs initially off). Finally, it sends an end-of-frame (EOF) signal to mark completion of the initialization sequence. This setup prepares the LEDs for subsequent color and blink control operations by configuring the communication and initial states.

Note

This function must be called before any other LED control operations. It assumes SPI_MSB, SPI_Rising macros and LED frame configurations are correctly defined.

See also

APA102_SOF() and APA102_EOF() macros for frame delimiters.

apa102_frame() for sending individual LED data frames.

apa102_led()

void apa102_led

(

const GFX_RGBA_Color *

color

)

Send an LED data frame with specified color and intensity.

Parameters

color

LED_Data structure containing intensity and RGB color values.

This function constructs and transmits a single LED data frame over SPI, combining the LED enable flag with the masked intensity value, followed by the blue, green, and red color components. The intensity value is masked with 0x3F to limit it to valid bits.

The frame format is:

• Mode byte: LED_ENABLE_FLAG OR'ed with intensity (0x3F mask).
• Blue color byte.
• Green color byte.
• Red color byte.

Note

Ensure the LED is initialized before calling this function.

apa102_led_off()

void apa102_led_off

(

void

)

Send an LED data frame to a single LED to turn it off.

This function constructs and transmits a single LED data frame covered with zeroes over SPI to a single LED, combining the LED enable flag with the minimum intensity value to switch the LED off.

The frame format is:

• Mode byte: LED_ENABLE_FLAG or APA102_SLEEP_FLAG if supported
• Intensity byte: APA102_MIN_INTENSITY (minimum brightness)
• Blue color byte set to zero.
• Green color byte set to zero.
• Red color byte set to zero.

Note

Ensure the LED is initialized before calling this function.

Here is the caller graph for this function:

apa102_leds()

void apa102_leds

(

const GFX_RGBA_Color *

color

)

Send an LED data frame to all LEDs with specified color and intensity.

Parameters

color

LED_Data structure containing intensity and RGB color values.

This function constructs and transmits a single LED data frame over SPI to multiple LEDs, combining the LED enable flag with the masked intensity value, followed by the blue, green, and red color components. The intensity value is masked with 0x3F to limit it to valid bits.

The frame format is:

• Mode byte: LED_ENABLE_FLAG OR'ed with intensity (0x3F mask).
• Blue color byte.
• Green color byte.
• Red color byte.

Note

Ensure the LED is initialized before calling this function.

apa102_leds_off()

void apa102_leds_off

(

void

)

Disable all LEDs by sending sleep commands (if supported) and turning off the SPI peripheral.

This function sends sleep commands (if supported) to all configured LEDs to put them into a low power state and disables all leds.

This operation is used to safely turn off the LEDs and reduce power consumption when LED functionality is not needed.

Note

Ensure no ongoing LED data transmission occurs before calling this function to avoid communication issues with the LED hardware. After calling this function, the SPI peripheral may be disabled to save power.

Here is the call graph for this function:

apa102_xof()

void apa102_xof

(

APA102_Transmission

type

)

Transmit a specified value repeatedly over SPI to form a data frame.

Parameters

value

The byte value to be sent repeatedly.

This function sends the given value repeatedly for LED_FRAME_SIZE times via SPI using the spi_transfer function. It is commonly used to send start or stop frames for LED data sequences to synchronize communication with the LED hardware.

Note

The function blocks until all bytes are transmitted. Ensure the SPI interface is initialized before calling this function.

Here is the call graph for this function: