= Tutorial: Writing the demo Module = This page aims to describe how to write and then run the demo module with GenoM3 either for ros and pocolibs. == Needs == Check this [[genom3/tutorial/install|instruction page]] to install GenoM3 and associated templates and tools. == Demo module with pocolibs == The final result of this tutorial module can be obtained from here. But this tutorial will walk you thru getting your own copy! Still, you can grab it if you want avoiding typing all the code. {{{ git clone git://trac.laas.fr/robots/demo-genom demo-genom-final cd demo-genom-final git checkout genom3 }}} = part 1: 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-genom. {{{ mkdir demo-genom cd demo-genom }}} == 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}}} module declaration * {{{ids}}} * {{{port}}} * {{{exception}}} * {{{task}}} * {{{attribute}}} * {{{function}}} * {{{activity}}} The entire file will look like this: {{{ /* The special / * / marker will copy the associated comment block (here, the * license) in the generated files. */ /*/ * Copyright (c) 1996-2013 CNRS/LAAS * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #include "demoStruct.idl" /* ---- component declaration ---- */ component demo { version "1.1"; email "openrobots@laas.fr"; lang "c"; require "genom3 >= 2.99.20"; /* ---- Data structures and IDS ---- */ ids { demo::state state; /* Current state */ demo::speed speedRef; /* Speed reference */ double posRef; }; /* ---- Port declaration ---- */ port out demo::state Mobile; /* ---- exception declaration ---- */ exception TOO_FAR_AWAY {double overshoot;}; exception INVALID_SPEED; /* ---- Execution task declaration ---- */ task motion { period demo::task_period ms; priority 100; stack 4000; codel InitDemoSDI(out ::ids, port out Mobile) yield ether; }; /* ---- Services declarations ---- */ 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"; }; function Stop() { doc "Stops motion and interrupts all motion requests"; interrupts MoveDistance, GotoPosition; }; activity MoveDistance(in double distRef = 0 :"Distance in m") { doc "Move of the given distance"; validate controlDistance(in distRef, in state.position); codel mdStartEngine(in distRef, in state.position, out posRef) yield exec, ether; codel mdGotoPosition(in speedRef, in posRef, inout state, port out Mobile) yield exec, end; codel mdStopEngine() yield ether; interrupts MoveDistance, GotoPosition; task motion; throw TOO_FAR_AWAY; }; activity GotoPosition (in double posRef = 0 :"Goto position in m") { doc "Move to the given position"; validate controlPosition (local in posRef); codel gpStartEngine() yield exec, ether; codel gpGotoPosition(local in posRef, inout ::ids, port out Mobile) yield exec, end; codel gpStopEngine() yield ether; interrupts MoveDistance, GotoPosition; task motion; throw TOO_FAR_AWAY; }; activity Monitor (in double monitor = 0 :"Monitored absolute position in m", out double position) { doc "Monitor the passage on the given position"; validate controlPosition (in monitor); codel monitor(in monitor, in ::ids) yield start, stop; codel monitorStop(in ::ids, out position) yield ether; task motion; throw TOO_FAR_AWAY; }; }; }}} == Data Structure Definition == The #include "demoStruct.idl" statement works as a header file in C and includes idl data structure. This file contains all the necessary declarations for the definition of the internal database. These structures are then used in the .gen file. In this example, the file "demoStruct.idl" contains the definition of the position and the speed. This file is preferably located in the same directory as {{{demo.gen}}}, since it contributes to the definition of the module interface. {{{ /* * Copyright (c) 1996-2013 CNRS/LAAS * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #ifndef IDL_DEMO_STRUCT #define IDL_DEMO_STRUCT module demo { const unsigned long task_period = 400; const double millisecond = 0.001; struct state { double position; /* current position (m) */ double speed; /* current speed (m/s) */ }; enum speed { SLOW, FAST }; }; #endif /* IDL_DEMO_STRUCT */ }}} == Module generation == Once your description file (.gen and .idl) are ready, you need to generate your module: {{{ gupta[demo-genom] genom3 skeleton demo.gen creating ./codels/demo_motion_codels.c creating ./codels/demo_codels.c creating ./demo-genom3.pc.in creating ./demo-genom3-uninstalled.pc.in creating ./bootstrap.sh creating ./autoconf/ag_templates.m4 creating ./configure.ac creating ./Makefile.am creating ./codels/Makefile.am }}} From now on, the module is ready to be compiled and run, but let's look at the result of the execution of the command: {{{ gupta[demo-genom] ls autoconf configure.ac demo-genom3-uninstalled.pc.in bootstrap.sh demo.gen demoStruct.idl codels demo-genom3.pc.in Makefile.am }}} {{{GenoM3}}} created two new directories {{{codels/}}} and {{{autoconf/}}}, and several new files. * Algorithms (or a part of them) are grouped in the directory {{{codels/}}}. The files in that directory give you template to start from, and also let {{{GenoM3}}} produce a module even if you still do not have written a single line of code. * The Makefile.am and configure.ac files are also under your control. These are the main files which are used for the compilation of the module. == Codels writing == Let's have a look in the codels directory. {{{ gupta[codels] ls demo_codels.c demo_motion_codels.c Makefile.am }}} === demo_codels.c === In this file, we will found codels executed by the control task such as the validateones , e.g. controlSpeed (Validation codel of attribute SetSpeed), controlPosition (Validation codel of activity GotoPosition) and controlDistance (Validation codel of activity MoveDistance).. At the beginning, the template will look like: {{{ gupta[codels] more demo_codels.c /* * Copyright (c) 1996-2013 CNRS/LAAS * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #include "acdemo.h" #include "demo_c_types.h" /* --- Attribute SetSpeed ----------------------------------------------- */ /** Validation codel controlSpeed of attribute SetSpeed. * * Returns genom_ok. * Throws demo_INVALID_SPEED. */ genom_event controlSpeed(demo_speed speedRef) { /* skeleton sample: insert your code */ /* skeleton sample */ return genom_ok; } /* --- Activity MoveDistance -------------------------------------------- */ /** Validation codel controlDistance of activity MoveDistance. * * Returns genom_ok. * Throws demo_TOO_FAR_AWAY. */ genom_event controlDistance(double distRef, double position) { /* skeleton sample: insert your code */ /* skeleton sample */ return genom_ok; } /* --- Activity GotoPosition -------------------------------------------- */ /** Validation codel controlPosition of activity GotoPosition. * * Returns genom_ok. * Throws demo_TOO_FAR_AWAY. */ genom_event controlPosition(double posRef) { /* skeleton sample: insert your code */ /* skeleton sample */ return genom_ok; } /* --- Activity Monitor ------------------------------------------------- */ /** Validation codel controlPosition of activity Monitor. * * Returns genom_ok. * Throws demo_TOO_FAR_AWAY. */ /* already defined in service GotoPosition validation */ }}} You notice that all the codels are empty and return genom_ok. Still the parameters are the corect ones. Here are possible code to include in these functions: === controlSpeed === {{{ genom_event controlSpeed(demo_speed speedRef) { /* insert your code */ if(speedRef != demo_SLOW && speedRef != demo_FAST) return demo_INVALID_SPEED(); return genom_ok; } }}} === controlDistance === {{{ genom_event controlDistance(double distRef, double position) { double lposRef; demo_TOO_FAR_AWAY_detail tfa; lposRef = position + distRef; if (lposRef > DEMO_MACHINE_LENGTH/2 || lposRef < -DEMO_MACHINE_LENGTH/2) { tfa.overshoot = fabs(lposRef) - fabs(DEMO_MACHINE_LENGTH/2); return demo_TOO_FAR_AWAY(&tfa); } return genom_ok; } }}} === controlPosition === {{{ genom_event controlPosition(double posRef) { demo_TOO_FAR_AWAY_detail tfa; if (posRef > DEMO_MACHINE_LENGTH/2 || posRef < -DEMO_MACHINE_LENGTH/2) { tfa.overshoot = fabs(posRef) - fabs(DEMO_MACHINE_LENGTH/2); return demo_TOO_FAR_AWAY(&tfa); } return genom_ok; } }}} Note the exception TOO_FAR_WAY for which we return the length we overshoot the maximum/minimum distance acceptable. Such information can be retrieve by the client/supervisor to take appropriate corrective actions. === demo_motion_codels.c === In this file, we will found codels attached to the '''motion''' task, such as : * InitDemoSDI: which is the codel of the task * gpStartEngine, gpGotoPosition, gpStopEngine: which are , and codels of the '''!GotoPosition''' activity * etc {{{ gupta[codels] more demo_motion_codels.c /* * Copyright (c) 1996-2013 CNRS/LAAS * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #include "acdemo.h" #include "demo_c_types.h" /* --- Task motion ------------------------------------------------------ */ /** Codel InitDemoSDI of task motion. * * Triggered by demo_start. * Yields to demo_ether. */ genom_event InitDemoSDI(demo_ids *ids, const demo_Mobile *Mobile) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_ether; } /* --- Activity MoveDistance -------------------------------------------- */ /** Codel mdStartEngine of activity MoveDistance. * * Triggered by demo_start. * Yields to demo_exec, demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event mdStartEngine(double distRef, double position, double *posRef) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_exec; } /** Codel mdGotoPosition of activity MoveDistance. * * Triggered by demo_exec. * Yields to demo_exec, demo_end. * Throws demo_TOO_FAR_AWAY. */ genom_event mdGotoPosition(demo_speed speedRef, double posRef, demo_state *state, const demo_Mobile *Mobile) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_exec; } /** Codel mdStopEngine of activity MoveDistance. * * Triggered by demo_end, demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event mdStopEngine(void) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_ether; } /* --- Activity GotoPosition -------------------------------------------- */ /** Codel gpStartEngine of activity GotoPosition. * * Triggered by demo_start. * Yields to demo_exec, demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event gpStartEngine(void) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_exec; } /** Codel gpGotoPosition of activity GotoPosition. * * Triggered by demo_exec. * Yields to demo_exec, demo_end. * Throws demo_TOO_FAR_AWAY. */ genom_event gpGotoPosition(double posRef, demo_ids *ids, const demo_Mobile *Mobile) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_exec; } /** Codel gpStopEngine of activity GotoPosition. * * Triggered by demo_end, demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event gpStopEngine(void) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_ether; } /* --- Activity Monitor ------------------------------------------------- */ /** Codel monitor of activity Monitor. * * Triggered by demo_start. * Yields to demo_start, demo_stop. * Throws demo_TOO_FAR_AWAY. */ genom_event monitor(double monitor, const demo_ids *ids) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_start; } /** Codel monitorStop of activity Monitor. * * Triggered by demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event monitorStop(const demo_ids *ids, double *position) { /* skeleton sample: insert your code */ /* skeleton sample */ return demo_ether; } }}} Let's have a look on how we can write such functions: {{{ /* * Copyright (c) 1996-2013 CNRS/LAAS * * Permission to use, copy, modify, and distribute this software for any * purpose with or without fee is hereby granted, provided that the above * copyright notice and this permission notice appear in all copies. * * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ #include "acdemo.h" #include #include #include "demoConst.h" #include "demo_c_types.h" #define SIGN(x) ((x)<0.?-1.0:1.0) /* --- Task motion ------------------------------------------------------ */ /** Codel InitDemoSDI of task motion. * * Triggered by demo_start. * Yields to demo_ether. */ genom_event InitDemoSDI(demo_ids *ids, const demo_Mobile *Mobile) { ids->state.position = 0.0; ids->state.speed = 0; Mobile->data()->position = ids->state.position; Mobile->data()->speed = ids->state.speed; Mobile->write(); /* write the poster. */ ids->speedRef = demo_SLOW; printf ("InitDemoSDI done.\n"); return demo_ether; } /* --- Activity MoveDistance -------------------------------------------- */ /** Codel mdStartEngine of activity MoveDistance. * * Triggered by demo_start. * Yields to demo_exec, demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event mdStartEngine(double distRef, double position, double *posRef) { *posRef = position + distRef; printf("starting engine\n"); return demo_exec; } /** Codel mdGotoPosition of activity MoveDistance. * * Triggered by demo_exec. * Yields to demo_exec, demo_end. * Throws demo_TOO_FAR_AWAY. */ genom_event mdGotoPosition(demo_speed speedRef, double posRef, demo_state *state, const demo_Mobile *Mobile) { double distRemain; double dDist; double v; distRemain = posRef - state->position; v = (speedRef == demo_SLOW) ? DEMO_DEFAULT_MAX_SPEED/4. : DEMO_DEFAULT_MAX_SPEED; dDist = v * demo_task_period * demo_millisecond* SIGN(distRemain); if (fabs(distRemain) < fabs(dDist)) { Mobile->data()->position = state->position = posRef; Mobile->data()->speed = state->speed = 0; Mobile->write(); /* write the poster. */ return demo_end; } Mobile->data()->position = state->position += dDist; Mobile->data()->speed = state->speed = v; Mobile->write(); /* write the poster. */ #ifdef VERBOSE printf ("speed %g m/s pos %g m\n", v, state->position); #endif return demo_exec; } /** Codel mdStopEngine of activity MoveDistance. * * Triggered by demo_end, demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event mdStopEngine(void) { printf ("stop engine\n"); return demo_ether; } /* --- Activity GotoPosition -------------------------------------------- */ /** Codel gpStartEngine of activity GotoPosition. * * Triggered by demo_start. * Yields to demo_exec, demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event gpStartEngine(void) { printf("starting engine\n"); return demo_exec; } /** Codel gpGotoPosition of activity GotoPosition. * * Triggered by demo_exec. * Yields to demo_exec, demo_end. * Throws demo_TOO_FAR_AWAY. */ genom_event gpGotoPosition(double posRef, demo_ids *ids, const demo_Mobile *Mobile) { return mdGotoPosition(ids->speedRef, posRef, &ids->state, Mobile); } /** Codel gpStopEngine of activity GotoPosition. * * Triggered by demo_end, demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event gpStopEngine(void) { return mdStopEngine(); } /* --- Activity Monitor ------------------------------------------------- */ /** Codel monitor of activity Monitor. * * Triggered by demo_start. * Yields to demo_start, demo_stop. * Throws demo_TOO_FAR_AWAY. */ genom_event monitor(double monitor, const demo_ids *ids) { double dDist; dDist = ids->state.speed * demo_task_period * demo_millisecond; if (fabs (monitor - ids->state.position) < dDist) { printf ("dist %f mon %f pos %f\n", dDist, monitor, ids->state.position); return demo_stop; } return demo_start; } /** Codel monitorStop of activity Monitor. * * Triggered by demo_stop. * Yields to demo_ether. * Throws demo_TOO_FAR_AWAY. */ genom_event monitorStop(const demo_ids *ids, double *position) { *position = ids->state.position; return demo_ether; } }}} Note that we include a demoConst.h file which you should also create in the same directory than the codels and containing: {{{ #ifndef DEMO_CONST_H #define DEMO_CONST_H #define DEMO_MACHINE_LENGTH 2.0 /* m */ #define DEMO_DEFAULT_MAX_SPEED 0.5 /* m/s */ #define VERBOSE #endif }}} == Module compilation == We are now ready to compile the module. Note that you could have done it with the empty codels just after generating the skeleton. The result would have been a valid GenoM3 module, runnable, but not doing anyhing of course. There are two steps in compilation of the module: * ''configuration'' of the module by running the configure script * ''compilation'' itself, controlled by the Makefile generated in the previous step. === Bootstrap === * bootstrap the autotools build system {{{ gupta[demo-genom] ./bootstrap.sh autoreconf: Entering directory `.' autoreconf: configure.ac: not using Gettext autoreconf: running: aclocal -I autoconf autoreconf: configure.ac: tracing autoreconf: running: libtoolize --install --copy libtoolize: putting auxiliary files in AC_CONFIG_AUX_DIR, `autoconf'. libtoolize: copying file `autoconf/config.guess' libtoolize: copying file `autoconf/config.sub' libtoolize: copying file `autoconf/install-sh' libtoolize: copying file `autoconf/ltmain.sh' libtoolize: putting macros in AC_CONFIG_MACRO_DIR, `autoconf'. libtoolize: copying file `autoconf/libtool.m4' libtoolize: copying file `autoconf/ltoptions.m4' libtoolize: copying file `autoconf/ltsugar.m4' libtoolize: copying file `autoconf/ltversion.m4' libtoolize: copying file `autoconf/lt~obsolete.m4' autoreconf: running: /usr/bin/autoconf autoreconf: running: /usr/bin/autoheader autoreconf: running: automake --add-missing --copy --no-force configure.ac:24: installing `autoconf/missing' codels/Makefile.am: installing `autoconf/depcomp' autoreconf: Leaving directory `.' }}} === Build directory === In order to keep objects files separated from the sources, for instance when you want to generate the module for several different architectures, or just in order to have a simple mean to clean up everything that was produced during the building phase, it is strongly recommended to create a separate ''build'' directory and run every command from there. {{{ gupta[demo-genom] mkdir build gupta[demo-genom] cd build }}} === Configuration === All the OpenRobots software and tools are generally installed in a specific directory (for instance {{{${HOME}/openrobots}}}). This is the main information that needs to be specified to the {{{configure}}} script. Don't forget to run {{{configure}}} from the build directory. Then, the options will be different given the templates you want to generate, you have several possibilities: * pocolibs ($TEMPLATES=pocolibs/server,pocolibs/client/c) * pocolibs/server is the genom pocolibs module itself * pocolibs/client/c is the pocolibs C client library * ros ($TEMPLATES=ros/server,ros/client/c,ros/client/ros) * ros/server is the genom ros module itself * ros/client/c is the ros C client library * openprs ($TEMPLATES=openprs/client), you can mix openprs template with the others (e.g.: $TEMPLATES=pocolibs/server,pocolibs/client/c,openprs/client) e.g. here, if we set $TEMPLATES=pocolibs/server,pocolibs/client/c {{{ gupta[build] ../configure --prefix=$INSTALL_DIR --with-templates=$TEMPLATES checking for a BSD-compatible install... /usr/bin/install -c checking whether build environment is sane... yes checking for a thread-safe mkdir -p... /bin/mkdir -p checking for gawk... gawk checking whether make sets $(MAKE)... yes checking build system type... x86_64-unknown-linux-gnu checking host system type... x86_64-unknown-linux-gnu ... ... ... checking for pocolibs... yes checking for genom3_pocolibs... yes checking for genom3... yes configure: creating ./config.status config.status: creating Makefile config.status: creating demo-c-client.pc config.status: creating demo-c-client-uninstalled.pc config.status: creating autoconf/acheader.h config.status: executing depfiles commands config.status: executing libtool commands configure: done configuring for pocolibs/client/c }}} === Compilation === To compile the module, just run {{{make}}} from the {{{build}}} directory. The GNU make utility is required, but this is the standard make on linux systems. {{{ make }}} === Installation === The built binaries and libraries (and some associated files) need to be copied to their final locations. This is achieved by executing {{{make install}}}. Depending of the {$INSTALL_PATH} you used, this may require ''root'' privilege. {{{ make install }}} == Module execution == Once compiled, the module is ready to be executed. The module is located in the {{{bin}}} subdirectory of the directory specified as {{{prefix}}} in the configuration step. This is an executable whose name will depend of the $TEMPLATE you choose. E.g., in our case, if we use pocolibs template, we will have {{{demo-pocolibs}}} executable and if you use ros template, we will have {{{demo-ros}}}. === pocolibs === You need to initialise pocolibs, to do so type: {{{ h2 init Initializing pocolibs devices: OK }}} at this point, you can start the module: {{{ demo-pocolibs -b pocolibs execution environment version 2.13 Copyright (c) 1999-2011 CNRS-LAAS demo: created outport demo/genom_state demo: created outport demo/genom_metadata demo: created outport demo/Mobile InitDemoSDI done. demo: spawned motion exec task demo: spawned control task demo: setup and running }}} the -b argument is to start the module in background. -h will indicate the other options available. Now that your module is running, you need to control it, to send request, get report, read the port, etc. For this you need a client, let's start with a tcl client. ==== tcl ==== To control the module with tcl, you need to start the genomixd program, then launch eltclsh which is an interactive tcl shell. {{{ genomixd & eltclsh eltclsh1.14 - Copyright (C) 2001-2012 LAAS-CNRS eltclsh > package require genomix 1.2 eltclsh > genomix::connect genomix1 eltclsh > genomix1 load demo pocolibs execution environment version 2.13 Copyright (c) 1999-2011 CNRS-LAAS demo }}} You can use completion (tab) at any point to get help on the available commands. Exemple: {{{ eltclsh > demo ::demo::GetSpeed ::demo::MoveDistance ::demo::connect_port ::demo::GotoPosition ::demo::SetSpeed ::demo::connect_remote ::demo::Mobile ::demo::Stop ::demo::genom_state ::demo::Monitor ::demo::abort_activity ::demo::kill }}} Note that all the services, port and some default services are provided. You can now play with your module. If you have started the module in the same window, you will see the following results. {{{ eltclsh > ::demo::GetSpeed speedRef ::demo::SLOW eltclsh > ::demo::GotoPosition -h Usage: demo::GotoPosition [-id var] [-s|-send] [-a|-ack] [-t|-timeout milli] [-f|-flat] [-h] [--] input [& ?script?] Input dictionary: double posRef: Goto position in m (0) eltclsh > ::demo::GotoPosition 1 starting engine speed 0.125 m/s pos 0.05 m speed 0.125 m/s pos 0.1 m speed 0.125 m/s pos 0.15 m speed 0.125 m/s pos 0.2 m speed 0.125 m/s pos 0.25 m speed 0.125 m/s pos 0.3 m speed 0.125 m/s pos 0.35 m speed 0.125 m/s pos 0.4 m speed 0.125 m/s pos 0.45 m speed 0.125 m/s pos 0.5 m speed 0.125 m/s pos 0.55 m speed 0.125 m/s pos 0.6 m speed 0.125 m/s pos 0.65 m speed 0.125 m/s pos 0.7 m speed 0.125 m/s pos 0.75 m speed 0.125 m/s pos 0.8 m speed 0.125 m/s pos 0.85 m speed 0.125 m/s pos 0.9 m speed 0.125 m/s pos 0.95 m stop engine eltclsh > ::demo::SetSpeed enum speedRef: Mobile speed (::demo::SLOW) > ::demo::FAST eltclsh > ::demo::Monitor 0 & demo::0 eltclsh > ::demo::GotoPosition double posRef: Goto position in m (0) > -1 starting engine speed 0.5 m/s pos 0.8 m speed 0.5 m/s pos 0.6 m speed 0.5 m/s pos 0.4 m speed 0.5 m/s pos 0.2 m speed 0.5 m/s pos 5.55112e-17 m dist 0.200000 mon 0.000000 pos 0.000000 speed 0.5 m/s pos -0.2 m speed 0.5 m/s pos -0.4 m speed 0.5 m/s pos -0.6 m speed 0.5 m/s pos -0.8 m stop engine }}} Note the monitor which reported when the mobile passes in 0. You can also read the port Mobile: {{{ eltclsh > ::demo::Mobile Mobile {position -1 speed 0} eltclsh > }}} To kill the module: {{{ eltclsh > ::demo::kill demo: terminating on Terminated signal request eltclsh > demo: shutting down motion exec task demo: shutting down control task demo: destroyed outport genom_state demo: destroyed outport genom_metadata demo: destroyed outport Mobile demo: shutdown complete eltclsh > }}} You can also kill genomixd, and clean up h2. {{{ pkill genomixd h2 end }}} === ros === NB: If you want to run the ros version, you need to have configure your system with ros Templates. If you have already configure with another template, you need to restart at the configure command. It is probably better to erase the build directory or make another one: {{{ mkdir build-ros cd build-ros ../configure --prefix=$INSTALL_DIR --with-templates=ros/server,ros/client/c make install }}} If you have not configure yet your module, you should follow Module Compilation instruction from the beginning. If you have configure your module with ros template: You will need to start roscore. {{{ roscore & }}} The ros module has a different name. {{{ demo-ros -b demo: advertising ports demo: initialized outport genom_state demo: motion task initialized and running demo: advertising services demo: control task initialized and running }}} From now on, you can control this module exactly the same way you did with the pocolibs version. You can also see that your ROS based demo module can be seen as a regular ROS node, with its topics, services and actions. {{{ rosnode info demo -------------------------------------------------------------------------------- Node [/demo] Publications: * /demo/GotoPosition/status [actionlib_msgs/GoalStatusArray] * /demo/MoveDistance/result [demo/MoveDistanceActionResult] * /demo/Mobile [demo/demo_state] * /rosout [rosgraph_msgs/Log] * /demo/genom_state [demo/genom_state_component] * /demo/Monitor/feedback [demo/MonitorActionFeedback] * /demo/MoveDistance/feedback [demo/MoveDistanceActionFeedback] * /demo/MoveDistance/status [actionlib_msgs/GoalStatusArray] * /demo/GotoPosition/feedback [demo/GotoPositionActionFeedback] * /demo/Monitor/result [demo/MonitorActionResult] * /demo/GotoPosition/result [demo/GotoPositionActionResult] * /demo/Monitor/status [actionlib_msgs/GoalStatusArray] Subscriptions: * /demo/Monitor/cancel [actionlib_msgs/GoalID] * /demo/GotoPosition/goal [demo/GotoPositionActionGoal] * /demo/MoveDistance/goal [demo/MoveDistanceActionGoal] * /demo/MoveDistance/cancel [actionlib_msgs/GoalID] * /demo/GotoPosition/cancel [actionlib_msgs/GoalID] * /demo/Monitor/goal [demo/MonitorActionGoal] Services: * /demo/connect_port * /demo/kill * /demo/GetSpeed * /demo/get_loggers * /demo/abort_activity * /demo/set_logger_level * /demo/Stop * /demo/SetSpeed * /demo/connect_remote ... ... ... }}} == Demo module with openprs == If you want to control this module with [[openprs]], you will need to install [[transgen3]], and follow this [[transgen3/tutorial/demo-transgen3|tutorial]] to create it.