Vehicle Orientation


The lander is defined with a right hand coordinate system matching NASA terminology, with the positive X axis pointing up at launch time:




(FIXME: engines 2 and 3 are now swapped, so the low numbered one on both axis gives positive rate increases)


Angles are defined around each axis, using the right hand rule to determine which direction is a positive angle.  If the thumb of a right hand points down the positive axis, a positive rotation will be in the direction that the fingers curl.


For roll, pitch, and yaw to have their conventional pilot meanings, the pilot is assumed to be in the vehicle, looking down the positive X axis (towards the sky), with his feet pointing down the positive Z axis.


This will cause some confusion, because our first two vehicles do not have the pilot controlling the vehicle (either remotely or onboard) facing the sky.  The manned vehicle will have the pilot standing on the Y Z plane, looking between positive Y and positive Z.  The original remotely piloted tests had the remote pilot looking down positive Z, but future tests will match the manned vehicle conventions, putting the vehicle exactly as shown in the picture.  Next generation manned vehicles with higher acceleration will require a prone pilot, at which point the pilot will be positioned exactly like NASA does.


Vehicle roll will be a well understood term, but vehicle pitch and yaw should generally not be referred to, because it will be confusing in current designs.


Engine Connection


The orientation of the electronics box determines the orientation of the vehicle.  Because our vehicle is symmetric about the roll axis, as long as the engine solenoid connectors on the back of the box are connected to appropriate engines, the vehicle can operate in any of four different configurations.


The box axis should be parallel with the lines between opposite pairs of engines.  On the demonstrator vehicle with the engines mounted on different sides of the cross members, the box should ideally be slightly rotated away from the cross members to account for this, but the flight control logic should be able to deal with the cross couple even if it isn’t perfect.


Note that the box does not have to sit at the vehicle center, because rotations will be sensed the same at any point in the vehicle.  On the first manned vehicle, the electronics box is placed as far away as possible to partially counterbalance the pilot.  Accelerometer readings will be effected by an off center location during rotations, however.


Looking at the solenoid connectors, engine 0 will be to the left, engine 1 will be to the right, engine 2 will be in front of the box, and engine 3 will be behind the box.


The engines are canted for roll control.  The top of the engine will be farther from the centerline than the bottom, accomplished by inserting a shim between the engine and the mounting bracket, and tightening the clamp below the shim.  Canting the other direction would require shims at the bottom, which would be likely to fall out.


Powering the Y axis engines (0 and 1) will induce a positive rotation around X, while powering the Z axis engines (2 and 3) will induce a negative rotation.


Normal pitch and yaw corrections around the Y and Z axis will induce some roll around X, but it will be automatically compensated for.


World Space


The vehicle’s orientation is tracked by maintaining a vector for each vehicle axis in world space.  World space is also a right hand coordinate system, with the XY plane parallel to the ground, and positive Z going towards the sky.


When the orientation is zeroed at the beginning of a flight test, the vehicle axis are assigned the following values:


Vehicle X axis = world ( 0, 0, 1 )          pointing straight up

Vehicle Y axis = world ( 1, 0, 0 )          pointing “east”

Vehicle Z axis = world ( 0, 1, 0 )          pointing “north”


If the vehicle is not level when the angles are zeroed, the neutral joystick position will have a translational acceleration that will need to be manually compensated.  In the future, we can use the three axis accelerometer as an inclinometer on the ground to calculate world vectors that accurately represent the tilt.  With this, the vehicle will level itself automatically when it lifts off.


Gyro bias sampling when zeroing.


We can also use a magnetometer in conjunction with the inclinometer to calculate actual initial vehicle roll angle relative to the true earth north.


Vehicle pitch and yaw are defined by the relationship of the vehicle Z and Y axis to the ground plane.


Vehicle Y angle (pitch) = asin( zvector[2] )

Vehicle Z angle (yaw) = -asin( yvector[2] )


The roll angle is zero when the vehicle Y axis is lined up with the world X axis.


Vehicle X angle (roll) = atan2( yvector[1], yvector[0] )


At each time step, the outputs of the rate gyros are used to rotate the orientation vectors.  It is important to note that the gyro outputs can’t simply be added up to get the current vehicle angles in degrees.  When deviations are small it almost works, but the applied rotations are order dependent.  For an obvious example, rotate something +90 degrees around the Z axis, then +90 around the Y axis, then –90 around the Z axis, then –90 around the Y axis.  It won’t be in the original position.


Eventually we will be incorporating accelerometer data each time step, so the vehicle’s position and velocity will also be tracked in world space.


Flight Control


The job of the flight control logic is to take the “desired vehicle angles” from the pilot’s joystick, and compare them against the vehicle rates sensed by the gyros and the vehicle angles derived from the world space orientation.



are the inputs that the control system will compare against the “current vehicle angles” (and rates) and choose “axis torques” to attempt to bring them together.



Inertial reference frame




All sensor values, such as gyro rates, accelerometer forces, and magnetometer readings, will be converted to vehicle space.  This may involve interchanging axis or negating values, depending on how the sensor was mounted.



Joystick Controls


The orientation of the pilot determines the mapping of joystick angles to desired vehicle angles.


In windows, joystick values come in as signed 16 bit values, but I renormalize to floating point values.


The joystick ranges are:


X: -1 to the left, +1 to the right

Y: -1 forward, +1 back

Twist: -1 counter clockwise, +1 clockwise

Throttle: 0 throttle all the way forward, 1 all the way back


A constant in the flight computer, JOYSTICK_TO_DEGREES, determines what range of vehicle angles the joystick angles will be mapped to.  This is 20 in the current code, which should be sufficient to maneuver and provide any necessary trim.  We do not want to have the vehicle accelerating parallel to the ground.


The joystick left / right / forward / back motions translate easily into desired vehicle pitch and yaw values.


Desired vehicle Y (pitch) angle = joystick Y + joystick X

Desired vehicle Z (yaw) angle = -joystick Y + joystick X


Because the pilot is facing between the vehicle axis, you only get a pure rotation on a single axis when the joystick is pushed diagonally.


In our initial tests, we will map the twist action on the joystick to this:


Desired vehicle X (roll) angle = -joystick twist


This will allow us to verify that roll control is working properly, but a fully operational VTVL will need to be able to fly in complete circles, so we will probably change the logic so that twisting specified a desired rate of roll, rather than an absolute destination.  When it returns to center, the current value should be made the desired angle, so the flight logic will hold the heading automatically.


There is no difference in the way the joystick data is handled between a remote pilot and a local pilot.  The global joyState variable is filled in by either reading the local joystick or by receiving a UDP packet from the remote pilot, the rest of the software does not care where it came from.


Pilot Trim


Inaccuracies in the gyros will cause the flight computer’s view of the vehicle’s orientation to slowly drift away from the true position.  For our short duration flights, this will not amount to more than a couple of degrees tops, but for longer flights that involve coming down with a drogue, the pilot may need to provide some manual trim on the joystick to compensate during powered landing.


If the range of the gyros (a bit over 100 degrees / second) is ever exceeded, some of the motion will be lost to the computer, resulting in the computer thinking the vehicle is at a different angle than it is.  The flight computer will never intentionally approach this rate, but a sudden strong gust of wind or a glancing collision during a rate correction could conceivably hit it.  If the error is within the joystick angular range, it may be correctable by the pilot.


TODO: The flight computer currently aborts thrust if the rate goes near the edge, because the cheaper gyros got wildly erratic under some circumstances.  The FOGs seem to be well behaved when their limits are hit, so it should be changed to continue on, but sound a warning that information has been lost.


 If the vehicle center of gravity is offset, or one engine of a pair degrades in performance, or one of the engines is tilted toward the center, there may be a slight bias in the motion of the vehicle.  The flight control will continue to kick the vehicle back to level, but the average time will be spent slightly off center, resulting in a small translational acceleration.  A small amount of pilot trim should compensate.