Use your badge as a flashlight with 'lumos'

This tutorial walks through the following:

• Find out how to do something on the badge, by looking at implementation details of a related existing BASIC command.
• Look at three ways to trigger the new code:
  1. Add it as a program to be launched at main menu command line.
  2. Add it as a new BASIC command.
  3. Add it to the default user program.

One of the first things we do with the badge is to light up its LED using BASIC commands. For this tutorial, we want to light up all three LEDs to use the badge as a flashlight. We can do this with the following simple BASIC program:

10 led 0,1
20 led 1,1
30 led 2,1

This works, but it's silly to take up a BASIC program slot just for this. So in order to add this feature to badge firmware, we start by looking at what happens under the hood when BASIC sees the "led" keyword.

• basic/tokenizer.h:
  • Declare enum TOKENIZER_LED.
• basic/tokenizer.c:
  • Static array keywords[] associates command string 'led' with TOKENIZER_LED.
• basic/ubasic.c:
  • Inside function statement() a TOKENIZER_LED triggers a call to led_statement()
  • led_statement() processes the tokens and calls into set_led()
• hw.c:
  • set_led() sets the PIC32 pins corresponding to LEDs.

Copying from set_led(), we can write a short function to turn on all three at once:

void flashlight()
{
  LED_R = 1;
  LED_G = 1;
  LED_B = 1;
}

Side note: this is equivalent to calling an existing function set_led_word(0x07), but for the sake of the tutorial we'll proceed with adding a new function.

Now we'll survey the options for putting our new function to work, you can use any combination of the below as you see fit for your code:

Option 1: add to main menu:

To light up LEDs when user enters a command in the main menu, we edit badge_menu() in badge.c. After the user presses enter (NEWLINE), there's an if/else tree to process commands. We can add a new menu command to this list. We'll make our new command "lumos".

[...existing code...]
    else if (strcmp(menu_buff,"lumos")==0)
        {
        flashlight();
        }
[...existing code...]

Now we can type "lumos" at the main menu to turn on flashlight mode.

Option 2: add to BASIC commands

(UPDATE: The Superconference badge firmware now has a much faster BASIC tokenizer, an upgrade over the Belgrade badge. The downside is that it's more difficult to modify. The instruction below applies to the slower but easier to modify BASIC tokenizer.)

This retraces our steps digging into BASIC commands, this time adding our own code.

• basic/tokenizer.h: 
  • Declare enum TOKENIZER_LUMOS.
• basic/tokenizer.c:
  • Add to keywords[] array to associate string "lumos" with TOKENIZER_LUMOS.
• basic/ubasic.c: 
  • Add to the switch statement inside statement(), so a TOKENIZER_LUMOS will call  lumos_statement()
  • Add new function lumos_statement() to process tokens and call flashlight().

Now "lumos" will work as a badge BASIC keyword

10 lumos

Option 3: add to user program:

The default user program waits for a user key press. Add a call to flashlight() just after a key is detected in user_program_loop() of user_program.c.

[...]
    if (get_stat!=0)
        {
        flashlight(); /* Turn on all three LEDs */
        /* Show which letter was pressed just as an example: */
[...]

With this change, the LEDs will light up on the first key press after the user program starts.

But the user program is your playground to do as you please, so feel free to experiment!

---

To see all of the above code snippets in context, look at this Github branch. (Disclaimer: as of Oct 25, this links to a fork of the older Belgrade badge repository. This link will be upgraded to the Supercon badge repository soon.)