RTuinOS: A Real Time Operating System (RTOS) for Arduino 1.0.1

Dear Arduino Fans,

I've made a small Real-Time Operating System (RTOS) for Arduino, called
RTuinOS.

Meanwhile a number of test cases are running stable and I decided to
publish it now. Instead of lots of explanation I put chapter "Introduction"
of the manual here. Please find the complete installation (including the
complete manual) attached to this thread. The manual should be your
starting point of reading.

Thank you for your kind interest in RTuinOS; your feedback is welcome.

With kind regards
Peter Vranken

P.S. A new release of RTuinOS is available. Please refer to
"RTuinOS 1.0: Second Release of the Real Time Operating System (RTOS) for Arduino"
in this forum for details. Or visit GitHub to get a download.

P.S. Meanwhile it turned out that the download of the setup file via this
post is not reliable. Occasionally, the operation aborts and reports an
invalid file. The reason is unclear. To circumvent the download problem, I
placed the setup file of RTuinOS at github, please see
RTuinOS/RTuinOS-0.9.1.zip at master · PeterVranken/RTuinOS · GitHub.
You have to follow this link and and click on Button "Raw" to start the file
download.

Introduction

Arduino (www.arduino.cc) is a popular open source and open hardware micro
controller platform for various purposes, mainly located in leisure time
projects. Arduino comes along with a simple to use integrated development
environment, which contains the complete tool chain to write source code,
to browse through samples and libraries, to compile and link the software
and to upload it to the board and flash it. The RTuinOS project adds the
programming paradigm of a real time operating system to the Arduino world.

Real time operating systems, or RTOS, strongly simplify the implementation
of technical applications which typically do things in a quite regular
way, like checking inputs and setting outputs accordingly every (fixed)
fraction of a second. For example, the temperature controller for a
heating installation could be designed this way. Temperature sensors,
which report the room temperatures are evaluated and the burner and maybe
some valves are controlled to yield the desired target temperature.
Furthermore, using a real time system the program could coincidentally and
regularly update a display to provide feedback - at the same or any other
rate. Regular, time based programming can be done without the need of CPU
consuming waiting loops as used in the implementation of Arduino's library
functions delay and delayMicroseconds. Real time operating systems
characterize the professional use of micro controllers.

RTuinOS is a small real time operating system (RTOS) for the Arduino
environment. It is simple to use and fits well into the existing Arduino
code environment. It adds the concept of pseudo-parallel execution threads
to the sketches.

The traditional Arduino sketch has two entry points; the function setup,
which is the place to put the initialization code required to run the
sketch and function loop, which is periodically called. The frequency of
looping is not deterministic but depends on the execution time of the code
inside the loop.

Using RTuinOS, the two mentioned functions continue to exist and continue
to have the same meaning. However, as part of the code initialization in
setup you may define a number of tasks having individual properties. The
most relevant property of a task is a C code function, which becomes the
so called task function. Once entering the traditional Arduino loop, all
of these task functions are executed in parallel to one another and to the
repeated execution of function loop. We say, loop becomes the idle task of
the RTOS.

A characteristic of RTuinOS is that the behavior of a task is not fully
predetermined at compile time. RTuinOS supports regular, time-controlled
tasks as well as purely event controlled ones. Tasks can be preemptive or
behave cooperatively. Task scheduling can be done using time slices and a
round robin pattern. Moreover, many of these modes can be mixed. A task is
not per se regular, its implementing code decides what happens and this
can be decided context or situation dependent. This flexibility is
achieved by the basic idea of having an event controlled scheduler, where
typical RTOS use cases are supported by providing according events, e.g.
absolute-point-in-time-reached. If the task's code decides to always wait
for the same absolute-point-in-time-reached event, then it becomes a
regular task. However, situation dependent the same task could decide to
wait for an application sent event - and give up its regular behavior. In
many RTOS implementations the basic characteristic of a task is determined
at compile time, in RTuinOS this is done partly at compile time and partly
at runtime.

RTuinOS is provided as a single source code file which is compiled
together with your other code, which now becomes an RTuinOS application.
In the most simple case, if you do not define any task, your application
will strongly resemble a traditional sketch: You implement your setup and
your loop function; the former will be run once at the beginning and the
latter repeatedly.

RTuinOS on its own can't be compiled, there need to be an application.
RTuinOS is organized as a package which combines the RTuinOS source file
with some sample applications which are the test cases at the same time.
The source code of each sample application is held in a separate folder,
named tc. Any of these can be selected for compilation. You may add
more folders, holding the source code of your RTuinOS applications. A
starting point of your application folder can be a copy of any of the
folders tc. The compilation always is the same. Run the makefile,
where the name of the folder (which doesn't need to be tc) is an
option on the command line. Refer to the manual for more.

The most relevant document to read is the manual of RTuinOS, found as
manual.pdf. The manual introduces the basic concept of RTuinOS and gives
an overview of its features and limitations:

Chapter 2 explains the basic principles of operation. Some core
considerations of the implementation are highlighted, but the relevant
documentation of the implementation is the code itself. It is commented
using doxygen (www.doxygen.org) tags; the compiled doxygen documentation
is part of this project. It contains only the documentation of the global
objects of RTuinOS; to fully understand the implementation you will have
to inspect the source code itself, please refer to [1], [2], [3].

Chapter 3 lists and documents all elements of RTuinOS' API.

Chapter 4 explains how to write a well-working RTuinOS-application. The
chapter starts with a short recipe, which guarantees soon success. Here is
where you may start reading if you are already familiar with the concept
of an RTOS.

The manual closes with chapter 5, which gives an overview of possible
improvements and still missing and maybe later released features.

RTuinOS-0.9.1.zip (2.33 MB)

Please note, that the download of the attached setup is possible only for members of the forum, which have signed in.

Regards
Peter

This project looks really impressive and is very cleanly written and documented.

I have several questions:

I think that this project deserves more attention.
Maybe you can move your project to a public Github repository?
That would make it a lot easier for people to find.

You could also write a Playground page and use this thread as a place for users to ask for question, like it's been done for Time/TimeAlarms library.

Hello,

here are some answers to the recently posted questions:

The development of RTuinOS has been made from scratch. I've tracked the
effort: It took about 90 hours to do the implementation (including
specification, makefile and all the test cases) and about 70 hours to
write the documentation.

I didn't hear about protothreads before and can't compare it to RTuinOS.

DuinOS is the port of FreeRTOS for our micro controller. FreeRTOS exists
for many years and has been ported to many controllers. Actually, it has
been designed to be easily portable to other controllers; this is one of
its major features. Obviously, FreeRTOS is much more mature than RTuinOS,
it would be overweening to announce RTuinOS as a comparable competitor of
FreeRTOS.

The only goal for developing RTuinOS was enthusiasm for Arduino and the
RTOS topic. When I got acquainted to Arduino a few month ago I was really
enthusiastic about the concept which put the ease of use on the first
place. I immediately bought a MEGA board, made some simple experiments
first and looked then for a challenging task. I'm professionally working
with existing RTOSs and took the chance to develop another one.

There's no university background, it's just a leisure time project.

The test cases which come along with RTuinOS have been developed together
with RTuinOS. You call it a proof of concept and this will hit the point.
RTuinOS is new and not proven in practice. There are no real life
applications of RTuinOS so far. If being used in a productive environment
this needs to be considered a major risk. For leisure time projects it
should be alright.

This is the first time I issued self-made software in the net and I'm not
so familiar with the various sites for publishing free software and how to
do. I going to investigate it and notify the Arduino Forum if I find
another adequate upload location. Furthermore, I will take a look at the
Arduino Playground. Thank you for your hints.

Kind regards

Peter

I have ported FreeRTOS as libraries for AVR and ARM Arduinos as FreeRTOSBeta20121215.zip http://code.google.com/p/beta-lib/downloads/list.

I am currently modifying the 16 examples from the FreeRTOS book http://shop.freertos.org/RTOS_primer_books_and_manual_s/1819.htm to run as Arduino sketches. I will be posting these soon.

I have also ported ChibiOS/RT as libraries for AVR and ARM Arduinos as ChibiOSBeta20121217.zip http://code.google.com/p/beta-lib/downloads/list.

ChibiOS/RT ChibiOS free embedded RTOS - ChibiOS Homepage is not as popular as FreeRTOS but is technically very interesting. It is high quality and I use it a lot.

Hello All ,

Is this RTOS compatible with the ARDUINO DUE 's ARM controller ? .

Please share the link for the tutorials and basic examples on the same .

The implementation uses assembler code, which makes it CPU and compiler dependent. RTuinOS is not compatible with ARM and it has not been designed for easy portability

Sounds like a very interesting project. I am currently investigating options for a light weight RTOS for my robot. Most of what i have seen is loaded with many functions I do not need nor want. Since there is limited resources on thease parts having just what you need is a plus. unfortunatly, the link to your code is not functoning. Have you uploaded the file in another place?

You can't tell how much flash and RAM an RTOS will take by looking at the API. Well designed RTOSs only link code you use.

For example ChibiOS takes as little as 2KB of flash if you only create tasks and simple timer functions.

You need to evaluate an RTOS for functionality, size, and performance.

Also most quality RTOSs have a configuration file that easily allows more memory to be saved by tuning the features you use.

Hello Bucknaz,

thanks for your hint, you were right, the attachment of this post became
invalid. I removed and uploaded it again but the file is still reported to
be invalid.

To circumvent the download problem, I tried to place the setup file of
RTuinOS at github, please see
RTuinOS/RTuinOS-0.9.1.zip at master · PeterVranken/RTuinOS · GitHub. You
have to follow this link and and click on Button "Raw" to start the file
download.

If memory size is a concern RTuinOS may be your choice. It's not
particularly designed for a minimum of memory usage but it does not waste
it neither.

RTuinOS is configured by an included header file. #define's enable or
disable code sections according to the demands of your application. If you
carefully design your application you will be satisfied by the achieved
memory usage. Nowadays, the code size typically barely matters and the
RAM size mainly depends on your application. Don't use threads which are
not really required; each thread requires the instantiation of a static
task descriptor variable in RAM plus an extension of the scheduler
internal thread lists plus a private stack area. The number of threads is
the main cost of RAM.

A design goal of RTuinOS is the understandability of the implementation.
Its documentation gives some hints how to further optimize the code with
respect to RAM consumption. These hints together with the clearly
documented code could enable you to tailor RTuinOS to your specific
demands.

Kind regards,

Peter

hi Peter Vranken,

nice project and i appreciate your effort, could you provide more information about how to implement it within Arduino IDE platform and much more examples as well. i have tried DuinOS and NilRTOS to solved multitasking project and i enthusiastic to do so with RTuinOS.

henry

Hi Henry,

I'm very sorry, but actually I didn't intend to support the Arduino IDE.
RTuinOS and its applications are intended to be built by makefile only.
The make processor is part of the Arduino installation, so there should be
no basic problem doing so. Accept maybe for the inconvenience if you
should not be familiar with using makefiles so far. But if so, you'll soon
learn to appreciate the advantages.

The Arduino IDE is superior with respect to getting acquainted to Arduino,
to browse the samples and documentation, to learn about the system and to
develop simple projects. However, to my opinion it's not the appropriate
tool for professional work. One will tend to use an advanced environment
like Eclipse or Emacs for software projects of larger scale. These
environments easily integrate the Arduino environment if you provide a
makefile, which defines the required build rules. But you can run the make
build also as simple as by typing a short command line. Please refer to
the RTuinOS manual, sections 4.1. to get an example.

The makefile, which comes along with RTuinOS is quite generic. It should
be applicable for most RTuinOS applications without the need for any
change. You will just have to set one or two variables (e.g. on the
command line) to specify the name of your application and the COM port
which your Arduino board is connected to. Please refer to the manual,
sections 4.2. for details.

Please refer also to section 4.6 of the manual, which discusses the
possibility of using the original Arduino libraries in RTuinOS
applications. The strongest disadvantage of any RTOS implementation for
Arduino is the fact, that the official Arduino development does not found
on this RTOS, that the Arduino libraries do not consider the specifics of
an RTOS. For a real use case (which is anything beyond playing and
learning) you will not be able to use the original libraries but you will
have to write the required I/O access code on your own. Doing the
development work with the Arduino IDE becomes even more questionable
because of this fact.

Kind regards

Peter

If you got a mega 1280/2560, and a quadram, you might want to look at this instead.
http://forum.arduino.cc/index.php?topic=160833.0
It's not an RTOS, instead, it allows up to 16 tasks, each with a private stack and malloc arena.
The area for the stack and arena is 32k, and you can partition it any way you like, either by just setting your own global default, or by tuning it before you start the task. I have to write the tuning before start code yet, but the demo shows the possibilities of just multitasking without much code space overhead. 8)

A new release of RTuinOS is available. This is the second release or version 1.0.2. It
introduces mutexes and semaphores. The kernel code, the makefile, the code
samples and the manual have been revised. The makefile based build process now
supports Linux, Mac OS and Windows.

Please refer to RTuinOS 1.0: Second Release of the Real Time Operating System (RTOS) for Arduino - Libraries - Arduino Forum in this forum for
details. Or visit GitHub at GitHub - PeterVranken/RTuinOS: RTuinOS, a small Real Time Operating System (RTOS) for Arduino to get a safe
download.

Peter,
Reading your last post has saddened me - no current support for 32 bit architecture.
I was happy to see that you added semaphore elements as that is essential for inter-process (think thread) communications.
The Arduino DUE is the processor of my choice mainly due to (1) higher speed, (2) larger available memory, (3) more digital pins.
Having to wait for the Arduino world to catch up to Linux level of threading brings tears to my eyes.
I can get Linux already on the Beagle Bone, but the I/O pins structure is much more restrictive.
Oh for a Linux on the DUE, the the world would happier for me.
Of course the Linux DUE will need to have 2GB of Flash in addition to 512 MB of RAM. The flash means the OS and your program can boot without need of a kludgy micro SD card.
My candle is rapidly burning down to the point of choosing the product hardware with the compelling need of an multi-threading OS so I can implement waitless read-and-continue and write-and-continue operations.

What do you think about Raspberry Pi, which seems to be even somewhat cheaper than the Due?

With avr-gcc 4.7.2 in Mint 16 I get the following results:

make -s APP=tc01 build
(...)
Compiling debug code
Linking project. Ouput is redirected to bin/tc01/DEBUG/RTuinOS_tc01.map
avr-gcc: error: unrecognized command line option ‘--fatal-warnings’
avr-gcc: error: unrecognized command line option ‘--no-undefined’
avr-gcc: error: unrecognized command line option ‘--reduce-memory-overheads’
make: *** [bin/tc01/DEBUG/RTuinOS_tc01.elf] Error 1

echo $?
2

I've searched but found none, anyone knows what is going on?

[Edit] Same problem with Ubuntu 14.04

Hello,

Unfortunatley I can't reproduce your problem as I have a different system (Windows, avr-gcc 4.3.2), which obviously doesn't have this problem.

A basic, general tip: Run the same build command without the -s; the actually used compiler and linker command lines will become apparent in the console output and if you compare them with the online help of these tools you might get a step ahead. Then copy the critical command line and enter them directly in the shell to see if you can reproduce the same error. If so, you can start manipulating the command line until you get the linker succeesfully run or let it at least print more meaningful messages.

If the printed error messages were literally correct all you'd to do is to remove the three options from the command line; none of them is essential. (Although it could indeed be just a matter of differences in the linker interface of our two versions, I don't really believe so. I'd rather guess that the reported problem is a subsequent fault and that you will have to find the true problem.)

Given, you've found a properly working linker command line it's straight forward to change the makefiles so that they adopt your findings. Open file makefile/compileLinkAndUpload.mk and change the definition of variable lFlags. Look for "Linking project".

And please let us know ...

Thanks,
Peter

P.S. Please note, that this topic refers to the first release of RTuinOS (0.9). Meanwhile, version 1.0 has been released. If you still work with the first release, the first thing you should do is to download, install and try the current revision. Please visit RTuinOS 1.0: Second Release of the Real Time Operating System (RTOS) for Arduino - Libraries - Arduino Forum to get more information

The manual is great to start with. Thank you Peter.