AME 3623: Project 6: Hovercraft Force Control

Now that you have your individual motors working, it is time for them to work together to produce acceleration of the hovercraft in a desired direction. In this project, you will implement code that translates desired acceleration (linear or rotational) into appropriate thrusts for each of the fans.

All components of the project are due by Wednesday, April 7th at 5:00pm.
Groups are the same as for project 1.
Discussion within groups is fine.
Discussion across groups may not be about the specifics of the solution (general programming/circuit issues are fine to discuss).

At the end of this project, you should be able to:

produce code that implements inverse hovercraft kinematics, and
use a Finite State Machine to test your code.

Component 0: Hardware and Libraries

Your central fan is hard-wired into the +11V switched power supply. This connection provides power to the fan's control circuitry and to the fan motor. In most cases, this power connection has been unplugged. You will need to plug it back in before you use the central fan (this will start an annoying beep, however; this beep continues until your code initializes the fan).
The remaining central fan connector has two pins: ground (black) and torque magnitude (white). Connect ground to your processor's ground and the torque magnitude signal to a free PWM pin. Note: if your connector has three pins, please clip the central red pin
Your battery should be mounted on the platform just behind the central fan on the lower deck.
Make sure your hovercraft is balanced left-to-right and front-to-back. It is okay to add counter-weights, as necessary (but try to minimize the amount of mass).
Download PWMServo-2.1.0.zip
In your Arduino environment: in the sketch menu, select Include Library / Add .Zip Library
Navigate to and select PWMServo-2.1.0.zip. Click Ok. You will only need to install this zip file once into your environment.
In your Arduino environment: in the sketch menu, select Include Library / PWMServo

Component 1: Force Control Software

Add the following code to the top of your program (yes, we are defining a global variable!):

PWMServo fan;  // create servo object to control the fan
const int CENTRAL_FAN_PWM = ???;   // Replace ??? with the Teensy PWM pin for the central fan
     
void fan_setup() {
     fan.attach(CENTRAL_FAN_PWM);  // attaches the fan to specified
                                   //   Arduino pin to the object
     delay(100);
     fan.write(20);  // write low throttle
     delay(3000);
}

Make sure to call this new function from setup()

Implement the following function:
```
void set_hovercraft_forces(float fx, float fy, float torque)
```
This function accepts as input desired forces to be applied to hovercraft chassis, translates these desired forces into an appropriate thrust level for each of the lateral fans, and changes the thrust state of these fans. Note that the precise units of these forces are not really known. Don't worry, the units will "wash away" once we introduce our control gains in the next project.

Component 2: Finite State Machine

Implement a new finite state machine in fsm_step(). This state machine will:
1. Wait for the switch to be pressed.
2. Set the central fan to a 25-40% duty cycle (use the smallest level that brings the craft off the ground).
  You can set the duty cycle of the central fan using:
  fan.write(duty)
  where the duty parameter is a value between 0 and 255 (corresponding to zero to 100% duty cycle)
3. Wait in this state for 15 seconds.
4. Generate a positive torque for 10 seconds.
5. Generate a negative torque for 10 seconds.
6. Turn off the central fan.
7. Wait in this state for 15 seconds.
8. Turn on the central fan
9. Wait for 10 seconds.
10. Generate a forward force for 10 seconds.
11. Generate a backward force for 10 seconds.
12. Turn off the central fan.
13. Wait in this state for 15 seconds.
14. Turn on the central fan
15. Wait for 10 seconds.
16. Generate a rightward force for 10 seconds.
17. Generate a leftward force for 10 seconds.
18. Turn off the central fan.
19. Return to waiting for the switch.
Note that each of these steps must be implemented as a separate state in your code.

Hints and Safety

With your craft balanced, when the lateral fans are not being driven, your craft might drift laterally a little (this is okay). If it drifts a lot, then you should rebalance your craft.
When you are producing only torque about the center of the hovercraft, if the craft drifts laterally a lot, then:
- your code for inverse kinematics is wrong, or
- you need to balance the "natural" vs "unnatural" thrust directions by adjusting the fan_gains (you will need to play with these values a little bit, but you will probably land somewhere in the 1.1 to 1.3 range).
Do not put items in any of the fan blades when they are spinning (this includes fingers!).
If any of your wires or motors become hot, stop using the system and get in touch with us. Likewise, if you smell something hot, immediately shut down the hovercraft and disconnect the battery.
If your battery is visibly damaged, then do not use it any longer. Bring it in to swap it out. If your battery begins to emit white smoke or becomes very hot (unlikely), do not breath the smoke and get the battery outside as quickly as possible.
When used heavily (continuous motor use), a single battery will have a 10-15 minute lifetime. As the voltage drops, your motors will sound and behave differently. Immediately disconnect the battery. Get it on the charger for a full charge before use.
Charging: every group is equipped with a battery charger. The dual chargers (gray and red plastic) will automatically charge a battery when the 4-pin connector is plugged into the charger. The single chargers (red and black metal) require that you:
- Plug the battery in (both the 2-pin and the 4-pin connectors).
- Hold down the enter button until the charger beeps and shows that it recognizes a battery (it should see a 3S battery).
- Hit the enter button again to start the charge. The current indicator will show positive current.
In all cases, the chargers should show that they recognize "LiPo 3S" batteries when they are plugged in (the dual chargers will show "6S" when two batteries are plugged in).
It is possible to get the single charger into the wrong mode and the above sequence will fail or indicate a different battery type. If so, the included manual will give you the steps to return to "LiPo 3S" charging.
When the battery is being charged, it must be placed inside the Kevlar "burn bag" that has been provided to your group. The wires should be routed outside the bag to be plugged into the charger (do not put the charger in the bag).
We have worked hard to make sure that your fans are working properly. However, if you have trouble with any of your fans, please let us know quickly so we can either talk you through the repair process or have you bring your hovercraft in for repairs.

What to Hand In

All components of the project are due by Wednesday, April 7th at 5pm

Demonstration/Code Review: All group members must be present. The demonstration must be completed by Friday, April 9th.
Check in the following to your project 6 area of Gradescope:
- Documented code: See the project 1 specification for detailed documentation requirements.

Grading

Project lead credit:

Each person must be the primary integrator of circuits and code for two projects over the course of the semester.

For a successful project, we expect:

A properly configured circuit
- Central fan connected to your processor
Properly written software
- set_hovercraft_forces()
- Finite State Machine implementation
Properly documented code
- Project-level documentation at the top of the ino file: name and group number, date and project number
- Function-level documentation above the function definition. Include an abstract description of what the function does; a list of the names, types and units associated with each parameter and return value; and the effects that the function has on the processor or connected components.
- In-line documentation inside of functions: individual lines or small groups of lines have an English description that describes logically what the code is doing

andrewhfagg -- gmail.com

Last modified: Sat Mar 27 15:29:40 2021