LEY DE PETROLEOS MEXICANOS No DE CONVOCATORIA: 033/

The GOGGLES API that runs on the Pico-ITX and interfaces with SPHERES is de-

fined in the spheres.h file, and its code is in spheres.c (these files require faked integrated accels.h and faked integrated accels.c, which are discussed later). The source code for this

Useful global variables in spheres.h

A number of global variables are defined that represent the state of the system. These are always overwritten with the latest data from the SPHERES satellite (timestamps are included and described later in this document). It is recommended that the following POSIX standard mutex be used to access this data:

1 pthread mutex lock(&spheres data mutex);

2 position x = global data[0];

3 pthread mutex unlock(&spheres data mutex);

float imu data[3]: This is the rotation rate in radians per second. It is the result of low pass filtering 50 1ms interval samples (the source code for the filter is in pads convert.c). These values are scaled by a default scale factor and have a bias removed (these have not been calibrated for the individual gyro). The 0, 1 and 2 elements in the array correspond to the X, Y and Z gyro respectively.

float imu data unfiltered[3]: This data is exactly the same as above, except that rather than filtering 50 samples on SPHERES and sending the result to the GOGGLES, the latest sample is sent unfiltered.

float global data[13]: This data is the SPHERES state that is estimated using the global metrology estimator, which takes into account measurements from the ultrasonic beacons and the gyroscopes. Section 5.3 of the spheres-gsp.pdf document defines the elements of the array. Their global coordinate frame is determined by the location of the beacons that are input through the KC GUI program.

int test number: This value represents the test number that is selected in the KC GUI program (i.e. pressing key ”3” to start the test will set this value to 3).

Time Stamps and Synchronization

The SPHERES and GOGGLES processors have two different clocks. The SPHERES clock (measured in ms) begins at 0 when user starts a test in the KC GUI. The GOGGLES clock is the linux CLOCK REALTIME that is defined in <time.h> (this begins at Jan 1, 1970), and is accessed using the code:

1 struct timespec current time;

2 clock gettime(CLOCK REALTIME, &current time);

There are 3 important variables for time synchronization: • struct timespec start sys time

• struct timespec latest sys time

• int test time (number of milliseconds since start of test)

The SPHERES-GOGGLES software interface uses a basic time synchronization mechanism. When the GOGGLES receives a start of test message, it records the current linux time in the start sys time variable. Whenever the GOGGLES receives a new gyro or global measurement, it contains a time-stamp of the current SPHERES test time. This is recorded in the test time variable as well as the current linux time (CLOCK REALTIME) is recorded in the latest sys time. Since the gyro measure- ments come in every 50 ms, this synchronization occurs every 50 ms and will prevent clock drift over long periods of time.

Therefore if a program running on the goggles wanted to know, exactly what the test time was on SPHERES, it should get the current linux time, subtract this from the latest sys time, convert to milliseconds and add the test time to this.

Functions in spheres.h

The spheres.h file defines a number of functions that will be discussed below. An example program that demonstrates the use of all of these functions is found in goggles.c.

Messages are passed between the SPHERES and GOGGLES using an ASCII protocol. This allows the messages to be inspected by a terminal program such as TeraTerm or minicom. The send functions use sprintf() while the receiving function uses sscanf(). (NOTE: the use of ascii messages will likely change in future releases due to the DSP/BIOS implementation of the SYS SPRINTF function).

initSpheres() This is the first function that should be called in any program that will interface with SPHERES. The main purpose of this function is to open the serial port with the correct parameters (baud rate, stop bits etc.) and start a new thread (defined in the function spheres thread(void *ptr)) that is dedicated to processing messages that come from SPHERES. The serial port is opened with the following parameters:

• 115200 baud • 8 bit

• NO PARITY • NO STOP BIT

The port is opened in canonical mode (read blocks until a null character is re- ceived), so that the thread will automatically block in its ”infinite loop”. When a new string is received, the function parseString(char* buffer) is called to process the data.

parseString(char* buffer) This function is called automatically by the spheres communications interface thread and does not need to be called by the user. When the thread receives a new string it is parsed using this function. The formats are defined below:

Table A.3: ASCII Data Communication Protocol SPHERES− >GOGGLES

Message Format Frequency Data

Start of Test ST: %d\r\n Once per test Test Number

End of Test PPPP\r\n Once per test

Filtered Gyro Y[%d]%X,%X,%X\r\n 20 Hz X, Y, Z stored in

imu data[3]

Unfiltered Gyro YS[%d]%X,%X,%X\r\n 20 Hz X, Y, Z stored in

imu data unfiltered[3]

Global Data G[%d]%x,%x,%x:%x,%x,%x:%x,

%x,%x,%x:%x,%x,%x\r\n

In the gyro and global data, the SPHERES test time is included in the square brackets [%d].

waitGspInitTest() This function provides a mechanism for waiting for the test to start. It will block until a start of test message is received (return 0), or until a 10 second timer elapses (return 1). A start of test message is transmitted by the SPHERES software whenever the user starts a test in the KC GUI (pushing a key from 1 to 9).

checkTestTerminate() In order to detect whether the user has pressed F4 on the KC GUI to stop the test, the GOGGLES software must call this function. A value of 0 is returned from checkTestTerminate() if the test is currently running. However if the test has stopped a 1 is returned. Additionally, this function implements a ”software watchdog”. If a test has been running, but it has been more than 10 seconds since a message has been received from SPHERES, this function also returns 1.

unsigned int sendCtrl(float* target, int ctrlmode) The sendCtrl function has three different control modes that are #defined in the spheres.h file. These modes are identical in behaviour to their corresponding modes. Each mode accepts a pointer to a float* target array (no out-of-bounds error checking is provided on the target vector).

CTRL MODE TARGET: This mode uses a PID controller to regulate the state. The desired state is an array of 13 vectors that is identical in sequence and units (all are m, m/s or rad/s) to the above mentioned Global Data array (e.g. the target[0] element is the X position, target[12] is the Z angular velocity, etc.). If a sequence of waypoints is desired, the GOGGLES code should call sendCtrl with different targets at different times.

CTRL MODE INERTIAL: This control mode provides direct control over the forces and torques generated by the SPHERES. The sequence of the target array for elements 0,1,2 are the forces in the X,Y,Z direction respectively and are measured in Newtons. The sequency of the target array for elements 3,4,5 are the torques about

the X,Y and Z axis respectively and are measured in Newton-meters. The reference frame for these forces and torques is in the global/inertial frame that is defined by the beacon’s locations.

CTRL MODE BODY: This control mode provides direct control over the forces and torques generated by the SPHERES. It is identical to the inertial control mode except that the forces are in the SPHERES body frame (see spheres-gsp.pdf). This is the only control mode that will work in tests 2 through 5 in the liive boot images. When the sendCtrl function is called, the GOGGLES will immediately transmit a message to the SPHERES controller with the provided parameters. The SPHERES software will receive this message and store the data in a buffer that will be used by the next control iteration. If the SPHERES satellite receives new data before the old data is used, the old data will be over-written. If the GOGGLES stop transmit- ting control messages, the SPHERES software will use the last received data in the buffer. Therefore no longer calling sendCtrl WILL NOT stop SPHERES from firing its thrusters.