25 Valleywood Drive, Unit 20 Markham, Ontario, L3R 5L9, Canada Tel: (905) 943-9572 Fax: (905) 943-9197 WiRobot SDK Application Programming Interface (API) Reference Manual - (For MS Windows) Version: 1.3 JUN.
Table of Contents Convention.......................................................................................................................................... 2 WiRobot SDK Overview ................................................................................................................... 3 WiRobot SDK API Reference for PMS5005............................................................................ 5 III.1. Sensor Peripherals ..............................................................
I. Convention Data Type int: UWord16: short: 16 bit signed interger 16 bit unsigned interger 16 bit signed interger Syntax Syntax under each API reference is based on the C/C++ calling convention. Corresponding Visual Basic calling convention can be found in relevant VB reference book, or from the WiRobot VB code examples. Copyright © 2007, Dr Robot Inc. All Rights Reserved. www.DrRobot.
II. WiRobot SDK Overview WiRobot Software Development Kit (SDK) is a part of the WiRobot development system. Being a PCbased software framework for robotic system development, the SDK contains the facilities for memory management, system communication and user interface, and the utilities for audio, video input/output, sensor data acquisition and motion control.
PMB5010 controllers. Data in between WiRobot hardware and the “WiRobot SDK ActiveX Module” is managed and transferred by the supplied WiRobot Gateway Program (WiRobotGateway.exe) with the shared memory as shown in Figure II.2. Figure II.2 WiRobot Software Architecture Copyright © 2007, Dr Robot Inc. All Rights Reserved. www.DrRobot.
III. WiRobot SDK API Reference for PMS5005 WiRobot SDK APIs for PMS5005 are grouped under the categories of Sensor Peripherals, Motion Control, Multimedia Control and Events. III.1. Sensor Peripherals This section contains the APIs for the operations of different sensor peripherals. III.1.1.
Remarks: 1. The default update rate is 20Hz. User can set up the data refresh rate according to real system requirements. 2. System is default to continuously sending all data when bootup. See Also: SetSysMotorSensorPeriod, SetSysStandardSensorPeriod, SetSysCustomSensorPeriod, SetSysAllSensorPeriod.
DisableCustomSensorSending disables batch updating custom sensor packets. DisableAllSensorSending disables batch updating all the sensor packets. Syntax: DisableMotorSensorSending(); DisableStandardSensorSending (); DisableCustomSensorSending (); DisableAllSensorSending (); // motor related sensors // standard sensors // custom sensors // all the sensors Parameter: void Return value: void See Alao: SystemMotorSensorRequest, SystemStandardSensorRequest, SystemCustomSensorRequest, SystemAllSensorRequest.
III.1.2. Range and Distance Sensors 17 18 19 20 21 22 23 short GetSensorSonar1 (); short GetSensorSonar2 (); short GetSensorSonar3 (); short GetSensorSonar4 (); short GetSensorSonar5 (); short GetSensorSonar6 (); short GetSensorSonar (short channel); Description: GetSonarSensorX returns the current distance value between the relevant ultrasonic range sensor module (DUR5200) and the object in front of it. The unit is cm.
Return Value <=585 585 to 3446 >=3446 Distance to Object 80 cm or longer 80 to 8 cm 0 to 8 cm Remarks: The relationship between the return data and the distance is not linear. Please refer to the sensor’s datasheet for distance-voltage curve. The data returned is the raw data of the analog to digital converter. The output voltage of the sensor can be calculated from the following equation: Sensor output voltage = (ival) * 3.0 / 4095 (V) (e.g. Sharp GP2Y0A21YK “http://sharp-world.
27 28 short GetSensorHumanMotion1 (); short GetSensorHumanMotion2 (); Description: GetSensorHumanMotion returns the current human motion value from DHM5150 Human Motion Sensor Module. Please refer to the DHM5150 hardware manual for detailed information.
Where 90DegreeGValue and ZeroGValue are module-specific values that can be measured by experiment: 1. Place the sensor level, so that the gravity vector is perpendicular to the measured sensor axis 2. Take the measurement and this value would be the ZeroGValue 3. Rotate the sensor so that the gravity vector is parallel with the measured axis 4. Take the measurement and this value would be the 90DegreeGValue 5.
Parameter: void Return value: short ival; Return data interpretation: Temperature (˚C) = (ival – 1256) / 34.8 III.1.6. Infrared Remote Control Handling 34 35 36 37 short GetSensorIRCode1(); short GetSensorIRCode2(); short GetSensorIRCode3(); short GetSensorIRCode4(); Description: GetSensorIRCodeX returns the four parts of a two-16-bit-code infrared remote control command captured by the Sensing and Motion Controller (PMS5005) through the Infrared Remote Controller Module (MIR5500).
Parameter: UWord16 LowWord; UWord16 HighWord; void Return value: st // 1 word nd // 2 word Remarks: 1. In infrared communication application, the data format and the interpretation can be defined by the user at the application level. 2. In infrared remote control application, the control command should be compatible to the device to which the command is sent. 3. This API function is under development and will be available shortly. III.1.7.
42 43 short GetSensorRefVoltage (); short GetSensorPotVoltage (); Description: GetSensorRefVoltage returns the current value of the reference voltage of the A/D converter of the controller DSP. GetSensorPotVoltage returns the current value of the power supply voltage of the potentiometer position sensors.
Parameter: void short Return value: short channel; // for GetSensorPotX /* 0, 1, 2, 3, 4, or 5 for Potentiometer # 1, 2, 3, 4, 5, 6 */ ival; Return data interpretation & Remark: 1. The return data is the raw value of the analog to digital converter indicating the output voltage of the sensor. The data range is between 0 and 4095. The angular position can be calculated as follows, with the 180˚ position defined at sensor’s physical middle position.
ival = GetMotorCurrent4 (); ival = GetMotorCurrent5 (); ival = GetMotorCurrent6 (); ival = GetMotorCurrent (short channel); Parameter: void short Return value: short // Current sensor #4 // Current sensor #5 // Current sensor #6 // Current sensor #1,2,3,4,5,or 6 // for GetMotorCurrentX // 0,1,2,3,4,5 for current sensor #1,2,3,4,5,or 6 channel; ival; Return data interpretation: The return data is the raw value of the analog to digital converter indicating the motor current.
(3) GetEncoderSpeedX returns the rotation speed. The unit is defined as pulse change within 1 second. And it is the absolute value. See also: SetDcMotorSensorUsage(). III.1.11.
The return data is the raw value of the analog to digital converter indicating the input voltage levels. The data range is between 0 and 4095. The voltage levels can be calculated from the following equation: Sensor output voltage = (ival) * 3.0 / 4095 (V) See also: GetSensorBatteryAD1~3 73 short GetCustomDIN(); Description: GetCustomDIN returns a value with lower 8-bits corresponding to the 8-channel custom digital inputs.
III.2. Motion Control This section contains the APIs for the operations of DC motors and standard RC servo motors. The digital controlled DC motor system is depicted as the following diagram. G E + Controller U DC Motor F Potentiometer In the case of PID control, the transfer function of the PID controller looks like as: U (s) / E (s) = K P + K D S + K I / S When using potentiometers (optical encoder and etc.
ival = SetMotorPolarity3 (short polarity); // Motor #3 ival = SetMotorPolarity4 (short polarity); // Motor #4 ival = SetMotorPolarity5 (short polarity); // Motor #5 ival = SetMotorPolarity6 (short polarity); // Motor #6 ival = SetMotorPolarity (short channel, short polarity); // motor#1, 2, 3, 4, 5, or 6 Parameter: short polarity; //1 or -1 short channel; // 0, 1, 2, 3, 4, or 5 for Sonar #1, 2, 3, 4, 5, 6 Return value: void ival; 82 83 void EnableDcMotor (short channel); void DisableDcMotor ( short channe
Syntax: SetDcMotorPositionControlPID (channel, KP, KD, KI _x100); SetDcMotorVelocityControlPID (channel, KP, KD, KI _x100); Parameter: short channel; short KP; short KD; short KI_x100; // 0, 1, 2, 3, 4, or 5 // Proportional gain // Derivative gain // 100 times KI (the desired Integral gain), when KI_x100 = 100, the actual integral control term is KI = 1, KI _x100 with range of 0 ~ 25599 Return value: void Remarks: 1. When setting KI = 0, that means NO integral control 2.
short SensorType; // 0, 1, or 2 for dual potentiometer sensor // 0 or 1 for quadrature encoder // 0 -- Single potentiometer sensor // 1 -- Dual potentiometer sensor // 2 – Quadrature encoder Return value: void Remarks: 1. The electrical angular range of the potentiometer position sensor is 0˚ to 332˚ and the corresponding mechanical rotation range is 14˚ to 346˚, when the 180 position is defined at sensor’s physical middle position. 2.
Description: DcMotorPositionTimeCtr sends the position control command to the specified motion control channel on the Sensing and Motion Controller (PMS5005). The command includes the target position and the target time period to execute the command. The current trajectory planning method with time control is linear.
4. When using encoder as sensor input, the target position value is the pulse count in the range of 0- 32767. See also: DcMotorPositionTimeCtr, GetSensorPot 94 void DcMotorVelocityTimeCtr(short channel, short cmdValue, short timePeriods); Description: DcMotorVelocityTimeCtr sends the velocity control command to the specified motion control channel on the Sensing and Motion Controller (PMS5005). The command includes the target velocity and the time period to execute the command.
Remarks: 1. Motor will be enabled automatically by the system when this command is received 2. No velocity is available for motor channel using single potentiometer sensor 3. The unit of the velocity is (Position change in A/D sampling data) / second when using dual potentiometer sensor for rotational position measurement and pulse/ second when using quadrature encoder. 4. Please refer to the description of GetSensorPot for data conversion between angular values and the A/D sampling data values.
Syntax: DcMotorPwmNonTimeCtr (channel, cmdValue); Parameter: short channel; short cmdValue; Return value: void // 0, 1, 2, 3, 4, or 5 // Target pulse width value Remarks: 1. The specified channel (motor) will be enabled automatically by the system when this command is received 2. Target pulse width value range is 0 to 32767 (0x7FFF), corresponding to the duty cycle of 0 to 100% linearly. 3. A pulse width value of 16363 means 50% duty cycle, putting motor in “Stop” stage.
3. Please refer to the description of GetSensorPot for data converting between angular values and the A/D sampling data values. 4. When using encoder as sensor input, the target position value is the pulse count in the range of 0- 32767. 5. When some motors are not under controlled, their command values should be set as -32768 (0x8000). That means NO_CONTROL.
100 void DcMotorVelocityTimeCtrAll(short cmd1, short cmd2, short cmd3, short cmd4, short cmd5, short cmd6, short timePeriods); Description: DcMotorVelocityTimeCtrAll sends the velocity control command to all 6 DC motor control channels on the Sensing and Motion Controller (PMS5005) at the same time. The command includes the target velocities and the time period to execute the command. The trajectory planning method for time control is linear.
Parameter: short cmd1; short cmd2; short cmd3; short cmd4; short cmd5; short cmd6; Return value: void // Target velocity for channel #1 // Target velocity for channel #2 // Target velocity for channel #3 // Target velocity for channel #4 // Target velocity for channel #5 // Target velocity for channel #6 Remarks: 1. Motor will be enabled automatically by the system when this command is received 2. No velocity is available for motor channel using single potentiometer sensor 3.
2. Target pulse width value range is 0 to 32767 (0x7FFF), corresponding to the duty cycle of 0 to 100% linearly. 3. A pulse width value of 16363 means 50% duty cycle, putting motor in “Stop” stage. Any value in between 16364 - 32767 will put the motor to turn clockwise (facing the front side of the motor) and any value in between 0 – 16362 will put the motor to turn counter-clockwise. 4. When some motors are not under controlled, their command values should be set as -32768 (0x8000). That means NO_CONTROL.
III.2.2. RC Servo Motor Control 104 void EnableServo (short channel); 105 void DisableServo (short channel); Description: EnableServo enables the specified servo motor control channel. DisableServo disables the specified servo motor control channel. Syntax: EnableServo (channel); DisableServo (channel); Parameter: short channel; Return value: void // 0, 1, 2, 3, 4, or 5 Remarks: All servo motor channels are disabled initially at system startup. They need to be enabled explicitly before use.
and model dependant, they are around 1ms, 1.5ms and 2.0ms respectively for most common servos. Experiments are required to obtain the exact value which varies for different servo motors. 108 void ServoNonTimeCtr(short channel, short cmdValue); Description: ServoNonTimeCtr sends the position control command to the specified servo motor control channel on the Sensing and Motion Controller (PMS5005). The command includes the target position command without specific execution time period.
Remarks: 1. Please refer to the remarks under ServoTimeCtr. 2. When some servo motors are not under controlled, their command values should be set as -32768 (0x8000). That means NO_CONTROL. See also: ServoTimeCtr 110 void ServoNonTimeCtrAll (short cmd1, short cmd2, short cmd3, short cmd4, short cmd5, short cmd6); Description: ServoNonTimeCtrAll sends the position control command to all 6 servo motor control channels on the Sensing and Motion Controller (PMS5005) at the same time.
Parameter: LPCTSTR bmpFileName; Return value: void // Full path of the BMP file for displaying Remarks: The graphic LCD display is mono with dimension of 128 pixels by 64 pixels. The bmp image must be 128x64 pixels in mono. III.4. Events This section documents the four Event mechanisms. When the relevant data arrive from the WiRobot PMS5005 system, relevant event will be fired, user could write his / her periodic data processing routine in the relevant event call back function.
IV. WiRobot SDK API Reference for PMB5010 WiRobot SDK APIs for PMB5010 supports advanced Multimedia Control features. IV.1. Multimedia Control This section contains the APIs for the operations of audio input and output, image capturing and LCD display. IV.1.1. Audio Input and Output 115 void PlayAudioFile(LPCTSTR fileName); Description: PlayAudioFile sends an audio file (.wav format) to the Multimedia Controller (PMB5010). The file will be played back on the speaker.
Syntax: lpVal = GetVoiceSegment(); Parameter: void Return value: long lpVal; // pointer to current voice data. Remark: (1) You should use method GetVoiceSegLength() to get the length of the Voice segment. (2) Voice data is in PCM raw data format with 16bit, 8KHz sampling rate. 118 long GetVoiceSegLength(); Description: GetVoiceSegLength returns the length of current voice data in memory.
StopRecord sends stop-recording command to the Multimedia Controller (PMB5010). SDK will not send recorded voice data to PC any more. Syntax: StopRecord(); Parameter: void Return value: void Remarks: There will be no effect if the Multimedia Controller is not recording. IV.1.2. Image Capturing 121 void TakePhoto(); Description: TakePhoto sends image capturing command to the Multimedia Controller (PMB5010).
2. When the image data arrive, the call back event “ImageEvent” will be fired 3. The cause of “failure to save” could be caused because the TakePhoto command was not sent or the file name / path is invalid. IV.1.3. LCD Display 123 void LcdDisplayPMB(LPCTSTR bmpFileName); Description: LcdDisplayPMB displays the image data in the file bmpFileName (BMP format) on the graphic LCD connected to the Multimedia Controller (PMB5010).
V. WiRobot DRK6000/8000 Specific APIs V.1. Low Level Protection Front When bumpers (optional) are installed on WiRobot RDK6000/8000 with the connection configuration shown on the right, a build-in lowlevel bumper collision protection scheme can be enabled or disabled with the next two commands.
