Differences

This shows you the differences between two versions of the page.

--- scenario_file_format [2017/09/01 09:07] – created mimbert
+++ scenario_file_format [2017/09/01 10:41] – mimbert
@@ Line 1: / Line 1: @@
 The scenario of a minus task is a file named ''scenario.yaml'', located at the toplevel of the task directory.
-The syntax of the file is [YAML](http://www.yaml.org/start.html), a popular file format. The full YAML specification is quite large but only a small subset of YAML is needed for scenario files, and this subset is very intuitive, and easily understandable just by looking at a ''scenario.yaml'' example.
+====== Syntax ======
+The syntax of the file is [YAML](http://www.yaml.org/start.html), a popular file format. The full YAML specification is quite large but only a small subset of YAML is needed for scenario files, and this subset is very intuitive, and easily understandable just by looking at a ''scenario.yaml'' example. See for example [[gnu_radio_benchmark_example#inspecting_the_example_task|the GNURadio benchmark example scenario]]. Otherwise, you can read the [[#Grammar]] section below to get a more formal description of the scenario grammar.
 Please bear in mind that YAML is indentation sensitive, just like python. YAML will follow whatever indentation system the scenario file uses, provided that it is consistent within the file. Note that in particular you should not mix spaces and tabs (beware, some text editors do that silently and need to be properly configured to avoid that). The suggested best practice is to use two spaces for indentation.
+Comments in YAML start with a ''#''
+The syntax of a yaml file may be checked with http://www.yamllint.com/
+====== Grammar ======
+The scenario.yaml file is structured as follows:
+  * It //MUST// contain a //description// key, value pair whose value is a string: ''description: <string>''
+  * It //MUST// contain a //duration// key, value pair, whose value is an integer, the max experiment duration expressed in seconds: ''duration: <integer>''
+  * It //MUST// contain a //nodes// key, whose value is a mapping (aka hash, or dictionnary): ''nodes:''. This mapping //MUST// contain:
+    * Nodes key, value pairs, whose keys are the node names (in the set //node1// to //node40//, and whose values are mappings:
+      * which //MUST// contain a //command// key, value pair, whose value is the command line string which will be run on the corresponding node: ''command: <string>''. Note that any filesystem path may be absolute or relative. If relative, it will be relative to the task top directory on the node. Note also that minus does NO magic with filesystem permissions, thus if a script or binary is to be executed, it needs to have executable permissions set before creating the task.
+      * which //MAY// contain a //passive// key, value pair, whose value is a boolean (default is ''false''). A minus task will terminate when the first of the following conditions occur: its //duration// is exceeded or all its //active// nodes terminate.
+Thus, an example scenario could be:
+<code>
+description: Dummy scenario example
+duration: 60
+nodes:
+  node1:
+    command: sleep 1000
+    # a bash command
+    passive: true
+  node2:
+    command: ./myscript
+    # relative path to a script embedded in the task
+  node3:
+    command: gnuradio-config-info -v
+    # calling a gnuradio executable which is in the $PATH
+  node4:
+    command: /cortexlab/toolchains/current/share/gnuradio/examples/uhd/usrp_wfm_rcv.py
+    # absolute path to a script or binary
+</code>