In Part 1, I documented the process of manufacturing my own Fadecandy boards, including converting design files from Eagle to KiCad, creating a BOM (filling in some missing details), and building a few boards.

Overview

In this part, I’ll flash the Fadecandy firmware onto the new boards we made in Part 1, using a SWD programmer and a custom jig. This will be followed by how to building the host software (fcserver), and how to build the firmware from source, and flashing it via USB.

Everything was tested on both Intel (macOS 11) and Apple-Silicone Mac (macOS 15). My fork of the fadecandy repo is here.

Writing to a blank board

The ability to flash firmware via USB is a standard part of the Arduino developer experience. For this to work, a small program called a bootloader need to be present on the MCU. This is either flashed at the factory, or built in at a silicon level (e.g. RP2040). The MK20DX128, fresh from the factory has neither, so we’ll need to go a different route - JTAG/SWD, a low level protocol that allows direct write to MCU flash.

We need some extra hardware to do this. I’m going to use a Segger J-Link EDU Mini programmer. There are several versions of this - though I believe the main difference is the type of USB connector. This has a standard ARM 10-pin JTAG connector. I’ve used an adapter to break it out to 0.1” pins, to facilitate connecting it to the Fadecandy’s programming ports (a.k.a. its hacker port)

The Teensy 3, on which the device is based on uses a second, auxiliary MCU to handle the USB programming. This second MCU, with it’s proprietary firmware, is the magic sauce that makes a board a Teensy.

hacker port

The hacker port is a set of pads on the back side of the board. I’ve used a 0.1” pitch 2x6 pin pogo connector to make contact. The pins are unnumbered. Each contact is defined as its own test point in the PCB design file. For the sake of this post, I’ve numbered them as follows:

Here’s a pinout

Only five of these pins need to be connected to the JTAG connector for SWD

I built the following jig

It’s an Omnifixo in case you are were wondering.

Before flashing the bootloader, both the J-Link and Fadecandy need to be plugged into USB - the later just for power.

We’ll use OpenOCD to do the flashing. On macOS, run brew install openocd to install. We’ll want a config file to make this easier. Using bootloader/openocd.cfg as a starting point, we create the following config file:

content of openocd_jlink.cfg

# openocd_jlink.cfg  –  use with:  openocd -f openocd_jlink.cfg -c "program PATH_TO_HEX verify reset exit"

# 1. Interface: use SEGGER J-Link rather than the Olimex FTDI probe
source [find interface/jlink.cfg]

# 2. Tell the J-Link we’re speaking SWD, not JTAG
transport select swd

# 3. Keep the target definition (k40.cfg handles all K20/K40 variants)
set CHIPNAME mk20dx128        ;# or just 'k40' – pick one name
source [find target/k40.cfg]

# 4. SWD clock. 1 MHz is safe on a breadboard; faster once wiring is short
adapter speed 1000

# 5. Mass-erase & program in one go
init; kinetis mdm halt; kinetis mdm mass_erase

A few things to note:

• Lots of link rot in the original file! Thankfully, they all seem to refer to patches to OpenOCD to make it work with the chip. 12 years down the line, mainline OpenOCD seems to work fine. Thank you open source contributors!
• A few commands have changed - better defaults? support of the kinetis mdm commands?

to flash it, run

openocd -f openocd_jlink.cfg -c "program ../bin/fc-firmware-v107.hex verify reset exit"

from the bootloader folder. This flashes the final factory firmware that Adafruit shipped (1.07).

You should see something like this:

Open On-Chip Debugger 0.12.0
Licensed under GNU GPL v2
For bug reports, read
	http://openocd.org/doc/doxygen/bugs.html
Info : add flash_bank kinetis k40.pflash
Info : J-Link EDU Mini V1 compiled Jun  6 2023 10:50:57
Info : Hardware version: 1.00
Info : VTarget = 3.277 V
Info : clock speed 1000 kHz
Info : SWD DPIDR 0x2ba01477
Info : [k40.cpu] Cortex-M4 r0p1 processor detected
Info : [k40.cpu] target has 6 breakpoints, 4 watchpoints
Info : MDM: Chip is unsecured. Continuing.
Info : starting gdb server for k40.cpu on 3333
Info : Listening on port 3333 for gdb connections
[k40.cpu] halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
Info : MDM: Chip is unsecured. Continuing.
[k40.cpu] halted due to debug-request, current mode: Thread
xPSR: 0x01000000 pc: 0xfffffffe msp: 0xfffffffc
Info : Kinetis MK20DX128xxx5 detected: 2 flash blocks
Info : 1 PFlash banks: 128 KiB total
Info : 1 FlexNVM banks: 32 KiB total, 32 KiB available as data flash, 2048 bytes FlexRAM
Info : Disabling Kinetis watchdog (initial WDOG_STCTRLH = 0x01d3)
Info : WDOG_STCTRLH = 0x01d2
** Programming Started **
Info : Padding image section 0 at 0x00000ee4 with 284 bytes
Info : Flash protection requested in the programmed file differs from current setting.
Info : Data flash protection requested in the programmed file differs from current setting.
Info : Trying to re-program FCF.
** Programming Finished **
** Verify Started **
** Verified OK **
** Resetting Target **
Info : MDM: Chip is unsecured. Continuing.
shutdown command invoked

This should allow the board to enumerate on USB. To verify, run

system_profiler SPUSBDataType | grep -i -A3 -B3 "fadecandy"

we see

      Host Controller Driver: AppleT8132USBXHCI

        Fadecandy:

          Product ID: 0x607a
          Vendor ID: 0x1d50

That’s it! This should work like a Fadecandy from the shops! The binary included the custom (and DFU compatible) bootloader, so subsquent firmware updates can be via USB.

Host software

For a Fadecandy to work, we also need host software to connect to it over USB. fcserver is the provided and most commonly used one, as documented in the Adafruit guide. The guide is very loud and clear that the code no longer works on 64 bit systems. A trivial change fixes this.

Of more significance, the soure made use of some git submodules which are no longer at their original location on github. I’ve included them in my fork.

A simple make should build fcserver now.

Open Lighting Architecture (OLA) is actively maintained, and have built in Fadecandy support. I have not tested this.

Building and flashing the firmware

We can disconnect the J-Link and remove the Fadecandy from the jig, if you like. The rest will work over just USB.

First Install DFU-util and the compiler using brew install arm-none-eabi-gcc dfu-util. There’s been some changes in the build tools between 2013-2025. A few small changes (mostly to do with how standard lib is handled) was required before the firmware will build.

Run make from the firmware folder and confirm it actually built.

arm-none-eabi-gcc  -Wall -Wno-sign-compare -Wno-strict-aliasing -g -Os -mcpu=cortex-m4 -mthumb -nostdlib -MMD -Werror  -I.  -c -o usb_desc.o usb_desc.c
arm-none-eabi-gcc  -Wall -Wno-sign-compare -Wno-strict-aliasing -g -Os -mcpu=cortex-m4 -mthumb -nostdlib -MMD -Werror  -I.  -c -o usb_dev.o usb_dev.c
arm-none-eabi-gcc  -Wall -Wno-sign-compare -Wno-strict-aliasing -g -Os -mcpu=cortex-m4 -mthumb -nostdlib -MMD -Werror  -I.  -c -o usb_mem.o usb_mem.c
arm-none-eabi-g++ -std=gnu++0x -felide-constructors -fno-exceptions -fno-rtti -Wall -Wno-sign-compare -Wno-strict-aliasing -g -Os -mcpu=cortex-m4 -mthumb -nostdlib -MMD -Werror  -I.  -c -o fadecandy.o fadecandy.cpp
arm-none-eabi-g++ -std=gnu++0x -felide-constructors -fno-exceptions -fno-rtti -Wall -Wno-sign-compare -Wno-strict-aliasing -g -Os -mcpu=cortex-m4 -mthumb -nostdlib -MMD -Werror  -I.  -c -o fc_usb.o fc_usb.cpp
arm-none-eabi-gcc -Os -Wl,--gc-sections -mcpu=cortex-m4 -mthumb -nostdlib -Tfcb-app.ld -o fc-firmware.elf startup.o pins_teensy.o usb_desc.o usb_dev.o usb_mem.o serial1.o fadecandy.o fc_usb.o OctoWS2811z.o -lm -lc -lgcc -lnosys
arm-none-eabi-size fc-firmware.elf
   text	   data	    bss	    dec	    hex	filename
  16340	      0	  15651	  31991	   7cf7	fc-firmware.elf
arm-none-eabi-objcopy -O binary fc-firmware.elf fc-firmware.dfu
dfu-suffix -a fc-firmware.dfu
dfu-suffix (dfu-util) 0.11

Copyright 2011-2012 Stefan Schmidt, 2013-2020 Tormod Volden
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

Suffix successfully added to file
arm-none-eabi-objcopy -O ihex fc-firmware.elf app-image.hex
(grep -v :00000001FF ../bin/fc-boot-v101.hex; cat app-image.hex) > fc-firmware.hex

make install should flash it onto the board via DFU:

dfu-util -d 1d50 -D fc-firmware.dfu
dfu-util 0.11

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2021 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to http://sourceforge.net/p/dfu-util/tickets/

Opening DFU capable USB device...
Device ID 1d50:607a
Run-Time device DFU version 0101
Claiming USB DFU (Run-Time) Interface...
Setting Alternate Interface zero...
Determining device status...
DFU state(0) = appIDLE, status(0) = No error condition is present
Device really in Run-Time Mode, send DFU detach request...
Device will detach and reattach...
Opening DFU USB Device...
Claiming USB DFU Interface...
Setting Alternate Interface #0 ...
Determining device status...
DFU state(2) = dfuIDLE, status(0) = No error condition is present
DFU mode device DFU version 0101
Device returned transfer size 1024
Copying data from PC to DFU device
Download	[=========================] 100%        16340 bytes
Download done.
DFU state(7) = dfuMANIFEST, status(0) = No error condition is present
dfu-util: unable to read DFU status after completion (LIBUSB_ERROR_NO_DEVICE)
make: *** [install] Error 74

It might also be handy to flash one of the pre-compiled firmware binaries:

dfu-util -d 1d50 -D ../bin/fc-firmware-v107.dfu

The creator of Fadecandy, Micah Elizabeth Scott, aka scanlime, seems to have stepped away from the project. She has deleted much of the official content, including the github repo. As it happens, I’ve already started a lot of the planning work for these DIY Fadecandies, before the github repo was deleted. I debated a bit on whether it’s appropriate to do this write up, given that the project creator would rather not see it continue. In the end, I believe an aspect of open source is to decouple the creation from the creator. With that in mind, consider this a tribute to the project.

Objective

• Document what it takes to build a Fadecandy board in 2023
• Provide information that might be useful for people maintaining existing projects: updated instructions on
  • How to build and flash the firmware
  • How to build/run the host side software
• Show the project some appreciation
• Learn a few things for myself, and hopefully help one or two other people learn a few things.

Non-goals

• Any continuation/expansion/evolution of the project
• Producing more than a handful of new boards. Certainly nothing commercial
• Commitment to keeping any of the documentation up to date

Bill of Materials

The goal is a reasonably close reproduction of an Adafruit revision B board. The Eagle files were in the repo, and I believe this makes up for the vast majority of Fadecandies made.

It’s worth noting that a Fadecandy, electrically, is based on a Teensy 3.0 + OctoWS2811 adapter, less Teensy’s two-chip bootloader setup, plus a 5V power supply. This will be useful in most component selection questions. I made good use of this forum thread.

A example of a (water damaged and dead) Fadecandy rev b board

Working through the schematic…

Microprocessor and its crystal

The core of the board is a NXP MK20DX128VLF5 - this microprocessor was originally released by Freescale in the early 2010s. It’s part of the Kinetis K20 family. It consists of a 50Mhz Cortex M4 core, 128KB of flash, and comes in a 48 pin LQFN package. As of late 2023, it’s still listed as “Active” by NXP. Stock availability is a bit patchy. I manage to buy a handful after looking across a few shops via Octopart. I expect this will go obsolete at some stage, and it will become impossible to produce firmware compatible boards.

It uses a handful of MLCC capacitors for decoupling. I’m going with some X5R or X7R 0805 parts, rated at 16V or higher.

Selecting the crystal takes a little bit more research. It’s a 4-pin 3.2x2.5mm SMD part. The schematics label it at 16Mhz. We need to determine its accuracy, load capacitance, and ESR. Digging this and this forum threads, we arrive at 10ppm or less stability, a bit less than 10pF or load capacitance. Looking at parts on Digikey that fits this description, we are looking at probably at least 50Ohm ESR.

I learnt about matching load capacitors to crystals in the RP2040 Hardware design guide, so I was a bit surprised to see that that the schematic didn’t include any load capacitors. the second thread linked to above yielded the information that the K20 MCU has software configurable internal load capacitors. To find out what the Fadecandy uses, I searched the relevant register names in the repo, and found these lines in the bootloader code.

    // enable capacitors for crystal
    OSC0_CR = OSC_SC8P | OSC_SC2P;

i.e. 10pF load capacitor configured. If we assume 3pF for trace capacitance… that gives around 8pF for the crystal. This checks out with the “a bit less than 10pF” from above! (The RP2040 Hardware design guide has a good section on this calculation in page 9.)

With all the above information, I went with an Epson part rated at 9pF, 10ppm stability and 60Ohms ESR. As it happens, the RGB-123 PCB design files included a BOM, which specified a very similar part (slightly lower stability/tolerance).

Charge pump

The design takes account of the fact that VBUS is nominally 5V for USB, it could be a lot lower in practice, especially when long cables and self powered hubs are used.

It includes a Skyworks AAT3110IGU-5.0-T1 charge pump, 100mA @ 5V output. This is discontinued and unavailable as of 2023. However, this is a jellybean part, and there are plenty of alternatives, though this might require different complementary passives.

I’ve replaced this with a MPS MP9361, 110mA @ 5V pump. This operates at 1.35Mhz, v.s. 750Khz of the Skyworks part. The only thing this will need to drive is the level shifter, which has a max supply draw in the region of 70mA (though I suspect it’s a lot lower in practice).

The reference design in the datasheet specifies a 0.47uF capacitor for flying cap (C9 in the schematic). The equation for flying capacitor values does suggest that capacitance being inversely proportional to frequency, so this makes sense. The datasheet also had different values for input/output caps, but those don’t have to be as exact, so I’ll leave them as they are.

The fact that this IC comes in a T(hin)SOT-23-6 package, whereas the original is a regular (thick?) SOT-23 doesn’t matter, as it’s purely a height issue.

Level shifter

This is responsible for shifting the 3.3V logic from the MCU up to 5V expected by WS2811 controllers. The schematic specifies a Texas Instruments SN74HCT245PWR Octo bus transceiver. This is available in large numbers as of 2023. As a member of the 7400 family, it’s likely to be made for the foreseeable future. In fact, the boards made by Adafruit used Nexperia 74HCT245PW versions. I used that version, as I had those on hand.

USB connector

The board uses a mini-B USB connector. It’s a common SMD footprint. I used a EDAC part that matched the Adafruit boards.

The connector has Ferrite Beads on the VBUS and GND lines. Going through forums, Paul suggested 600Ohm @ 100Mhz parts.

Hacker port

Lastly, the bottom of the board has a programming/debug header, in the form of 10 square test pads in a 2x6 2.54mm pitch array. One could easily solder onto these… but I ordered a spring loaded connector that I’ll build into a jig.

Resistor changes

A visual inspection of the Adafruit boards I have show 22Ohm resistors for R1 and R2 (USB D+/D-) instead of the 33Ohm components in the schematic. I have no idea why, and chances are, it’s not crucial. I’m going to err on what went onto the manufactured boards.

The current limiting resistor for the indicator LED is 470Ohm instead of 180Ohm. This might be related to the schematic specifying a yellow LED, whereas the boards are populated with a green one… though those two colours tend to have similar forward voltages (~2.1V), so it might just be there to make it a bit less bright. This is also unlikely to be critical. I ended up swapping the LED to a white one, and used a 220Ohm resistor.

Lastly, the Eagle files specified 68Ohm for R4-R11. This matches the boards I have. However, the PDF schematic used 75Ohm. I’ve gone with 68Ohms. These resistors are there to reduce ringing, as discussed here. There is no right value, as it depends on what you are going to wire the board up to.

(Modified) Bill Of Materials

This decisions described above. For the capacitors and resistors, I included a Digikey part number as an illustration of a suitable part, but anything in spec would have worked (probably).

My impression of the design

• It uses a Mini USB type B plug, though by 2013, Micro USB was already dominant (USB type C was only 2 years away!). I believe this is done for mechanical robustness.
• 0805 components: these are huge! Not sure why this was chosen, as Adafruit’s SMD lines could certainly have handled small components.
• The 68 Ohm resistors didn’t use a resistor array component.

Manufacturing

(I’ve also converted the Eagle files to KiCad. The process was somewhat manual, but nothing especially interesting.)

I ordered the boards and a stencil from JLCPCB. It looks like hand soldering the board should be possible, but I didn’t try.

I applied the paste using a vacuum rig to hold the stencil flat. It wasn’t as neat as it should have been. I’m still figuring out the vacuum method.

This was all reflowed on an Aliexpress 100x100mm hot plate.

There was some reworking needed to remove a few bridges around the LQFP package.

Next part: programming!

Problem

Getting an Adafruit Metro Mini recognised on a fresh-ish macOS install. The current revision of the board uses the SiLabs CP2104 chip, which requires a driver under macOS. I believe this chip is also used in a few other popular devboards. This is documented on Adafruit’s site (above link). However, this was broken for a few reasons. Net result is that though the driver appear to install correctly, plugging in the chip does not yield a serial port cu.SLAB_USBtoUART.

There’s a couple of posts/forum threads about it, but none, by themselves, helped me resolve this.

The causes

As usual with these things, a bunch of things conspired to make this difficult. The two main drivers:

• v5 of SiLabs’ CP210x USB to UART driver is/was incorrectly signed. This might have been fixed now, but I used the v4 driver (labeled Legacy MacVCP Driver) in the download.
• In macOS 10.13, Apple changed some security stuff around System Extension things, detailed here. This only affects new extensions. Ones already installed are grandfather-ed in.

Solution

1. Make sure existing extensions are uninstalled. ls /Library/Extensions/SiLabs* should show you what’s there. You can then sudo rm -rf /Library/Extensions/SiLabsUSBDriver64.kext etc.
2. Reboot. Check they are gone.
3. Install the v4, legacy driver from the above link. v5 might be fixed now, but there were no compelling reasons to move to it for me.
4. Reboot. Go to System Preferences => Security and Privacy You should see a message along the lines of “System software from developer ‘Silicon Laboratories Ltd’ was blocked from Loading”. Click “Allow”
5. The previous step didn’t do anything for me. As it turns out, this particular screen check if there’s any mouse automation software active, and does not allow loading of said extensions if that’s the case. To find out what’s going on, open Console.app from spotlight. Keep the logs where you can see it. Now, click on the “Allow” button again. You should see a log line about something beign disallowed because it came from the wrong PID. Look this PID up in Activity Monitor. In my case, it was Chrome, which had the Chrome Remote Desktop plugin installed. Killing Chrome and clicking on “Allow” again worked.
6. Plug your CP2104 board in again, and check for /dev/cu.SLAB_USBtoUART. If it’s there, you should be ready to go.

Parting thoughts

This whole thing seems to be a casestudy in why silent faliures are bad. Unless you go quite deep, there’s no “This didn’t work” dialogs. Just no expected effect. Further more, the macOS update didn’t break any existing setups, so this wasn’t immediately linked to the OS update.

One of the earlier tasks is to wire the app up to Auth0, an IaaS, and for simplicity, I’m using their Lock library.

This post works, but is not very re-frame-y.

Effect handler code

(ns your-app.auth0
  (:require [re-frame.core :as re-frame]
            [cljsjs.auth0-lock]))

(defonce lock-instance (atom nil))

(defn *js->clj
  [js]
  (js->clj js :keywordize-keys true))

(defn make-lock
  [client-id domain options on-authenticated]
  (let [lock (js/Auth0Lock. client-id domain
                            (clj->js options))]
    (.on lock "authenticated"
         #(re-frame/dispatch (conj on-authenticated (*js->clj %))))
    lock))

(defn get-user-info
  [lock value]
  (.getUserInfo
   lock (:access-token value)
   (fn [e p]
     (let [error   (*js->clj e)
           profile (*js->clj p)]
       (if e
         (re-frame/dispatch (conj (:on-failure value) error))
         (re-frame/dispatch (conj (:on-success value) profile)))))))

(re-frame/reg-fx
 :lock
 (fn [value]
   (let [lock @lock-instance]
     (case (:method value)
       :instantiate   (reset! lock-instance
                              (make-lock (:client-id value)
                                         (:domain value)
                                         (:options value)
                                         (:on-authenticated value)))
       :show          (.show lock)
       :logout        (.logout lock
                               (clj->js {:returnTo (:return-to value)}))
       :get-user-info (get-user-info lock value)
       nil))))

Event handler code

On app-startup (called with a dispatch-sync)

(re-frame/reg-event-fx
 :initialize-lock
 (fn [_ _]
   {:lock {:method           :instantiate
           :client-id        config/auth0-client-id
           :domain           config/auth0-domain
           :options          lock-options
           :on-authenticated [:new-auth-result]}}))

Log in

(re-frame/reg-event-fx
 :login
 (fn [_ _]
   {:lock {:method :show}}))

On Auth result

(re-frame/reg-event-fx
 :new-auth-result
 (fn [{:keys [db]}
      [_ {new-access-token :accessToken
          new-id-token     :idToken}]]
   {:db          (assoc db
                        :id-token new-id-token
                        :access-token new-access-token)
    :lock        {:method :get-user-info
                  :access-token new-access-token
                  :on-success [:profile-change]
                  :on-failure [:auth-fail]}}))

etc.

Thoughts

We are not using the app-db to store the lock object. But this kind of lives in a separate world anyways.

This followed the pattern set by re-frame-http-fx, callbacks via dispatches and all.

Setting the behaviour of the lock object via the on call on creation feels more appropriate than exposing the on method directly. We are limiting that stateful behaviour to app setup, when we can impose more control on sequence of events.

If we have a relatively simple auth flow, doing things in this re-frame purist way doesn’t add a whole lot more value, as compared to triggering it via side-effects, but it might allow for more complex events.

It might be worth fleshing this out into a full (micro)library. re-auth0-fx?

TP-Link’s MR3040 occupies a strange niche: a battery powered device, with an ethernet port and USB, that also runs OpenWRT. This led to a bunch of interesting use cases, including distributing bibles and penetrating networks.

I came upon it in building the LSDome, an installation for AfrikaBurn. Someone got the Fadecandy server to run on its diminitive 4MB flash. This, paired with a Fadecandy board, makes ia very neat, self-contained, WS2812 LED controller. I believe the USB port can even be used to power the LEDs themselves, in addition to the Fadecandy. For the LSDome’s first version, we added a USB-hub hub and drove 4 Fadecandies. This worked really well: you can use WiFi for diagnostic and quick tests, and the ethernet connection for more reliable connections. The little router worked perfectly even when pushing 1500+ LEDs.

It was somewhat handy to have the built-in battery: it kept the server code up even when DC power was off, and worked well for 3-4 hours on a full charge. For most of the time though, we ran it with USB power plugged in, and this worked as expected.

For the second outing of the project, we added two more Fadecandies, which also required a 2nd hub. This seemed to work well in brief testing, so off to the desert we went…

And the system started failing after one day of operation. Even when supplied with USB power, the MR3040 would not boot. Cutting a long story short, the extra USB hub (and maybe two more Fadecandies?) increased the total system power draw above the 2.5W that can be drawn from the 500mA charging port! However, since it runs off of the battery first, which can support the higher power draw, it would slowly discharge the battery over a long period. Note that the 500mA limit is the MR3040’s thus using a 1A/2A power supply did not help.

This places the device into a frustrating class of devices, where max power draw from the external input is less than its own peak draw. In other words, it can be plugged into the wall, but the battery may drain over time. One infamous device in this category is the iPad 3, which prompted Apple to move from a 10w to 12w charger for the iPad 4 onwards, contributing to the creation of the strange 2.4A quasi-standard for USB charging.

This characteristic is mostly an oddity for genuinely unplugged use cases, but makes these devices unsuitable for installed use, where you expect it to sustain peak power usage indefinitely as long as input power is adequate. I’ve often thought of devices with batteries as normal, externally powered devices with a temporary backup. This does not hold true in this case.

This also might explain why the device doesn’t boot without the battery.

We found a workaround by replacing the battery with a fresh one (charged in a spare MR3040) every day, but this was obviously far from ideal.

This is the second of a two part series on technology available around addressable LEDs. Part one, covered different types of LEDs avaliable, microcontrollers and associated libraries.

There are few limits to what you can do with a microcontroller and some LEDs. However, as you grow to a larger scale, or start looking at more complex graphics or interactivity, it becomes easier if we brought more layers of abstraction into play.

With this, comes a slight paradigm change in how we see your overall system. For smaller, LED projects, we tend to use this abstract view:

Conceptual view of smaller projects

Here, a lot of work goes toward making anything work at all. Thus, more emphasis is placed on libraries and controller boards. The actual animation code often takes less than 50 lines.

If you are trying to win Burning Man, building an LED installation for a client to help fund a Burning Man project, or one of the more fringe reasons to embark on a large scale LED project, it’s probably more useful to think of your system like this:

Big installation conceptual view

Your unique core program captures the bulk of the complexity in your project. This could be taking a webcam feed, doing some real time video processing, based on sound input, and sending the output to an LED grid and sound system. Or it could be using motion sensing data to light up a stage and trigger flames when certain dance move combos are detected. Your core program will most likely be written in a high level language, such as Python or Processing. This program will likely access the hardware (including LEDs) through a more general interface.

For example, a microcontroller library such as FastLED includes a lot of framework code to make animation and colour related calculations easier. This make sense as your animation code would be running on the same processor as your LED library. However the flip side is that the library can only directly interact with C/C++ code that’s running on the same controller. To interact with another program, running on a different computer, you’d need to get radios, networks, and serial ports involved.

A more generalised LED output stack, as we outline later, will only allow most simple commands, such as specifying that LED 34 is set to the colour that corresponds to the RGB triplet (127, 0, 127). However, this interface can be access by almost any program, often across a network.

–Not sure how this read–

The interface between your program (referred to as “client”) and the LED subsystem (referred to as “server”) is usually the ability to set an LED (addressed by an integer) a certain colour (specified as a RGB triplet). It’s up to the server code to translate that down to well timed signals to the LEDs. The client is responsible for ensuring that the intention of the program is carried out. This means that, among other things, the client need to be aware of the physical geometry of individual LEDs, and their relation to each other.

For the purposes of this article, we’ll discuss three solutions:

Fadecandy

Fadecandy is the brainchild of Micah Elizabeth Scott. She developed the WS2812 only system while working on a Burning Man installation. The system comprise of:

• A custom designed board, based on a Teensy 3.0. It connects to a host system running Linux, OSX or Windows via USB. This is manufactured and sold by Adafruit. Each board can control up to 512 LEDs.
• Custom firmware on the board that improves the range of colours possible from WS2812s, and smoother animations.
• Server software that exposes the LEDs over Open Pixel Control protocol over the network.

The client could run on practically any platform, and written in any language, as long as it can communicate via TCP sockets.

The system is very accessible: each Fadecandy board costs $25, and that gets you up and running. When installed, aRaspberry Pi could be used to the server, controlling upwards of 10 000 LEDs.

LEDscape/RGB-123 Cape

This system is used in many Burning Man installations, and is a combination of several projects. It comes together to expose 1000s of WS2812 LEDs through an Open Pixel Control server, using a BeagleBone Black (BBB) as both the LED controller and server. The components are:

• BeagleBone Black, a computer by BeagleBoard that is similar to, and somewhat more powerful than a Raspberry Pi. Significantly, it contains two Programmable Realtime Units, or PRUs. These can run with enough timing precision to control WS2812b LEDs.
• Ryan O’Hara’s BBB output capes, sold through his RGB-123 shop. These handle level shifting, comes in 24 or 48 strand configurations. Significantly, there is also a version that uses the RS-485 standard to extend the signal via Cat6 cables and RJ45 connectors.
• LEDscape library, originally written by Tremmel Hudson, and forked by Yona Appletree. This contains all the softare, from PRU firmware up to an OPC implementation. This also includes some of the same firmware tweaks that Fadecandy has.

As with the Fadecandy system, there is huge amount of flexibility in terms of what technology the client can use. In fact, LEDscape and Fadecandy could share client code without any modification.

This system has a slightly higher cost of entry, with output capes costing from $35 upwards, in addition to the cost of a BBB ($55). However, it’s becomes competitive with Fadecandy above a scale of approximately 1500 LEDs.

On a tangent: Open Pixel Control and Processing

This pair of technology is widely used for LED control.

Many large LED projects are written in Processing, a Java based language geared at creative coding. It provides easy access to graphics and input handling, but loses some of Java’s more robust testing/compiling tools.

Open Pixel Control (OPC) protocol is used by various projects as the interface between core program and the LED stack. It’s very easy to implement, and Micah Scott’s Processing client implementation, and her example projects are widely used.

PixelPusher

This is the last of the trio of LED systems this article will discuss. Shockingly, it’s also developed for Burning Man projects, by Christopher Schardt. It differs from LEDscape and Fadecandy by being both a bit more flexible, but also closed source and commercial.

• PixelPusher (v3) controller, is the hardware component. It’s a custom ARM board that can control most types of LEDs, including all four types covered in Part 1 of the article. Each unit can control 8 strands of LEDs, and connects to a network via a RJ45 socket.
• The PixelPusher protocol, which allows for easier configuration of multiple PixelPushers as part of the same installation. The vendor also provides tools to bridge control across to DMX, the dominant system for professional theater and stage lighting. The vendor provides a Processing library for client code.
• If you don’t want to write a client program, there is L.E.D. Lab, an iPad App that acts as a default client for the system. The app includes a selection of built-in effects.

The cost of entry for the system is similar to that of LEDscape, with each PixelPusher unit costing $120. But, at 5000+ LEDs scale, LEDscape may be cheaper.

Originally posted on Medium

So, you want to play with addressable LEDs! Whether it’s for home decor, wearables, a hula hoop, making a video wall or winning Burning Man, they are great fun. However, once you know what you want to do with them, you need to decide what hardware and software to do it with. As often is the case, there’s no right and wrong choices, but there are better and worse choices. This can be quite daunting, so when the loud man at your maker meetup insists that “You should totally use a PixelPusher to drive some 2801s, but roll your own app in Processing”, like they did for their project, is it right for you? What is a PixelPusher? Is it larger than a duck? Can you git clone it? Is the man actually an Oracle salesperson who arrived at the wrong venue, is trying to sell you an enterprise license to something?

With this guide, I aim to provide a survey of significant technology choices, and a view of why people would prefer one over the other for their application. It assumes that you’ve gotten some LEDs to light up with an Arduino, or read through a guide for a project that you like. However, you’d like some help in joining the dots, and helping you decide on what hardware and software to bring together for your next LED project. It aims to provide breadth in the form of comparisons of techs, rather than depth of actual how-tos: those are already done much better than I can hope to achieve elsewhere. Furthermore, I’ll aim to cover the more popular options, because I believe that they are often better by the virtue of having more community discussion and support. If what you need is more niche, I hope this guide will help you answering the question of “Why won’t X work for you?”, which should help you find your right specialised solution.

I would suggest that you use this article as follows:

1. Find a project guide on what you’d like to do. As with many things maker, Adafruit does an excellent job of producing and curating a wide selection. Instructables has an even wider range of projects to look at.
2. If the guide helps you to achieve what you want, great! This article will be simply too much information.
3. If what you’d like to achieve is different from the guides you are using as references, or you want to figure out if there are simpler, better, or just different ways to do that, use this article to understand why the authors might have chosen what they did, what else they could have chosen, how their requirement may differ from yours, and therefore, what might be some good avenues of exploration for you.

The article is compromised of two parts. The first (this part) covers most small/medium sized projects you’d want to undertake. This will cover the different types of LEDs, the electronics you’ll need to control them, libraries to help you program them, and a bit on how to power them.

The second will cover the extra technology pieces involved in more complex, less commonly seen projects, that require extra layers of abstraction (see: winning Burning Man). This would include dedicated hardware, network protocols and libraries for wider range of languages.

The LEDs

There are many types of addressable LEDs out there, but I’ll focus on four:

• WS2812: mostly seen in its WS2812b form, but also marketed as NeoPixels by Adafruit. These have become the de-facto standard for addressable RGB LEDs, used from wearables all the way up to giant installations. They are cheap, bright, compact and only require three wires. These factors have combined to make them wildly popular. The WS2812 contains a chip called WS2811, so you can see these used somewhat interchangeably.
• APA102: mostly seen in its APA102c form, marketed as DotStars by Adafruit. These are the new kid on the block. They are as compact as WS2812s, will have less flicker, works with Pis directly. However, they are more expensive and require four wires.
• WS2801 and LPD8806: think of these are precursors to the APA102s: four wires, relatively easy to control, but because the chips are separate from the LEDs, they are more bulky.

Which one? The default option is the WS2812s, if only because they are so widely available, cheap, and require 25% less soldering. If you have to mounting on them on something that moves fast and generate light trails (OMG LED Hula Hoops), have a look at the APA102s. The APA102s are also good if you need to control them directly into a Raspberry Pi. Use the older WS2801s or LPD8806s only if they are cheaper, more available, or come in a specific packaging you need.

On three v.s. four wires: the WS2812’s most distinct feature is that it requires only three wires. This means less cabling, less soldering and smaller connectors. As a consequence of this design choice, though, it need to be controlled by a very precisely timed signal, otherwise it will glitch/flicker more, or just not work outright. Something like a Raspberry Pi will be too busy running Linux (or similar) to be able to guarantee the precision required. Typically, we’ll use an Arduino-like board to do the job.

Microcontroller and Libraries

For most applications, you will want to control the LEDs using just your microcontroller of choice. This could be an Arduino (or equivalent), Teensy or even an ESP8266. There just a few things to note:

• It often takes more memory/faster processor to control more LEDs. However, you are unlikely to hit any limit until you have 500+ LEDs. The exception is the smallest boards, such as the Arduino Gemma, which only has 512 bytes of RAM, in comparison to 2kb in an Arduino Uno, or 64kb in a Teensy 3.2. These boards can only handle around 100 LEDs.
• Different boards send signals out at various voltages, whereas almost all LEDs are designed to receive signal at 5V. Therefore, something called a level shifter might be required for 3.3V (or lower) boards.

The task of converting the C code you write to actual signals sent to the LEDs along IO pins is typically done by a library. Unless you have a very good reason to, don’t try to do this yourself — this is a very general, but also solved, problem. You should probably be using one of these:

• Adafruit’s libraries: Adafruit provides libraries for NeoPixels (WS2812), DotStar (APA102), LDP8806 and WS2801. They are used extensively in most of Adafruit’s excellent LED project tutorials, including the extensive NeoPixel Uberguide.
• FastLED: this is a more sophisticated library. It supports most LEDs and boards you can think of, and is maintained and supported by its own strong community.

Which one? Adafruit’s library is relatively basic, allowing you to specify colours via RGB values. It’s an excellent entry point, especially if you are following Adafruit’s tutorials. It also glues into their Matrix and Graphics libraries, for basic animation work. However, if you find yourself writing or using a lot of framework code (e.g. animation, different ways to specify colour) to layer over the library, then it’s probably worth pausing and looking at what FastLED has to offer. This library has a slightly steeper learning curve, but provides a lot more built in functions, including HSV/RGB colour management, animation timing, and Perlin noise.

There are other libraries, such as OctoWS2811 and light_ws2811. However, they target more fringe use cases. I’d suggest that you explore them only once you’ve ran into a limitation of the more popular libraries.

Raspberry Pi

When controlling the four-wire LEDs from a Raspberry Pi directly, there is still some work involved in turning higher level code to control signals. Some libraries that do this for the APA102 include:

• Adafruit’s DotStar Pi: a Python module
• APA102_Pi: another Python(3) module

There are others libraries, of course, including ones for older LEDs. But as we are typically working with higher level languages on a Pi, with it’s megabytes of RAM, one would look at more general libraries for colour/graphic capabilities. The LED controller library has a smaller role to play.

Powering LEDs

The power requirement of having many LEDs add up very quickly. 10 WS2812s can draw up to 600mA, and a 5m strip of 60/m LEDs can draw up to 18A. Calculating your power requirement, and meeting that is a broader, electrical topic that goes beyond the scope of this article. However, a few popular approaches include:

• Most microcontroller boards will have a 5V or 3.3V pin that can supply at least 500mA. using this pin will typically provide the neatest solution in terms of wiring. If you limit LED brightness, this solution can carry you surprisingly far, but do the maths.

• Direct battery power: a single cell Li-ion cell supplies between 3.3–4.2V, depending on chemistry and state of charge. This is often used for compact, wearable projects. Alternatively, AA or AAA batteries are also used. 3 Alkaline (non-rechargeable) or 4 lower voltage NiMH cells provide suitable voltage.
• Conveniently, USB is designed around 5V, and many solutions make use of that. A USB powerbank will often supply 1–2A at 5V, with the added benefit of safety cutoffs. Most cellphone chargers can also be used to supply 1–2A at 5V. Larger projects will use AC/DC adapters to supply power from mains at 5V, or buck converters to provide 5V from a large (typically higher voltage) batteries.

Next: Part 2 will cover more complex projects. These are typically bigger, both physically and in terms of number of LEDs. They also tend to have more complex control mechanisms, typically spanning a computer network.