4.3 Getting Data From the Robot Base
The base offers the robot programmer status, error and operational information. The base generates an error report automatically whenever it detects an anomalous situation.
With status reports, the base keeps the programmer informed of data gathered and compiled by its internal controllers. For instance, the motion controllers continually integrate translation and rotation information in order to generate an running estimate of how far the robot has moved from some initial position. The programmer can periodically check on the continually updated status information.
Sometimes, the programmer issues a command to the base and needs a response. Did therequested action actually happen? How is the battery voltage? The base provides this information.
Many commands to the base are requests that it perform a particular action, such as checking the battery status, and returning the voltage value to the user program. Since this might take a bit of time, the user program doesn’t wait around until the base is ready to report. Rather, your user program can register a callback for each kind of data the base offers.
Use registerBaseCallback to specify which of your user program routines you want called when the base returns an error message or an event completion message.
Use registerStatusCallback to specify which of your user program routines you want called when the base returns updated status data in its status data structure.
Use registerWatchdogCallback to register a which of your user program functions you want called when the base’s watchdog timer expires.
The user program routines you specify will receive an OpCode, specifying to which command the base is responding. And, if appropriate, the base also returns a value. For example, when the base notifies your program that a requested rotational motion is completed, it does not need to return a value. But when you’ve requested the battery voltage, the base returns that voltage value to your program, along with the OpCode.
Error Report and Event Completion Callbacks
Sometimes, the robot’s base encounters an error condition. For example, perhaps the base requires more torque to move that you’ve allowed it with the setTranslateTorque command. When it tries to perform a translation motion you’ve requested, the base generates an error report.
In addition, many commands to the base are requests that it perform a particular action, such as moving forward a few meters, or rotating about its axis. Your program wants to know when those requested actions have been performed.
To handle such situations, register a callback to be called whenever the base reports an error or completes a requested action. This function is called with a single unsigned char argument, with one bit set for every error the base reports. To register the callback, call registerBaseCallback.
void registerBaseCallback(void funct (ulong, ulong))
Specifies which of your program’s functions to call when the response requested by a command to the base is ready. The value returned to your callback routine is called an OpCode. These opcodes are defined in the file baseMessages.h. OpCodes you might getfrom registerBaseCallback include such indicators as BASE_rotateHalt , BASE_rotateError, BASE_translateHalt or BASE_translateError.
void rotateCurrent();
Requests that the base report how much current is flowing through the rotation axis motor. The base returns the OpCode BASE_rotateCurrent, and the value of the current in units of tenths of amps.
void translateCurrent();
Requests that the base report how much current is flowing through the translation axis motor. The base returns the OpCode BASE_translateCurrent, and the value of the current, in units of tenths of amps.
Unwittingly running the robot’s onboard batteries down low enough can cause the robot’s onboard computers to crash unexpectedly. It can also damage the batteries themselves. Therefore, it’s a good idea to keep tabs on the battery voltage. To get the current voltage of the robot’s onboard batteries, your program first registers a callback with registerBaseCallback. Later, when you need to check on the batteries, you’d call batteryVoltage. As soon as the base has checked the battery and obtained a voltage reading, it calls your registered callback function with an OpCode of BASE_batteryVoltage along with the battery voltage value.
void batteryVoltage ( );
Commands the base to report back the voltage of its onboard batteries. The OpCode returned is BASE_batteryVoltage; the value is the battery voltage, in tenths of volts.
Your user program can specify which base status information it wants reported and how often it wants to see reports. One way your program can check on status information is to look at the reports delivered periodically by the base. As updated information arrives from the base, it is placed into a global status report structure, defined in the file mcpStatus.h, that your program can then consult as needed. Or, your program can call registerBaseCallback to register a callback that will be passed back a pointer to the status report structure only when updated status information has arrived.
Depending on your program’s needs, the status report may contain either voluminous or sparse information. For instance, your program might be intensely curious about the estimated X and Y axis position of the base, but not particularly care about the current value of the base clock. Therefore, you can specify that the status reports you see contain only the information you’re interested in.
In estimating the robot’s current X and Y coordinates and heading, the controllers assume that the robot is operating in an X-Y coordinate system with a specific origin and orientation. Then, as the base rotates and translates, it can make a reasonably accurate estimate of the robot’s position with respect to the coordinate system at any given time. To simplify the use of these estimates, your user program can reset the origin and heading of the coordinate system relative to the robot’s current position and orientation.
void registerStatusCallback (statusHandler);
Specifies which of your user program functions you want called when the base has an updated status report available. You supply a pointer to the status data structure.
void statusReportPeriod (unsigned long heading);
Determines the interval at which you want the base to send status reports. Intervals are in 1/256ths of a second. For example, if you want a ½ second interval, set the parameter to 128. The maximum number of reports you can get per second is 10.
