|
@@ -36,35 +36,62 @@ will be started by Kalliope. So keep in mind that the best practice is to use re
|
|
|
|
|
|
An event is a way to schedule the launching of a synapse periodically at fixed times, dates, or intervals.
|
|
|
|
|
|
-The event system is based on [Linux crontab](https://en.wikipedia.org/wiki/Cron). A crontab is file that specifies shell commands to run periodically
|
|
|
- on a given schedule.
|
|
|
-When you declare an event in the signal, Kalliope will load the crontab file to schedule the launching of the target synapse.
|
|
|
+The event system is based on [APScheduler](http://apscheduler.readthedocs.io/en/latest/modules/triggers/cron.html) which it is itself based on [Linux crontab](https://en.wikipedia.org/wiki/Cron).
|
|
|
+When you declare an event in the signal, Kalliope will schedule the launching of the target synapse.
|
|
|
|
|
|
The syntax of an event declaration in a synapse is the following
|
|
|
```
|
|
|
signals:
|
|
|
- - event: "<contab period>"
|
|
|
+ - event:
|
|
|
+ parameter1: "value1"
|
|
|
+ parameter2: "value2"
|
|
|
```
|
|
|
|
|
|
-Where a crontab period follows the syntax bellow:
|
|
|
+For example, if we want Kalliope to run the synapse every day a 8:30, the event will be declared like this:
|
|
|
```
|
|
|
- ┌───────────── min (0 - 59)
|
|
|
- │ ┌────────────── hour (0 - 23)
|
|
|
- │ │ ┌─────────────── day of month (1 - 31)
|
|
|
- │ │ │ ┌──────────────── month (1 - 12)
|
|
|
- │ │ │ │ ┌───────────────── day of week (0 - 6) (0 to 6 are Sunday to
|
|
|
- │ │ │ │ │ Saturday, or use names; 7 is also Sunday)
|
|
|
- │ │ │ │ │
|
|
|
- │ │ │ │ │
|
|
|
- * * * * *
|
|
|
+- event:
|
|
|
+ hour: "8"
|
|
|
+ minute: "30"
|
|
|
```
|
|
|
|
|
|
-For example, if we want Kalliope to run the synapse every day a 8 PM, the event will be declared like this:
|
|
|
-```
|
|
|
-- event: "0 20 * * *"
|
|
|
-```
|
|
|
+### Parameters
|
|
|
+Parameters are keyword you can use to build your event
|
|
|
+
|
|
|
+List of available parameter:
|
|
|
+
|
|
|
+| parameter | required | default | choices | comment |
|
|
|
+|-------------|----------|---------|-----------------------------------------------------------------|-----------|
|
|
|
+| year | no | * | 4 digit | E.g: 2016 |
|
|
|
+| month | no | * | month (1-12) | |
|
|
|
+| day | no | * | day of the (1-31) | |
|
|
|
+| week | no | * | ISO week (1-53) | |
|
|
|
+| day_of_week | no | * | number or name of weekday (0-6 or mon,tue,wed,thu,fri,sat,sun) | 6=Sunday |
|
|
|
+| hour | no | * | hour (0-23) | |
|
|
|
+| minute | no | * | minute (0-59) | |
|
|
|
+| second | no | * | second (0-59) | |
|
|
|
+
|
|
|
+> **Note:** You must set at least one parameter from the list of parameter
|
|
|
+
|
|
|
+### Expression
|
|
|
+Expressions can be used in value of each parameter. Multiple expression can be given in a single field, separated by commas.
|
|
|
+
|
|
|
+| Expression | Field | Description |
|
|
|
+|------------|-------|-----------------------------------------------------------------------------------------|
|
|
|
+| * | any | Fire on every value |
|
|
|
+| */a | any | Fire every `a` values, starting from the minimum |
|
|
|
+| a-b | any | Fire on any value within the `a-b` range (a must be smaller than b) |
|
|
|
+| a-b/c | any | Fire every c values within the `a-b` range |
|
|
|
+| xrd y | day | Fire on the `x` -rd occurrence of weekday `y` within the month |
|
|
|
+| last x | day | Fire on the last occurrence of weekday `x` within the month |
|
|
|
+| last x | day | Fire on the last day within the month |
|
|
|
+| x,y,z | day | Fire on any matching expression; can combine any number of any of the above expressions |
|
|
|
|
|
|
-Let's make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7 AM and:
|
|
|
+
|
|
|
+### Examples
|
|
|
+
|
|
|
+#### Web clock radio
|
|
|
+
|
|
|
+Let's make a complete example. We want Kalliope to wake us up each morning of working day (Monday to friday) at 7:30 AM and:
|
|
|
- Wish us good morning
|
|
|
- Give us the time
|
|
|
- Play our favourite web radio
|
|
@@ -73,7 +100,10 @@ The synapse in the brain would be
|
|
|
```
|
|
|
- name: "wake-up"
|
|
|
signals:
|
|
|
- - event: "0 7 * * 1,2,3,4,5"
|
|
|
+ - event:
|
|
|
+ hour: "7"
|
|
|
+ minute: "30"
|
|
|
+ day_of_week: "1,2,3,4,5"
|
|
|
neurons:
|
|
|
- say:
|
|
|
message:
|
|
@@ -83,6 +113,7 @@ The synapse in the brain would be
|
|
|
- "It is {{ hours }} hours and {{ minutes }} minutes"
|
|
|
- shell:
|
|
|
cmd: "mplayer http://192.99.17.12:6410/"
|
|
|
+ async: True
|
|
|
```
|
|
|
|
|
|
After setting up an event, you must restart Kalliope
|
|
@@ -92,8 +123,23 @@ python kalliope.py start
|
|
|
|
|
|
If the syntax is ok, Kalliope will show you each synapse that it has loaded in the crontab
|
|
|
```
|
|
|
-Synapse "wake up" added to the crontab
|
|
|
-Event loaded in crontab
|
|
|
+Add synapse name "wake-up" to the scheduler: cron[day_of_week='1,2,3,4,5', hour='7', minute='30']
|
|
|
+Event loaded
|
|
|
```
|
|
|
|
|
|
That's it, the synapse is now scheduled and will be started automatically.
|
|
|
+
|
|
|
+
|
|
|
+#### Make Kalliope say something on the third Friday of June, July, August, November and December at 00:00, 01:00, 02:00 and 03:00
|
|
|
+```
|
|
|
+- name: "wake-up"
|
|
|
+ signals:
|
|
|
+ - event:
|
|
|
+ day: "3rd fri"
|
|
|
+ month: "6-8,11-12"
|
|
|
+ hour: "0-3"
|
|
|
+ neurons:
|
|
|
+ - say:
|
|
|
+ message:
|
|
|
+ - "This is a schedulled sentence"
|
|
|
+```
|