Tutorials/Your First Egg (for uGFX badges)

From Badge team
Revision as of 13:58, 23 August 2019 by SynQ (talk | contribs) (→‎Which type of badge do you have?: updated referral to the ugfx versions)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Introduction[edit]

One of the aims of the badge.team project is to ensure that as many people as possible can develop software for the platform. This ensures that badges and other hardware running our firmware are more likely to have a life beyond the event for which they were created.

The problem with many event badges has been that the learning curve for new developers is too steep and the acceptance process for new software too difficult. When detailed knowledge of a toolchain is required to write code and each addition must wait to be built into a fresh badge firmware update, most would-be developers go away and enjoy the event instead.

With an online app store we refer to as the hatchery and MicroPython apps we refer to as eggs, publishing new software for badges running our firmware is a much simpler process.

Not everybody is immediately familiar with a new platform though, so to help with your first badge egg we've produced this tutorial. The aim here is not to teach you Python, but to introduce you to the structure of an extremely basic badge.team egg as well as get you going with the user interface. We'll be following the time-honoured tradition of introducing you to badge programming with a Hello World egg.

Which type of badge do you have?[edit]

The different badges do not all have exactly the same hardware, so there are some slight differences in the code. If you have a LED matrix badge such as the CampZone 2019 badge you will need to proceed to the CampZone 2019 section.

If you have an eInk badge such as the SHA2017 or Hacker Hotel 2019 badges **and** you have an old (pre July 2019) firmware version (and you want to keep that ) please use the Your First Egg (ugfx badges) section. Newer versions no longer use uGFX (and are thus more open and more compatible).

Your First Egg (CampZone 2019 badge)[edit]

Compatibility[edit]

The software in this section has been tested on the CampZone 2019 badge with the current firmware for 2019-07-26.

The __init__.py file[edit]

The first thing the firmware does when it tries to run an egg is look for a file named __init__.py, and run it. Some eggs also have other files, but at its simplest all the code for an egg can be contained within this one file.

So the first thing you should do is take an empty new directory, and create a file called __init__.py within it using your favourite text editor.

Libraries[edit]

Your badge comes with a set of MicroPython libraries that contain functions allowing you to access its hardware. The first lines you must put in your __init__.py file simply tell MicroPython that your egg will need to use one of them. The rgb library contains functions for interacting with the LED matrix display. Type the following into your file:

import rgb

Clearing the screen[edit]

Before writing to the screen, whatever is still in place from any previous software must be erased. The rgb library has a clear() function to perform this task. Add the following to a fresh line of your file:

rgb.clear()

Saying Hello World![edit]

Having now set everything up, we can now make our egg perform its purpose in life and display the string "Hello World!". In the first line we're assigning the string to a variable called displaytext though this is not essential and we could pass it directly. Then we are using rgb's text() function to write the text to the display. So, enter the following lines into your file:

displaytext = "Hello World!"
rgb.text(displaytext)

The completed egg[edit]

Your Hello World egg should now consist of an __init__.py file containing the following code:

import rgb
rgb.clear()
displaytext = "Hello World!"
rgb.text(displaytext)

Of course, you now want to test it, and this can be done by uploading it to your badge using a tool called mpfshell. We have created a tutorial on that process, so head on over to the simple egg deployment page and follow the procedure there. When you have done so, you should see something like the screenshot below.

Your First Egg (ugfx badges)[edit]

Compatibility[edit]

The software in this section has been tested on both the SHA2017 and Hacker Hotel 2019 badges with the current firmware for March 2019.

These and other badge.team badges at this point launched with a firmware containing the ugfx display library. This section describes a Hello World egg for badges with this firmware.

The __init__.py file[edit]

The first thing the firmware does when it tries to run an egg is look for a file named __init__.py, and run it. Some eggs also have other files, but at its simplest all the code for an egg can be contained within this one file.

So the first thing you should do is take an empty new directory, and create a file called __init__.py within it using your favourite text editor.

Libraries[edit]

Your badge comes with a set of MicroPython libraries that contain functions allowing you to access its hardware. The first lines you must put in your __init__.py file simply tell MicroPython that your egg will need to use two of them. The badge library contains low-level badge-specific functions, and the 'ugfx library contains functions relating to the display and keys of the user interface. Type the following into your file:

import badge
import ugfx

Initialising the libraries[edit]

The two libraries must now be initialised, and to that end both have an init() function which must be called before they can be used. Now enter the following code into the next lines of your file:

badge.init()
ugfx.init()

Clearing the screen[edit]

Before writing to the screen, whatever is still in place from any previous software must be erased. The uGFX library has a clear() function to perform this task, which can be passed a colour as a predefined constant. In our case we want to clear the screen to white, so we are passing it the ugfx.WHITE constant. Add the following to a fresh line of your file:

ugfx.clear(ugfx.WHITE)

Saying Hello World![edit]

Having now set everything up, we can now make our egg perform its purpose in life and display the string "Hello World!". In the first line we're assigning the string to a variable called displaytext though this is not essential and we could pass it directly. Then we are using uGFX's string() function to write the text to the display buffer. This takes five arguments, of which the first two are the coordinates at which we want the text to appear, the third is the text contained in our displaytext variable, the fourth is the name of one of the built-in fonts, and the fifth is another uGFX colour constant. We want black text, so we've used ugfx.BLACK. The final line executes uGFX's flush() function to send the display buffer to the screen.

So, enter the following lines into your file:

displaytext = "Hello World!"

ugfx.string(0, 0, displaytext,"PermanentMarker36", ugfx.BLACK)

ugfx.flush()

The completed egg[edit]

Your Hello World egg should now consist of an __init__.py file containing the following code:

import badge
import ugfx

badge.init()
ugfx.init()

ugfx.clear(ugfx.WHITE)

displaytext = "Hello World!"

ugfx.string(0, 0, displaytext,"PermanentMarker36", ugfx.BLACK)

ugfx.flush()

Of course, you now want to test it, and this can be done by uploading it to your badge using a tool called mpfshell. We have created a tutorial on that process, so head on over to the simple egg deployment page and follow the procedure there. When you have done so, you should see something like the screenshot below.

Hello World, on a Hacker Hotel 2019 badge.

Adding some interactivity[edit]

This egg now runs, but once it's running you can't exit it. The only way to do so is to reset your badge, either by power-cycling it or by pressing the reset button on the reverse. We'll now add some code to exit the egg on a button press.

The red lines in the listing below should be added to your __init__.py file. The system library holds system functions related to managing the behaviour of eggs on the badge, it is necessary to include it. We must then initialise a subset of uGFX functions related to the buttons, ugfx.input_init() allows us access to these.

At the bottom of the listing we define an exiteggg function that takes us back to the launcher with the system.home() function, and in the final line we use ugfx.input_attach to set up button A to call it. Loading the app onto a badge, you'll find the same "Hello World!" text, but this time pressing button A will return you to the launcher.

import badge
import ugfx
import system

badge.init() ugfx.init()

ugfx.input_init()

ugfx.clear(ugfx.WHITE)

displaytext = "Hello World!"

ugfx.string(0, 0, displaytext,"PermanentMarker36", ugfx.BLACK)

ugfx.flush()

def exitegg(pressed):
    if(pressed):
        system.home()
    ugfx.flush()

ugfx.input_attach(ugfx.BTN_A, lambda pressed: exitegg(pressed))

Further reading[edit]

What we have shown you here are only a few of your badge's capabilities, we have only tried to familiarise you with the egg development process. You may find the following further reading to be useful as you explore egg development further for your badge.

Finally, don't be afraid to look at other people's code. If you open up any app's page in the Hatchery, you should be able to look at the contents of its MicroPython files in your browser. For example, take the the Game of Life egg and look at the code in a file called game_of_life.py.