The Molcajete Project, brought to you by Xavier R

Introduction

I built this project so we can program under the Arduino platform using both the command line and a real time operating system, FreeRTOS. Good news are that you can still use sketches.

The super-loop Arduino's model doesn't scale well, so for any non trivial projects we need not only to separate responsabilities, but also to start from the main function. Moreover, most embedded projects rely on a system tick, and the delay() function is not a proper system tick. Finally, the everything-is-a-sketch philosophy doesn't scale well, too.

As professionals programmers we need to start out our programs as usual: from the very fundamentals, which is the main() function; we need to have the control. Then we split the program's functionality into independent, but related, C functions. And as a consecuence of all this stop using global variables!. Then we'll need a system tick, and Arduino doesn't provide one. Finally, some Arduino's functions block while executing; this means that while they are doing what they do, no other code can be executed.

For a LED to blink this is not important; however, for real time systems that must respond to critical events as soon as possible, we can't wait until the delay() function finishes (or any other blocking function). So we must find a way to pre-empt the less critical functions so the incoming (and might be more critical) event is executed. Dispatching critical events before (or pre-empting) non-critical ones is the core of any real time operating system, like FreeRTOS.

What is a real time operating system?

What is FreeRTOS?

As for today this project only works for boards compatibles with Arduino UNO, it means, any board with the ATMEGA328 processor. Later I'll add more processors.

Alternatives to The Molcajete Project

There are several approaches to using FreeRTOS along Arduino; some of them (that I'm aware of) work without altering the Arduino's platform. But it comes with a price:

• Use the timer's Watchdog as system tick, or
• Use a timer other than the TIMER0 (Arduino use this timer for timing functions, like delay()) as system tick.

The problem with the Watchdog approach is that it has issues:

1. You can't program any common frequency for the system tick. Even more, its frequency is too low. The most you can get are weird frequencies like 6ms, when in the practice it's used 1ms or 10ms.
2. Its frequency is unstable (it drifts) and it's very dependent of external factors, as temperature, since it don't use a crystal.
3. You lost the Watchdog functionality.

The problem with the timers approach is that it has issues too:

1. A common solution is to use the TIMER1. But you lost it. It means you can't use it for PWM, or any other timer functionality, like counting external events. Well, in fact you can still use it, but whatever you do is bound to the set frequency.

I decided to hack the platform so that my approach uses TIMER0 as its base time (almost 1ms), so you can still use the Watchdog and the other 2 timers. Besides that, it has been so fun to hack it!

NOTE: Because of hardware limitations, you can't get by any means an exact frequency of 1KHz (or 1ms base time) on TIMER0. Most you can get is 1.024 KHz (or 0.977ms). It's not your fault, it's Arduino's designers.

Installation

IMPORTANT errata from 03/01/21: YOU NEED TO REPLACE THE FILE HEAP_1.C WITH THE FILE HEAP_3.C.

After you finished the steps below you need to:

1. Enter into the folder /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/src and delete the file heap_1.c.

2. Download the file heap_3.c from this repository and copy it into the folder /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/src

Download

Download the bundle that fits your operating system. As for today there are only version for Linux and Windows.

Install

You don't need to install anything else unless you want to compile from the console. Just decompress the bundle wherever you want.

The Molcajete project isn't aimed to substitute your current Arduino installation (if any), however you can install it in your operating system as any other application. Keep in mind that I have tweaked several core files in the Arduino platform, so your installation might behave erraticaly with regular sketches. Besides, there exist several versions of Arduino for the Windows operating system that complicates keeping track all of them. So with the steps described one doesn't have to deal with such issue.

Compile sketches

If you want to try sketches then:

1. Before you compile/upload any sketch you need to tweak a file called FreeRTOSConfig.h. In this file there are several options for the operating system. The file is located at /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/src. For example, in order to run the dynamic_task_1 example make sure that the option configSUPPORT_DYNAMIC_ALLOCATION is set to 1:

   define configSUPPORT_DYNAMIC_ALLOCATION 1

2. Enter into the folder arduino-1.8.13 and click on the file arduino (for Linux) or arduino.exe (for Windows). The Arduino IDE will start.

3. Go to File -> Examples -> FreeRTOS.

4. Open any of the examples provided. For example, try dynamic_task_1 program.

5. Compile and upload the sketch to any Arduino UNO compatible board (any board that uses the ATMEGA328 processor) as usual.

6. This example prints out analog reads to the serial port, so open the IDE's built-in serial monitor (Ctrl-shift m).

Compile from the command line (for Linux only)

If you want to try the command line (my prefered one) then you first need to install two packages for reasons I can't understand:

1. Install Arduino-core (without the IDE) and Arduino-mk:

   $ sudo apt install arduino-core arduino-mk

2. Before you compile the examples you need to tweak a file called FreeRTOSConfig.h. In this file there are several options for such operating system. The file is located at /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/src. For example, in order to run the Blink_StaticTask program make sure that the option configSUPPORT_STATIC_ALLOCATION is set to 1:

   define configSUPPORT_STATIC_ALLOCATION 1

3. Before you compile the examples you need to tweak (again) a file called Makefile. Each example aimed to be compiled in the console includes its own Makefile. In the Makefile there are several options for compiling from the console, and this file is located at /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/examples/Blink_StaticTask. Make sure that the first line points to your Molcajete installation, otherwise it won't compile:

   ARDUINO_DIR = /your/installation/path/arduino-1.8.13

4. Open a terminal (or console) pointing to /your/installation/path/arduino-1.8.13/libraries/FreeRTOS/examples folder. There you'll find several examples, including those for sketches.

5. Let's compile the Blink_StaticTask example ($ means the prompt and you don't need to type it). Then in the terminal you need to move into that folder (so far you're in the examples folder, remember?):

   $ cd Blink_StaticTask

6. Compile and upload it with:

   $ make

   $ make upload

7. This example prints out analog reads to the serial port. For Linux you can open the terminal monitor:

   $ make monitor

To exit the monitor press Ctrl-a, then k, finally y (Control+a, kill, yes). Alternatively you can also use the IDE's built-in monitor: just open the IDE and open the monitor (Ctrl-Shift-m) in both Linux and Windows.

Adding the FreeRTOS goodies

FreeRTOS has growth a lot since Amazon aquired it, but the Molcajete project only includes its kernel. However, if you need any other of its amazing functionality then you can download it and add it to the FreeRTOS library.

A note about the FreeRTOSConfig.h file

As I have already mentioned, you can tweak and fine tune several options for the operating system editing the FreeRTOSConfig.h file.

In an ideal world there should be one FreeRTOSConfig.h file per project. However, my ignorance in regard of Makefiles hasn't allowed me to bring in this option for all of us. It means that one FreeRTOSConfig.h file is shared among ALL projects, either sketches or in the console. So be aware of this situation when you are working on different projects at the same time, or when you comeback to a project after a while.

---

Releases

0.9.3, Major changes

26/12/20

Both Arduino and FreeRTOS have been updated to their lastest releases, by this time, Arduino 1.8.13 and FreeRTOSv202012.00 (after the 10.4 release, FreeRTOS has changed its way of numbering its releases).

0.9.2, Minor changes

04/05/20

• The 0.9.1 release didn't allow to compile programs without using FreeRTOS. Now, 0.9.2 do allow to compile programs without FreeRTOS at all.

• I renamed back the folder FreeRTOS-10.0.1/ to FreeRTOS/ (without the release number). For some reason the system didn't accept it.

0.9.1, Minor, yet important updates

18/04/20

• I added the callbacks that the FreeRTOS static tasks support needs. In previous releases the user must provide them somewhere into the project. This update adds the file src/static_mem_callbacks.c in the FreeRTOS folder.
• I grouped some items logically in the FreeRTOSConfig.h file.
• I modified the splash and about pics so that it informs you that you are using the Molcajete project. This way you know which version is running when you have both the official Arduino installation and the Molcajete project in your box.

Get rid of dynamic tasks support

If you don't need the dynamic FreeRTOS support at all, e.g. when configSUPPORT_DYNAMIC_ALLOCATION is set to 0, then you must rename (or delete it, which I strongly don't recommend) the file heap_3.c to heap_3.txt, so that the compiler does not include it in the building.

Manual installation

If you don't want to install the whole Molcajete project, or I have not taken into account your platform (Mac), then you can modify by hand what is need it:

1. Download and uncompress either the Linux or Windows installation.
2. Copy the folder libraries/FreeRTOS-10.0.1 and past it in the libraries/ folder in your current Arduino installation.

3. Copy the folder hardware/arduino/avr/cores/arduino and past it in the hardware/arduino/avr/cores/arduino folder in your current installation.

   I have modified some files in this folder towards FreeRTOS works along Arduino, so it's important that you don't skip this step.

Big news!!!

23/03/20

• A Windows release is available !!!
• You can program now with sketches in both releases, Linux and Windows !!!
• The Linux release should work in Mac out of the box.

Both releases are not intended to be installed. If you're planning to program with sketches, look for the Arduino.exe file (for Windows, or Arduino for Linux) in the root folder and click on it. The IDE will show up. Then, look for File->Examples->FreeRTOS to find some examples.

(Be aware of that I'm not user neither Windows nor Mac.)

First release

05/22/2018

Patch: molcajete-0.1.1-linux64.tar.bz2 There was an issue building the Tick example. Fixed. Some compile-time constants were added to make the compilation a better experience.

Molcajete bundle: molcajete-0.1.1.tar.bz2 It already includes the changes to source code to use the tick system. It also includes the Tick example.

05/17/2018 Patch. Instead of downloading the complete platform, a patch file is included, molcajete-0.1-linux64.tar.bz2, so the user can apply the patch against his/her already downloaded Arduino platform. If you don't want to download the complete bundle, or your bandwidth is scarce, or you are comfortable applying patches, then this option is for you. There are instructions inside the package for applying the patch.

System tick

The patch also includes a system tick facility. If using a kernel is too much for you or for your application, and a system tick fulfills your needs, then to apply the patch is a good idea. An example is included in FreeRTOS/examples/Blink_Tick.

molcajete-0.1-linux64.tar.bz2, Size: 320 KB

05/12/2018 Initial release. It includes the complete Arduino platform along the FreeRTOS kernel and two examples.

molcajete-0.1.tar.bz2, Size: 150 MB