Input and Output Functions
int addMotorOnPort( int portCode )
This method opens a connection to a motor on the given PWM port. It doesn't power the motor at all. The possible values for portCode are:
MOTOR_PORT_01
MOTOR_PORT_23
MOTOR_PORT_45
MOTOR_PORT_67
MOTOR_PORT_89
MOTOR_PORT_1011
MOTOR_PORT_1213
MOTOR_PORT_1415
The return value is either a descriptor for the motor that is used later to set the power for the motor attached to the given port, or an error code. Note that motors use 2 TPU ports, each determining opposing directions. The error code may be one of the following:
INVALID_PORT_ERROR - the port code given is invalid
PWM_PORT_ALREADY_ALLOCATED_ERROR - the port has already being used for something
An example of the use of this code can been seen in the reference for setMotorPower.
(see also setMotorPower)
int setMotorPower( int portDescriptor, float val )
This function sets the PWM output (i.e. power) to a motor attached to the TPU port associated with the given portDescriptor. The first parameter portDescriptor must be a return value of previously calling addMotorOnPort previously. The second parameter val must be a value in the range (-1..1), the range mapping onto a function of applying power fully in one direction to applying power fully in the other, with the middle value 0 meaning no power supplied at all. An example of the use of this function is:
#include <OS.h>
#include <math.h>
int main() {
/**
* Function that turns a motor first one way, then the other.
*/
int portDescriptor;
float val = 0.0;
portDescriptor = addMotorOnPort( MOTOR_PORT_01 );
for ( ;; ) {
setMotorPower( portDescriptor, sin( ( val += 0.01 ) );
}
return 0;
}
float readAnaloguePort( int portNo )
This function allows access the one of the A/D ports on the board. It maps the raw range of 0-255 to a float of range 0..1. You do not have to open this port to use it. If nothing is physically attached to this port, the returned value will float randomly. The is only one possible error value return:
INVALID_PORT_ERROR - note that this is unusually returned as a float value rather than an integer as normal.
(see also addMotorOnPort)
int readEPort( int portNo )
Reads a single bit from the 'E' port. The single parameter portNo is a range from 0..7.
The E port is an 8-bit port providing binary input and output. Although technically it's a single byte-sized port, from the software point of view, it's treated as 8 single-bit ports. Two of the ports are already allocated - these are E port 0, which is attached to the PAUSE/CONTINUE switch, and E port 1, which is attached to the STOP/RESTART switch. You can still read these bits, but not set them. There is a single possible error message:
INVALID_PORT_ERROR - returned in case that the portNo isn't within the range 0..7
(see also setEPort, readFPort, setFPort)
int setEPort( int portNo, int value )
Sets a single bit on the 'E' port. The single parameter portNo is a range from 2..7. The second parameter value determined how to set the port - 0 clears the port, whereas a non-zero value sets it to 1.
The E port is an 8-bit port providing binary input and output. Although technically it's a single byte-sized port, from the software point of view, it's treated as 8 single-bit ports. Two of the ports are already allocated - these are E port 0, which is attached to the PAUSE/CONTINUE switch, and E port 1, which is attached to the STOP/RESTART switch. There is a single possible error message:
INVALID_PORT_ERROR - returned in case that the portNo isn't within the range 0..7
(see also readEPort, readFPort, setFPort)
int readFPort( int portNo )
Reads a single bit from the 'E' port. The single parameter portNo is a range from 0..7.
The F port is an 8-bit port providing binary input and output. Although technically it's a single byte-sized port, from the software point of view, it's treated as 8 single-bit ports. There is a single possible error message:
INVALID_PORT_ERROR - returned in case that the portNo isn't within the range 0..7
(see also readEPort, setEPort, setFPort)
int setFPort( int portNo, int value )
Sets a single bit on the 'F' port. The single parameter portNo is a range from 2..7. The second parameter value determined how to set the port - 0 clears the port, whereas a non-zero value sets it to 1.
The F port is an 8-bit port providing binary input and output. Although technically it's a single byte-sized port, from the software point of view, it's treated as 8 single-bit ports. There is a single possible error message:
INVALID_PORT_ERROR - returned in case that the portNo isn't within the range 0..7
(see also readEPort, setEport, readFPort)
void setExitOnErrorFlag( int errorFlag )
Determines how the library will deal with errors. The single parameter errorFlag should be either 0 or 1.
If this flag isn't set (the default), when it encounters an error, the program will stop and print a message showing what the error is to both the serial port and the LCD screen. If it is set, then the error function will return an error value instead of the normal return value, and the user can deal with the error themselves. For example:
#include OS.h
int main() {
/**
* Shows two types of error handling.
*/
setExitOnErrorFlag( 1 ); Handle error ourselves
if ( setMotorPower( 1, 0.5 ) != NO_ERROR ) {
/**
* Uh-oh! We didn't open the motor
* port before setting it...
*/
printToLCD( "Handling error..." );
}
setExitOnErrorFlag( 0 ); //Set so program ends on error
setMotorPower( 1, 0.5 ); //Same error, but program will end here
return 0;
}
int printToLCD( const char *message )
Note: This function is not yet implemented! This will print a message to the LCD screen. The single parameter message is a null-terminated array of chars.
The return value is an error code.
The LCD screen is 22x2 characters big. Any string larger than 22 characters will be truncated. If both lines are displayed and printToLCD is called again, then the lines will scroll upwards, losing the top one. To print across both lines with one function call, put the escape code n in your string. To move to the first character position in a line without moving on to the next one, put the escape code r in your string.
If the exit-on-error-flag is set (see setExitOnErrorFlag), then when the program ends, an error message will be printed in the LCD screen.
void setGreenLED( int flag )
Sets the green LED on the board either on or off. The single parameter must be either 0 or non-zero.
(see getGreenLED, setRedLED, getRedLED)
int getGreenLED()
Returns a flag value specifying whether or not the green LED on the board is on or off. A return of zero means the light is presently off, whereas a non-zero value means the light is on.
(see setGreenLED, setRedLED, getRedLED)
void setRedLED( int flag )
Sets the red LED on the board either on or off. The single parameter must be either 0 or non-zero.
(see getRedLED, setGreenLED, getGreenLED)
int getRedLED()
Returns a flag value specifying whether or not the red LED on the board is on or off. A return of zero means the light is presently off, whereas a non-zero value means the light is on.
(see setRedLED, setGreenLED, getGreenLED)
|
