******** leOS.h - little embedded Operating System ******* leOS (little embedded Operating System) This is not a complete OS nor an RTOS as you usually know but it's a simple scheduler to schedule the execution of little routines in background, so that you can forget about them. It's designed for Arduino and other common Atmel microcontrollers (for the complete list please read below). Written by Leonardo Miliani <leonardo AT leonardomiliani DOT com> *********************** Version history v. 1.2.2: use correct field separator in keywords.txt (per1234) v. 1.2.1: fixed compatibility with Arduino IDE >= 1.6.7 v. 1.2.0: fixed a critical bug that lead to infinite execution of task 0 (also if ONETIME) v. 1.1.4: scheduler's code revisited and fixed some bugs v. 1.1.3: little bugs fixed v. 1.1.2: fixed an issue in modifyTask v. 1.1.1: minor changes v. 1.1.0: new methods to stop/restart the scheduler v. 1.0.3: now a task can be started once it has been added to the scheduler v. 1.0.2: code cleaning v. 1.0.1a: function taskIsRunning renamed as getTaskStatus v. 1.0.1: code cleaning and 32-bit overflow fixing v. 1.0.0: added a method to check if a task is running - first stable release v. 0.1.5: added support for Atmega344 v. 0.1.4: core code rewriting (now it uses Structs) v. 0.1.3: now a task can be added in "paused mode"; new example sketches v. 0.1.2: fixed a bug in the management of one-time pads v. 0.1.1: now the user can choose between 32-bits & 64-bits math v. 0.1.0: leOS now works correcty on Arduino Leonardo/Atmega32U4 v. 0.0.8: now the user can modify running tasks v. 0.0.7: introduced one-time tasks v. 0.0.6: (preliminary) support for Arduino Leonardo/Atmega32U4 v. 0.0.5: fixed some bugs and optimized code & memory consumption v. 0.0.4: use of a 64-bit counter so the scheduler will overflow after 584,942,417 years v. 0.0.3: added methods to pause and restart a task v. 0.0.2: user can now delete scheduled tasks v. 0.0.1: early release - user can only add tasks *********************** How to use it - Methods Unpack the library and copy it into your /libraries folder, that usually is in your sketchs' folder. Then include the library and create a new istance of it by adding the following code at the top of your sketch: #include "leOS.h" leOS myOS Then you have to initialize the library in the setup() routine: void setup() { myOS.begin(); ..... } Now you can add a task by simply call the method .addTask(): void setup() { myOS.begin(); myOS.addTask(yourFunction, scheduleTime[, status]); ... } yourFunction must be a routine that is inside your sketch. scheduleTime is the scheduled interval in milliseconds at which you want your routine to be executed. Starting from version 0.1.3, now the user can choose the status of the task when it adds it to the scheduler. status can be: PAUSED, for a task that doesn't have to start immediately; SCHEDULED (default option), for a normal task that has to start after its scheduling; ONETINE, for a task that has to run only once. An interesting feature is the ability to run one-time tasks. A one-time task is a task that will be run only once: the scheduler, once it has run the task, will remove it from the running tasks (it won't be paused, it will be permanently deleted). To pause a task, just call the following method: myOS.pauseTask(yourFunction); You can restart it with: myOS.restartTask(yourFunction); To remove a task from the scheduler call this method: myOS.removeTask(yourFunction); To modify a running task, simply call the modifyTask method with the new interval time and/or the kind of the status' task, i.e. a normal or a one-time task: myOS.modifyTask(yourFunction, newInterval [, newTaskStatus]); newTaskStatus can be ONETIME if you decide to transform a normal task into a one-time task, or SCHEDULED if you want to transform a one-time task into a normal task (the one-time has still to be executed). To check if a task is running, you have to use the taskIsRunning() method: myOS.getTaskStatus(yourFunction); This will return 255 if there was an error (task not found) or a value for the current status: PAUSED - task is paused/not running SCHEDULED - task is running ONETIME - task is scheduled to run in a near future. SCHEDULED_IMMEDIATESTART or simply IMMEDIATESTART, for a task that has to be executed once it has been added to the scheduler. Introduced with leOS 1.1.0 there are 2 new methods that permit to stop/restart the scheduler, useful if you need to stop all the running tasks at the same time: myOS.haltScheduler(); stops the scheduler and freezes all the tasks preserving their current intervals; myOS.restartScheduler(); restarts the scheduler resuming all the tasks that were running. *Be careful*: the user is asked to check his code to avoid strange situations when he pauses a task. I.e.: if the task that has been paused alternated the output of a pin and that pin drove an external circuit, the user should check if the status of the pin after the task has been paused is safe and compatible with his needs. *********************** 32-/64-bit math Starting with version 0.1.1, the user can choose between 32-bit and 64-bit math. Using 32-bit math, the maximum interval that can be choosed is limited to 49.7 days; the overflow of the counter has been fixed since versione 1.0.1. While using 64-bit math the maximum that can be choosen is only limited by the user's fantasy, due to the fact that the 64-bit counter will overflow after 584,942,417 years (default maximum interval is 1 hour, but you can change this value editing the leOS::addTask method inside the leOS.cpp file). To switch between 32-bit and 64-bit math just comment/uncomment the line #define SIXTYFOUR_MATH that is present at the beginning of the code inside the leOS.h file. *********************** How it works The scheduler makes use of a 8-bit timer of the microcontroller to schedule the user's tasks, so you'll loose PWM functionalities on the related pins. This is a list of the timers used on each microcontroller and the pins that you cannot use as PWM pins anymore: 1) Atmega48/88/168/328 (Arduino UNO/2009): timer 2 - pins 5 & 17 (pins D3 & D11 on Arduino UNO) 2) Atmega344/644/1284: timer 2 - pins 20 & 21 (pins D14 & D15 on Maniacbug core) 3) Atmega640/1280/1281/2560/2561: timer 2 - pins 18 & 23 (pins D9 & D10 an Arduino MEGA) 4) Attiny25/45/85: timer 0 - pins 5 & 6 (pins D0 & D1 on Tiny core) 5) Attiny2313/4313: timer 0 - pins 9 & 14 (pins D7 & D11 on Tiny core) 6) Attiny24/44/84: timer 0 - pins 5 & 6 (pins D2 & D3 on Tiny core) 7) Atmega8: timer 2 - pins 17 (pin D11 on older Arduino boards) 8) Atmega32U4 (Arduino Leonardo): timer 3 - pin 32 (pin D5 on Arduino Leonardo) The user has to remember that he has to create simple tasks that: 1) don't use any other interrupts/timers inside them (due to the fact that an interrupt service routine, ISR, is atomic - this means that it cannot be halted or interrupted by another interrupt); 2) don't use PWM functionalities on the pins listed above; 3) don't keep too much running time - this is important because a task that runs for a long time will freeze the execution of the other tasks and the main loop. *********************** Supported microcontrollers Actually the library has been successfully tested with Arduino UNO, Atmega328, Arduino MEGA2560 and Arduino Leonardo. The library should compile and work versus the following: - Attiny2313/4313 - Attiny24/44/84 - Attiny25/45/85 - Atmega344/644/1284/P - Atmega8/A - Atmega48/88/168/328/P - Atmega640/1280/1281/2560/2561 - Atmega32U4 (only at 16 MHz) Supported clocks are 1, 4, 8, and 16 MHz. NOTE: To use leOS on Attiny 24/44/84 microcontrollers you have to modify a file of the Tiny core to move the millis() and delay() functions from timer 0 to timer 1. To do that, open the file /arduino-your_version/hardware/tiny/cores/tiny/core_build_options.c and look for the section "Build options for the ATtiny84 processor". A couple of rows below, change this line #define TIMER_TO_USE_FOR_MILLIS 1 to #define TIMER_TO_USE_FOR_MILLIS 0 then save the file and reload the Arduino IDE. *********************** Licence This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3.0 of the License, or (at your option) any later version. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. *********************** Document revision 25th revision: 2016/02/20
vakochetkov/leOS
leOS is a little interrupt-driven scheduler to execute little routines in background - For Arduino boards and Atmel microcontrollers
C++