Basic: first application

In this tutorial you will learn how to write your first BeRTOS application. We'll be using one of the cpu's currently supported by BeRTOS, the ATMega1281. We will use the wizard to set up the project, then we'll set up debugging facilities and we'll print some output messages to the debug port.

Project setup

Download BeRTOS and launch the wizard. From cfg select debug. This will automatically include debug support in BeRTOS. Set the correct output port for your cpu and then create the project. Let's call our project hello_world.

The wizard creates the directory hello_world/, in which you see:

• bertos/: the whole bertos source tree;
• Makefile: the makefile for the whole project. To build the project, simply launch make;
• hello_world/: our project directory
  • cfg/: directory with all the configuration files
  • hw/: hardware specific files
  • main.c: our application entry point

Coding

Open main.c and input:

#include "buildrev.h"

#include <cfg/debug.h>
int main(void)
{
    IRQ_ENABLE;

    kdbg_init();
    kprintf("Program build: %d\n", VERS_BUILD);
    kputs("Hello world!\n");
    return ;
}

Then compile the program; you will see some warnings but for now you can safely ignore them. Flash your board and reset. On the debugging serial you'll see these messages:

*** BeRTOS DBG START ***
Program build: 17
Hello world!

Congratulations! You have built your first BeRTOS program!

Line by line tutorial

#include <cfg/debug.h>

The first line includes function prototypes. Since this is often included by other files, you can omit it in larger projects.

IRQ_ENABLE;

This line enables IRQs on your CPU. We don't need it for this simple example, but you will need for almost every other module in BeRTOS, so it's a good habit to learn as soon as possible.

kdbg_init();

This line initializes the debug subsystem, opening a serial port for debugging. The parameters for this port are in hello_world/cfg/cfg_debug.h.

kprintf("Program build: %d\n", VERS_BUILD);
kputs("Hello world!\n");

Writes a debug string on the output. You can also use a printf-like function to format the output. Be aware, though, that the delay introduced by printf is high, so use it sparingly.

To reduce footprint and cpu usage, BeRTOS implements different types of formatting for printf. You can select your formatting options modifying hello_world/cfg/cfg_formatwr.h. Remember the warnings we got on the first build? These were due to using full formatting on an underpowered cpu. To avoid the warnings you can change printf format option to PRINTF_NOFLOAT.

Binary file flashing

Compiled files will be placed in the directory images/ of your project directory. You will find lots of formats, for example .elf, .s19, .hex or .bin. The last BeRTOS version has a flashing and debugging infrastructure integrated directly into the makefile to speed up these repetitive operations

The operations to flash and debug a target vary greatly from CPU to CPU, so you have to write a script which will flash your CPU. For example, when using AVR targets it's enough to run Avrdude or Avarice with the correct parameters. The script may use one of the following environment variables, which are defined directly in the makefile:

• PROGRAMMER_CPU: the CPU you are using in your project.
• PROGRAMMER_TYPE: the programmer type to use
• PROGRAMMER_PORT: the port to which the programmer is connected
• GDB_PORT: port to wait GDB connections
• ELF_FILE: file path with debug symbols for GDB

Variables PROGRAMMER_TYPE and PROGRAMMER_PORT are defined in the project's makefile (for example hello_world.mk). Once you have created the scripts, you just need to execute one of the following commands:

make flash_hello_world
# oppure
make debug_hello_world

That's all. Have fun with BeRTOS!