Module interface

The standard practice for public function names in the Stickybot project is in format MODULENAME_FunctionName. The name is comprised of the module's abbreviated name in uppercase followed by the function name in camel case with the two seperated by an underscore _ .

void _Init(void)

This function is called once upon entry to the module. This allows the module is initialize any module-level variables. This function is called manually from the main menu code upon state switching. Note: there is no deinitialization code. The module is expected to call it's own deinitialization function from update if an EVN_BTN_ABC_HOLD event (or other module-defined exit condition) is seen.

void _OnTick(CmdPacketStruct * Cmd, RptPacketStruct * Rpt)

This function is called every servo loop (once a millisecond) and contains pointers to the command and report structures. This function is responsible for implementing motor commands. It is required that the module fully populate the command packet since it contains uninitialized data. When in doubt, make sure to set Cmd->servos[i].gain.motorOn = 0 where i is the index of a servo that is unused. As long as motorOn is set to zero, the servo will ignore all other elements (it's best practice to zero everything else out in order to make debugging data logs easier.) More information on how to generate motor commands can be found at SB3MotorCommands

unsigned char _Update(EVN_event event)

This function is called as fast as possible (typically receiving event = EVN_NO_EVENT). This function is expected to return either MOD_STILL_ALIVE or MOD_EXIT depending on whether or not the module wants to return to the main menu (note: an EVN_BTN_ABC_HOLD event will be last call to _Update)

Example module code

The standard module contains a .c and .h file located in SB3/Embedded/MainBoard . For this example, we will add the existing Manual Servo Mode. The source code is located in manual_servo.c and manual_servo.h Each module has three public functions which are called from main.c

manual_servo.h example code

#ifndef _MANUAL_SERVO_H_
#define _MANUAL_SERVO_H_

   #include "events.h"
   #include "datastruct.h"

   void MAN_SRV_Init(void);
   void MAN_SRV_OnTick(CmdPacketStruct * Cmd, RptPacketStruct * Rpt);
   unsigned char MAN_SRV_Update(EVN_event event);

#endif

We use the standard method for allowing nested #include files since we require the events.h and datastruct.h inside each behavior headers for the event and packet type definitions. We have the module abbreviation MAN_SRV used to define the three functions _Init, _OnTick and _Update.

main.c example code

Locate the module switching code in main.c by looking for the line:

/************** PLACE TRIGGERS TO USER MODULES HERE **************/

After this line in the source code, there are several case blocks, one for each module. The following code waits for the B button to be held and then connects the manual servo module. The onTickFunc and updateFunc are function pointers that allow the main code to dynamically switch between the various modules.

//Manual servo adjustment module
case EVN_BTN_B_HOLD:

   //Initialize the module
   MAN_SRV_Init();

   //Connect the module
   onTickFunc = MAN_SRV_OnTick;
   updateFunc = MAN_SRV_Update;
break;

Available events to access modules during run-time

Upon power-up, the code enters the main menu state which waits for buttons press (or potentially events from either the serial port or the Bluetooth radio.) There are three buttons connected to the CPU, labelled A, B and C. Modules can be activated by either tapping or holding the buttons. The following nine events (defined in #include<events.h>) can be generated to trigger modules:

• EVN_BTN_A_TAP
• EVN_BTN_B_TAP
• EVN_BTN_C_TAP
• EVN_BTN_A_HOLD
• EVN_BTN_B_HOLD
• EVN_BTN_C_HOLD
• EVN_BTN_AB_HOLD
• EVN_BTN_BC_HOLD
• EVN_BTN_AC_HOLD

The EVN_BTN_ABC_HOLD event is reserved to return the robot to the main menu from any state. This functionality is hard coded into the main menu code, but each module gets a chance to see the event before it loses control.

-- SalomonTrujillo - 05 Mar 2010