HOW TO Compile and Run a HDT for SubSim

This document explains how to build and compile a Hardware Description Table (HDT) for your EyeBot and using it in SubSim.

SubSim and the Eyebot HDT - Hardware Description Table

The Eyebot uses a mechanism called the Hardware Description Table, or HDT, for defining low-level attributes for sensors and actuators. SubSim also supports the HDT format and it is necessary for writing programs that use any sensors or actuators. To load the HDT in SubSim, you have to give the file path in the <Submarine> tag when defining the Submarine object in the world/simulation file. See *.sub Howto or world howto

Creating a HDT

Creating an HDT for SubSim is much easier than for the Eyebot. This is because the void data pointer in the HDT entries point to const char* arrays rather than data structures. The character array corresponds to the name parameter for a sensor/actuator inside a SubSim submarine XML file. The same HDT as above, only this time for SubSim, would be defined as follows.

For more information see http://robotics.ee.uwa.edu.au/eyebot/doc/API/HDT.txt

			
 /* Hardware description table (HDT) */
 extern __declspec(dllexport) HDT_entry_type HDT[] = 
 { 
      {MOTOR,MOTOR_RIGHT, "MotA-R","motor0"}
      {END_OF_HDT,UNKNOWN_SEMANTICS,"END",NULL}
 };
 

The above HDT would only be valid if there existed a submarine, with a motor named motor0, when the HDT was loaded. Otherwise there is no entry created for MOTOR_RIGHT and any calls to MOTORInit(MOTOR_RIGHT) would fail.

Details

The HDT is an array of HDT_entry_type elements.

	
typedef struct
{
  TypeID              type_id;
  DeviceSemantics     semantics;
  String6             device_name;
  void*               data_area;
} HDT_entry_type;

The type_id is an integer specifying the type of hardware the entry represents. The TypeID constants are listed in eyebot_hardware_types.h. Example TypeIDs that are used often are MOTOR, QUAD, PSD, and SERVO. The semantics is an integer that specifies the specific instance of the hardware type. The DeviceSemantics for various common hardware elements are found in eyebot_hardware_sem.h. Example DeviceSemantics that are used often are MOTOR_LEFT, MOTOR_RIGHT, PSD_FRONT, etc... The third variable, device_nameis a short name (6 characters or less) description of the hardware. This is used by the RoBIOS to display a descriptive name when displaying hardware data. The final variable, data_area, is a void pointer that is used to point to the address of any associated data for a specific hardware device.

The void data pointer allows for a great deal of flexibility when using the HDT. RoBIOS defines a set of data types for all available hardware in eyebot_hardware_types.h. In many cases it is easier to define the HDT and the specific hardware separately. A minimal example HDT with a single motor is below.

			
 /* Hardware description table (HDT) */
 extern __declspec(dllexport) HDT_entry_type HDT[] = 
 {
     {MOTOR,MOTOR_RIGHT, "MotA-R",(void*)&motorA}
     {END_OF_HDT,UNKNOWN_SEMANTICS,"END",NULL}
 };
 			
 /* HDT entry point */
 extern __declspec(dllexport) HDT_entry_type *HDTbase = &HDT[0];
 
 /* MOTOR_RIGHT speed look-up table */ 
 BYTE motconvA[101]= 
 { 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4,
   5, 5, 5, 5, 6, 6, 6, 6, 7, 7, 7, 8, 8, 8, 8, 9, 9, 9, 10,10,
   10,11,11,11,12,12,13,13,13,14,14,15,15,15,16,16,17,17,18,18,
   19,19,20,20,21,21,22,23,23,24,25,25,26,27,27,28,29,30,31,32,
   33,34,35,36,37,39,40,42,43,45,47,49,52,54,57,61,66,72,80,94,100 
 };
 
 /* motor data */
 motor_type motorA = {2, 1, TIMER1, 8191, (void*)sim_porte, 2, 3, motconvA};
 

Notice that the HDT is simply an array whose variables are assigned values upon instantiation. In C, an array or structure initializer list is enclosed in curly braces {}. A multi-dimensional array uses nested braces {{1,2,...},{1,2,...}}. The HDT must be initialized when it is first declared.

To use this HDT with an Eyebot, you would compile it with gcchdt to create a .hdt file, then download it to the Eyebot's flash memory. SubSim follows the same conventions as RoBiOS, although the specific hardware data types may differ. The TypeID and DeviceSemantics are the same, however, so this difference is not apparent to a user calling RoBiOS hardware functions. A simple program that uses the above HDT is listed below.

			
 #include eyebot.h
 
 int main(int argc, char** argv[])
 {
     MotorHandle m;
     m = MOTORInit(MOTOR,MOTOR_RIGHT);
     MOTORRelease(m);
     return 0;
 }
 

Compiling a HDT

Using Microsoft Visual Studio 7.1

  1. Create a new Win32 project. In the Win32 Application Wizard set Application type to DLL and Additional options to Empty project.
  2. Open the Project Properties and select the Configuration Properties->Linker->Input. Add EyebotLib.lib to the Additional Dependencies. Select Configuration Properties->C++->General. Add the path to eyebotAPI.h on your system in the Addition Include Directories. Select Configuration Properties->C++->Code Generation. Set the Runtime Library to Multithreaded Debug DLL or Multithreaded DLL (for either debug or release mode).