KURT2xxx.DLL: Dynamic Link Library (DLL) for KURT2

Objective

The library KURT2xxx.DLL enables an application executed by the PC system to control the real world robot KURT2, i.e. to receive all appropriate sensor values and to supply motor commands according to desired behaviors, without taking care of the very low level details of microcontroller programming and CAN communication. It is a Win32 interface for easy access to the CAN messages transmitted and received by KURT2's firmware, as described in the documentation of the C167 firmware. The xxx in KURT2xxx.DLL stands for the variety of CAN interface cards that may be used to connect the PC to CAN bus. Currently, these variants are available:

Functionality of KURT2xxx.DLL

All functions return a character string describing the reason for an eventual error that occurred during the execution. This message may contain the original function return code of the Softing API as described in [1]. A NULL pointer is returned if the function was completed successfully.

Some functions have an output parameter time, which means the timestamp when the corresponding CAN message was received by the CAN controller, measured in microseconds since the controller was started. This feature may be useful as an aid to confirm that the connection between PC and microcontroller is still alive. Note: this parameter is only set when using a Softing CAN interface card, which has a built-in timer.

There are several functions with the purpose to control the motors. The general rule for conflict resolution in this case is that only the last command counts. An application may either use the function can_motor to have complete control over the motor controllers hardware, or it may use a function like can_speed to activate a special controller, which is implemented in the firmware.

char *can_init(int *version)

The function can_init performs the necessary initialization of the CAN interface and defines all the CAN message objects used. It must be called by the control application exactly one time, before any of the other functions of KURT2xxx.DLL is called. The function delivers the version number of the DLL in use * 100 (e.g. value 120 means version 1.20). FYI: the speed of the CAN bus is set to 1 Mbaud.

char *can_sonar0_3(int *sonar0, int *sonar1, int *sonar2, int *sonar3, unsigned long *time)

The function can_sonar0_3 delivers the current values of the sonar sensors 0 - 3 in raw format.

char *can_sonar4_7(int *sonar4, int *sonar5, int *sonar6, int *sonar7, unsigned long *time)

The function can_sonar4_7 delivers the current values of the sonar sensors 4 - 7 in raw format.

char *can_sonar8_9(int *sonar8, int *sonar9, unsigned long *time)

The function can_sonar8_9 delivers the current values of the sonar sensors 8 - 9 in raw format.

char *can_current(int *left, int *right, unsigned long *time)

The function can_current delivers the current values of the left and right motor's current sensor in raw format.

char *can_tilt(int *tilt1, int *tilt2, unsigned long *time)

The function can_tilt delivers the two current values of the tilt sensor in raw format.

char *can_compass(int *curve1, int *curve2, unsigned long *time)

The function can_compass delivers the current values of the electronic compass (curve1 and curve2) in raw format.

char *can_encoder(int *left, int *right, unsigned long *time)

The function can_encoder delivers the current values of the left and right motor's encoders in raw format, represented as number of encoder signals per 100 msec.

char *can_bumper(char *value, unsigned long *time)

The function can_bumper delivers the current values of the bumpers 0 - 5 in a single byte, containing '0' at the corresponding bit position if the bumper is pressed and '1' otherwise, i.e. 0x3F means "no bumper is pressed".

char *can_rc(char *value, unsigned long *time)

The function can_rc delivers the current values of the remote control's buttons 0 - 7 in a single byte, containing '0' at the corresponding bit position if the button is pressed and '1' otherwise, i.e. 0xFF means "no button is pressed".

char *can_adc2nd0_3(int *adc2nd0, int *adc2nd1, int *adc2nd2, int *adc2nd3, unsigned long *time)

The function can_adc2nd0_3 delivers the current values - in raw format - of the analog sensors attached to channels 0 - 3 of the optional second microcontroller.

char *can_adc2nd4_7(int *adc2nd4, int *adc2nd5, int *adc2nd6, int *adc2nd7, unsigned long *time)

The function can_adc2nd4_7 delivers the current values - in raw format - of the analog sensors attached to channels 4 - 7 of the optional second microcontroller.

char *can_adc2nd8_11(int *adc2nd8, int *adc2nd9, int *adc2nd10, int *adc2nd11, unsigned long *time)

The function can_adc2nd8_11 delivers the current values - in raw format - of the analog sensors attached to channels 8 - 11 of the optional second microcontroller.

char *can_adc2nd12_15(int *adc2nd12, int *adc2nd13, int *adc2nd14, int *adc2nd15, unsigned long *time)

The function can_adc2nd12_15 delivers the current values - in raw format - of the analog sensors attached to channels 12 - 15 of the optional second microcontroller.

char *can_motor(int left_pwm, char left_dir, char left_brake, int right_pwm, char right_dir, char right_brake)

The function can_motor controls the left and right motor. The two motors are controlled by three parameters: pulse width (similar to voltage), direction of rotation and brake (switch motor on or off).

Pulse width for left and right motor may be set separately to a value between 0 and 1024, where the meaning of 0 is "full power", 256 is corresponding to a duty cycle of 75 %, 512 is corresponding to a duty cycle of 50 %, and the meaning of 1024 is "no power at all". The intermediate values are treated in an analogous manner.

Direction is controlled by one character, where 0 means "forward" and 1 means "back".

Brake is controlled by one character, where 0 means "brake off" (i.e. actually drive) and 1 means "brake on".

char *can_speed(int left_speed, int right_speed)

The function can_speed sets the desired speed of the left and right motor. The speed for left and right motor may be set separately to a value between -100 and +100, where the meaning of -100 is maximum speed back, 0 means no speed at all, and the meaning of +100 is maximum speed forward. The intermediate values are treated in an analogous manner. The desired speed will be maintained by the firmware with means of a proportional controller. To understand the control characteristic, its implementation may be studied (function control_speed in file kurt2mc.c).

char *can_time(unsigned long *time)

The function can_time delivers the current time of the CAN controller as described above. Note: this function is only available when using a Softing CAN interface card, which has a built-in timer.

char *can_close(void);

The function can_close releases and unlocks system resources. It should be called at any possible application exit after successful call to can_init.

References

[1] SOFTING GmbH: CAN-AC2-104 User Manual. Version 4.0 September 1999
[2] Phytec Elektronik GmbH: CAN-Treiber für Win95/98 und WinNT 4.0, Software-Manual. 1. Auflage April 1999
[3] MicroControl: CANpie User Manual Version 0.8 Rev. A



$Id: win32dll.htm,v 1.3 2002/03/20 09:54:51 worst Exp $