RobotAPI API

RobotAPI

To build a program that uses the RobotAPI:
gcc progname.cpp RobotAPI.cpp -lpthread -o progname

Global Variables

#define MAX_CONNECTIONS 5 This is the maximum number of secondary connections available.

Global Functions

void robotWait ( int MicroSeconds ) Generates a timed delay for the given number of microseconds. Very processor intensive, do not use with multiple threads.

PointList

Attribute Summary

private int maxsize This is the maximum size of the pointlist. This value can be at most 50, anything larger will cause segmentation faults.

private XYPoint TheList[50] This is the array list of 50 points used to store the data. The maximum possible list size is set at compile time (currently 50). I originally wanted a linked list data structure for this, but sending a linked list over a socket is useless.

private int NumOfPoints This is the current number of points that have been created for the list of points.

Method Summary

public PointList ( int Size ) This method will initialize the PointList data structure. The list will have to use an array to be transmitted over the socket (a linked list is useless because the address on the other side won't have anything in them). So the array needs to have a fixed length set during initialization.

public int addPoint ( int X, int Y ) This will be used for the user program to easily add data points to the list. It will return -1 if the list is already full, else it will return 0 if the operation was successful.

public void pathToString ( char* Path ) This will create a string and store a text representation of the path in the string to be outputted. (Not implemented)

public void printList () This is used during debugging to print out the entire list and other important variables

ConfigSys

Attribute Summary

public char ServerIP[40] A string representing the IP address of the robot controller to connect to.

public int HorizontalArea The number of units wide the Robot Surrogate's working area should be. The vertical distance is calculated from this value by considering the aspect ratio of the window it will be contained in.

public int PortNumber This is the port number to connect to the controller computer.

Method Summary

public void loadConfiguration () Loads the configuration information for the program out of the config.txt file.

abstract RobotAPI

Attribute Summary

protected int PortNumber The port number for the communication socket.

protected int SocketFD The file descriptor for the main communication socket.

protected TesterClass* MessageReceiver I tried to make this a RobotCommandReceiver interface, but C++ doesn't support interfaces quite like Java does. The interface is needed so that the RobotAPI can call the receiveCommand () method when there is an incoming command. The user program can then decide how to handle the incoming commands.

protected int ConnectionOK This is a flag variable used for the safety meausres. Every time data is received from the connection, this variable is changed to 1 (meaning the connection is active and working). The saftey thread meanwhile changes this variable back to 0 (inactive connection) every 1.5 seconds. After 1.5 seconds, if the connection is still inactive, the saftey measures are implemented.

protected int CommunicationSockets[] This is an array of up to MAX_CONNECTIONS communication connections. All of these connections are secondary connections (the main connection is stored in the parent class and is accessed through getSocketFD () and setSocketFD (). Each element in this array is a socket file descriptor to an active secondary connection, or -1 if a connection doesn't exist.

private int ServerSocket The socket file descriptor for the main server socket. The server socket accepts the initial client connections, and then creates a communication socket while it continues to listen for new connections.

Method Summary

RobotAPI () Initializes all the RobotAPI variables, and sets all the different socket file descriptors to -1.

friend void* listenForData ( void* RobotAPIObject ) This method is a friend function of the RobotAPI. It is a friend because a thread cannot start in a member function, it has to be a classical C style function. It is passed a RobotAPI object so it can access the attributes and methods of the RobotAPI. This function listens on the main communication socket for data coming from the main robot. It then calls the receiveCommand () method after the data is received. This function is called from inside of the establishConnection () method, do not call this function from the user program!

friend void* sendNullCommand ( void* RobotAPIObject ) This method runs as a thread, and simply sends a null command every 0.1 seconds. This is used to keep the safety measures from activating even if new commands are even being sent.

friend void* safetyOverride ( void* RobotAPIObject ) This method is run as a thread. The method simply sets the ConnectionOK variable to 0, then waits 1.5 seconds. After 1.5 seconds, it checks ConnectionOK, if ConnectionOK is still 0, then the safety measures start. If ConnectionOK is 1, the method restarts.

protected void startSafetyOverride ( void ) Creates and starts a thread that executes the safetyOverride () method. This is called during the establishConnection () of the main connection.

public int sendCommand ( RobotCommand CommandToExecute ) This method sends a command to all of the connections by calling the sendCommandTo () method with each socket file descriptor specified. This method is used by both RobotAPIRobot and RobotAPIController. This method returns a 1 on a failure, and 0 on a success.

public void setPort ( int PortNum ) Sets the communication socket's port number. Only use this method before establishConnection () is called. Calling it afterwards, will have no effect.

public void setReceiver ( TesterClass* InterfaceForAPI ) This method gives the RobotAPI access to the receiveCommand () method of the program. It establishes a way for the RobotAPI to talk back to the program. Call this method before the establishConnection () method is called.

protected int getSocketFD () This is so the children of RobotAPI can access the file descriptor for the main communciation connection. For some odd reason, the children couldn't just direcly access this attribute; the value wasn't always updated correctly.

protected void setSocketFD ( int SFD ) The children classes use this method to set the main connection file descriptor.

protected int sendCommandTo ( RobotCommand CommandToExecute, int SFD ) This command sends the data to the specified socket. This command is called from sendCommand () method.

RobotAPIController

Method Summary

friend void* waitForNewConnections ( void* RobotAPIControllerObject ) This method is called by the establishConnection () method. This method runs in a thread, and waits for any secondary connection attempts. Up to MAX_CONNNECTIONS secondary connections can be made. The connections are added in order into the CommunicationSockets[], and once a connection is closed, that connection can never be reestablished. The connection can be restarted, but it will take up another connection bringing you closer to the connection limit.

friend void* listenOnSecondaryConnection ( void* RobotAPIControllerObject ) This function runs in a thread and is started every time a new secondary connection is established. The secondary connection data is ignored by the program, but the sockets need to be read to determine when they become disconnected. When a socket gets disconnected, this method will change the corresponding element of CommunicationSockets[] to -1. This is a friend function because a member function isn't accepted as a valid function for a thread, a traditional C style function is required.

public int establishConnection () This method establishes the main server socket and waits for the first connection (which will become the main connection) before returning. It returns a -1 if an error occurs (along with printing an error message) and return a 0 on a sucess. As soon as the first connection is established, this method starts a thread that runs the waitForNewConnections () method. After the secondary listening thread is started, the function returns.

RobotAPIRobot

Method Summary

public int establishConnection ( char* IPAddress ) This method is used to connect the robot to the controller application. This method will return immediantly. It returns a -1 if an error occurs (along with printing an error message) and return a 0 on a sucess. If the method is successful, it will start a thread listening for the incoming commands.

RobotCommand

Attribute Summary

public int Value This attribute is used for simple commands like CHANGE_ORIENTATION or CHANGE_SPEED. When receiving a CURRENT_STATUS command, this attribute is the steering motor input.

public int ValueB When receiving a CURRENT_STATUS command, this value is the robot's speed.

public int ValueC When receiving a CURRENT_STATUS command, this value is the robot's orientation.

public int XCoordinate Cartesian coordiante x of a point during a GOTO_XY or CURRENT_STATUS command.

public int YCoordinate Cartesian coordiante y of a point during a GOTO_XY or CURRENT_STATUS command.

public Path PointList A list of points creating a path during a FOLLOW_PATH command.
Method Summary

public void copyCommand ( RobotCommand Source ) Copies the contents of the source command into the object calling the copyCommand method.

abstract RobotCommandReceiver

Method Summary

public void receiveCommand ( char InstructionCode, RobotCommand* Command ) This class is supposed to be an interface for the RobotAPI to the main program. Unfortunatly, interfaces aren't really supported in C++ like they are in Java, so this isn't working yet.

TesterClass

Method Summary

public int RunMe () This function is where I put the majority of my code for my user program. This class was created to simulate the abstract RobotCommandReceiver that didn't quite work as planned in C++

public void receiveCommand ( char InstructionCode, RobotCommand* NewCommand ) This method is called by the RobotAPI when it receives a command. The InstructionCode is a character representing the command. This is useful when setting up a switch statement to handle the incoming commands easily. When the program finishes with the RobotCommand be sure to delete so the program does not leak memory.

XYPoint

Attribute Summary

public int X Cartesian coordinate x of a point

public int Y Cartesian coordiante y of a point

public XYPoint* NextPoint Pointer to the address of the next point in a linked list of points. If NextPoint is NULL, then this is the last point in the list.

Method Summary

public XYPoint() Pointless constructor created during debugging

Global Variables
`#define MAX_CONNECTIONS 5`	This is the maximum number of secondary connections available.
Global Functions
`void robotWait ( int MicroSeconds )`	Generates a timed delay for the given number of microseconds. Very processor intensive, do not use with multiple threads.

Attribute Summary
`private int maxsize`	This is the maximum size of the pointlist. This value can be at most 50, anything larger will cause segmentation faults.
`private XYPoint TheList[50]`	This is the array list of 50 points used to store the data. The maximum possible list size is set at compile time (currently 50). I originally wanted a linked list data structure for this, but sending a linked list over a socket is useless.
`private int NumOfPoints`	This is the current number of points that have been created for the list of points.
Method Summary
`public PointList ( int Size )`	This method will initialize the PointList data structure. The list will have to use an array to be transmitted over the socket (a linked list is useless because the address on the other side won't have anything in them). So the array needs to have a fixed length set during initialization.
`public int addPoint ( int X, int Y )`	This will be used for the user program to easily add data points to the list. It will return -1 if the list is already full, else it will return 0 if the operation was successful.
`public void pathToString ( char* Path )`	This will create a string and store a text representation of the path in the string to be outputted. (Not implemented)
`public void printList ()`	This is used during debugging to print out the entire list and other important variables

Attribute Summary
`public char ServerIP[40]`	A string representing the IP address of the robot controller to connect to.
`public int HorizontalArea`	The number of units wide the Robot Surrogate's working area should be. The vertical distance is calculated from this value by considering the aspect ratio of the window it will be contained in.
`public int PortNumber`	This is the port number to connect to the controller computer.
Method Summary
`public void loadConfiguration ()`	Loads the configuration information for the program out of the `config.txt` file.

Attribute Summary
`protected int PortNumber`	The port number for the communication socket.
`protected int SocketFD`	The file descriptor for the main communication socket.
`protected TesterClass* MessageReceiver`	I tried to make this a `RobotCommandReceiver` interface, but C++ doesn't support interfaces quite like Java does. The interface is needed so that the RobotAPI can call the `receiveCommand ()` method when there is an incoming command. The user program can then decide how to handle the incoming commands.
`protected int ConnectionOK`	This is a flag variable used for the safety meausres. Every time data is received from the connection, this variable is changed to 1 (meaning the connection is active and working). The saftey thread meanwhile changes this variable back to 0 (inactive connection) every 1.5 seconds. After 1.5 seconds, if the connection is still inactive, the saftey measures are implemented.
`protected int CommunicationSockets[]`	This is an array of up to `MAX_CONNECTIONS` communication connections. All of these connections are secondary connections (the main connection is stored in the parent class and is accessed through `getSocketFD ()` and `setSocketFD ()`. Each element in this array is a socket file descriptor to an active secondary connection, or -1 if a connection doesn't exist.
`private int ServerSocket`	The socket file descriptor for the main server socket. The server socket accepts the initial client connections, and then creates a communication socket while it continues to listen for new connections.
Method Summary
`RobotAPI ()`	Initializes all the `RobotAPI` variables, and sets all the different socket file descriptors to -1.
`friend void* listenForData ( void* RobotAPIObject )`	This method is a friend function of the `RobotAPI`. It is a friend because a thread cannot start in a member function, it has to be a classical C style function. It is passed a `RobotAPI` object so it can access the attributes and methods of the `RobotAPI`. This function listens on the main communication socket for data coming from the main robot. It then calls the `receiveCommand ()` method after the data is received. This function is called from inside of the `establishConnection ()` method, do not call this function from the user program!
`friend void* sendNullCommand ( void* RobotAPIObject )`	This method runs as a thread, and simply sends a null command every 0.1 seconds. This is used to keep the safety measures from activating even if new commands are even being sent.
`friend void* safetyOverride ( void* RobotAPIObject )`	This method is run as a thread. The method simply sets the `ConnectionOK` variable to 0, then waits 1.5 seconds. After 1.5 seconds, it checks `ConnectionOK`, if `ConnectionOK` is still 0, then the safety measures start. If `ConnectionOK` is 1, the method restarts.
`protected void startSafetyOverride ( void )`	Creates and starts a thread that executes the `safetyOverride ()` method. This is called during the `establishConnection ()` of the main connection.
`public int sendCommand ( RobotCommand CommandToExecute )`	This method sends a command to all of the connections by calling the `sendCommandTo ()` method with each socket file descriptor specified. This method is used by both `RobotAPIRobot` and `RobotAPIController`. This method returns a 1 on a failure, and 0 on a success.
`public void setPort ( int PortNum )`	Sets the communication socket's port number. Only use this method before `establishConnection ()` is called. Calling it afterwards, will have no effect.
`public void setReceiver ( TesterClass* InterfaceForAPI )`	This method gives the `RobotAPI` access to the `receiveCommand ()` method of the program. It establishes a way for the `RobotAPI` to talk back to the program. Call this method before the `establishConnection ()` method is called.
`protected int getSocketFD ()`	This is so the children of `RobotAPI` can access the file descriptor for the main communciation connection. For some odd reason, the children couldn't just direcly access this attribute; the value wasn't always updated correctly.
`protected void setSocketFD ( int SFD )`	The children classes use this method to set the main connection file descriptor.
`protected int sendCommandTo ( RobotCommand CommandToExecute, int SFD )`	This command sends the data to the specified socket. This command is called from `sendCommand ()` method.

Method Summary
`friend void* waitForNewConnections ( void* RobotAPIControllerObject )`	This method is called by the `establishConnection ()` method. This method runs in a thread, and waits for any secondary connection attempts. Up to `MAX_CONNNECTIONS` secondary connections can be made. The connections are added in order into the `CommunicationSockets[]`, and once a connection is closed, that connection can never be reestablished. The connection can be restarted, but it will take up another connection bringing you closer to the connection limit.
`friend void* listenOnSecondaryConnection ( void* RobotAPIControllerObject )`	This function runs in a thread and is started every time a new secondary connection is established. The secondary connection data is ignored by the program, but the sockets need to be read to determine when they become disconnected. When a socket gets disconnected, this method will change the corresponding element of CommunicationSockets[] to -1. This is a friend function because a member function isn't accepted as a valid function for a thread, a traditional C style function is required.
`public int establishConnection ()`	This method establishes the main server socket and waits for the first connection (which will become the main connection) before returning. It returns a -1 if an error occurs (along with printing an error message) and return a 0 on a sucess. As soon as the first connection is established, this method starts a thread that runs the `waitForNewConnections ()` method. After the secondary listening thread is started, the function returns.

Method Summary
`public int establishConnection ( char* IPAddress )`	This method is used to connect the robot to the controller application. This method will return immediantly. It returns a -1 if an error occurs (along with printing an error message) and return a 0 on a sucess. If the method is successful, it will start a thread listening for the incoming commands.

Attribute Summary
`public int Value`	This attribute is used for simple commands like CHANGE_ORIENTATION or CHANGE_SPEED. When receiving a CURRENT_STATUS command, this attribute is the steering motor input.
`public int ValueB`	When receiving a CURRENT_STATUS command, this value is the robot's speed.
`public int ValueC`	When receiving a CURRENT_STATUS command, this value is the robot's orientation.
`public int XCoordinate`	Cartesian coordiante x of a point during a GOTO_XY or CURRENT_STATUS command.
`public int YCoordinate`	Cartesian coordiante y of a point during a GOTO_XY or CURRENT_STATUS command.
`public Path PointList`	A list of points creating a path during a FOLLOW_PATH command.
Method Summary
`public void copyCommand ( RobotCommand Source )`	Copies the contents of the source command into the object calling the `copyCommand` method.

Method Summary
`public void receiveCommand ( char InstructionCode, RobotCommand* Command )`	This class is supposed to be an interface for the `RobotAPI` to the main program. Unfortunatly, interfaces aren't really supported in C++ like they are in Java, so this isn't working yet.

Method Summary
`public int RunMe ()`	This function is where I put the majority of my code for my user program. This class was created to simulate the abstract `RobotCommandReceiver` that didn't quite work as planned in C++
`public void receiveCommand ( char InstructionCode, RobotCommand* NewCommand )`	This method is called by the `RobotAPI` when it receives a command. The `InstructionCode` is a character representing the command. This is useful when setting up a `switch` statement to handle the incoming commands easily. When the program finishes with the `RobotCommand` be sure to delete so the program does not leak memory.

Attribute Summary
`public int X`	Cartesian coordinate x of a point
`public int Y`	Cartesian coordiante y of a point
`public XYPoint* NextPoint`	Pointer to the address of the next point in a linked list of points. If `NextPoint` is `NULL`, then this is the last point in the list.
Method Summary
`public XYPoint()`	Pointless constructor created during debugging