WiRobot SDK Application Programming Interface (API) Reference Manual - (For MS Windows) Version: 1.3.
Table of Contents Convention ...................................................................................................................................... 3 WiRobot SDK Overview ................................................................................................................ 4 WiRobot SDK API Reference for PMS5005.......................................................................... 6 III.1. Sensor Peripherals ......................................................................
VI.1. VI.2. VI.3. VI.4. VI.5. VI.6. VI.7. VI.8. VI.9. VI.10. VI.11. VI.12. VI.13. VI.14. short GetGPS01( ) .............................................................................................................................. 44 short GetGPS02 ( ) ............................................................................................................................ 44 short GetGPS03 ( ) ............................................................................................................
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 © Dr Robot Inc.
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.
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 © Dr Robot Inc.
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.
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).
UWord16 HighWord; void Return value: 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 = 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 channel); Description: These functions are obsolete.
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. System default value for position control: KP = 50; KD = 5; KI _x100 = 0. 3. System default value for velocity control: KP = 50; KD = 5; KI _x100 = 0.
// 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. Each DC motor channel for dual potentiometer sensor utilizes two potentiometer channels.
Syntax: DcMotorPositionTimeCtr (channel, cmdValue, timePeriod); Parameter: short channel; short cmdValue; short timePeriod; Return value: void // 0, 1, 2, 3, 4, or 5 // Target position value // Executing time in milliseconds Remarks: 1. Motor will be enabled automatically by the system when this command is received. 2. Target position value is in the A/D sampling data range 0 to 4095 when using single potentiometer, 0-4428 when using dual potentiometers. 3.
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. The current trajectory planning method for time control is linear.
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.
Return value: void 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 16383 means 50% duty cycle, putting motor in “Stop” stage.
See also: DcMotorPositionTimeCtr, 99 void DcMotorPositionNonTimeCtrAll(short cmd1, short cmd2, short cmd3, short cmd4, short cmd5, short cmd6); Description: DcMotorPositionNonTimeCtrAll sends the position 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 positions without specific execution time period. The motion controller will drive the motor to reach the target position with maximum effort.
Syntax: DcMotorVelocityTimeCtrAll (cmd1, cmd2, cmd3, cmd4, cmd5, cmd6, timePeriods); Parameter: short cmd1; short cmd2; short cmd3; short cmd4; short cmd5; short cmd6; short timePeriod; 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 // Executing time in milliseconds Remarks: 1.
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. 5.
103 void DcMotorPwmNonTimeCtrAll(short cmd1, short cmd2, short cmd3, short cmd4, short cmd5, short cmd6); Description: DcMotorPwmNonTimeCtrAll sends the PWM 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 PWM values without specific execution time period. The motion controller Send the desired PWM pulse width right away.
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. 106 void SetServoTrajectoryPlan(short channel, short TrajPlanMthod); Description: This function is obsolete.
Syntax: ServoNonTimeCtr (channel, cmdValue); Parameter: short channel; short cmdValue; Return value: void // 0, 1, 2, 3, 4, or 5 // Target Pulse Width (ms) * 2250 Remarks: Please refer to the remarks under ServoTimeCtr.
ServoNonTimeCtrAll sends the position control command to all 6 servo motor control channels on the Sensing and Motion Controller (PMS5005) at the same time. The command includes the target position commands without specific execution time period. The motion controller send the desired pulse width to the servo motor right away.
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. 112 StandardSensorEvent Description: When the standard sensor data arrive, this event will be triggered. 113 CustomSensorEvent Description: When the custom expansion sensor (AD and Input) data arrive, this event will be triggered.
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.
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. Syntax: voiceLength = GetVoiceSegLength (); Parameter: void Return value: long voiceLength; // Length of current voice data.
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. V.1. Power Controller API short GetVolRef( ) Description: GetVolRef returns the power controller AD reference voltage (AD value) Syntax: ival = GetVolRef (); Parameter: void Return value: short ival Remarks; The AD reference Voltage Vref = ((ival / 4095) * 3.0 ) * 2 V.2. short GetBat1Vol( ) Description: GetBat1Vol returns the battery1 voltage (AD value) Syntax: ival = GetBat1Vol (); Parameter: void Return value: short ival Remarks: The Battery1 voltage VBat1 = (ival /4095 *Vref ) * 8 V.3.
V.5. short GetBat2Temp( ) Description: GetBat2Temp returns the battery2 temperature sensor (AD value) Syntax: ival = GetBat2Temp (); Parameter: void Return value: short ival The value must be in the range of 1100 – 2500, if beyond this range, stop charging the battery V.6. short GetDCINVol() Description: GetDCINVol returns the DCIN voltage (AD value) Syntax: ival = GetDCINVol (); Parameter: void Return value: short ival Remarks: The DCIN voltage VBat2 = (ival /4095 *Vref ) * 8 V.7.
Parameter: Return value: Bit 0 1 2 3 4 5 6 7 V.9. ival Description X X X X X Power by DCIN Power by Battery 2 Power by Battery 1 byte GetCHGStatus( ) Description: GetCHGStatus Syntax: Parameter: Return value: Bit 0 1 2 - CH 3 – PF 4 -DC 5 – LP 6—FA 7 V.10. void Byte returns the status of power controller.
4 5 6 7 Copyright © Dr Robot Inc.
VI. VI.1. Constellation system API short GetGPS01( ) Description: Get the distance measurement (unit: mm) from the LEFT Constellation receiver module on the car to the selected Constellation transponder (ID = ID1). Syntax: ival = GetGPS01 ( ); Parameter: void Return value: short ival Remarks: If ival = 0x7fff, it means receiver did not get the distance measurement, the transponder with ID1 is out of range. If ival = 0x7ff0, it means receiver did not get any new distance data. VI.2.
Parameter: void Return value: short ival Remarks: If ival = 0x7fff, it means receiver did not get the distance measurement, the transponder with ID4 is out of range. If ival = 0x7ff0, it means receiver did not get any new distance data. VI.5. short GetGPS05 ( ) Description: Get the distance measurement (unit: mm) from the RIGHT Constellation receiver on the car to the selected Constellation transponder (ID = ID1).
Get the distance measurement (unit: mm) from the RIGHT Constellation receiver on the car to the selected Constellation transponder (ID = ID4). Syntax: ival = GetGPS08 ( ); Parameter: void Return value: short ival Remarks: If ival = 0x7fff, it means receiver did not get the distance measurement, the transponder with ID4 is out of range. If ival = 0x7ff0, it means receiver did not get any new distance data. VI.9.
Get the ID of Constellation transponder that the robot is using. The distance measurement that is obtained with getGPS03( ) function is from the LEFT receiver module, and distance measurement that is obtained with getGPS07( ) function is from the RIGHT receiver module. Syntax: ival = getSenID3( ) Parameter: void Return value: byte ival VI.13. byte getSenID4 ( ) Description: Get the ID of Constellation transponder that the robot is using.
Dis_ID2_R = getGPS06 ( ); Dis_ID3_R = getGPS07 ( ); Dis_ID4_R = getGPS08 ( ); } Step 3: Calculate the position based on the information of distance measurement.
(x2,y2,z2) DisSensor (x1,y1,z1) L3 L4 L1 (xR,yR,zR) L2 CarSensorDis (xL,yL,zL) CarHeight The the robot position X = (xL + xR) /2 Y = (yL + yR) /2 Z = zL = zR = z1- CarHeight = z2 - CarHeight Copyright © Dr Robot Inc.
