Khepera III Toolbox/The Toolbox/Modules/khepera3

The khepera3 module provides access to all sensors and actuators of the robot and it divided into the following parts:
 * General: firmware version and timestamp
 * Motor: left and right motor (accessed individually)
 * Drive: drive system (both motors)
 * Infrared: infrared sensors, in ambient or proximity mode
 * Ultrasound: ultrasound sensors
 * Battery: battery voltage, current and charge level

Even though each part is implemented in a separate file, it is sufficient to include khepera3.h, which includes all other files.

Description
The khepera3 module is build around a statically allocated data structure called khepera3. This structure is hierarchically organized and contains fields for all sensors and actuators. A few fields are set at module initialization (khepera3_init), but most fields are updated by the sensor functions provided by this module.

To get a measurement for any sensor, first call the appropriate sensor function (e.g. khepera3_infrared_proximity). When this function returns, the corresponding fields in the khepera3 data structure will contain the new values. Some sensors also return a timestamp, which is a 32bit-counter incremented at regular time intervals. The interval is not precisely defined, and the counter overflows (i.e. restarts at 0 after having reached 2^32-1). Nevertheless, the timestamp is sometimes useful to find out at what regularity measurements are taken.

For actuator functions (e.g. khepera3_drive_set_speed), on the other hand, the values are directly passed as arguments to the function call, and not through the khepera3 structure. Note that for all drive functions, the left motor value is specified before the right motor.

Error Handling
All functions return either -1 to indicate success, or 0 to indicate failure. Failure usually means that the data could not be tranferred over the I2C bus to the microcontroller in charge of the corresponding sensor or actuator. Such errors may occasionally appear, and most often require to cold reboot (switch off, wait a few seconds, then switch on again) the robot.

Therefore, it is not worth implementing sophisticated error handling procedures - either let the program crash (or not work properly) in such cases, or quit cleanly upon failure.

Multi-Threaded Programs
Since the khepera3 structure is allocated statically, it is not safe to call functions which update the same fields from two different threads. I.e. calling khepera3_infrared_proximity results in a race condition. The same also applies to the underlying i2cal module, which makes use of statically allocated structures as well. Thread safety interferes with programming simplicity here, which would suffer if these structures were not allocated statically.

API
Since the function and variable names are self-explanatory, we do not provide a huge documentation here, but instead list functions, constants and structures of each module part. For a more exhaustive documentation, refer to the .h files.

Motor
Motor functions take one of &(khepera3.motor_left) and &(khepera3.motor_right) as first argument.

Drive
Drive functions act on both motors and therefore use and modify both khepera3.motor_left and khepera3.motor_right in the khepera 3 data structure.