genom3

h1. Genom3tutorialdemo-genom3

{{toc}}

h2. Needs

h2. How to write your first module ?

This section will illustrate a concrete use of genom3. The demo module will control a virtual mobile that can move in a 1D world. Some of the services the module offers are:

* read and set the current speed at any moment

* move the mobile to a given position

* move the mobile of a given distance (from its current position)

* monitor when the mobile passes a given position

* stop the motion 

Moreover, the demo module export a port with the current state of the mobile (position and speed).

To implement this, we first create a directory named demo-genom3. 

<pre>

mkdir demo-genom3

cd demo-genom3

</pre>

h3. Write .gen file

In that directory, we will write the description file demo.gen. The file demo.gen is made up of several parts, each of them being identified with a keyword

* @component@

* @ids@

* @port@

* @exception@

* @task@

* @attribute@

* @function@

* @activity@

The easiest way is to start from an existing file, so you can download ".gen" file. We will now explain step by step each part of this file.

h4. @component@

The component declaration describes the instance of the GenoM component. It is defined by a unique name (an identifier) that also defines an IDL scope for any embedded types. See the "component declaration documentation":http://homepages.laas.fr/mallet/share/doc/genom3/genom3.html/Component-declaration.html#Component-declaration for details.

<pre>

component demo {

  version	"1.1";

  email		"openrobots@laas.fr";

  lang		"c";

  require	"genom3 >= 2.99.20";

</pre>

* version : The component version number, as a string

* lang : The programming language of the codels interface

* email : A string containing the e-mail address of the author of the component.

* requires : A list of dependencies of the component. It indicates an external dependency on a software package that is required. It assumes that the package is using the pkg-config utility Each string should contain a package name in pkg-config format. 

NB: component declaration is not over, the final } is left for the end @.gen@ file.

h4. @ids@

@ids@ stands for internal data structure, it contains information that need to be shared all over the module. For example here, we consider: 

<pre>

ids {

  demo::state state;          /* Current state */

  demo::speed speedRef;       /* Speed reference */

  double      posRef;

};

</pre>

@demo::state@ and @demo::speed@ are types derived from 

h4. @port@

Ports implement the data flow between components as a publish/subscribe model. Ports have a name and a type and can be either out (for publishing data) or in (for subscribing to a sibling out port). In this example, we choose to export:

<pre>

/* ---- Port declaration ---- */

  port out demo::state Mobile;

</pre>

h4. @exception@

It is possible to 

<pre>

/* ---- exception declaration ---- */

  exception TOO_FAR_AWAY {double overshoot;};

  exception INVALID_SPEED;

</pre>

h4. @execution task@

Tasks define an execution context suitable for running activities. A task may define a state machine and associated codels. 

The state machine starts in the start state when the task is created during component initialization.

Tasks can define the following properties:

* @period@ The granularity of the codel scheduler. Periodic task will sequence the codels they manage at that frequency.

* @delay@ The delay from the beginning of each period after which codels are run. This can be used to delay two tasks running at the same period in the same component.

* @priority@ Can be used to prioritize different tasks whithin the same component.

* @scheduling real-time@ This indicates that the task requires real-time scheduling. This may not be supported by all templates.

* @stack@ Defines the required stack size for this task. The stack size should be big enough to run all codels that the task manages.

In our example, we choose to get the task_period from ...

<pre>

/* ---- Execution task declaration ---- */

  task motion {

    period	demo::task_period ms;

    priority	100;

    stack	4000;

    codel <start>	InitDemoSDI(out ::ids, port out Mobile) yield ether;

  };

</pre>

h4. services declations

h5. @attribute@

<pre>

 attribute SetSpeed(in speedRef = demo::SLOW	:"Mobile speed")

  {

    doc		"To change speed";

    validate	controlSpeed (local in speedRef);

    throw	INVALID_SPEED;

  };

  attribute GetSpeed(out speedRef =	:"Mobile speed")

  {

    doc		"To get current speed value";

  };

</pre>

h5. @function@

<pre>

 function Stop()

  {

    doc		"Stops motion and interrupts all motion requests";

    interrupts	MoveDistance, GotoPosition;

  };

</pre>

h5. @activity@

<pre>

activity MoveDistance(in double distRef = 0	:"Distance in m")

  {

    doc		"Move of the given distance";

    validate	controlDistance(in distRef, in state.position);

    codel <start>	mdStartEngine(in distRef, in state.position,

                              out posRef) yield exec, ether;

    codel <exec>	mdGotoPosition(in speedRef, in posRef, inout state,

                               port out Mobile) yield exec, end;

    codel <end, stop>	mdStopEngine() yield ether;

    interrupts	MoveDistance, GotoPosition;

    task	motion;

    throw	TOO_FAR_AWAY;

  };

</pre>