Cron

Cron daemon
Status	Stable
menuconfig	Applications->Cron daemon
Pinning	no
Ecmd	yes
Depends on	ECMD, Clock
Code	https://github.com/ethersex/ethersex/tree/master/services/cron

Cron daemon manage cron jobs. This rules define repeated or unique events that call certain commands.

Cron jobs are implemented in two flavors: a static list that is defined at compile time and not changeable at runtime, and a dynamic approach, which loads the joblist to the RAM at statup. Jobs can be added and removed at runtime.

Preconditions

Both approaches have in common that you need to define a function that is called from the con daemon at a appropriate time. The function signature, however, varies dependend on the choosen implementation.

Menuconfig

The module needs the current time to function properly. So you have to select at least one time source. To enable crontabs in ethersex select

 │ │                Load a Default Configuration  --->
 │ │                ...
 │ │                Applications  --->
 │ │                  ...
 │ │                  [*] Cron daemon --->
 │ │                  [ ] Cron daemon (static jobs)

Static Cron Daemon

The function to be called from the daemon has to have the signature void func(void) and has to be defined in cron_static/cron_static.c.

Furthermore you have to insert a rule of the type cron_static_event_t to the structure array events. The meaning of the values are minute, hour, day, month, days of week, callback function and a flag if UTC or local time is used (in that order).

A value of -1 is a wildcard. The entries are checked every minute, so an entry with all wildcards will be executed every minute.

Values less than -1 mean "every x-th minute/hour/etc.". So in case of -4 in the minute field the job will be executed every 4th minute.

Dynamic Cron Daemon

View jobs via ecmd

Simply execute the ecmd command cron list i.e. in your browser. All jobs will be displayed, two lines for each job. The first line contains the job attributes (position, repeats, ecmd/callback job, use UTC, etc.), the second line shows the timing data (MIN HOUR DAY MONTH DAYOFWEEK) and the ecmd command/address of the callback function to be executed.

Remove jobs via ecmd

cron rm N removes the Nth job (start counting at 0) from the cron list. Caution! cron rm without paramater removes ALL jobs without confirmation request!

Add jobs via ecmd

cron add MIN HOUR DAY MONTH DAYOFWEEK ECMD

MIN HOUR DAY MONTH and DAYOFWEEK can be -1 (as wildcard).

ECMD: The ecmd command to be executed.

After creating the new job it's position in the list will be displayed.

Mark job as persistent via ecmd

cron persistent N 1 mark job N as persistent

cron persistent N 0 remove persistent flag

cron persistent N show current state

Write persistent jobs to VFS/EEPROM via ecmd

cron save all persistent jobs will be stored in VFS/EEPROM.

Mark job for UTC time via ecmd

cron utc N 1 mark job N for UTC time

cron utc N 0 remove UTC flag

cron utc N show current state

Mark job as anacron job via ecmd

This flag provides a kind of anacron functionality which is intended for jobs that set specific states. Take the circulation pump of a central heating as example. If the pump has to be switched on at 6.00 and switched off at 9.00 this could be realized by a simple cron job. But if the controller reboots at 7.00 (i.e. as the result of a blackout) the pump will not be switched on till 6.00 of the following day. The same counts in case of a time skip by NTP updates.

To solve this problem all anacron jobs that falls in the skiped time range will be executed (in case of boot this means from 1.1.1970 till the current time), each job just one time and in correct order (latest execution time counts). To keep the runtime of the decision loop short, the starting point in the past is limited to <current time> - CRON_ANACRON_MAXAGE secs. Default is one day (86400 secs).

cron anacron N 1 mark job N as anacron job

cron anacron N 0 remove anacron flag

cron anacron N show current state

Define cronjob in source code: callback function

Wer scharf hinsieht, erkennt, dass diese Funktionalität auch durch den statischen Cron Daemon abgedeckt wird. Der statische Dienst verbraucht dabei sogar weniger Ressourcen. Aber, hier die Vorteile des dynamischen Dienstes:

• Du musst keinen Quelltext in ein fremdes Modul einfügen (Übersichtlichkeit der cron_static.c nimmt mit jedem weiterem Modul ab)
• Du kannst zur Laufzeit den cronjob auch wieder entfernen.
• Du kannst Extradaten an die Callback Funktion übergeben

Die Funktion, welche der Daemon aufrufen soll, muss folgende Signatur haben void func(char* data) und sollte nicht in der cron/cron.c Datei definiert werden, sondern in dem jeweiligen Modul, welche die Cron Funktionalität nutzen will.

1. Binde in dein Modul die Datei 'cron/cron.h' ein.
2. Nutze die Callback Variante des Cron-Einfügen Befehls cron_jobinsert_callback in der Initalisierungsfunktion deines Moduls um beim Start von ethersex cronjobs hinzuzufügen.
3. Die Funktionsparameter haben die folgende Semantik:

• Minute, -1 für ignorieren, -2 für jede 2te Minute etc
• Stunde, -1 für ignorieren, -2 für jede 2te Stunde etc
• Tag, -1 für ignorieren, -2 für jeden 2te Tag etc
• Monat, -1 für ignorieren, -2 für jeden 2te Monat etc
• Wochentag, 1 für Sonntag, 2 für Montag, 4 für Dienstag, 8 für Mittwoch, 16 für Donnerstag, 32 für Freitag, 64 für Samstag oder eine Addition daraus
• Wiederholen, INFINIT_RUNNING für endlos, 1=einmal etc
• Position des Crons in der Cronliste (CRON_APPEND, wenn angehängt werden soll)
• Callback Funktion
• Größe von Extradaten
• Extradaten

Beispiel aus der Test Einträge Datei:

void test(void* data) { /* tu was */ }
// in init
cron_jobinsert_callback(-1, -2, -1, -1, -1, INFINIT_RUNNING, CRON_APPEND, test, 0, NULL);

Extradaten sind eine ziemlich coole Sache. Stella PWM zum Beispiel speichert darin Lichtkanal und Zielwert. Beim Aktivieren des Cronjobs wird der Zeiger auf diese Extradaten dann an die Callback Funktion mit übergeben und diese stehen direkt zur Verfügung. Bitte beachte hierbei aber, dass der Pointer auf die Extradaten durch einen Malloc Aufruf gewonnen werden muss, sprich die Speicherstelle für die Extradaten müssen vorher auf dem Heap allokiert werden. (Beispiel: char* extra = malloc(2); für 2 Bytes auf dem Heap)

Du musst und solltest dich nicht um die Freigabe des allokierten Speichers kümmern. Dies erledigt der Cron daemon bereits.

Define cronjob in source code: ecmd command

Der statische cron daemon bot die Möglichkeit eine Funktion zu gegebenem Zeitpunkt aufzurufen. Wenn du jedoch den dynamischen Dienst nutzt, kannst du auch ecmd Befehle zeitabhängig aufrufen lassen (z.B. Pins setzen, Stella PWM kontrollieren, ethersex reseten etc).

Die Funktion die du in dein Modul hierfür einbauen musst, lautet folgendermaßen:

cron_jobinsert_ecmd(-1, -2, -1, -1, 127, INFINIT_RUNNING, CRON_APPEND, "ECMD");