Browse Source

update event doc

nico 8 years ago
parent
commit
db60d20939
1 changed files with 68 additions and 22 deletions
  1. 68 22
      Docs/signals.md

+ 68 - 22
Docs/signals.md

@@ -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.
 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
 The syntax of an event declaration in a synapse is the following
 ```
 ```
 signals:
 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
 - Wish us good morning
 - Give us the time
 - Give us the time
 - Play our favourite web radio
 - Play our favourite web radio
@@ -73,7 +100,10 @@ The synapse in the brain would be
 ```
 ```
   - name: "wake-up"
   - name: "wake-up"
     signals:
     signals:
-      - event: "0 7 * * 1,2,3,4,5"
+      - event:
+          hour: "7"
+          minute: "30"
+          day_of_week: "1,2,3,4,5"
     neurons:
     neurons:
       - say:
       - say:
           message:
           message:
@@ -83,6 +113,7 @@ The synapse in the brain would be
             - "It is {{ hours }} hours and {{ minutes }} minutes"
             - "It is {{ hours }} hours and {{ minutes }} minutes"
       - shell: 
       - shell: 
           cmd: "mplayer http://192.99.17.12:6410/"
           cmd: "mplayer http://192.99.17.12:6410/"
+          async: True
 ```
 ```
 
 
 After setting up an event, you must restart Kalliope
 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
 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.
 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"
+```