3.2 The BeeSoft™ Parameter Structure
Users of precursors to the BeeSoft™ package are familiar with a parameter file called Robot.h. Please be aware that Robot.h and bRobot.h have been removed from BeeSoft. If your applications used the old parameter file, you can use oldRobot.h and your code will still compile.
All new development work should utilize the new BeeSoft parameter file, beeSoft.ini. With beeSoft.ini, configuration is a runtime event rather than a compile time event.
BeeSoft™ Parameters: An Overview
In the BeeSoft-supplied file bUtils.h, you’ll find the definition of the global robot parameters structure, bRobotParams, and the global instance of it named bRobot, which is provided by libbUtils.a. These definitions make it easy for user application programs to employ a straightforward, consistent method of specifying the configuration of a particular robot and other environmental variables. Using the definitions in beeSoft,ini and bUtils.h, the programmer can consistently specify all the descriptive information needed in one handy location, accessed by one simple, flexible set of tools.
Consistent, exclusive use of these new structures will render BeeSoft programs runtime portable between different platforms, such as B14's and B21's. Wander, the example application program discussed later in this chapter, has been written using these parameters.
Runtime parameter lists in BeeSoft programs must be accessed through the parameter file commands listed below. Parameters are added to the parameter list in sequence. The last value added is the one that is used. The hierarchy of priorities is as follows:
1. Default values, hard-coded into beeSoft.ini
2. A parameter file you specify.
You can specify parameters through either as environment variables, or as command line arguments. Command line arguments, as they are added last, have the highest priority, and override any hard-coded or predefined parameter values. You can specify virtually any parameter, for example, TCXHOST, on the command line for runtime use.
Review the files bUtils.h and beeSoft.ini carefully . And, as you study the sample application program wander later in this chapter, pay special attention to how wander uses the BeeSoft global parameter structure.
NOTE: Calls that end in M malloc memory that you must free up afterwards yourself.
bParametersAddArray (struct bParamList *list, const char *prefix, int argc, char const * argv);
Appends command line arguments or any other array or arguments to the bParamListstructure for a program. The array terminates at argc elements or when argv[i]==NULL, whichever comes first. The -parameter==value format is used instead of -parameter value because the latter either doesn’t allow a value without a parameter, or doesn’t allow negative-valued parameters. Items that don’t both begin with "-" and contain an "=" are ignored.
bParametersAddEntry (struct bParamList * list, contr char *prefix, cont char *name, const char *value);
Appends an entry to the bParamList structure for a program.
bParametersAddEnv (struct bParamList *list, const char *prefix, const char *env);
Appends environment variable(s) to a program’s bParamlist structure.
bParametersAddFile (struct bParamList *list, FILE *fp);
Appends the contents of a file, such as a parameter file, to a program’s bParamlist structure.If the structure is NULL, create it. If the list is !NULL, append to it. If fp==NULL, or the specified file is empty, or the specified file does not begin with "[bParamFile]" or the routine is unavailable to malloc a block of memory, the routine returns NULL. If the routine returns NULL, and the bParamList structure was NULL to begin with, the newly-created list is freed by the routine before it returns. The only case of lost data that had been inserted in the bParamList structure will be a malloc failure when starting with list==NULL. All other failures will occur before creating the list structure. File syntax error will be returned as "ERROR" entries in the list.
bFindDirM (const char *dirName);
This routine searches in standard locations for a directory, and will return a char * to the directory name. The entire pathname is returned. NOTE: The space pointed to by the returned char * is malloc’ed by bFindDirM() and must be freed by the calling user program or function.
bFindFileM (const char *name);
This routine searches in standard locations for a configuration file, and will return char * to the file name. The entire pathname is returned. NOTE: The space pointed to by the returned char * is malloc’ed by bFindFileM() and must be freed by the calling user program or function.
void bParameterFillParams (struct bParamList *list);
This command fills in the global bParamList structure bRobot in the program.
bParametersFreeList (struct bParamList * list);
Frees the space occupied by a program’s bParamList structure.
bParametersGetParam (const struct bParamList * list, const char *prefix, const char* name);
bDaemonize (const char *logfile);
This will put the specified program into background. While running, its output will be directed to <logfile>.stdout and <logfile>.stderr
3.2.2 String Handling in the Parameters Structure
bGetArrayElementM (const char *arrayStr, int dimc, const int *userIndex);
Using the value passed in as an index into an array, extracts an element, as a string, from within bParamList and returns it to the caller. NOTE: The space pointed to by the returned char * is malloc’ed by bGetArrayElementM() and must be freed by the calling user program or function.
bStrToBaud (const char *baudStr);
This will convert a string representing a baud rate, such as one extracted from the bParamList structure, into an actual baud rate value that can be input to the program routines.
int bStrToTruth (const char *str);
This interprets a string, such as one extracted from the bParamList structure, to be either true (1) or false (0). It looks for "yes", "y", "true" and "t" and interprets all of these strings as having a value of true. It looks for "no", "n", "false" and "f" and interprets all of these strings as having a value of false. (All of these tests are case insensitive.) If none of the first tests find a match, the string is converted, using strtol (). If the result is zero (0), 0 is returned; otherwise, 1 is returned.
