Hackaday Badge Keyboard

The most visible physical feature of the Hackaday Belgrade 2018 badge, taking up most of the space on its circuit board, is an array of tiny little tactile clicky buttons making up a QWERTY keyboard. This is where badge hackers can type in BASIC programs and run them for an easy entry into this badge’s retrocomputing theme.

I’m no electronics expert, but I’ve seen enough circuit boards to recognize the convention for components to be lined up nicely in a grid. The keyboard buttons didn’t follow this pattern and sat at a slight angle. I had thought this was done just for aesthetics, standing apart from convention, but I was wrong. There was a functional goal at work: the slight angle allowed the button’s pins to be staggered and thus packed more closely together. Neat!

Hackaday Badge Keys

Electrically, most of the keys are laid out across a matrix of 10 columns and 5 rows. This allows the PIC32 chip to detect any single press of these 50 buttons using just 15 pins on the chip. The default firmware has a timer that fires regularly for household maintenance, and one of the tasks is to scan these pins for keyboard activity in function keyb_tasks in hw.c. Each timer slice checks one row on the keyboard, so it may take up to five time slices to scan the entire keyboard.

This is simple and efficient, but only works properly when one key at a time is pressed. When more than one key is pressed, the combination is ambiguous. For example, the following key combinations:

Hackaday Badge Keyboard Main

  • E + D
  • E + D + R
  • E + D + S
  • E + R + S
  • E + D + R + S

Would all light up the same four pins: B10, B11, B13, and B14 and there’s no way to tell them apart. This ambiguity will present a challenge for projects that require multiple simultaneous key presses. For example, some games require the user to press up and right simultaneously to command a movement to the upper right. Fortunately, this specific scenario is possible because the arrow keys are all on the same row, so a game that depends on arrow keys has to implement a custom variant of keyb_tasks that scan just pin F4’s row for one or more arrow keys. However, other typical sets of game directional keys (“WASD” and “IJKL”) could not be supported in the same way.

Hackaday Badge Keyboard Other

A few special keys on the keyboard have their own pins and read by other places in the firmware. The power button, break, and each of the two shift buttons have their own pin. The reset button is wired in series with the left shift key, so they both must be pressed to reset the badge. They do not share the D10 pin as the schematic might be interpreted to imply. A press of left shift + reset actually goes to MCLR pin, the PIC32 chip’s hardware reset guaranteeing that reset always works regardless of any potential firmware bugs.

 

Hackaday Badge Power Source

When I got the Hackaday Belgrade 2018 badge playing music, I noticed the LCD screen brightness would visibly pulse when a note is playing. I thought it might be an intentional visual effect to go with the beat of the music, but I didn’t see any sign of code to do so intentionally. The next most obvious explanation, then, would be a dip in screen supply voltage when the speaker amplifier is drawing power.

Hackaday Badge Power

If this is the case, then the problem should be related to voltage regulation on the badge. Can we improve on this situation? I looked on the schematic for the voltage regulator and… hmm… there doesn’t seem to be one.

It looks like the badge is running directly on the pair of AA batteries. The positive terminal is the voltage supply rail, and the negative terminal is the ground plane. So there isn’t anything working to keep the supply voltage constant when the battery level dips, and users see a change in LCD screen backlight brightness.

The lack of voltage regulation also means the most obvious power upgrade carries some risk. Last year’s Hackaday camera badge saw several upgrades from its pair of AA batteries to a single lithium ion battery cell. We were cautioned against doing it, but some people went ahead anyway and seemed successful.

With the microcontroller knowledge I learned over the past year, I understand the warning: The PIC32 chips at the heart of both badges are 3.3V parts and according to their datasheet, they are only officially rated for operation at up to 3.8V. A lithium ion battery cell’s nominal voltage is 3.7V which would be fine. But (and this is a BIG BUT) a fully charged lithium ion battery cell delivers 4.2V directly. This is well into “At Your Own Risk” territory.

So yeah – last year some people connected a lithium cell and that seemed OK, but it’s going beyond spec. I expect that some people will again perform the same upgrade to their badge this year. Personally? I’m not going to do it.

If I need to power my badge with anything other than AA batteries, I’ll remove the AA pair and power the badge through its expansion header. The +V pin connects directly to the supply rail, and GND connects directly to the ground plane. Putting a 3.0-3.3V regulated voltage on those pins should power the badge nicely.

Note that in this case, when I disconnect the external power supply the AA pair will still need to be reinstalled for a firmware upgrade, as the programmer (PICkit 3 or similar) is not able to supply enough power to run the badge.

Hackaday Badge LCD Screen

The main user interface for the Hackaday Belgrade 2018 badge is the LCD screen up front and center. Looking at the badge’s main menu, we can tell it can display text characters. 40 columns in width, and 20 rows in height according to DISP_BUFFER_WIDE and DISP_BUFFER_HIGH in hw.h. This is just a little under an Apple II’s capabilities, which are 40 columns wide and 24 characters high.

Hackaday Badge Main Menu Straight

Based on badge startup animation and the user program demo art, this screen is not strictly limited to character display. However, at first glance it’s hard to tell if what we saw are creative text art or if we can do general purpose graphics on this screen. Where can we get this information? The datasheet for the screen, of course. Based on the badge schematic, we have a model number to use in a web search.

Hackaday Badge LCD

And it was a very easy search! The display unit is from a company whose product model numbers correspond to the unit’s capabilities. It starts with NHD which is the company name Newhaven Display Inc, followed by a 2.4 indicating screen’s physical size of 2.4″ in diagonal, and 240320 meaning a graphics resolution of 240 by 320 pixels, etc.

One unexpected attribute of this LCD module is that it has an integrated controller chip. The display module datasheet has all the relevant electrical details, but for the specifics of data flow and command set, it asks the user to go look in the datasheet for the Sitronix ST7789V controller.

Newhaven Display’s web site has an “Application Notes” section for their products. Clicking on the link for the 2.4″ display with ST7789 controller points to this fragment of C code, which looks a lot like some of the badge display interface code in disp.c.

Also in disp.c is the text display code and a hard-coded basic font. So all the character display stuff is on the badge for us to hack. This is a very promising start to exploring the graphics capability of the badge. I’ll definitely return to dig deeper.

Hackaday Badge Music

Hackaday Badge AudioAfter looking at the Hackaday Belgrade 2018 badge‘s onboard RGB LED, I moved on to looking over the audio subsystem to see how it accomplished its three-voice audio functionality. My first guess was that music playback was handled by a peripheral of some sort. On the board schematic I saw that the speaker was connected to a chip labelled LM4890 so it seemed like an obvious candidate for audio peripheral. However, after downloading and reading the datasheet for LM4890, I learned the chip only functions as an amplifier to take a low-powered audio waveform (via pins labeled +IN and -IN) as input and push that same waveform out at a speaker-appropriate level of power. So yes, it is a dedicated audio peripheral, but not a tone or music generator.

So where’s the music coming from? I see on the schematic capacitors and resistors but nothing else that would generate sound waves, except maybe what’s connected to the PIC32’s pins D0 through D3. Perhaps the PIC32 has a built-in music peripheral?

Looking in the code, I started tracing from the BASIC side with the tune statement, handled by tune_statement in ubasic.c. It calls sound_play_notes in hw.c. A few more straightforward C call tracing ended at sound_set_generator which flips some hardware control bits and puts the desired frequency in a hardware register. What are the results of these actions?

Searching on the specific keywords in set_sound_generator didn’t get me anywhere immediately. Reading the code more carefully led to a key insight: for sound generator 0, it deals with the number 2. For generator 1, number 3, and for generator 2, number 4. After running around in circles for a bit, I figured out these are PIC32 hardware timer peripherals. These bits control PIC hardware timers 2, 3, and 4 whose actions are handled by Timer2Handler, Timer3Handler, and Timer4Handler in hw.c. Every time the timer interrupt fires, the handler inverts a pin named GEN_0_PIN / GEN_1_PIN / GEN_2_PIN defined to be LATDbits.LATD1 / LATDbits.LATD2 / LATDbits.LATD1 which matches up with the PIC32 pins on the schematic.

So it’s not a music peripheral like I originally guessed. They are three of the PIC32’s generic timer peripherals, each used to toggle a pin on and off at a set frequency. These three timers are responsible for the three voices, whose waveforms are merged and sent into a LM4890 chip (lower center of picture below) to drive the speaker (center of picture).

Hackaday Badge Audio

Hackaday Badge RGB LED

The canonical introductory activity in microcontroller programming is to blink a LED. The Hackaday Belgrade 2018 badge makes this easy because there’s already an LED on board. Actually three LEDs – a red, a green, and a blue inside a single integrated unit.

Badge RGB LED

To make this even easier to access, this LED can be commanded from the onboard BASIC interpreter enhanced with badge-specific command led. It makes the LED blinking activity nearly trivial. This is a great way to get people started in a way that is as non-intimidating as possible

The custom led command in the BASIC interpreter is handled by the function led_statement inside ubasic.c, which calls the function set_led inside hw.c. Custom user programs written in C can call set_led as well, or copy code from set_led to manipulate LED hardware directly. They set the state of several predefined PIC hardware pins. In hw.h, we see the following

#define LED_R LATDbits.LATD6
#define LED_G LATFbits.LATF1
#define LED_B LATDbits.LATD7

Belgrade Badge LEDs

These pins match up with what we see on the schematic, wired to three pins on the controller each in series with a current-limiting resistor and the corresponding LED.

So if someone wants to blink the LED on/off, they are all set. The infrastructure exists to do so from either BASIC or from C.

However, if they want to do something more sophisticated than just on or off – such as dimming, pulsing, or mixing the three LEDs to create custom colors, the existing infrastructure is not enough. In order to create a light intensity level somewhere between full on and full off, additional code will be required. The PIC is perfectly capable of creating this pulse-width modulated (PWM) activity on an output pin, it’d take just a bit of code, and should be one of the easier custom coding project to tackle.

Hackaday Badge User Program Template

As part of the retro computing theme, the Hackaday Badge offers a BASIC interpreter and an emulated Z80 computer running CP/M. However, there’s also provision for people who want to get closer to the hardware. This took the form of a “User Program” option on the main menu, which points to a sample C program for modification and experimentation. This C program has access to all the badge system infrastructure utilized by the aforementioned BASIC interpreter and Z80 emulation.

Since I had the luxury of a badge on hand, the easy thing to do first is to launch the sample program and see what it does. I can see some text printed on screen, and a prompt for a key press. Once I pressed a key (no need to hit ENTER) the program switched over to a graphics drawing demonstration.

Hackaday Badge User Program

The colorful patterns cycled through with a very visible scan rate, taking roughly two seconds to update pixels from the top to bottom of the screen. My first reaction was: “Gosh, I hope 0.5 frames per second is not the fastest it can go.”

Once I saw it in action, it was time to dive into the source code. Here the text I saw was drawn using the same commands to draw the main menu: clear screen, set color, set X/Y position, and output text.

The first bit of novelty was processing the key press. Unlike the menu, the non-blocking keyboard check is interleaved with text drawing commands that could continue executing while waiting for a key press. This will be useful in things like game loops, where we want the action to keep going even if the user hasn’t pressed anything.

After the key press is the drawing demo. It is using a bitwise operator to update screen contents on every pass. And here we have good news: Not only is there an explicit delay in here (there’s a code comment that says “less than 1 ms”) the screen update is also taking place one pixel at a time, the least efficient method possible.

So the graphics demo update rate is definitely NOT the fastest the badge can go. How fast can we push it? That’s something to test in the near future.

Hackaday Badge Main Menu

When exploring a new codebase, it’s a great luxury to also reference it in running form, a luxury I have with the Hackaday badge code project and a physical badge on hand to see it run. What’s the first point of interaction with running code? The main menu! So that’s where I decided to start looking at details of the code.

Hackaday Badge Main Menu Straight

From the main() function, the main menu is handled by function badge_menu() in file badge.c. The first thing it calls is showmenu() in the same file which draws everything visible onscreen for the main menu. Including title bar, screen border, menu entries, and the user input prompt. This is a great reference for writing code to output text on screen.

Most of the code in badge_menu() reads user key presses and builds up the typed command in menu_buff. Upon pressing ENTER, the command is checked against the list of known commands. This is a chunk of code that can easily be recycled for processing user text input.

When a user enters a command that’s none of the recognized list items, the badge selects one of a set of error messages at random. This pseudo-random number is seeded with the standard srand() call using a PIC chip’s timer counter value at the time of user’s first key press. Seeding with a time value is common practice, but usually done with a real-time clock on the assumption that the current time is unpredictable. Here, the unpredictability comes from the amount of time a human user would take before pushing their first key after powerup, every person has a slightly different reaction time.

When an user command is recognized, badge_menu() calls into corresponding code to make things happen. The menu entries are straightforward, but there are a series of “easter egg” behavior. Rather than a direct string comparison, which spoils the surprise by embedding the secret code in source code, the responses are actually keyed against a hash of the string.

Hackaday Badge Code Exploration in MPLAB X IDE

MPLAB X logo

Now that the Hackaday badge project compiles successfully on my computer, it’s time to look around and get oriented with the structure of this code project. Part of the orientation is actually getting re-oriented with Microchip’s own MPLAB X IDE for developing software running on their chips, like the PIC32MX chip that’s at the center of the badge.

I only use MPLAB X when dealing with PIC code. While it’s not exactly my favorite, I would agree it is sufficient to be a productive tool. The features most relevant to me right now are for code navigation. MPLAB parses the project files enough to knows how pieces of code are linked and lets me traverse those links easily.

For exploration, the following two key combinations are super useful:

Control + B: Go to declaration/definition

Alt + Left: Go back

While it is possible to use a text search to do both of these things, having an IDE that understands the project and makes navigation simple is a real time saver. With these keystrokes I could take a deeper look inside a particular function to see what it does, repeating to trace calls further if necessary. And when I’ve had enough with a particular area of code, go back to where I was before I started digging.

But of course, these tools are only useful once I have a starting point. Looking over the project files, I thought main.c sounded like a great place to start and indeed it was. There was just a short snippet of code in the main() function but it is the root of all functionality.

hw_init();
badge_init();
if (KEY_BRK==0) post();
if ((SHOW_SPLASH)&(K_SHIFTR==1)) boot_animation();
badge_menu();

  • hw_init() initialize all the PIC settings upon startup. What the pins do, which peripherals are activated, set things to default values, etc.
  • badge_init() seemed redundant but Control+B lets me see its comment saying this is work done whenever badge wakes up from sleep. So hw_init() is for a cold boot, and badge_init() is for resuming from sleep.
  • If a specific key is pressed upon power-up, there’s post(). The code looks like some sort of self-test, which implies POST = Power-On Self-Test.
  • The badge does have a little startup animation, which is apparently launched by boot_animation() if a compile-time flag and a runtime key both agree it should be run.
  • Finally, badge_menu() which is a loop for the badge main menu. This call never returns.

Most of main.c actually consist of comments which invites hackers to look around, find certain items discussed in the comment by using Control + Shift + F to search on strings in comments.

I will absolutely accept that invitation.

Hackaday Badge requires PIC32 Legacy Peripheral Library

The Hackaday Superconference is in a few weeks, and as part of preparing for the conference, I have a badge from the Hackaday event this past May in Belgrade. Supposedly the upcoming Supercon badge will be a very close successor to this badge so I’m going to dig in and understand as much as I can about it.

The first task is to get the badge firmware project file up and running. There is a repository up on Github. I see the device is built around Microchip’s PIC32 line of processors, so obviously I needed to get my MPLAB X IDE updated and running.

When I tried to build the project as-is, my first errors were related to C standard compliance, which I’ve seen before in the context of working with Microchip’s 8-bit chips but could be addressed the same way.

Then I ran into the second compiler error:

fatal error: peripheral/adc10.h: No such file or directory

An internet search found this thread on Microchip’s developer forums, which indicated I need to download something called “PIC32 Legacy Peripheral Libraries” which is a separate download link on the same page as the XC32 compiler download.

PIC32 Legacy Peripheral Library

It is an archive file that, once unpacked, is an executable installer. Everything was relatively straightforward except for the installation path. By default it puts all the library files under my home directory and used version number of an old compiler. (On my Ubuntu machine, that translated to /home/roger/microchip/xc32/v1.40) which I guess could work given some project path updates. But it made more sense to install into the directory for my currently installed compiler, so the project path doesn’t have to be updated. (On my Ubuntu machine, that translated to /opt/microchip/xc32/v2.10.)

Once installed, the project built successfully!

And after I did this investigative work, I found that there were already instructions telling me I’d need the legacy library. So this turned out to be a failure to RTFM but I learned something in the process, so all good.