Explorar o código

update event doc

nico %!s(int64=8) %!d(string=hai) anos
pai
achega
db60d20939
Modificáronse 1 ficheiros con 68 adicións e 22 borrados
  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.
 
-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"
+```