KleOS

Arduino + FreeRTOS = Real time applications for the Arduino platform

Arduino + FreeRTOS + Arduino-mk = Real time applications for the Arduino platform coded in VIM (or whatever editor you love) and compiled in the CLI (and with sketches, of course!)

KleOS is the continuation of my former project called Molcajete, but KleOS is easier to use than ever: * Molcajete (ancient aztec food blender tool) name was never well received. * More important, now every project must have its own FreeRTOSConfig.h configuration file. In the Molcajete project there was one FreeRTOSConfig.h configuration file for all projects. * I've included all 5 FreeRTOS memory allocated schemes. * I've included less but clearer examples.

OVERVIEW

KleOS project is here to help you create real time applications for the Arduino platform.

For that I've grouped three glorious tools:

• Arduino. Your preferred electronics platform.
• FreeRTOS. The real time operating system for embedded systems.
• Arduino-mk. The tool to compile your Arduino projects from the command line.

Arduino is the opposite to real time; however, so many real world applications need to react to internal and external events in real time, e.g. as fast as possible, even seizing the CPU from the code that is currently executing. FreeRTOS is the glorious tool behind getting such behaviour.

And as you become an Arduino power user you find the IDE too clumsy, so why don't you compile your way (e.g. in the terminal) using your preferred source code editor? Arduino-mk is the glorious tool behind this behaviour. You can still use sketches and the horrible Arduino IDE for your real time applications!

"Kleos" is the greek word for "glory", and it has embedded our preferred letters "OS".

FEATURES

• Real time Arduino based upon FreeRTOS.
• Tasks (and any other operating system object) can be created with statically or dynamically allocated memory.
• You can develop your real time applications with both, sketches and from the CLI (thanks to Arduino-mk).

For the time being this project only covers the Arduino UNO boards, e.g. those boards based upon the AVR ATMEGA328P chip.

I haven't tested yet tickless and/or low-power modes.

EXAMPLES

I've added 2 sketches and 2 CLI examples so you can test your installation and start coding real time applications as soon as possible. The examples are located at: /your/KleOS/installation/path/arduino-1.8.13/libraries/FreeRTOS/examples.

In the Arduino IDE you can find them through the main menu: File->Examples->FreeRTOS.

QUICK START

I'm a happy Linux user, so my testings on Windows are severely limited (using Win7 on an abandoned PC); however, I can assure yout that the KleOS for Windows works as good as on Linux, but don't expect from me more than this.

In order to start as quickly as possible writing your own real time applications on the Arduino UNO platform, please follow the next steps, either for Linux or Windows.

1. Download and decompress the project in whatever location you want.
2. You don't need to install it! unless it's what you want; the overall project is self contained. Be warned: this project doesn't compile regular sketches unless you touch some Arduino inwards.

Sketches

1. Locate the file arduino inside /your/KleOS/installation/path/arduino-1.8.13/ and run it (click on it, you don't need to be root). If your Linux box asks you what to do, choose Execute.

2. Once in the Arduino IDE open one of the included examples. You can find them through the main menu: File->Examples->FreeRTOS.

3. The sketch will be opened along a file called FreeRTOSConfig.h, which configures FreeRTOS. You can tune it to meet your needs, but it's already configured for the example. Take a look at it so you get acquainted (you can learn more about the configuration here).

4. Press the Verify button (or Ctrl+r) to compile the sketch.

5. Upload the project in the usual way (Ctrl-u) to any board Arduino UNO compatible (e.g., a board featuring the ATMEGA328P chip).

If the LED attached to pin 13 blinks every second, you've done it!

From here you can create your own sketches from scratch using the given template and saving them wherever you want.

CLI projects

1. Locate one of the included examples: /your/KleOS/installation/path/arduino-1.8.13/libraries/FreeRTOS/examples/. Say you've chosen the hello_world_cli example.

2. Enter into the folder and you'll see 3 files: main.cpp, FreeRTOSConfig.h and a Makefile.

3. Open the Makefile file and modify the first and last line so that both lines point to your KleOS installation path (you can watch the introductory video, or click here).

4. You might want to open the FreeRTOS configuration file FreeRTOSConfig.h in order to configure FreeRTOS to meet your application needs, but it's already configured for the example. Take a look at it so you get acquainted (you can learn more about the configuration here).

5. Open a terminal pointing to where the main.cpp file (and the other two as well) is.

6. Inside the terminal execute a make command to build the example (don't type the $ symbol, it's the terminal's prompt):

$ make

1. For uploading the executable, in the same terminal type:

$ make upload

If the LED attached to pin 13 blinks every second, you've done it!

1. To clean the build, in the same terminal type:

$ make clean

1. To open a serial terminal if your project is using the serial stream (Serial.print()), in the same terminal type:

$ make monitor

To exit from the monitor you need to type Ctrl-a followed by k followed by y. Alternatively you can open the IDE (as explained above) and then open the embedded serial monitor (with Ctrl-Shift-m).

From here you can create your own CLI projects from scratch using the given template and saving them wherever you want.

Remember: * Sketches: A FreeRTOSConfig.h file must be present in the same folder as the .ino file is. * Terminal: A FreeRTOSConfig.h file and a Makefile file must be present in the same folder as the .c/cpp file(s) is(are). * Makefile (only for when compiling from the terminal): Make sure that ARDUINO_DIR variable and the very last line both point to your KleOS installation.

Take a look at the examples included (and this video, as well).

DYNAMICALLY ALLOCATED MEMORY

FreeRTOS includes 5 schemes to allocate memory dinamically (heap_x.c, with 1 <= x <= 5, and you can find them in /your/KleOS/installation/path/arduino-1.8.13/libraries/FreeRTOS/src); although it's strongly recommended not to use dynamic memory in embedded systems, I've included for your convinience the same 5 schemes. You just need to change the name of the one you want to use. BE AWARE THAT:

• The heap_1.c scheme is the simplest and just implements the heap as an array of bytes (and it doesn't allow to deallocate the memory); but IT DOESN'T WORK with the ATMEGA328P port, so DON'T USE IT.

• Instead use the heap_3.c scheme which in turn calls the standard malloc() and free() functions from the AVR-GCC toolchain. In this regard, the constant (located at FreeRTOSConfig.h) configTOTAL_HEAP_SIZE is not taken into account, but it must exist.

If you still want to use dynamically allocated memory then you might want to create all tasks at once at the global space and to avoid any task deletion, so the memory won't get fragmented.

OPERATING SYSTEM

This project works in Linux and Windows, and you don't need to install it, just run it. Regular Arduino applications (those that will not use any task or any real time mechanism from FreeRTOS, like software timers) won't compile under KleOS: Compile your regular applications with your regular Arduino installation; compile your real time applications with KleOS.

MODIFIED FILES

I needed to modify some files so that Arduino can work along FreeRTOS. If you are interested, these are the files I touched:

• FreeRTOS side

  • port.c

• Arduino side

  • wiring.c (The FreeRTOS system tick is tied to T0, the same timer used by Arduino as its base time.)
  • platforms.txt

Side effects

I've modified a little bit the optiboot bootloader, and this change is included in the bundle. If you don't use it, then you have nothing to worry about. If you're planning to burn the bootloader into your chips, you might want to check my modifications.

LICENSES

Each entity in this project have its own licensing scheme. For details visit:

arduino.cc freertos.org https://github.com/sudar/Arduino-Makefile

As per my little contribution, the GPL license is enough (I'm just the guy that grouped those amazing programs).

CONTRIBUTIONS

All contributions are welcome: examples, sketches, testing in boards other than UNO or Leonardo, testing in OSs other than Linux, etc. I'm NOT asking for money. I've done this little contribution due to my love for embedded systems and my beliefs on the open source and open hardware movement.

The KleOS project is brought to you by Xavier R. You can reach me at fjrg76 at hotmail dot com.