Some Links first
- A video I sent to the Somnolians
- The Reference I used(yes i'm doing this in c++)
- the compiler I used
My first project on the microbit
After a few test programs to learn a little on how the microbit works, I decided to make a program to show a short message and then scroll a rendition of the bulb across the display.
Simple in concept and simple in practice, the perfect first project. The first thing I did was read the documentation. I know... boring, but I needed a plan of attack and I find that easier to think of when you're being spoonfed possible approaches. And the documentation is okay for that. Anyway, specs. The microbit has a 5x5 LED display, 16Kb of RAM, and no soul. So we need a rendition of the somnolescent bulb. So I made this.
Yes it's that small, it's 5x7, The microbit still can't open it though. So I had to convert it to the correct format, and figure out a way to store it in the script. In the reference(see linklist above) under MicroBitImage it shows a constructor that takes raw image data and converts it into the right datatype. So I can input the bitmap as a byte/char array and do some type casting magic directly, as they show in the reference.
static const char bulb_raw[] __attribute__((aligned(4))) = {0xff,0xff,0x05,0x00,0x08,0x00,
0x00,0x00,0x00,0x00,0x00,
0x00,0xff,0xff,0xff,0x00,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0xff,0xff,
0x00,0xff,0xff,0xff,0x00,
0x00,0xff,0xff,0xff,0x00};
MicroBitImage bulb((ImageData*)(void*)bulb_raw);
Not the most readable, but still readable. I added an empty row to the top of the image for making scrolling easier. The first line of hex (the one that's 6 items long) is the header, and I love how simple it is. it's 6 bytes, or 3 shorts with little endian encoding. The header starts with two full bytes, which makes finding the start nice and easy. The next 4 bytes are actually two shorts. the first one is the width (0x05 0x00 in little endian is 0x0005), the second one is the height. so from the header we can tell it's 5 wide and 8 tall. the next 40 bytes are brightness values for each pixel. The microbit supports(acording to the reference) 256 different brightness levels, including off. My vision isn't good enough to see every brightness levels, but I can pick out three distinct levels. The bulb graphic is monochrome, not dichrome, so I didn't bother with brightness.
Now a quick step-aside. The microbit has a resolution of 5x5, not 5x8, but we can display a 5x5 chunk a graphic. The plan is to scroll the bulb from top to bottom, and for this we can use the MicroBitImage.paste(const MicroBitImage& image, int16_t x, int16_t y) to paste the graphic onto the display at an offset. A quick note, the offset is the top left corner of the MicroBitImage being pasted. Due to what we're doing, it's easier to think of it as scanning a camera over a graphic, which makes the offset different. The MicroBitImage.paste(const MicroBitImage& image, int16_t x, int16_t y)'s offset acts in relation to the MicroBitImage being pasted on, not in relation to the one being pasted. So we need to change how we think of the numbers we're putting into it. Luckily the conversion is simple, We offset the pasted relative to how we want it to be displayed. So if we want it to displayed with a camera coordinate of (0,1) we preform the opposite to the MicroBitImage we're pasting so we will use the coordinate (0,-1)1. So to go from top to bottom, we need to offset y from negative to positive.
the scrolling text is pretty simple. MicroBitDisplay.scroll command will suffice. So, anyway what does the code look like
#include "MicroBit.h"
static const char bulb_raw[] __attribute__((aligned(4))) = {0xff,0xff,0x05,0x00,0x08,0x00,
0x00,0x00,0x00,0x00,0x00,
0x00,0xff,0xff,0xff,0x00,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0x00,0xff,
0xff,0xff,0x00,0xff,0xff,
0x00,0xff,0xff,0xff,0x00,
0x00,0xff,0xff,0xff,0x00};
MicroBitImage bulb((ImageData*)(void*)bulb_raw);
MicroBit mBit;
int main()
{
mBit.init();
mBit.display.scroll("Hello Somnolescent");
for (int i = -4; i <= 4; i++)
{
mBit.display.image.paste(bulb,0,i);
mBit.sleep(333);
}
mBit.display.image.clear();
}
It's nothing advanced, it's readable, there's some stuff with pointers, it has many semicolons, and a single hashtag. Now with the whole program just here, it does make me feel exposed. But let's get to explaining. The line #include "MicroBit.h" is just to tell the compiler that we're using code from the header file "MicroBit.h", it allows us to use the microbit stuff. The next line we'll look at is MicroBit mBit;, which is just saying that the global variable mBit is an instance of / reference to the microbit, the hardware this code will be running on.
When c++ is compile, the compiler will look for an entry point, where the code should start running. By default it's a function called main. So int main() is just us telling the compiler where we want the program to start, after finishing it's set up (generating the image). The next two lines just tell the microbit to get everything ready. We could've just told it to ready the the display, but where's the fun in that. We then tell it to scroll the text "Hello Somnolescent" across the display. The command is what we call "blocking", our program stops until the whole string has been scrolled, this is useful for our timing, but you can run it without blocking, if needs be. Jumping to the end, mBit.display.image.clear() tells the microbit to clear all imagedata from the display.
Now the fiddly diddle. My favourite part of c++, the for loop. If I hated you, I could've written it as for (int i = -1; i <= -4; mBit.display.image.paste(buld,0,i++) ) mBit.sleep(333);. But I'm nice, and that wasn't my first attempt at scrolling the bulb top to bottom. Anyway, This loops the code in the pointy brackets( { } ) with the variable i equal to -4, to 4. And in the loop it pastes the bulb graphic offset down by i and then tells the microbit to wait a third of a second. As simple as that.
Elaborations/Explanations
- AB = B - A => BA = A - B