TamuBot Version 3.0: Parker01
 
Search this site

Software Developer Guide

Download Server Source: TAMUBotServer.zip
Download Client Source: TAMUBotClient.zip

Introduction:

------------------------------------------------------------------------------------------------------------------------------------------------------

The purpose of this software package is to facilitate the use of the TAMU Bot robotic research platform. The software allows the user to control the robot, set experiment and sensor parameters, and receive data input from the robot and its sensors. The goal of this software is to eliminate any need for a laptop riding with the robot, which is dangerous as well as inefficient in terms of accessing and controlling experiment data and parameters.

===================================================================================

Visual Overview:

------------------------------------------------------------------------------------------------------------------------------------------------------

The higher-level code is organized in the following manner:


===================================================================================

Files:

------------------------------------------------------------------------------------------------------------------------------------------------------

The remaining unmentioned files deal with supporting these files. The respective purposes for the files shown above is described below:
  • tamuclient.cpp: This is the main driver program for the software package. This code is responsible for initializing the socket with the sock_connect function, then beginning the socket_read thread to listen for commands from the server. It also is responsible for communicating with the spi_thread, which is responsible for the wheels. It must detect if the speed has been changed by the server and communicate this change with the spi_thread.
  • init_sock.cpp: This file contains the sock_connect function responsible for initializing the socket connection with the server. It also contains the read_socket and write_socket threads. The read_socket thread is responsible for listening to the socket and parsing any commands sent from the server. This thread initializes the sensor threads depending on which sensors the server requests to be used. The read_socket thread is also the point where the application terminates if the server sends the command to stop. The write_socket thread is responsible for writing the contents of the transmission queue (txQ) onto the socket. The thread will write until there is no more data left in the queue in order to ensure that txQ never becomes full. The synchronization process is outlined more specifically later.
  • protocol.c: This code contains functions to deal with the wheels functioning and also the encoders. The spi_thread is contained in this file and deals with reading the encoder data. If the server sent the command to record encoder data, a flag is set in protocol.c and the encoder data is pushed onto txQ and written to the socket.
  • thr_microstrain.cpp: The Microstrain 3DM-GX1 IMU sensor uses thr_microstrain.cpp to communicate sensor data to txQ. This thread also calls lower-level serial functions that obtain sensor data either once upon initialization or continuously, depending on the setting the server selected.
  • thr_imu.cpp: The IMU-605 sensor uses thr_imu.cpp to communicate sensor data to txQ. This thread also calls lower-level serial functions that obtain sensor data at a rate set in the actual sensor settings (usually either 60 Hz or 125 Hz).
The only part dealing with socket communication in each of these sensor threads (including the spi_thread) is where the data is pushed onto txQ and waits to be written to the socket.

===================================================================================

Socket Communication Details:

------------------------------------------------------------------------------------------------------------------------------------------------------

A more detailed explanation for the socket communication system is described below.

------------------------------------------------------------------------------------------------------------------------------------------------------

Socket data-flow overview:

Client-side data flow


Server-side data flow

-----------------------------------------------------------------------------------------------------------------------------------------------------

Communication and Synchronization Details:
A linked FIFO queue is used to push data from each sensor and be popped by the write_socket thread to write the data over the socket. Queue.h is the class that supports this data structure. Since each sensor must independently write to the shared memory of the queue, mutex locks and signals must be implemented to ensure correct thread synchronization. There is one shared mutex for control over the queue, as well as one mutex per thread to deal with handling the signal. Whenever data is pushed to the queue from a sensor, the sensor thread signals that txQ is not full, and waits for the write_socket thread to signal that txQ is empty once again before writing more data to it. The write_socket queue runs continuously to empty the queue.

------------------------------------------------------------------------------------------------------------------------------------------------------

Parser Details:
In order for the server to know exactly which sensor sent the data it is observing, the client attaches a single character to the beginning of each line of data. The server then notices this flag and selects the correct output file for the rest of the data read until another flag is read, in which case it selects another output file for writing. A similar method is used for parsing server commands sent to the client. When the server sends a command, however, it need only be a single character since there are very few transmissions sent to the client. The character is simply parsed by the client and whatever needs to be executed is called directly from where the parser is implemented in the read_socket function.

===================================================================================

Adding Additional Sensor Support:

------------------------------------------------------------------------------------------------------------------------------------------------------

It is quite simple to implement another sensor into this system if the same method is followed as was with the first three. The focus should be mainly on the IMU-605 and the 3DM-GX1 IMU since these are standalone sensors and not integrated into another thread like the encoders are. The new sensor will need its own thread function, including all supporting files for the serial or other communication it needs to acquire data. To integrate the sensor, simply follow the same procedure used in the other two sensor threads:
  • Find out how the data is meant to be communicated, i.e. stored as a double, float, int, char, etc.
  • Use sprintf to convert the data string to a character string and store the amount of data as an int.
  • Check to see if txQ is full, and if it is, print and error. If it is not, continue.
  • Lock the shared mutex and push an identifying character for the sensor onto txQ.
  • Using for loops with the int amount of data stored as the stopping point, push the character data onto txQ.
  • Unlock the mutex and signal that txQ is not empty.
  • Use a while loop to check the predicate for when the sensor should push more data (i.e. when the queue is empty).
  • In the read_socket function to implement the parsing process and implement the thread initialization after parsing the corresponding character identifier from the server.
  • On the server, you will need to implement the same system used for the other sensors in which the server looks for a flag and then outputs to that file, sometimes attaching a server-side timer in the process.
  • Finally, change the dialog to include options for specifying the use of the sensor.

===================================================================================

Adding Additional Robot Support:

------------------------------------------------------------------------------------------------------------------------------------------------------


It is less trivial to add the option for additional robots. The client software will remain almost unchanged except for changing the port it listens on and the identifiers used for the sensors. On the server, there will need to be several iterations of almost the exact same code, possibly implemented on tabs or other dialog area options. The server will need to be able to select which socket it wants to communicate with, as well as have the option to control all at once. This will require much of the same code as for the single robot instance, however the functions may need to change to allow for broad usage as opposed to specific usage for a particular parsing scheme.

===================================================================================

Attachments (2)

  • TAMUBotClient.zip - on Jul 29, 2008 12:42 PM by Unknown user (version 1)
    126k Download
  • TAMUBotServer.zip - on Jul 29, 2008 12:24 PM by Unknown user (version 1)
    6826k Download