Kwanzaa kinara on an Arduino Uno
Seven WS2812B candle lights in red, black and green on a kinara: each press is the next day of Kwanzaa, lighting one more candle and showing that day’s principle on a 16x2 LCD. The whole build, an Arduino Uno and 4 more parts, runs here in your browser on the firmware below; open it in the editor to change the wiring or the code and run it again.
Teaching? Assign it to your class in one click.
Beginner About 25 minutes to build and run. Runs in your browser. Free, and no account needed.
The parts retail for about $37. On Mokxi they're free.
What you'll learn
- Driving addressable LEDs with
Adafruit_NeoPixel - Showing text on an I2C character LCD
- Using an array to set the order things happen in
- Scrolling long text without blocking the program
- Reading a button with
INPUT_PULLUP
- Difficulty: Beginner
- Time: About 25 minutes
- Board: Arduino Uno R3
- Parts: 6
How it works
Seven WS2812B lights stand for the seven candles of a kinara: three red, one black and three green. The black one is shown as warm white. Each press of the button on pin 2 starts the next day of Kwanzaa and lights one more candle.
The black candle lights first. After that, the candles light from the outside in, in the order set by ORDER. The LCD shows the day's principle, such as Umoja, with its meaning on the second line. A long meaning scrolls along the bottom row.
Lit candles flicker at random. After day seven, the next press clears everything and shows a greeting.
Parts list
6 parts, plus the jumper wires. They retail for about $37; on Mokxi they're free.
- 1 × Arduino Uno R3In Starter Kit, Claw Machine Kit, Vending Machine Kit.
- 1 × Half breadboard
- 1 × PushbuttonIn Starter Kit, Christmas Lights Kit, Logic Lab Kit.
- 1 × Resistor, 330 ΩIn Starter Kit, Claw Machine Kit, Halloween Prop Kit.
- 1 × Addressable RGB LEDsIn Claw Machine Kit, Halloween Prop Kit, Christmas Lights Kit.
- 1 × Character LCD with I2C backpackIn Claw Machine Kit, Vending Machine Kit, Rhythm Game Kit.
Wiring table
Every connection, pin by pin, read from the circuit itself. Each row joins the pin on the left to the pin on the right, by a jumper wire or a breadboard strip.
| Part and pin | Connects to |
|---|---|
| Resistor, 330 Ω pin 1 | Arduino Uno R3 pin 6 |
| Pushbutton pin 1a | Arduino Uno R3 pin 2 |
| Addressable RGB LEDs pin VDD | Arduino Uno R3 pin 5V |
| Character LCD with I2C backpack pin VCC | Arduino Uno R3 pin 5V |
| Pushbutton pin 2a | Arduino Uno R3 pin GND |
| Addressable RGB LEDs pin VSS | Arduino Uno R3 pin GND |
| Character LCD with I2C backpack pin GND | Arduino Uno R3 pin GND |
| Character LCD with I2C backpack pin SDA | Arduino Uno R3 pin A4 |
| Character LCD with I2C backpack pin SCL | Arduino Uno R3 pin A5 |
| Addressable RGB LEDs pin DIN | Resistor, 330 Ω pin 2 |
The code
The firmware exactly as the editor opens it. Change a line there and press Run: it compiles in the browser.
// Kwanzaa kinara: seven candle lights, three red, one black and three green,
// with the day's principle on a little screen. Each press of the button is the
// next day of Kwanzaa, and one more candle is lit.
//
// candles 7 WS2812B LEDs in a row, DIN <- 330 ohms <- pin 6
// (left to right: red, red, red, black, green, green, green)
// LCD 16x2 with an I2C backpack: SDA -> A4, SCL -> A5
// button pin 2 -> button -> GND (INPUT_PULLUP): the next day
//
// Kwanzaa runs from December 26th to January 1st, a celebration of African
// American culture and heritage with a principle for each day, the Nguzo
// Saba. The kinara holds the mishumaa saba, the seven candles: the black one
// in the middle for the people, three red on the left for the struggle, and
// three green on the right for the future and hope.
//
// The black candle is lit first, on the first day. After that, one common
// order alternates from the outside in: the first red on the far left, then
// the first green on the far right, and so on toward the middle. Families
// differ a little in the order they use, so it is one line, ORDER, to change.
//
// Each candle's LED glows in its candle's color, red, warm white for the
// black candle, and green, with a flame's flicker on top.
//
// Things to try. Press the button for each day. Change ORDER to the one your
// family uses.
#include <Wire.h>
#include <LiquidCrystal_I2C.h>
#include <Adafruit_NeoPixel.h>
const int CANDLES = 7;
const int BUTTON_PIN = 2;
// Which place lights on each day: the black candle, then outside in.
const int ORDER[CANDLES] = {3, 0, 6, 1, 5, 2, 4};
const char *PRINCIPLES[CANDLES][2] = {
{"Umoja", "Unity"},
{"Kujichagulia", "Self-Determination"},
{"Ujima", "Collective Work and Responsibility"},
{"Ujamaa", "Cooperative Economics"},
{"Nia", "Purpose"},
{"Kuumba", "Creativity"},
{"Imani", "Faith"},
};
Adafruit_NeoPixel kinara(CANDLES, 6, NEO_GRB + NEO_KHZ800);
LiquidCrystal_I2C lcd(0x27, 16, 2);
int day = 0;
bool lit[CANDLES];
const char *marquee = ""; // the bottom line, scrolled when it is long
int marqueeAt = 0;
unsigned long nextScroll = 0;
// Show the bottom line, sliding along one letter at a time if it is wider
// than the screen, with a pause at each end.
void scrollLine() {
int len = strlen(marquee);
if (len <= 16 || millis() < nextScroll) return;
lcd.setCursor(0, 1);
for (int i = 0; i < 16; i++) lcd.print(marquee[marqueeAt + i]);
nextScroll = millis() + (marqueeAt == 0 || marqueeAt == len - 16 ? 1200 : 300);
marqueeAt = marqueeAt >= len - 16 ? 0 : marqueeAt + 1;
}
// The candle's color at place i: red on the left, black (shown warm white)
// in the middle, green on the right, scaled by the flame's level.
void candle(int i, int v) {
if (i < 3) kinara.setPixelColor(i, v, 0, 0);
else if (i == 3) kinara.setPixelColor(i, v, v * 3 / 4, v / 3);
else kinara.setPixelColor(i, 0, v, 0);
}
void setup() {
Serial.begin(9600);
pinMode(BUTTON_PIN, INPUT_PULLUP);
kinara.begin();
kinara.setBrightness(170);
kinara.show();
lcd.init();
lcd.backlight();
lcd.print("Habari Gani?");
lcd.setCursor(0, 1);
lcd.print("Press for day 1");
Serial.println("Kwanzaa kinara: press the button for the first day");
}
void loop() {
if (digitalRead(BUTTON_PIN) == LOW) {
day++;
if (day > CANDLES) {
day = 0;
for (int i = 0; i < CANDLES; i++) lit[i] = false;
marquee = "";
lcd.clear();
lcd.print("Heri za Kwanzaa");
Serial.println("Heri za Kwanzaa! All seven days are done");
} else {
lit[ORDER[day - 1]] = true;
lcd.clear();
lcd.print(PRINCIPLES[day - 1][0]);
lcd.setCursor(0, 1);
for (int i = 0; i < 16 && PRINCIPLES[day - 1][1][i]; i++) lcd.print(PRINCIPLES[day - 1][1][i]);
marquee = PRINCIPLES[day - 1][1];
marqueeAt = 0;
nextScroll = millis() + 1200;
Serial.print("Day ");
Serial.print(day);
Serial.print(": ");
Serial.print(PRINCIPLES[day - 1][0]);
Serial.print(", ");
Serial.println(PRINCIPLES[day - 1][1]);
}
while (digitalRead(BUTTON_PIN) == LOW) delay(10);
}
for (int i = 0; i < CANDLES; i++) {
if (lit[i]) candle(i, random(0, 15) == 0 ? random(120, 180) : random(200, 256));
else kinara.setPixelColor(i, 0);
}
kinara.show();
scrollLine();
delay(50);
}
Code walkthrough
The key functions of the sketch, and what each one does.
scrollLine sketch.ino
If the bottom line is longer than 16 characters, it prints a 16-character window and moves it one letter at a time. It pauses longer at each end. When the line fits on the screen, it does nothing.
// Show the bottom line, sliding along one letter at a time if it is wider
// than the screen, with a pause at each end.
void scrollLine() {
int len = strlen(marquee);
if (len <= 16 || millis() < nextScroll) return;
lcd.setCursor(0, 1);
for (int i = 0; i < 16; i++) lcd.print(marquee[marqueeAt + i]);
nextScroll = millis() + (marqueeAt == 0 || marqueeAt == len - 16 ? 1200 : 300);
marqueeAt = marqueeAt >= len - 16 ? 0 : marqueeAt + 1;
}candle sketch.ino
Sets one candle's color from its place. Places 0 to 2 are red, place 3 is a warm white for the black candle, and 4 to 6 are green. The value v scales the brightness, which is how the flicker works.
// The candle's color at place i: red on the left, black (shown warm white)
// in the middle, green on the right, scaled by the flame's level.
void candle(int i, int v) {
if (i < 3) kinara.setPixelColor(i, v, 0, 0);
else if (i == 3) kinara.setPixelColor(i, v, v * 3 / 4, v / 3);
else kinara.setPixelColor(i, 0, v, 0);
}setup sketch.ino
Starts the serial port, sets the button pin to INPUT_PULLUP, starts the LEDs at brightness 170, and starts the LCD with its backlight. It shows the greeting and a prompt to press for day 1.
void setup() {
Serial.begin(9600);
pinMode(BUTTON_PIN, INPUT_PULLUP);
kinara.begin();
kinara.setBrightness(170);
kinara.show();
lcd.init();
lcd.backlight();
lcd.print("Habari Gani?");
lcd.setCursor(0, 1);
lcd.print("Press for day 1");
Serial.println("Kwanzaa kinara: press the button for the first day");
}loop sketch.ino
A button press adds a day, lights the candle given by ORDER, and updates the LCD and Serial Monitor. After day seven it resets. Every pass then redraws each lit candle with a random level and runs scrollLine.
void loop() {
if (digitalRead(BUTTON_PIN) == LOW) {
day++;
if (day > CANDLES) {
day = 0;
for (int i = 0; i < CANDLES; i++) lit[i] = false;
marquee = "";
lcd.clear();
lcd.print("Heri za Kwanzaa");
Serial.println("Heri za Kwanzaa! All seven days are done");
} else {
lit[ORDER[day - 1]] = true;
lcd.clear();
lcd.print(PRINCIPLES[day - 1][0]);
lcd.setCursor(0, 1);
for (int i = 0; i < 16 && PRINCIPLES[day - 1][1][i]; i++) lcd.print(PRINCIPLES[day - 1][1][i]);
marquee = PRINCIPLES[day - 1][1];
marqueeAt = 0;
nextScroll = millis() + 1200;
Serial.print("Day ");
Serial.print(day);
Serial.print(": ");
Serial.print(PRINCIPLES[day - 1][0]);
Serial.print(", ");
Serial.println(PRINCIPLES[day - 1][1]);
}
while (digitalRead(BUTTON_PIN) == LOW) delay(10);
}
// ... 9 more lines in the editorTroubleshooting
The usual mistakes with this circuit, and the fix for each.
- The LCD stays blank This project
Check that SDA goes to A4 and SCL goes to A5, and that the address inLiquidCrystal_I2Cmatches your backpack. - The candles do not light This project
The data line goes from pin 6 through the 330 ohm resistor to DIN, and the strip needs 5V and GND. - The lighting order is not the one your family uses This project
Edit the numbers inORDER. - The input reads random HIGH and LOW when the button is not pressed. Pushbutton
A floating pin picks up noise. Add a 10 k pull-down or pull-up resistor, or use INPUT_PULLUP and wire the button between the pin and GND. Then pressed reads LOW. - The button seems always pressed, or never changes. Pushbutton
A 4-leg tactile switch has legs joined in pairs. Place it across the breadboard center gap so the pairs sit on different rows. Wired along one side, the legs are already connected. - The LED is dim, burns out, or the pin reads wrong because the resistor value is off. Resistor
Read the color bands again. A 220 ohm to 330 ohm resistor suits a typical LED on 5 V. 10k is a common pull-up or pull-down value. Check with a multimeter if unsure. - A pull-up or pull-down resistor is missing, so the input floats and reads random values. Resistor
Tie the input to 5 V or ground through about 10k. Or use INPUT_PULLUP and wire the switch to ground. - The first LED flickers, shows wrong colors, or the whole strip glitches. Addressable RGB LEDs
Join the grounds of the strip and the controller. Add a 300 to 500 ohm resistor in series with the data line. Put a 1000 uF capacitor across the strip's 5 V and GND.
Change it and keep it
Open it in the editor, change the circuit or the code, and keep your version in a free account.