------------------------------------------------------------- Rules and Conventions for using GaitBuilder with RiSE Revisions: created: ulucs Wed Dec 1 16:15:06 EST 2004 ------------------------------------------------------------- GaitBuilder is a collection of Matlab scripts that facilitate the generation of custom gait RC files to be used with the RiSE control software. Gaits in RiSE consist of periodic piecewise linear profiles for the crank (in beta coordinates) and wing degrees of freedom for each leg. This README.txt outlines a set of guidelines for creating GaitBuilder scripts together with file naming conventions and requirements. -------------------------------------------------- Concepts: - gait family: This refers to a specific choice of parameterization of the generation of leg profiles. Normally, the set of possible piecewise linear profiles is infinite. Gait families reduce this space to a finite dimension and present a limited set of parameter variables and choices. A gait family is not usable by itself on the robot. There MUST be a GaitBuilder script associated with each family. - gait instance: This refers to a gait family with a specific set of parameter values chosen, instantiating the family for a particular behavior. Usually, different gait instances correspond to different "tuning" experiments wherein developers adjust particular timings, angles etc. Each gait instance MUST have its own Matlab script, which will choose parameter values and call the corresponding gait family script. -------------------------------------------------- Naming conventions: - Naming of scripts: Matlab scripts associated with gait families and instances MUST have one of following formats: cg_.m cg___.m cgx_.m cgx___.m where is the name of the gait family (such as metachronal, ripple, faripple etc.). This MUST be chosen to be DESCRIPTIVE. Names such as gait1, mygait, yetanothergait ARE NOT ACCEPTABLE. Every time a structural change to the gait is made (i.e. change in the parameterization) a NEW SCRIPT must be created with a new and descriptive gait family name. In contrast, is the name given to the particular instance of the gait. Usually, this refers to the operating conditions for which the gait is being tuned. For example, the name can include the slope, the surface type, maximum stride period etc. The field is optional and can be used to distinguish between slight variations on parameters. Developers must follow these guidelines almost religiously to prevent Demo-time confusion and facilitate collaboration. - Naming of gaits (and associated RC files): Gait RC files will be automatically generated from the gait instance Matlab scripts. Developers of new families must ALWAYS make sure that the generated files are named with the following conventions: cg___.rc cgx___.rc where , and MUST correspond to the scripts with which this gait file was generated. -------------------------------------------------- Relevant directories and organization - GaitBuilder tools are located in RoboDevel/RiSE/Tools/Matlab/GaitBuilder. The following Matlab command will ensure that these tools can be located by the gait family and instance scripts: addpath( '~/RoboDevel/RiSE/Tools/Matlab/GaitBuilder' ); You only need to execute this command once after Matlab is started. - All gait family and instance scripts are located under oDevel/RiSE/Tools/Matlab/GaitScripts. This directory can be further organized into subdirectories for categorization of scripts based on institution, behaviors etc. - All gait RC files are located under RoboDevel/RiSE/Demo/Config/default. This directory will further be organized with subdirectories to prevent cluttering. -------------------------------------------------- General Guidelines: - Using existing gait families to create behaviors: In order to do this, you need to create an M-file which fills in a PARAMS struct with appropriate values for parameters and call the M file for the gait family. All family implementations must use the following parameters (and possibly more): params.gait_name : Identifier name to appear on the GUI. Note that this will automatically be prefixed by a family identifier params.instance_name : Name of the calling gait instance (string) params.instance_version : Version of the calling gait instance (string) - Creating new gait families This is somewhat more involved that simply tuning existing gait families. The easiest way to do this is to copy and edit one of the M files for example gait families. There are a number of points to be careful about: * You MUST properly edit the comments at the beginning of the file to reflect the changes you make to the file. DO NOT leave these comments as they appear in the copied example file. * Use MEANINGFUL parameter names to be passed in the PARAMS structure. They should not be one or two character variables, but should be understandable, meaningful names. Try to avoid hardcoding any values. The gait families should be as parameterizable as possible. Put some time and thought into its design NOW, and it will save all the RiSE group a lot of time in the future. * MAKE SURE to properly set 'family_name' in the M file and conform to the standard file naming conventions described above. DO NOT leave these settings as they are. The filename is generated using family_name, params.instance_name and params.instance_version. The name of the gait should be set to the value supplied in params.gait_name. * Once again: Please properly comment all newly created gait family files and use meaningful variable names at all times.