Welcome to this series of tutorial lessons on the Pixelblaze. Feedback is always welcomed, especially if something isn’t clear. Eventually, these lessons will be folded into a book.
Lesson #1 - The Little Engine that could
In order to understand how to program a Pixelblaze, you need to understand how it works, how to talk to it, and what it can do. The first step, even before we begin covering the language or the interface you’ll use to program it, is that we need to start with the guts of it.
Learning to ride a bike, you can learn to ride without understand the physics of a bicycle (though that can help), but you must learn that the pedals connect to the wheels, and that getting the wheels spinning at the right speed matters for your balance, and also how the handle bars control the direction, right?
In the same way, understanding how the Pixelblaze decides what to do and how to do it is critical to eventually making it as easy as riding a bike, or whatever activity you associate with making fun stuff happen, in this case, lighting up LEDs.
I like to use an engine analogy, because in large part, just like with a physical engine, if things aren’t working right, debugging the problem is usually about looking at the essentials.
For a physical engine, the essential things to consider: Fuel, Air, Spark, Compression and Timing
No, there will no test on car repair, and you don’t need to worry about us getting too far off track. The video above is mostly as a example: that car was sitting for years, ‘not working’, and if you watch the video, it turns out the fix was actually just one part that wasn’t tight enough, but the owner of the car didn’t know how to fix it, so he gave the car away to someone who did. Here on this forum, we see many folks who purchase a PB, and then confronted with the daunting task of ‘programming’ it, give up because they don’t understand the fundamentals. We’re going to teach the fundamentals of PB, so your LEDs will ‘crank right up’
What’s required for the Pixelblaze engine? It’s a little simpler than a car engine, thankfully. I usually compare it to a 2 stroke engine:
You don’t actually need to understand how that engine works, but you do need to see that it has 2 parts to its’ cycle: One loads the fuel into the combustion chamber, then the other sparks the fuel, which burns the fuel, causing the piston to move back down, starting the cycle over again… This keeps the cylinder moving up and down, up and down. 2 stroke engines are often used in small engines, like lawnmowers, blowers, and so on.
While we don’t have any fuel for our LEDS, we do have electric, and we do have timing. Let’s see what our two cycle engine looks like here:
We begin with a Pixelblaze, hooked up to proper voltage (5v), with enough power (amps) to driving the LEDs hooked up to it. In our example, let’s assume we have a simple strip of 30 ws2812 LEDs attached to it, and the power supply is big enough to drive those (and the PB) without any issue. 30 leds is small enough that we have no concerns about powering your LEDs separately from the PB, and so powering them thru the PB makes sense in this case.
In the settings, we’ve told the PB, what kind of LEDs we have hooked up, ws2812, and how many we have hooked up, in this case, 30. PB remembers that number, and saves it into a variable (we’ll return to what variables are later), the variable is labeled/named pixelCount, and in this case is equal to 30. Unless you change the settings, the PB will think you have 30 LEDs hooked up. Even if you add more, or change the LEDs out for some other string of 200… it will ONLY deal with the 30 it knows about from the settings where you told it that. There are other settings, which we’ll address in future lessons.
The PB engine when turned on, goes looking for part 1 of its’ 2 part cycle. This is equivalent to the fuel collecting in the combustion chamber in the 2 stroke engine. In this part, we figure out if there is anything we need to calculate that might affect ALL pixels. It’s not considering each pixel separately. It’s entirely possible that there is NOTHING we need to do. This also is where we might have to handle timing issues. (Again, we’ll come back to that) But for now, let’s keep it ultra simple. Let’s say we have nothing to figure out.
export function beforeRender(){
}
In fact, we could even avoid having this code, since it’s not doing anything, but since it’s always the piece of code the PB looks for in step 1, even if it doesn’t exist, so teaching you it now makes more sense than teaching you about a 2 stroke engine and then only having 1 step. So think of this as a placeholder for now. You’ll be using the beforeRender() step quite a lot.
So let’s move on to step 2. In this step, PB attempts to loop thru all of the pixel LEDs it knows about (in this case, 30). It considers each pixel, one at a time, from first to last. How does it do this?
It goes looking for the render() function. As we’ll learn later, there are actually a few of these functions it might want to consider, but the main one is just the plain render(), and it’s called in a simple loop thru each pixels, starting at the first pixel, and then the 2nd, and so on, till we get to the last pixel. Think of this as the equivalent of the fuel burning and expanding the piston: The engine says “Time to go! Pixel 1? Pixel 2?.. Pixel 30!” and then it sends all of those pixels the info they need to light up (or not), in one burst.
stripped down to the minimal example, this looks like this:
export function render(pixelnumber){
// we'll do something here, eventually.
}
Usually, where it says pixelnumber is labeled as index. But that first pixel, that’s not the number 1, it’s start with the number 0. So if you think about this… if we start with zero for the first pixel, and count upwards, when we get to the last pixel we have, aka 30, what number will we be at? That’s right, 29.
So first lesson: Your pixelCount is always ONE higher than the actual value the PB engine looks at. So we need to remember this: index starts at 0, and ends at pixelCount-1 if/when you see ‘index’, think of this as 'the pixel number we’re looking at, as we loop".
So in the above code, we did NOTHING. Nothing in Part 1 aka beforeRender(), and Nothing in Part 2, aka render()
So what would the PB do? If you said Nothing, you’d be correct. It will just cycle back and first… Part 1, Part 2, Part 1, Part 2, Part 1, Part 2, onward and forever, doing… Nothing. Pretty useless.
But it’s running. It runs step 1, step 2, step 1, step 2, lighting up… nothing.
We’ll return more to this 2 stroke engine idea later, when we discuss more complex issues like timing, or heavy code, or even why certain approach to coding LEDs on the PB aren’t really easy to do, compared to other methods. But for now, if you think of the PB engine as “prep for a frame, loop thru all pixels, prep, loop, prep, loop…”, you’ll be in good shape.
export function beforeRender(){
}
export function render(pixelnumber){
// we'll do something here eventually, but this is just a comment for now
}
So let’s add something for it to do? We’re going to spend all of the rest of these lessons, teaching you how to add code to this most simple of programs, making it actually do things. (We’ll also explain why we needed to have ‘export function’ there, and how to add code comments, both of which snuck into our example)
Before we do, we need more critical background, on both the expectations of the PB and its’ language, as well as how LEDs work.
Let’s not end here. We’ll add a teaser:
rgb(red, green, blue) is the command to light up a pixel with a mix of red, green and blue light. Each of those values needs to be between 0 (none) and 1 (100%)
Consider this a hint towards the next lesson.
So what if we add this command into our example?
export function beforeRender(){
}
export function render(pixelnumber){
rgb(1,0,0)
}
What’s going to happen here?
Step 1: nothing
Step 2:
pixel 0: light it up with 100% red, 0% green, 0% blue
pixel 1: light it up with 100% red, 0% green, 0% blue
pixel 2: light it up with 100% red, 0% green, 0% blue
pixel 3: light it up with 100% red, 0% green, 0% blue
pixel 4: light it up with 100% red, 0% green, 0% blue
… etc all the way to pixel 29…
pixel 29: light it up with 100% red, 0% green, 0% blue
then we repeat:
Step 1: Nothing
Step 2:
pixel 0: light it up with 100% red, 0% green, 0% blue
pixel 1: light it up with 100% red, 0% green, 0% blue
pixel 2: light it up with 100% red, 0% green, 0% blue
pixel 3: light it up with 100% red, 0% green, 0% blue
pixel 4: light it up with 100% red, 0% green, 0% blue
… etc all the way to pixel 29…
pixel 29: light it up with 100% red, 0% green, 0% blue
Exercise(s) for this lesson:
- Make the LEDs light up in Green, instead of Red
- Make the LEDs light up in Blue.
- Make the LEDs light up in White.
- Make the LEDs light up in Yellow.
- Make the LEDs light up in Purple.
