Khepera III Toolbox/Writing your Own Modules

If you add want to use the same piece of code in multiple programs (i.e. a sensor board interface, or a common algorithm), it may be useful to create a module. Such a module can be included and used in all your programs.

The Khepera III Toolbox provides you with a module template and a Makefile.

Preparing the Environment edit

Make sure that you have a working development environment as described in Writing your Own Programs.

Creating a New Module edit

To create a new module, type

cd my_khepera3_module_directory
k3-create-module my_new_module

where my_new_module denotes the name of your module. This creates a folder my_new_module with a header and an implementation file (my_new_module.h ,my_new_module.c). A Makefile is created as well.

To check if everything is all right, try to compile the new module:

cd my_new_module
make

This should create an archive my_new_module.a.

You can now edit the files my_new_module.h and my_new_module.c. In case your module is more complex, you can of course create additional my_new_module_*.c and my_new_module_*.h files (note the prefix my_new_module_!). All these additional files will automatically be compiled and available to the programs including the module.

Testing the Module edit

A module cannot be executed by itself. To test a module, you must create a program that includes this module. To include your module, add the following line to the Makefile of your program:

MY_MODULES := path/to/my_new_module

This will tell the compiler to look for the *.h files of that module, and to integrate the my_new_module.a archive into the program. (If your program needs multiple modules, simply add them on the same line. Note that all module folders must reside at the same location.)

Now, you can use the functions of the module in your program, and test them therewith. Note that whenever you change code in your module, you need to first recompile the module, and then recompile the program.

Miscellaneous edit

Renaming a Module edit

The name of the binary executable can be changed in the Makefile by modifying the line

ARCHIVE := my_new_module.a

Note that the archive should always have the same name as the project folder, suffixed by .a.

Including Modules in a Module edit

A module can include other modules. To include standard modules, add the following line (with the modules you want to add, of course) to the Makefile:

MODULES := khepera3 commandline i2cal

To include other modules that you wrote on your own, add

MY_MODULES := path/to/my_other_module_1 path/to/my_other_module_2

to the Makefile.

SVN / Versioning System Issues edit

Just as for programs, we strongly suggest using a versioning system such as SVN (Subversion) to store your Khepera III modules. SVN is probably the most prominent system today, and easy to set up and use.

If you are using a versioning system, you should check in the following files of your module:

  • All source files (*.c, *.h)
  • The Makefile
  • The compiled archive (*.a) (such that a compiled copy is available for those who don't have a compiler set up)
  • Any additional files that the program needs

You should not check in:

  • Intermediate compilation files (*.o, *.d)