Once new and more ergonomic handles were installed on my LED helix project, it’s time to pause on hardware advancements and switch gears back to software. Let’s see what we can build with what we have on hand before going much further with CAD and 3D printing side of things.

By this point I’ve selected one idea to implement, out of my list of candidate Pixelblaze projects: I want to implement a Pixelblaze pattern that gives the illusion my LED helix is a container holding brightly glowing liquid that moves around inside as it is moved. The accelerometer will provide input for physical motion, and Pixelblaze pattern code will adjust LED colors to present the intended illusion.

And to accomplish this, we’re going to have to do some math. Liquid sloshes about inside a container in response to sideways movement, and this is the acceleration vector of gravity downwards plus vector of however we’re moving the container around.

Rephrase another way: When a container of liquid is standing still on a flat surface, the downward direction of the container is lined up with downward direction of gravity. But when we start pushing the container around the surface, the downward direction of the container doesn’t change but the downward direction of acceleration does: the direction is now gravity plus motion pushing it across the surface.

Our LED helix 3D pixel map declares downward direction of the container as its Z axis, and the accelerometer reports downward direction of gravity plus motion. The difference moves the liquid, and this difference can be expressed in spherical coordinates, translated from cartesian accelerometer data with standard formulae. Once the two angles of spherical coordinates have been calculated, they can be used in 3D transforms for each LED’s pixel mapper coordinates.

The result is to translate a LED pixel position based on spherical coordinate of accelerometer tilt, so we can color in a LED depending as a function of the “down” reported by accelerometer. And once the colorfully glowing LEDs start emulating liquid flowing inside a container, we have our project name: the Glow Flow.

Pixelblaze pattern code for this project is available on Github.

 

Once I figured out the accelerometer directions for a Pixelblaze Sensor Expansion Board, I realized an earlier oversight was going to cause problems.

The first draft of LED helix top end were designed with the following goals:

1. Have an opening for top end of LED strip to enter interior
2. Give me something to hold on to.
3. Physically mount the Pixelblaze somewhere.

Goal #1 was simple to meet. I put in two arched bits of plastic for #2, and there wasn’t a whole lot of thought put into #3. The only goal at the time was to make sure the Pixelblaze doesn’t rattle around and get damaged.

Now that I want to play with the accelerometer and tie it in to my LED strip with 3D Pixel Mapper coordinates in 3D space, I realized my mistake: the Pixelblaze sensor is offset at an angle to the LED. In the image above, the red line represents X axis, the green the Y axis, and yellow is the Pixelblaze at approximately 15 degrees offset from the Y axis. This meant my initial test programs looked odd because the lights were reacting to a force vector 15 degrees offset from where they physically were.

While I could address this strictly in software by changing my 3D pixel map coordinates to match my Pixelblaze axis directions, moving the helix around also exposed more problems with the first draft that I could not solve with just software changes. First, the USB power bank started falling out of place as I had only designed a shallow stand. And second, the thin strips of plastic wasn’t a very good handle for moving the thing around.

So a new top end was designed and printed to satisfy slightly different goals:

1. Still have the opening for the top end of LED strip.
2. Give me something to hold on to.
3. Physically mount the Pixelblaze in a way that aligns accelerometer axis with 3D Pixel Mapper axis.
4. Hold the USB battery power pack in place.

This top piece no longer has to provide handles, instead I’ll add a dedicated and more ergonomic handle (or two) to this project.

To me, the most interesting peripheral on the Pixelblaze Sensor Expansion Board was its accelerometer module. Its microphone seems to be a decently well-explored space, with multiple examples available on the pattern database, and I haven’t figured out how I would use the light sensor creatively. But there weren’t as many examples of using the accelerometer and I have a few potential ideas there.

The first task of playing with an accelerometer is to determine direction. From Pixelblaze documentation I know it will populate an array accelerometer of three elements for acceleration in X, Y, and Z axis. But which direction do each of these point?

Pixelblaze IDE makes exploration easy. Variables that are export-ed (like the variables to hold sensor values) can be watched live. This simple test program is enough to get started:

export var accelerometer = array(3)

export function render() {
}

Once entered, look for the “Vars Watch” window on the right hand side and a green “Enable” button.

Once enabled, Pixelblaze will display values of all exported variables and update them as the pattern is running.

Gravity is a constant acceleration towards the center of the earth, so we could tilt the Pixelblaze around and see which orientation shows the maximum positive number. The downward direction will be aligned with the axis showing the largest number while the other two are nearly zero. Once determined, jot them down in a notebook:

To double-check this answer, I went to look up the datasheet for the accelerometer chip itself. Looking on my expansion board, I saw the top was labeled with “*2815 C3H BCSHN” and a web search was inconclusive. Looking into Pixelblaze sensor expansion source code, I found comments marking code to talk with a LIS3DH accelerometer whose data sheet had the following diagram:

All three axis line up as my notes indicated, but their arrows point in opposite direction from mine. Perhaps there’s a convention I’m violating and the arrow actually points opposite of acceleration? This would allow the convenience of a Z pointing up when sitting flat where gravity is accelerating downwards.

Either way, this is enough information to continue. My earlier RGB-XYZ 3D Octants sample program was rewritten to add an accelerometer component. This way the colored blocks move around in response to physical movements of the LED helix. But the visual motion was not intuitive to a human, because my LED pixel mapper matrix does not align with my accelerometer axis. One way to solve that problem is with a new top end piece for my LED helix.

The success of a static test pattern in 3D space is encouraging, but it’s still in the realm of something fairly easy to replicate with a simple microcontroller. We have barely tapped into the power of a Pixelblaze controller. Using the pixel mapper is fun, but it’s the animation engine that makes a Pixelblaze exciting.

Resisting an urge to go wild, this next step is only a small incremental step from the static pattern. Again it is a test of all three coordinate axis, and again I will map RGB to XYZ in that order. The difference this time is that each axis and their positive direction will be shown with an animation, and since I’m starting to play in the time domain, each axis will get their own time to shine with an animated band of illuminated pixels.

The band needs to be wide enough to span several pixels, for a smooth handoff between one to the next. If the band covers less than two pixels, it would look more like a collection of blinking LEDs which might be cool but the objective is to convey motion.

Since the coordinate space is passed into render3D(index,x,y,z) in the range of 0 to 1, the naive first approach is to animate from 0 to 1. This turned out to look strange, because the animated band would pop into existance across several LEDs, reach the opposite end, and blink out abruptly. The solution to this problem is to increase the range of sweep so that our band (mathematically) starts off the display space before entering the stage, and exits the stage gracefully out the other end.

But that alone didn’t give us a pleasing sweep. I realized the band is too harsh so an additional blend was required: instead of LEDs turning on and off, there will be a ramp-up and a ramp-down for a smoother edge to the band. This looks better but might get in the way of diagnosing pixel alignment issues, so I left both as option in the code that can be switched back and forth with the style variable.

Code for this pattern is avilable on Github and also shared on public Pixelblaze pattern database as “RGB-XYZ 3D Sweep”

What’s next? Maybe add some interactivity by introducing some sensors into the mix.

Pixelblaze documentation offers a simple pattern for testing that my 3D pixel map volume is indeed doing something in three-dimensional space: a simple call piped coordinates (x,y,z) directly into the HSV (hue, saturation, and value) for a LED color. This turns my LED helix into a cylindrical sample of the HSV color space. With this, I could look for color or brightness variations from one side of the cylinder to the other. A non-repeating variation across a single loop tells me X and Y axis are doing something, and a gradient from top to bottom tells me the Z axis is doing something.

The next step is to go from verifying it does something to verifying the X, Y, and Z axis are indeed pointing in the intended directions. And to do that, I wanted something that visually distinguishes each of the three axis and shows the positive direction for each axis. To meet this requirement, I implemented a Pixelblaze pattern to display my 3D pixel map volume cut up into eight octants.

Each axis will be assigned a color. To keep the axis color assignments easy to remember, They’ll be mapped in the order they’re typically named. Color components are usually listed in RGB order, and coordinates listed in XYZ order. Keeping the same order in both means red is X, green is Y, and blue is Z.

Along each axis, the positive direction half of the pixels will receive the assigned color. Pixelblaze render3D() coordinate parameters are given in the range from 0.0 to 1.0, so pixels with a coordinate from 0.5 to 1.0 will receive the color assigned to that axis.

Examples:

• (0,0,0) lies in the negative direction of every axis, so it doesn’t receive any color and will be black.
• (1,1,1) lies in the positive half of every axis, so it receives R, G, and B turning white.
• (0.75, 0.15, 0.35) lies in the upper half of X, but lower half of Y and Z. So this pixel is assigned red.

This render3D() pattern displayed on a 3D pixel mapped display will visually indicate alignment and direction of X by all the pixels with a red component, alignment and direction of Y with green, and Z with blue.

Code for this test pattern is available on Github, and also shared on the public Pixelblaze pattern database as “RGB-XYZ 3D Octants”.

It is a functional test pattern, but not very visually dynamic. Pixelblaze is all about animated LED patterns, so the next step is to make an animated variant of this test pattern.

Completing first draft of a LED helix mechanical chassis means everything is in place to dig into Pixelblaze and start playing with the software end of things. There are a selection of built-in patterns on the default firmware, and they were used to verify all the electrical bits are connected correctly.

But I thought the Pixel Mapper would be the fun part, so I dove in to details on how to enter a map to represent my helical LED strip. There are two options: enter an explicit array of XYZ coordinates, or write a piece of JavaScript that generates the array programmatically. The former is useful for arrangements of LEDs that are irregularly spaced, building a shape in 3D space. But since a helix is a straightforward mathematical concept (part of why I chose it) a short bit of JavaScript should work.

There are two examples of JavaScript generating 3D maps, both represented cubes. There was a program to generate a 2D map representing a ring. My script to generate a helical map started with the “Ring” example with following modifications:

• Ring example involved a single revolution. My helix has 30 LEDs per revolution around the cylinder, making 10 loops on this 300 LED strip. So I multiplied the pixel angular step by ten.
• I’ve installed the strip starting from the top of the cylinder and winds downwards, so Z axis is decremented as we go. Hence the Z axis math is reversed from that for the cube examples.

We end with the pixel map script as follows.

function (pixelCount) {
  var map = [];
  for (i = 0; i < pixelCount; i++) {
    c = -i * 10 / pixelCount * Math.PI * 2
    map.push([Math.cos(c), Math.sin(c), 1-(i/pixelCount)])
  }
  return map
}

Tip: remember to hit “Save” before leaving the map editor! Once saved, we could run the basic render3D() pattern from Pixel Mapper documentation.

export function render3D(index, x, y) {
  hsv(x, y, z)
}

And once we see a volume in HSV color space drawn by this basic program, the next step is writing my own test program to verify coordinate axis.