electronic throttle docs (#16)

* etb

* warning

* dot em dee

* no fsio

* more config

FAQ/HOWTO_electronic_throttle_body.md

@@ -1,22 +1,37 @@
 
+# Electronic Throttle Body (ETB)
+
 
-TODO :)
+## _WARNING: An electronic throttle, if misconfigured or damaged, has the ability to open the throttle without your foot on the pedal, potentially leading to engine damage [or a crash](https://en.wikipedia.org/wiki/2009%E2%80%9311_Toyota_vehicle_recalls).  Proceed with caution!_
 
-[HOWTO_tune_electronic_throttle_body](HOWTO_tune_electronic_throttle_body)
+rusEfi supports controlling an electronic throttle body.  Also called "drive by wire", this means there's no physical cable between your foot and the throttle.  Your foot presses on a pedal without a cable, just a sensor.  The ECU interprets this information, and converts it to a desired position for the throttle, and then works to drive the throttle plate to the desired position.
 
-See https://rusefi.com/forum/viewtopic.php?f=5&t=592&start=150#p32044
+This offers a number of benefits:
 
-tl;dr:
+- Rev limiter by simply closing the throttle (not yet implemented)
+- Superior idle control
+- No need to route a cable to the throttle
+- Programmable throttle target curve/nonlinearity to improve drivability with a large throttle on a small engine
 
-1) Zero out PID gains, adjust bias table to cancel out the spring
+## Theory of Operation
 
-2) Tune PID
+Electronic throttles typically consist of:
+- A brushed DC motor.  Positive torque pushes the throttle open, and negative torque pushes the throttle closed.
+- A position sensor.  This tells the ECU the true position of the throttle, so that the ECU can use the motor to hold it where we want it.  This is a potentiometer or hall effect angle sensor, depending on the throttle, though they both function the same.
+- A "limp home" return spring.  This spring pushes the throttle plate back towards a position that's nearly closed, approximatly the correct amount of air for idle (generally 3-10% open).
 
+rusEfi hardware and software have components to deal with all three of these parts of the throttle.
+- DC motor driver H-bridge(s) to control the motor.  An H-bridge can apply a variable voltage (via PWM) in either direction to the motor.
+- Analog inputs and corresponding software to detect the position of the throttle and accelerator pedal.
+- A control algorithm that uses a table to linearize the return spring, and PID to move the throttle to the targeted position.
 
-See also https://rusefi.com/s/debugmode/
+## Configuration & Tuning
 
+[See configuration guide here.](HOWTO_electronic_throttle_body_configuration.md)
 
-# H-bridge settings
+## Hardware Configuration
+
+**If you have a pre-assembled board, ignore this section!  The default settings are correct.**
 
 Different H-bridge chips are controlled differently. So far we have experiences three different ways:
 
@@ -31,8 +46,6 @@ PWM on Control pin, open/close using one on/off direction pin, second direction
 
 PWM on both direction pins, one for forward another one for reverse.
 
-Enable on/off pin should be controlled via FSIO.
-
 TLE7209 is an example of two wire mode.
 
 # Pinouts

FAQ/HOWTO_electronic_throttle_body_configuration.md

@@ -0,0 +1,55 @@
+# Electronic Throttle Body Configuration Guide
+
+## Wiring
+
+TODO
+
+## Calibrate Sensors
+
+### Pedal position sensor
+
+TODO
+
+### Throttle position sensor
+
+Zero position requires you to push throttle closed. Full throttle requires you to push throttle open.
+
+Neutral position is usually somewhere around 0-10%.
+
+## Tune Bias Table
+
+"Bias curve" is a curve of PWM duty cycle values which kind of get TPS close to desired value, for each of the 8 points on the curve.
+It measures how much duty is required to hold the throttle at that spot.
+
+The goal is that at position X, the bias will somewhat hold it there on it's own.
+
+Bias is also known as feed-forward.
+
+We are interested in positions like 0, between-0-and-default, default, a bit open, a bit more open, 50% open, wide open, 
+
+Set P=I=D=0. Set curve to all zeros.
+
+Now use offset (offset is same thing as constant bias) to manually control duty cycle. Try different values and see which offset sets throttle to closed, which offset
+starts to open throttle, which offset is enough to open throttle completely.
+
+## Tune PID
+
+See https://rusefi.com/forum/viewtopic.php?f=5&t=592&start=150#p32044
+
+### Start with autotune
+
+rusEfi has auto-tuning software that can help generate a starting point for your PID settings.
+
+### _Ensure the engine is off! Do not attempt to start the engine during this process!_
+
+1. Ensure your electronic throttle roughly tracks the target position.  It doesn't have to be perfect or super fast, but it should at least work.  Confirm this by checking that the gauge "ETB position error" displays small values while moving the throttle around gently (a few percent is fine, so long as it trends towards zero if you stop moving).
+2. Set debug mode to ETB autotune and add gauges Ku, Tu, Kp, Ki, Kd (in debug menu) (todo: add screenshot)
+3. Using the accelerator pedal, hold the throttle at approximately 50% open.
+4. Press `ETB PID Autotune` button.  The throttle will begin oscillating around the target: this is normal.
+5. Observe the estimated PID parameters on gauges Kp, Ki, Kd
+
+## Configure Pedal Map
+
+The pedal map allows you to configure how the electronic throttle's position responds to driver input on the accelerator pedal.  Since engines with electronic throttles often have oversized throttles (because they can), this table is required to make the accelerator less sensitive for small openings, as this hurts drivability.
+
+This table is really one to tune to taste, since it has no bearing on actual engine performance, only on the relationship between driver input and resulting throttle position.

FAQ/HOWTO_tune_electronic_throttle_body.md

@@ -1,27 +0,0 @@
-
-### Step 1. Set bias curve.
-
-
-1.1 Calibrate throttle position sensor in your electronic throttle body.
-
-Zero position usually requires you to push throttle closed. Full throttle would definitely require you to push throttle open.
-
-Default position is usually somewhere around 4-8%.
-
-1.1 Feed-forward curve/Bias curve.
-
-"Bias curve" is a curve of PWM duty cycle values which kind of get TPS close to desired value, for each of the 8 points on the curve.
-It measures how much duty is required to hold the throttle at that spot.
-
-The goal is that at position X, the bias will somewhat hold it there on it's own.
-
-Bias is also known as feed-forward.
-
-We are interested in positions like 0, between-0-and-default, default, a bit open, a bit more open, 50% open, wide open, 
-
-Set P=I=D=0. Set curve to all zeros.
-
-Now use offset (offset is same thing as constant bias) to manually control duty cycle. Try different values and see which offset sets throttle to closed, which offset
-starts to open throttle, which offset is enough to open throttle completely.
-  
-