microBlinky

The “hello world” of the microNIMO and umake universe, microBlinky is (one of) the simplest applications for the microNIMO board, it initialises the IO pin of the user LED and the delay timer to flash the LED once every 2 seconds.

File structure

A umake project is very lightweight, only requiring 2 files to create a minimum functional project, however there are additional files that may be used.

Required files

• umakefile
• main.c (the specific filename can be configured in umakefile)

The minimum viable umake project consists of a json file called umakefile which describes the project to umake, and at least one C source file. Often this will be called main.c, however this can be configured in the umakefile.

Optional files

• nimolib.h (Library configuration settings, required if using nimolib)
• .gitignore (other source control programs will generally have an equivalent. Whilst entirely optional, it will help to keep source controlled projects tidy)
• system.h (Whilst not really required for a project the size of microBlinky, for larger projects this can be used for IO configuration, project specific configuration etc.)

Lets go…

This section contains detailed step by step instructions for creating a project from scratch. If you prefer the TLDR; then you can download the entire project here and jump to Build It!

Fire up your favourite editor, we recommend VSCode, however any editor that creates plain text files (gedit on Linux, notepad on Windows etc.) will work as well.

Generally speaking, the Makefile is an important file in a C based project, however in this case it is generated automatically by umake and can therefore also be treated as temporary.
The folders build/ and umake/ are temporary environments created by umake they can be regenerated at any time and as such don’t need to be permanently stored.
As these files / folders are automatically generated, you shouldn’t edit them by hand as your changes will be overwritten by umake.

Create a new directory for your project and fire up your favourite text editor.

.gitignore

Create a new file called .gitignore. As above, this file is optional however a nice addition when using git or other source control systems. If you aren’t using any source control then skip this step.

build/*
umake/*
Makefile

umakefile

Create a new file called umakefile. This will describe our project to umake allowing it to create the build environment for our project.

{
	"target": "blinky",
	"microcontroller": "m032lg6ae",
	"toolchain": "arm-none-eabi",
	"ucLib": "nimolib-m032",
	"c_sources": [
		"main.c"
	],
	"includes": [
		"./"
	],
	"buildDir": "./build",
	"libraries": [
		{
			"libName": "nimolib",
			"libPath": "https://github.com/nimo-labs/nimolib.git",
			"books": [
				"gpio",
				"delay"
			]
		},
		{
			"libName": "nimolib-m032",
			"libPath": "https://github.com/nimo-labs/nimolib-m032.git"
		}
	]
}

umakefiles are standard JSON files that allow us to specify the make up of our project. For the most part, the file above can be considered as standard boilerplate and reused from project to project with minimal changes. As such, we will only describe the important parts, a full description can be found in the umake project.

Target specifies the name of the binary file for our project, upon a successful build this file will be written to the microcontroller by the bootloader. In this case, we’ve called our project blinky, so the final file will be blinky.bin

Microcontroller defines the name of the microcontroller we would like to build for, in the case of the microNIMO board, this will always be m032lg6ae.

c_sources lists the source files used by our project. Syscalls and support are provided by nimolib and are required by all projects. main.c will be our main (and in this project only) source file though as noted in File Structure this can be called almost anything.

books: These are sub modules of a larger library set, in this case we are using the GPIO and delay books from the larger nimolib library.

umake is capable of creating custom make targets the exact detail is out of the scope of this article, but in this case it allows us to create a simple command that programs the microcontroller. The programmer needs to know the name of the file burn to the microcontroller, in this case blinky.bin if you change the name in target then you will also need to update this with the new file name.

nimolib.h

This file is required when using the standard nimo libraries and contains configuration information for the various books. For this project, we only need to define the main processor clock speed, in this case 48MHz.

#define UP_CLK 48000000

system.h

Whilst not strictly required for a project as small as microBLINKY, system.h provides a convenient place to store project specific configuration options such as the GPIO pin an LED is connected to.

#define LED_BLUE_PORT GPIO_PORTC
#define LED_BLUE_PIN 14

The schematic for the microNIMO board shows us that the user LED built into the board is connected to pin 14 of PORT C.

main.c

This is the entry point for our program, it contains the standard C main function which is the beginning of all C programs.

/* Project configuration */
#include "nimolib.h"
#include "system.h"

/* Books */
#include <gpio.h>
#include <delay.h>

void main(void)
{
    GPIO_PIN_DIR(LED_BLUE_PORT, LED_BLUE_PIN, GPIO_DIR_OUT);
    GPIO_PIN_OUT(LED_BLUE_PORT, LED_BLUE_PIN, GPIO_OUT_LOW);

    delaySetup(DELAY_BASE_MILLI_SEC); /*Clock timer at 1mS*/

    while (1)
    {
        GPIO_PIN_TGL(LED_BLUE_PORT, LED_BLUE_PIN);
        delayMs(2000);
    }
}

In order to build correctly, we have to include some standard header files, NuMicro.h, nimolib.h and system.h are standard for all projects. In addition, we have to include a header file for each book we are using, in this case gpio.h and delay.h.

Inside the main function, we use the GPIO_PIN functions to set the LED pin as an output, then to set it low (LED off) by default. Once the LED has been setup, we also set up the delay timer and ask it to count in milliseconds.

The while(1) statement creates an infinite loop runs the same short block of code forever. In this case, we toggle the LED pin and then wait for 2 seconds before doing it all again.

Build it!

If you are here then you are almost ready to test your first microNIMO application, if you read through the entire Lets Go section then well done, if you cheated and downloaded the code, then no offence is taken.

Building a umake project involves a couple of simple commands. First of all, open a terminal and change to the directory containing your project. If you are using VSCode, then choose New Terminal from the Terminal menu.

If you have just created a new project or have made changes to the umakefile then run the umake command to create the project environment. Once umake has finished without error, umake will have created build and umake directories, downloaded the required libraries and created a Makefile that will build the project.

Next, run the make command which if successful will compile our project and create blinky.bin in the build directory.

Burn it!

Now that we have successfully built our project, it’s time to burn it into the microcontroller. For this, the microNIMO needs to be in bootloader mode, if there is no application loaded (such as a new board) the microNIMO will be in bootloader mode by default. If not, hold down the user button whilst pressing and releasing the reset button. Release the user button once the blue LED is flashing twice a second.

Once the board is in bootloader run the command sudo make program from the terminal (this is the target that we created in the umakefile). If everything worked successfully, the blue LED should start blinking once every 2 seconds. Currently sudo is required to interact with the bootloader, we are working on a udev file to remove that requirement.