embedded system library for e-puck

Introduction

This library provides a straight forward programming interface to the hardwares on the e-puck, including proximity sensors, LEDs, stepper motors, etc. Unlike the standard e-puck lib (has several modules), this library used all-in-one design (one header path, one .a file).

Highlights:

• A user-friendly and fast (40x15 @ 18.4 fps maximum) interface for e-puck's camera.
• Multi-tasking with 'Process' — a mechanism based on cooperative multitasking that enables several functions with time delays run concurrently. For example, asynchronized blinking of two LEDs can be written like this:
  
  With this library, the two while loops in the above code can run concurrently.
• Reshape the concept of hardware timers and interrupts using two object-oriented interfacing models: 'Timer' and 'Trigger'.
• A 'Timer' can be used to produce delay, as well as creating periodic callbacks (similar to the agenda in the e-puck standard library).
• A 'Trigger' can automatically launch a 'Process' once some event occurs, which let you do things only interrupts can do without dealing with hardware interrupts. (This is also known as "Event-Driven Interface").
• The whole library follows "No user code in interrupts" rule, so no multi-access problem needs to be worried. All user code, processes or timer callbacks, are handled within a 'mainloop' function of this lib that is typically placed in the main thread of the microcontroller.

Environment

• MPLAB X with XC16 compiler
• Only support e-pucks with the camera model PO6030K.
• A computer with Bluetooth
• Tiny Bootloader

Related Links

• code distribution page of this library on GitHub > https://github.com/jianingchen/epucklib
• online documentation for this library on GitHub > http://jianingchen.github.io/epucklib/html/
• official site of the e-puck robot > http://www.e-puck.org/
• official page to download MPLAB X IDE > http://www.microchip.com/mplabx/
• official page to download XC16 Compiler > http://www.microchip.com/compilers/
• homepage of Tiny Bootloader > http://www.etc.ugal.ro/cchiculita/software/picbootloader.htm
• homepage of the Natural Robotics Lab > http://naturalrobotics.group.shef.ac.uk/

Repository Contents

The repository should contains the following items:

• el — This is the library directory. All headers and sources are inside.
• el_serial_utility
  • el_serial_com — This is the serial communication utility of the library.
  • Serial — This is the CSerail lib (see http://www.codeproject.com/Articles/992/Serial-library-for-C).
• examples
  • el_example_01.X — This is Example 1.
  • el_example_02.X — This is Example 2.
  • el_example_03.X — This is Example 3.
  • el_example_04.X — This is Example 4.
  • el_example_hw.X — This is the "Hello World" example.
• other_materials — some other related materials

Getting Started

Download and install MPLAB X IDE and the XC16 Compiler. Then, download this library.

Build This Library

1. In MPLAB X, a project is opened by locating its directory. Open the directory of this library.
2. On the tool bar, select the build configuration to be "Static_Lib_xc16_O1" and then click "Build Main Project" (see the image below).
   
3. Wait until the building process is finished.
4. The static library ("el.a") will be generated in "dist/Static_Lib_xc16_O1/production" under the project directory.

Build A Project

To develop for e-puck based on this library, it is recommended to setup a standalone project that links "el.a".

The example project "el_example_hw" is nearly an empty project. Therefore, it can be copied and used as a project with necessary configurations. To setup a project in MPLAB X IDE from scratch, see New Project Setup.

To get more details on using the IDE, read "MPLAB X IDE User's Guide" on the official site of Microchip.

When the building process of the project is finished, a report similar to the following one will appear in the "Output" panel of the IDE:

To guarantee the functioning of the Process module, "maximum length" of stack must be at least 2048 bytes.

The generated HEX file will be in the "dist" folder under the project's folder.

Program The Microcontroller

If the e-puck has Tiny Bootloader's bootloader, the HEX file can be programmed onto the microcontroller using the Tiny Bootloader application via Bluetooth. Otherwise, use a wired programmer (e.g. ICD3 or PICkit3) to program the microcontroller through the ISP port on the e-puck.

To get more details about putting the HEX file into the e-puck, check the homepage of Tiny Bootloader or the official site of e-puck robot.

Examples

In all of these examples, the e-puck will not do anything if the selector position is below 4. The e-puck will also automatically reset it self when the "Write Flash" button in Tiny BootLoader is clicked and proceed to programming.

Example 1

(located in "./examples/el_example_01.X")

In this example, the e-puck flashes some of its LEDs. Sending a char of 'f' through UART1 (the UART channel used by the Bluetooth module) will toggle the front led. In UART1, the e-puck will also report the number of seconds since start running.

This example includes the usage of following modules:

• Process
• LED and Selector
• UART STDIO

Example 2

(located in "./examples/el_example_02.X")

When the e-puck is shaken or detects an impact, it will flash all of its ring LEDs. In UART communication, sending a 'g' makes the e-puck report the outputs of the accelerometers.

This example includes the usage of following modules:

• Process
• Trigger
• Accelerometer
• LED and Selector
• Infrared Receiver
• UART STDIO

Example 3

(located in "./examples/el_example_03.X")

The e-puck can be remotely controlled via Bluetooth. It is recommended to use this program with the serial communication utility of this library.

This example includes the usage of following modules:

• Process
• Trigger
• Timer
• Camera
• LED and Selector
• Stepper Motor
• Infrared Proximity Sensors
• UART STDIO

Example 4

(located in "./examples/el_example_04.X")

The e-puck follows any green object in front of it. Through UART1, color of the object to be followed can be selected among red, green and blue.

This example includes the usage of following modules:

• Process
• Trigger
• Camera
• LED and Selector
• Stepper Motor
• Infrared Proximity Sensors
• UART STDIO

An image processing technique used to tracking the object is also demonstrated in this example.

License & Attributions

The source files starting with "e_" are copied from the e-puck standard library and attribute to whomever own the copyright of the e-puck standard library.

The e-puck embedded system library is distributed under the MIT license.

Logo of the library (see top left of this page) is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

This library has been developed as a part of the PhD of Jianing Chen in Sheffield Robotics, The University of Sheffield.