This document explains how to build and compile a Hardware Description Table (HDT) for your EyeBot and using it in SubSim.
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 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 https://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.
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; }