Basic Display Tutorial

There’s basically no way to make a Blinks game without lighting up the lights. So let’s learn about the display system of Blinks!

Here’s how we’ll start. Make a script, then put this code in setup():

void setup() {
  // put your setup code here, to run once:
  setColorOnFace(WHITE, 0);

Install that on a Blink and you’ll see that all the lights except one turn blue, and one turns white. There are basically 2 important things happening here, and we’re going to break them down in turn.

1. setColor and setColorOnFace

These two commands are the only way to create displays. They both require you to input a color (more on that later) and, in the case of setColorOnFace, a face. As you might guess, setColor displays a color on the entire Blink, and the other only on a single face. By calling them in the order we did, we set all 6 faces to blue, then overwrote face 0 to white. This is a method we often use in Blinks development - using setColor as a base then setColorOnFace to augment it.

Something that is very important to understand about setting color is that once a color is set on a face, it will remain that color until another command is called. This means, for instance, that if you want a Blink to be red for a while, you don’t have to call it every frame. Instead, you can just call it once, and as long as you don’t later overwrite it, it will stay that way. This is good to remember when you’re making more complicated graphics: any face you don’t send a color command to on a given frame will remain the color it was previously.

2. Colors

Because these commands require you to input a color, it’s probably important to understand how color works on Blinks. There are 3 ways to produce a color, and we’ll go over them briefly here before we actually use them later.

The first is the way we’ve done it in the code above: by using what we call “system rainbow.” These are 9 pre-defined, named colors. They are:

  • RED
  • CYAN
  • BLUE
  • OFF

Yes, OFF means exactly what you think: no light at all. Go ahead and change out the colors in the code we’ve written with any of these to see the full system rainbow for yourself.

But this is not the only way to summon colors, and in reality, is probably not the way you’ll do it in your own games. After all, why would you want to use our colors when you could make your own? To do this, you’ll need to use one of the two color methods: makeColorRGB() and makeColorHSB(). We don’t really have time to explain the RGB and HSB concepts in this tutorial, but here are two links explaining them, I think, pretty well.

Let’s add these methods to our code. And while we’re at it, I’m going to use a fun little trick that I think is good for making your own colors - we’re going to define a custom color at the top of the script. Initially we’ll using the RGB method.

#define LIME makeColorRGB( 75, 255, 0)

By using #define, we can create and name a color that can be called just like system rainbow. Technically speaking, this is identical to system rainbow, except the definitions live in the codebase, not your specific script. But you don’t have to use a define - you can also just use the makeColor commands directly inside of setColor or setColorOnFace. Either way, the way makeColorRGB works is that it lets you set the values of ( R)ed, (G)reen, and (B)lue in your color. It actually does this quite literally because it just changes how brightly the R, G, or B component of the LED light shines. Levels range from 0 (off) to 255 (full blast). Let’s replace our use of BLUE with our new LIME in the code and try it out.

If you’ve done that, you might notice that… it looks pretty green. I certainly wouldn’t call it lime. Seems like it needs more… yellow? We don’t have a yellow light, but we know from the RGB model that yellow is a made by combining green and red. So I’m just going to crank the red value (the first in the method) from 75 to, say, 150. If you install that, you’ll see a much “limier” green appear on your Blink. Any color can be achieved by futzing around with these values, so I definitely recommend you spend some time doing that, getting a sense of how to tune your colors to your liking.

Now let’s make another color, this time with HSB. As you might have read in the link, H stands for Hue, S for Saturation, and B for Brightness. This is closer to the standard “color picker” that you might be used to, where the rainbow is displayed across the top, then fades to white at the bottom as the saturation dips. Anyway, here’s a new color we’re going to make:

#define LILAC makeColorHSB (200, 120, 255)

If you use that in the setColor command, you should get a nice light purple. As before, I encourage you to mess with these variables, especially saturation. All three values range from 0 to 255, just like in makeColorRGB. It’s worth mentioning that we use this method, and only this method, to create the colors in most of the launch titles, because setting saturation and brightness to 0 are convenient ways to create white flashes and dimming effects respectively.

Speaking of which, there’s one last thing we can do to colors, and that’s “dim” them. This is a method that is applied to colors themselves, not the Blink. Let’s say we wanted to dim the lights in our existing code, we’d add this to the script:

setColor(dim(LIME, 150));

Now when you turn it on, the lights are much less bright, but maintain the colors themselves. And like all the other methods, 255 is full brightness and 0 is off. But I imagine you had guessed that already.

And that’s actually it for the display code. I realize we didn’t really get into any practical cases, but since displays are so important, essentially very other tutorial will give you a chance to practice using these commands. Stay tuned for those!

EDIT - There are some technical details I didn’t mention on this tutorial that are actually pretty important. Take a look at the comment by bigjosh below this for that information!


Great article! I might also add these minor details…

  1. the setColor() and setColorOnFace() commands do not actually update the color on the LEDs until loop() returns.
  2. Even though you can set the brightness to any number between 0 and 255, there are only 32 actual visibly different rightness levels, so makeColorRGB( 1, 0, 0) and makeColorRGB( 2, 0, 0) look identical while makeColorRGB( 8, 0, 0) will be slightly brighter.
1 Like

I was exploring HSB/HSV on Wikipedia and on a color picker website since I was unfamiliar with it. The hue parameter should be from 0-360 (degrees of a circle) and the saturation and brightness/value parameters should be 0-100 (percentage). While I can assume the reason is to limit the parameters to a byte, I’m curious what’s happening behind the scenes. Should we basically map 0-360 and 0-100 to 0-255 and expect that they will be treated as such? Thanks, and sorry for bumping an old topic!

1 Like

Yes, that’s right. HSB are all 0-255 so when you use color picker helpers you need to translate them as such. The blinks library code has the makeColorHSB function where you can check out the code, if curious.

1 Like

No worries about bumping an old topic, this is a great question! As ScarPixel said, it all needs to be translated: hue 360 on a color picker is hue 255 on Blinks, and the rest scale from those points. I generally just find myself using a calculator to quickly do the math, but in most cases you’ll need to fine-tune on the Blinks themselves. Some colors don’t translate super well if you just translate the values - you often need to futz with them before you get the desired result.

Hope this helps!