feat(docs): improve IC engine docs

- add dedicated page for ICE config and explanation
- update diagrams and screenshots

Signed-off-by: Silvan <silvan@auterion.com>
This commit is contained in:
Silvan authored and Silvan Fuhrer committed 2026-09-24 12:10:34 +02:00
1 parent 2c5c54a3d5
commit 1bcefdd86c
9 files changed
+599 -89

No files matched your search

Binary file not shown.

Before

Width:  |  Height:  |  Size: 111 KiB

After

Width:  |  Height:  |  Size: 234 KiB

@@ -0,0 +1,127 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 890 758" width="890" height="758" role="img" aria-labelledby="title desc">
<title id="title">Internal combustion engine control architecture</title>
<desc id="desc">The internal_combustion_engine_control module takes the throttle demand from ActuatorMotors control[0] published by the control allocator, plus Rpm, VehicleStatus and ManualControlSetpoint. It publishes InternalCombustionEngineControl, which the output driver maps onto the four output functions IC Engine Ignition, IC Engine Throttle, IC Engine Choke and IC Engine Starter, which drive the engine hardware. It also publishes InternalCombustionEngineStatus, which feeds MAVLink EFI_STATUS, the flight log and the DroneCAN ICE bridge.</desc>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
markerUnits="userSpaceOnUse" markerWidth="9" markerHeight="9" orient="auto">
<path d="M0 0 L10 5 L0 10 z" fill="#4b5563"/>
</marker>
</defs>
<style>
.bg { fill:#ffffff; stroke:#e3e6ec; }
.mod { fill:#fdf0e2; stroke:#c2701c; stroke-width:1.5; }
.subj { fill:#fbe6cd; stroke:#a95a0d; stroke-width:2.5; }
.msg { fill:#f1f3f7; stroke:#9aa4b5; stroke-width:1.5; }
.ext { fill:#ffffff; stroke:#6b7280; stroke-width:1.5; stroke-dasharray:6 4; }
text { font-family:system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; fill:#12161f; }
.t { font-size:12.5px; text-anchor:middle; }
.m { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:12px; text-anchor:middle; }
.hd { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:13px; text-anchor:middle; font-weight:600; }
.sub { font-size:10.5px; fill:#5b6472; text-anchor:middle; }
.li { font-size:11.5px; }
.fn { fill:#ffffff; stroke:#c2701c; stroke-width:1; }
.fnt { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:10px; text-anchor:middle; }
.edge { stroke:#4b5563; stroke-width:1.6; fill:none; marker-end:url(#arrow); }
.elab { font-size:10.5px; fill:#5b6472; }
.lgd { font-size:10.5px; fill:#5b6472; }
</style>
<rect class="bg" x="0.5" y="0.5" width="889" height="757" rx="10"/>
<!-- Row 1: control allocation produces the throttle demand -->
<rect class="mod" x="40" y="40" width="140" height="46" rx="6"/>
<text class="t" x="110" y="67">rate controller</text>
<rect class="msg" x="215" y="40" width="200" height="46" rx="6"/>
<text class="m" x="315" y="59">VehicleThrustSetpoint</text>
<text class="m" x="315" y="75">VehicleTorqueSetpoint</text>
<rect class="mod" x="450" y="40" width="150" height="46" rx="6"/>
<text class="m" x="525" y="67">control_allocator</text>
<rect class="msg" x="635" y="40" width="145" height="46" rx="6"/>
<text class="m" x="707.5" y="59">ActuatorMotors</text>
<text class="sub" x="707.5" y="75">control[0]</text>
<line class="edge" x1="180" y1="63" x2="215" y2="63"/>
<line class="edge" x1="415" y1="63" x2="450" y2="63"/>
<line class="edge" x1="600" y1="63" x2="635" y2="63"/>
<line class="edge" x1="707.5" y1="86" x2="707.5" y2="190"/>
<text class="elab" x="716" y="142">throttle demand</text>
<!-- Row 2: the module and its remaining inputs -->
<rect class="msg" x="40" y="190" width="250" height="42" rx="6"/>
<text class="m" x="165" y="207">Rpm</text>
<text class="sub" x="165" y="223">measured engine speed</text>
<rect class="msg" x="40" y="242" width="250" height="42" rx="6"/>
<text class="m" x="165" y="259">VehicleStatus</text>
<text class="sub" x="165" y="275">arming state · VTOL transition</text>
<rect class="msg" x="40" y="294" width="250" height="42" rx="6"/>
<text class="m" x="165" y="311">ManualControlSetpoint</text>
<text class="sub" x="165" y="327">aux1 / aux2 switch</text>
<line class="edge" x1="290" y1="211" x2="330" y2="211"/>
<line class="edge" x1="290" y1="263" x2="330" y2="263"/>
<line class="edge" x1="290" y1="315" x2="330" y2="315"/>
<rect class="subj" x="330" y="190" width="440" height="150" rx="8"/>
<text class="hd" x="550" y="216">internal_combustion_engine_control</text>
<text class="sub" x="550" y="233">runs at 50 Hz</text>
<line x1="350" y1="245" x2="750" y2="245" stroke="#d9a877" stroke-width="1"/>
<text class="li" x="366" y="270">• start / stop state machine</text>
<text class="li" x="366" y="294">• idle RPM governor — feed-forward + PI on measured RPM</text>
<text class="li" x="366" y="318">• throttle slew-rate limit (ICE_THR_SLEW)</text>
<line class="edge" x1="390" y1="340" x2="390" y2="400"/>
<line class="edge" x1="710" y1="340" x2="710" y2="400"/>
<!-- Row 3: published topics -->
<rect class="msg" x="250" y="400" width="280" height="52" rx="6"/>
<text class="m" x="390" y="421">InternalCombustionEngineControl</text>
<text class="sub" x="390" y="437">ignition · throttle · choke · starter</text>
<rect class="msg" x="570" y="400" width="280" height="52" rx="6"/>
<text class="m" x="710" y="421">InternalCombustionEngineStatus</text>
<text class="sub" x="710" y="437">state · sub-state · idle PID integral</text>
<line class="edge" x1="390" y1="452" x2="390" y2="510"/>
<line class="edge" x1="710" y1="452" x2="710" y2="510"/>
<!-- Row 4: consumers -->
<rect class="mod" x="250" y="510" width="280" height="116" rx="6"/>
<text class="t" x="390" y="531">Output driver (MixingOutput)</text>
<text class="sub" x="390" y="547">maps each field onto an output function</text>
<rect class="fn" x="262" y="556" width="122" height="26" rx="4"/>
<text class="fnt" x="323" y="573">IC Engine Ignition</text>
<rect class="fn" x="396" y="556" width="122" height="26" rx="4"/>
<text class="fnt" x="457" y="573">IC Engine Throttle</text>
<rect class="fn" x="262" y="588" width="122" height="26" rx="4"/>
<text class="fnt" x="323" y="605">IC Engine Choke</text>
<rect class="fn" x="396" y="588" width="122" height="26" rx="4"/>
<text class="fnt" x="457" y="605">IC Engine Starter</text>
<rect class="ext" x="570" y="510" width="280" height="52" rx="6"/>
<text class="t" x="710" y="531" style="font-size:11.5px">MAVLink EFI_STATUS · flight log</text>
<text class="sub" x="710" y="548">DroneCAN ICE bridge (UAVCAN_SUB_ICE)</text>
<line class="edge" x1="390" y1="626" x2="390" y2="666"/>
<!-- Row 5: hardware -->
<rect class="ext" x="250" y="666" width="280" height="52" rx="6"/>
<text class="t" x="390" y="688">Engine hardware</text>
<text class="sub" x="390" y="704">relays / servos on the assigned outputs</text>
<!-- Legend -->
<text class="lgd" x="40" y="404" style="font-weight:600; letter-spacing:0.06em">LEGEND</text>
<rect class="mod" x="40" y="416" width="24" height="15" rx="3"/>
<text class="lgd" x="74" y="427">Module</text>
<rect class="msg" x="40" y="440" width="24" height="15" rx="3"/>
<text class="lgd" x="74" y="451">uORB topic</text>
<rect class="ext" x="40" y="464" width="24" height="15" rx="3"/>
<text class="lgd" x="74" y="475">External / hardware</text>
</svg>

After

Width:  |  Height:  |  Size: 7.0 KiB

@@ -0,0 +1,102 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 720" width="900" height="720" role="img" aria-labelledby="title desc">
<title id="title">Internal combustion engine control state machine</title>
<desc id="desc">Four states. Stopped goes to Starting when the engine is requested on and start attempts remain. Starting alternates between Cranking and a one second Rest between attempts, goes to Running once the measured RPM exceeds ICE_MIN_RUN_RPM, and goes to Fault once the attempts are exhausted. Running alternates between the Run sub-state, which passes the motor 1 throttle demand through, and the Idle sub-state, in which the RPM governor drives the throttle; it falls back to Starting if the RPM is lost and ICE_RUN_FAULT_D is enabled. Any state returns to Stopped when the engine is requested off.</desc>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5"
markerUnits="userSpaceOnUse" markerWidth="9" markerHeight="9" orient="auto">
<path d="M0 0 L10 5 L0 10 z" fill="#4b5563"/>
</marker>
</defs>
<style>
.bg { fill:#ffffff; stroke:#e3e6ec; }
.st { fill:#f3f5f8; stroke:#8a95a5; stroke-width:1.5; }
.stc { fill:#fdf3e7; stroke:#c2701c; stroke-width:2; }
.stf { fill:#fdeeec; stroke:#c0392b; stroke-width:1.5; }
.chip { fill:#ffffff; stroke:#c2701c; stroke-width:1; }
text { font-family:system-ui,-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; fill:#12161f; }
.sname { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:14px; font-weight:600; text-anchor:middle; }
.cname { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:12px; font-weight:600; text-anchor:middle; }
.ssub { font-size:9.5px; fill:#5b6472; text-anchor:middle; }
.csub { font-size:9.5px; fill:#5b6472; text-anchor:middle; }
.elab { font-size:10px; fill:#5b6472; }
.cap { font-size:10px; fill:#5b6472; }
.edge { stroke:#4b5563; stroke-width:1.6; fill:none; marker-end:url(#arrow); }
.plain { stroke:#4b5563; stroke-width:1.6; fill:none; }
</style>
<rect class="bg" x="0.5" y="0.5" width="899" height="719" rx="10"/>
<!-- Stopped -->
<rect class="st" x="320" y="60" width="200" height="60" rx="8"/>
<text class="sname" x="420" y="86">Stopped</text>
<text class="ssub" x="420" y="104">ignition off · throttle → disarmed</text>
<!-- Starting (composite) -->
<rect class="stc" x="240" y="180" width="360" height="175" rx="8"/>
<text class="sname" x="420" y="203">Starting</text>
<rect class="chip" x="265" y="218" width="150" height="42" rx="5"/>
<text class="cname" x="340" y="236">Cranking</text>
<text class="csub" x="340" y="251">ignition on · starter on</text>
<rect class="chip" x="265" y="296" width="150" height="42" rx="5"/>
<text class="cname" x="340" y="314">Rest</text>
<text class="csub" x="340" y="329">ignition off · 1 s</text>
<line class="edge" x1="300" y1="260" x2="300" y2="296"/>
<line class="edge" x1="380" y1="296" x2="380" y2="260"/>
<text class="elab" x="430" y="272">attempt timed out</text>
<text class="elab" x="430" y="290">after 1 s</text>
<!-- Fault -->
<rect class="stf" x="700" y="195" width="180" height="70" rx="8"/>
<text class="sname" x="790" y="222">Fault</text>
<text class="ssub" x="790" y="240">ignition off · throttle 0</text>
<!-- Running (composite) -->
<rect class="stc" x="240" y="400" width="360" height="195" rx="8"/>
<text class="sname" x="420" y="423">Running</text>
<rect class="chip" x="265" y="438" width="150" height="42" rx="5"/>
<text class="cname" x="340" y="456">Run</text>
<text class="csub" x="340" y="471">motor 1 demand</text>
<rect class="chip" x="265" y="540" width="150" height="42" rx="5"/>
<text class="cname" x="340" y="558">Idle</text>
<text class="csub" x="340" y="573">RPM governor</text>
<line class="edge" x1="300" y1="480" x2="300" y2="540"/>
<line class="edge" x1="380" y1="540" x2="380" y2="480"/>
<text class="elab" x="430" y="497">throttle &lt; 2%, or</text>
<text class="elab" x="430" y="510">RPM &lt; ICE_IDLE_RPM</text>
<text class="elab" x="430" y="532">throttle &gt; governor output</text>
<!-- Main transitions -->
<line class="edge" x1="420" y1="120" x2="420" y2="180"/>
<text class="elab" x="430" y="152">requested on, attempts remain</text>
<line class="edge" x1="350" y1="355" x2="350" y2="400"/>
<text class="elab" x="358" y="381">RPM &gt; ICE_MIN_RUN_RPM</text>
<line class="edge" x1="540" y1="400" x2="540" y2="355"/>
<text class="elab" x="548" y="381">RPM lost (ICE_RUN_FAULT_D)</text>
<line class="edge" x1="600" y1="230" x2="700" y2="230"/>
<text class="elab" x="616" y="216">attempts</text>
<text class="elab" x="616" y="228">exhausted</text>
<!-- Return to Stopped -->
<line class="plain" x1="240" y1="270" x2="160" y2="270"/>
<polyline class="edge" points="240,490 160,490 160,90 320,90"/>
<text class="elab" x="42" y="290">engine requested off</text>
<polyline class="edge" points="790,195 790,90 520,90"/>
<text class="elab" x="800" y="145">requested off</text>
<!-- Caption -->
<text class="cap" x="40" y="645">state → InternalCombustionEngineStatus.state</text>
<text class="cap" x="40" y="662">sub-state → InternalCombustionEngineStatus.substate</text>
<text class="cap" x="40" y="684">The Idle sub-state exists only when ICE_IDLE_RPM &gt; 0.</text>
</svg>

After

Width:  |  Height:  |  Size: 5.3 KiB

+1
View File
@@ -329,6 +329,7 @@
- [Vertiq Motor/ESC Modules](peripherals/vertiq.md)
- [VESC Project ESCs](peripherals/vesc.md)
- [Zubax Telega ESCs](dronecan/zubax_telega.md)
- [Internal Combustion Engines](actuators/internal_combustion_engine.md)
- [Manual Control](config/manual_control.md)
- [Radio Control (RC)](getting_started/rc_transmitter_receiver.md)
- [Radio Setup](config/radio.md)
+1
View File
@@ -7,6 +7,7 @@ This section contains topics about the core actuators used for flight control (E
- [ESCs & Motors](../peripherals/esc_motors.md) — ESCs such as [DShot](../peripherals/dshot.md) (recommended) and DroneCAN.
- [ESC Calibration](../advanced_config/esc_calibration.md) — Calibration for PWM ESC (not required for DShot/CAN ESC/servos).
- [Internal Combustion Engines](../actuators/internal_combustion_engine.md) — Petrol/nitro engines, including start/stop sequencing and idle RPM control.
## See Also
@@ -0,0 +1,337 @@
# Internal Combustion Engines (ICE)
PX4 can operate a single spark-ignition internal combustion engine (ICE) — a petrol/nitro two- or four-stroke engine — as the propulsion system of a fixed-wing, VTOL, or helicopter vehicle.
Unlike an electric motor, an engine cannot simply be commanded to a thrust value: it has to be _started_ (choke, ignition, electric starter), it can _die_ in flight and need restarting, and it must be kept above a minimum idle speed to keep running at all.
The [`internal_combustion_engine_control`](../modules/modules_system.md#internal-combustion-engine-control) module implements this logic as a state machine that drives four dedicated actuator outputs and closes the loop on a measured engine speed (RPM).
::: warning
A running combustion engine with a propeller attached is dangerous.
The engine can be commanded to start automatically (for example on arming, or on a VTOL transition to fixed-wing), and the starter motor will crank the propeller without further warning.
- Always do your first bench tests with the propeller removed.
- For continuous operation without a propeller, a flywheel is recommended.
- Keep clear of the propeller arc whenever the vehicle is powered.
- Verify that the engine stop functionality (ignition off, choke closed) reliably stops the engine before you rely on it.
:::
## Hardware Requirements
- **Throttle servo** connected to a PWM/AUX output.
- **Ignition cut** on an output, typically through a relay or opto-isolated switch that shorts or interrupts the ignition circuit.
Optional.
- **Choke servo** on an output (optional if the engine has no choke, or an automatic one — set [ICE_CHOKE_ST_DUR](../advanced_config/parameter_reference.md#ICE_CHOKE_ST_DUR) to `0` and leave the function unassigned).
- **Electric starter** on an output, typically through a relay or an ESC driving the starter motor.
Optionally, the engine can also be hand-started.
- **RPM sensor** feeding the `RPM Input` function on a timer-capture-capable PWM pin, for example a Hall-effect or optical sensor on the crankshaft, or an ignition-pulse pickup.
Many engines have a built-in spark-timing sensor that can be used for this.
If yours does not, see [Tachometers](../sensor/tachometers.md) for other options.
::: warning
RPM feedback is **required**.
The state machine only leaves `Starting` for `Running` once it sees a measured engine speed above [ICE_MIN_RUN_RPM](../advanced_config/parameter_reference.md#ICE_MIN_RUN_RPM).
Without a working RPM sensor the module will exhaust its start attempts and latch into the `Fault` state.
:::
## Firmware Configuration
The module and the RPM capture driver are not in the default builds.
Add them to the [board configuration](../hardware/porting_guide_config.md) for your flight controller:
```text
CONFIG_MODULES_INTERNAL_COMBUSTION_ENGINE_CONTROL=y
CONFIG_DRIVERS_RPM_CAPTURE=y
```
Both can also be enabled interactively with `make <target> boardconfig`, under **modules** and **drivers** respectively.
## Parameter Setup
Set the following and reboot:
- [ICE_EN](../advanced_config/parameter_reference.md#ICE_EN) to `Enabled`.
The startup script only starts the module if this is set.
- [RPM_CAP_ENABLE](../advanced_config/parameter_reference.md#RPM_CAP_ENABLE) to `Enabled`.
- [RPM_PULS_PER_REV](../advanced_config/parameter_reference.md#RPM_PULS_PER_REV) to the number of sensor pulses per crankshaft revolution (for example `2` for a two-magnet setup, or `1` for a single ignition pulse per revolution on a two-stroke).
Then work through the remaining `ICE_*` parameters:
- [Actuator Configuration](#actuator-configuration) — wire up the engine outputs.
- [Start/Stop Command Source](#start-stop-command-source) — choose what commands the engine on and off.
- [Idle RPM Governor](#idle-rpm-governor) — set up and tune closed-loop idle, and the `ICE_IDLE_*` parameters.
- [Parameter Reference](#parameter-reference) — the full list, including the start sequence timing.
## Actuator Configuration
Assign the four engine functions and the RPM input in [Actuator Configuration](../config/actuators.md), for example:
![Actuator setup for ICE, with the engine output functions and the RPM input highlighted](../../assets/hardware/ice/ice_actuator_setup.png)
Each setpoint is in the range `[0, 1]` and is mapped to the `[-1, 1]` servo range before being scaled to the output's **Minimum**/**Maximum** values.
In other words, a setpoint of `0` produces the configured **Minimum** output and `1` produces the configured **Maximum** output (or the reverse, if **Rev Range** is ticked).
::: info
When the engine is commanded off, the throttle setpoint is `NAN`, which by definition drives the output to its configured **Disarmed** value rather than to **Minimum**.
This lets you park the throttle servo at an idle-stop position that is different from the closed-throttle position used to switch off the engine.
The throttle output also goes to _Disarmed_ while the engine is running if the [idle governor](#idle-rpm-governor) is disabled and the throttle demand drops to near zero (the fixed-wing controller stops the motor below 2% thrust).
:::
Points to note when setting the values:
- `IC Engine Throttle` uses **Minimum** for closed throttle and **Maximum** for full throttle.
Setting **Disarmed** to a value other than **Minimum** parks the servo at an idle stop when the engine is off, rather than at closed throttle.
- `IC Engine Choke` uses **Minimum** for choke open and **Maximum** for choke closed; tick **Rev Range** if the servo linkage is inverted.
- `IC Engine Ignition` and `IC Engine Starter` behave as on/off outputs: **Minimum** is "off" and **Maximum** is "on".
Set both values so that the relay switches reliably, and make sure **Disarmed** corresponds to ignition off and starter off.
- `RPM Input` must be on a channel that supports timer capture on your board.
::: tip
In the example above the **Actuators** tab stays red in the sidebar, and the page shows "One or more actuator still needs to be assigned to an output".
This is expected for an engine setup and does not stop the engine from running: the airframe's `Motor 1` slot is deliberately left unassigned, because the throttle reaches the servo through `IC Engine Throttle` instead — see [How It Works](#how-it-works).
:::
::: warning
While the vehicle is disarmed, every output — including ignition, choke, and starter — is held at its **Disarmed** value, regardless of what the module commands.
The engine can only be commanded when [armed or prearmed](../advanced_config/prearm_arm_disarm.md).
:::
Whether prearming happens at all is set by [COM_PREARM_MODE](../advanced_config/parameter_reference.md#COM_PREARM_MODE), which matters if you want to start the engine before arming (for example from an AUX switch, see [Start/Stop Command Source](#start-stop-command-source)):
| `COM_PREARM_MODE` | Effect on the engine outputs |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `Disabled` (default) | Never prearms, so the outputs stay at their **Disarmed** values until the vehicle is armed. |
| `Safety button` | Outputs become live once the safety switch is released. Has no effect on boards that have no safety button — prearm then never engages. |
| `Always` | Outputs become live 5 s after boot. |
::: warning
With `Always` the ignition, choke, and starter outputs are live shortly after power-up, before any arming check has run.
The engine can be commanded to crank on a vehicle that was never armed, so treat the propeller as live whenever the vehicle is powered.
:::
## Start/Stop Command Source {#start-stop-command-source}
[ICE_ON_SOURCE](../advanced_config/parameter_reference.md#ICE_ON_SOURCE) selects what asks for the engine to run:
| Value | Engine is requested on when |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `On arming - disarming` (0) | The vehicle is armed. This is the default. |
| `Aux1` (1) | The AUX1 manual control channel is above `0.5`; requested off when it goes below `-0.5`. Map a switch to it with `RC_MAP_AUX1`. |
| `Aux2` (2) | As above, using AUX2 and `RC_MAP_AUX2`. |
| `On Vtol Transitions` (3) | The vehicle is in fixed-wing mode or transitioning to fixed-wing. Use this on a hybrid VTOL where the engine only drives the pusher/forward propeller. |
::: info
For the AUX sources, values between `-0.5` and `0.5` leave the request unchanged.
This dead zone means a three-position switch has a middle position that does not change the engine state, and it prevents a channel that is momentarily centred (or lost and defaulted to zero) from cutting the engine.
:::
## Idle RPM Governor
Left at a fixed low throttle, an engine tends either to die or to sit at an unpredictable idle speed that depends on temperature, air density, and mixture.
The idle governor closes the loop on measured RPM whenever the throttle demand is low, keeping the engine alive and ready to accelerate.
It is enabled by setting [ICE_IDLE_RPM](../advanced_config/parameter_reference.md#ICE_IDLE_RPM) to a non-zero idle speed.
When enabled, the `Running` state has two sub-states, reported in `InternalCombustionEngineStatus.substate`:
- `Run` — the throttle demand from allocation is passed straight through.
- `Idle` — the throttle output is produced by the governor instead.
The module enters `Idle` when the throttle demand drops below 2% (or becomes invalid, i.e. the vehicle is disarmed), **or** whenever the measured RPM falls below the idle setpoint.
The second condition is what catches a sagging engine: even at high commanded throttle, if the engine is being dragged below its idle speed the governor takes over and pushes the throttle to recover it.
It leaves `Idle` again as soon as the throttle demand exceeds the governor's current output, so the handover happens without a step in the output.
### Control Structure
The governor is a feed-forward plus PI controller with output clamped to `[0, 1]`:
```
throttle = ICE_IDLE_THR_FF + P · e + ∫ I · e dt
e = ICE_IDLE_RPM − rpm_estimate
P = ICE_IDLE_RPM_P · 1e-3
I = ICE_IDLE_RPM_I · 1e-3
```
The `1e-3` scaling is what makes the gains convenient to reason about:
- [ICE_IDLE_RPM_P](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_P) is the normalised throttle added per **1000 RPM** of error.
`ICE_IDLE_RPM_P = 1` means an engine running 500 RPM slow gets `+0.5` throttle.
- [ICE_IDLE_RPM_I](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_I) is the normalised throttle added per **1000 RPM·s** of accumulated error.
`ICE_IDLE_RPM_I = 1` means a steady 100 RPM error winds the output up by `0.1` every second.
- [ICE_IDLE_THR_FF](../advanced_config/parameter_reference.md#ICE_IDLE_THR_FF) is the throttle that holds the idle speed on its own, so the PI terms only have to correct for the difference.
It is applied as a constant offset whenever the governor is active.
The integrator is limited to `±1` and uses conditional integration: it stops winding up in whichever direction is already driving the output into saturation.
It is reset to zero every time the engine reaches `Running`, so a start never inherits wind-up from a previous run.
### Tuning Procedure
Do this on the ground, with the propeller removed or the vehicle firmly restrained, and with the engine warm.
1. **Find the idle speed.**
Pick the [ICE_IDLE_RPM](../advanced_config/parameter_reference.md#ICE_IDLE_RPM) you want — low enough not to produce useful thrust, high enough that the engine runs smoothly and can accelerate without hesitating.
The engine's specification or a hand-throttled test is the starting point.
2. **Find the feed-forward.**
With the governor still off (`ICE_IDLE_RPM = 0`), start the engine and hold it at that RPM with the throttle stick in a manual mode.
Read the commanded throttle off the log (`internal_combustion_engine_control.throttle_control`), set [ICE_IDLE_THR_FF](../advanced_config/parameter_reference.md#ICE_IDLE_THR_FF) to it, and set `ICE_IDLE_RPM` to the target.
3. **Verify feed-forward only.**
With both gains still at `0`, restart and let the engine idle.
It should settle near the setpoint.
A large steady offset means the feed-forward is wrong — correct it before adding gains, because the PI terms are only meant to trim.
4. **Add proportional gain.**
Raise [ICE_IDLE_RPM_P](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_P) in steps (`0.2` is a reasonable first step) until the engine recovers briskly when you disturb it — for example by briefly blipping the throttle up and releasing it.
Back off as soon as you see the RPM hunting or the throttle oscillating.
5. **Add integral gain.**
Raise [ICE_IDLE_RPM_I](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_I) just enough to remove any remaining steady-state RPM offset within a few seconds.
Too much integral shows up as a slow oscillation around the setpoint.
6. **Check the handover.**
Sweep the throttle demand up and back down through the idle point and confirm there is no jump or dead spot as the sub-state switches between `Idle` and `Run`.
The signals to look at in the [flight log](../log/flight_log_analysis.md):
| Signal | Use |
| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `rpm.rpm_estimate` | Measured engine speed — compare against `ICE_IDLE_RPM`. |
| `internal_combustion_engine_control.throttle_control` | Throttle actually commanded, after the governor and the slew rate limit. |
| `internal_combustion_engine_status.substate` | Whether the governor is active (`1` = `Idle`). |
| `internal_combustion_engine_status.pid_idle_rpm_integral` | Integrator state. Parked at `±1` means it is saturated and the feed-forward is far off. |
| `internal_combustion_engine_status.state` | State machine state — reveals unnoticed restarts. |
Both `internal_combustion_engine_*` topics are logged when the module is running.
::: info
`rpm_capture` low-pass filters the RPM estimate with a 0.5 s time constant.
That lag is part of the loop you are tuning and puts a practical ceiling on how high the gains can go before the governor starts hunting.
:::
## Parameter Reference
| Parameter | Unit | Default | Description |
| ------------------------------------------------------------------------------ | ---- | ------- | ---------------------------------------------------------------------------- |
| [ICE_EN](../advanced_config/parameter_reference.md#ICE_EN) | — | `0` | Start the ICE control module. Requires a reboot. |
| [ICE_ON_SOURCE](../advanced_config/parameter_reference.md#ICE_ON_SOURCE) | — | `0` | What requests the engine on/off: arming, AUX1, AUX2, or VTOL transitions. |
| [ICE_MIN_RUN_RPM](../advanced_config/parameter_reference.md#ICE_MIN_RUN_RPM) | rpm | `2000` | RPM above which the engine counts as running. |
| [ICE_IGN_DELAY](../advanced_config/parameter_reference.md#ICE_IGN_DELAY) | s | `0` | Delay between switching on the ignition and engaging the starter. |
| [ICE_CHOKE_ST_DUR](../advanced_config/parameter_reference.md#ICE_CHOKE_ST_DUR) | s | `5` | How long the choke stays closed on the first start attempt. |
| [ICE_STRT_DUR](../advanced_config/parameter_reference.md#ICE_STRT_DUR) | s | `5` | Cranking time per attempt after the choke opens, before declaring a timeout. |
| [ICE_STRT_THR](../advanced_config/parameter_reference.md#ICE_STRT_THR) | norm | `0.1` | Throttle held during choking and cranking. |
| [ICE_STRT_ATTEMPT](../advanced_config/parameter_reference.md#ICE_STRT_ATTEMPT) | — | `3` | Start attempts before entering `Fault`. `0` means a single attempt. |
| [ICE_RUN_FAULT_D](../advanced_config/parameter_reference.md#ICE_RUN_FAULT_D) | — | `1` | Detect an engine stop while running and attempt a restart. |
| [ICE_STOP_CHOKE](../advanced_config/parameter_reference.md#ICE_STOP_CHOKE) | — | `1` | Close the choke while the engine is stopped or in fault. |
| [ICE_THR_SLEW](../advanced_config/parameter_reference.md#ICE_THR_SLEW) | 1/s | `0.5` | Maximum rate of change of the throttle output. |
| [ICE_IDLE_RPM](../advanced_config/parameter_reference.md#ICE_IDLE_RPM) | rpm | `0` | Idle RPM setpoint. `0` disables the idle governor. |
| [ICE_IDLE_THR_FF](../advanced_config/parameter_reference.md#ICE_IDLE_THR_FF) | norm | `0` | Feed-forward throttle for the idle governor. |
| [ICE_IDLE_RPM_P](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_P) | — | `0` | Idle governor proportional gain, per 1000 RPM of error. |
| [ICE_IDLE_RPM_I](../advanced_config/parameter_reference.md#ICE_IDLE_RPM_I) | — | `0` | Idle governor integral gain, per 1000 RPM·s of error. |
## Troubleshooting
| Symptom | Likely cause |
| ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nothing happens at all; `internal_combustion_engine_control status` reports the module is not running | `ICE_EN` is not set, or the module is not in the firmware. Check the [build configuration](#firmware-configuration) and reboot. |
| The engine runs but the state machine goes to [`Fault`](#state-machine) | The RPM sensor is not working or is misconfigured. Check `RPM_CAP_ENABLE`, `RPM_PULS_PER_REV`, and that the sensor is on a capture-capable pin; compare `rpm.rpm_estimate` against a hand tachometer. |
| Outputs never move even though the state machine advances | The vehicle is disarmed and not prearmed, so outputs are held at their **Disarmed** values. See the [note above](#actuator-configuration) on `COM_PREARM_MODE`. |
| The starter cranks but the engine never fires | There may be no fuel in the engine yet. Closing the choke is what draws fuel in, so a dry engine needs a longer priming window — increase `ICE_CHOKE_ST_DUR`. Also check the cranking time (`ICE_STRT_DUR`) and the start throttle (`ICE_STRT_THR`), and note that too much choke floods the engine. |
| The engine fires and then dies just after `Starting` finishes | No idle governor. Set up the [idle governor](#idle-rpm-governor); with `ICE_IDLE_RPM = 0` there is nothing holding the engine up when the throttle demand is zero. |
| Repeated in-air restarts logged as `IC engine fault detected` | `ICE_MIN_RUN_RPM` is set too close to the actual idle speed, so normal idle dips read as an engine stop. Raise the idle setpoint or lower the threshold. |
| The engine bogs down or stalls on throttle up | `ICE_THR_SLEW` is too high for the engine. Reduce it so the throttle opens more gradually. |
## Developer Information
### How It Works
<img src="../../assets/hardware/ice/ice_control_diagram.svg" alt="ICE control architecture" class="diagram-invert">
The module sits between the [control allocator](../config/actuators.md) and the outputs:
- It takes the **throttle demand** from `actuator_motors.control[0]`, i.e. the thrust that allocation computed for `Motor 1`.
::: info
The engine takes its throttle from whichever rotor the airframe geometry defines as `Motor 1` (rotor 0, `CA_ROTOR0_*`), so you must set up the geometry with the engine as rotor 0.
On a standard VTOL, this means making the pusher rotor 0 rather than the last rotor.
You do not need to (and should not) assign an output for the `Motor 1` function.
:::
- It takes the **on/off request** from [VehicleStatus](../msg_docs/VehicleStatus.md) (arming state, or the VTOL transition) or from [ManualControlSetpoint](../msg_docs/ManualControlSetpoint.md) (the AUX channels), depending on [ICE_ON_SOURCE](#start-stop-command-source).
- It runs the start/stop state machine and publishes [InternalCombustionEngineControl](../msg_docs/InternalCombustionEngineControl.md) with the setpoints for ignition, throttle, choke, and starter.
- The mixer maps those four fields to the four `IC Engine *` [output functions](../config/actuators.md), which is where you wire the engine hardware.
- It subscribes to [Rpm](../msg_docs/Rpm.md) to know whether the engine is actually turning, and publishes [InternalCombustionEngineStatus](../msg_docs/InternalCombustionEngineStatus.md) with the current state.
The module runs at 50 Hz.
#### Output Functions
| Output function | Field in `InternalCombustionEngineControl` | Meaning |
| -------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `IC Engine Ignition` | `ignition_on` | Spark/ignition enable. `false` cuts the spark and stops the engine (optional: many engine spark boxes always run when powered). |
| `IC Engine Throttle` | `throttle_control` | Throttle servo setpoint, `0`…`1`. `NAN` while the engine is commanded off. |
| `IC Engine Choke` | `choke_control` | Choke servo setpoint, `0`…`1`, where `1` is fully closed (richest mixture). Optional actuator. |
| `IC Engine Starter` | `starter_engine_control` | Electric starter motor setpoint, `0`…`1`. Optional actuator: the engine can also be hand-started. |
### State Machine
<img src="../../assets/hardware/ice/ice_control_state_machine.svg" alt="ICE control state machine" class="diagram-invert">
The module has four states, reported in `InternalCombustionEngineStatus.state`:
| State | Ignition | Throttle | Choke | Starter |
| ---------- | -------- | --------------------------------------- | ------------------------------------- | ------------------------------------- |
| `Stopped` | off | `NAN` (→ **Disarmed** value) | `ICE_STOP_CHOKE ? 1 : 0` | `0` |
| `Starting` | on | `ICE_STRT_THR` | see [start sequence](#start-sequence) | see [start sequence](#start-sequence) |
| `Running` | on | motor 1 demand, or idle governor output | `0` | `0` |
| `Fault` | off | `0` | `ICE_STOP_CHOKE ? 1 : 0` | `0` |
Transitions:
- `Stopped` → `Starting` when the engine is requested on and the start attempt budget is not exhausted.
- `Starting` → `Running` as soon as the measured RPM exceeds [ICE_MIN_RUN_RPM](../advanced_config/parameter_reference.md#ICE_MIN_RUN_RPM).
This can happen part way through an attempt.
- `Starting` → `Fault` when all attempts have been used without the engine coming up.
- `Running` → `Starting` if the RPM drops back below the threshold and [ICE_RUN_FAULT_D](../advanced_config/parameter_reference.md#ICE_RUN_FAULT_D) is enabled — this is the automatic in-air restart.
An `IC engine fault detected` event is emitted.
- Any state → `Stopped` when the engine is requested off.
This also resets the attempt counter, so switching the request off and on again is the way to clear a `Fault`.
Both `Starting` and `Running` have sub-states, reported in `InternalCombustionEngineStatus.substate`.
`Starting` alternates between cranking and a one-second rest between attempts (see [Start Sequence](#start-sequence)), and `Running` switches between passing the throttle demand straight through and running the [idle governor](#idle-rpm-governor).
::: info
The throttle setpoint is rate limited by [ICE_THR_SLEW](../advanced_config/parameter_reference.md#ICE_THR_SLEW) in all states, which protects the engine from abrupt throttle steps that would make it bog down or stall.
The limit does not apply to the `NAN` used in `Stopped`; the slew state is reset to zero instead, so the next start ramps up from closed throttle.
:::
#### Start Sequence
One start attempt runs the following timeline, measured from entry into the attempt:
| From | To | Ignition | Choke | Starter | Throttle |
| ---------------------------------- | ------------------------------------------------- | -------- | ----- | ------- | -------------- |
| `0` | `ICE_IGN_DELAY` | on | `1` | `0` | `ICE_STRT_THR` |
| `ICE_IGN_DELAY` | `ICE_IGN_DELAY + ICE_CHOKE_ST_DUR` | on | `1` | `1` | `ICE_STRT_THR` |
| `ICE_IGN_DELAY + ICE_CHOKE_ST_DUR` | `ICE_IGN_DELAY + ICE_CHOKE_ST_DUR + ICE_STRT_DUR` | on | `0` | `1` | `ICE_STRT_THR` |
- [ICE_IGN_DELAY](../advanced_config/parameter_reference.md#ICE_IGN_DELAY) holds the starter off for a moment after the ignition is switched on, for ignition systems that need time to come up.
- [ICE_CHOKE_ST_DUR](../advanced_config/parameter_reference.md#ICE_CHOKE_ST_DUR) is how long the choke stays closed.
Note that the starter is already cranking during this window.
- [ICE_STRT_DUR](../advanced_config/parameter_reference.md#ICE_STRT_DUR) is how much longer the starter cranks with the choke open before the attempt is declared timed out.
If the attempt times out, the module rests for **1 second** with the ignition off and the throttle at its disarmed value (to reduce starter motor wear) and then begins the next attempt.
::: info
Choke and ignition delay are applied on the **first** attempt only.
Retries crank with the choke open immediately, on the assumption that the first attempt already primed the engine and that further choking would flood it.
:::
[ICE_STRT_ATTEMPT](../advanced_config/parameter_reference.md#ICE_STRT_ATTEMPT) caps the number of attempts before the module gives up and enters `Fault`.
A value of `0` means a single attempt with no retry.
### Status and Telemetry
- [InternalCombustionEngineControl](../msg_docs/InternalCombustionEngineControl.md) carries the commanded setpoints and the current user request.
- [InternalCombustionEngineStatus](../msg_docs/InternalCombustionEngineStatus.md) carries the state machine state and the governor's integrator.
The same topic is used by the [DroneCAN](../dronecan/index.md) ICE bridge (`UAVCAN_SUB_ICE`), which fills in the richer engine telemetry — temperatures, pressures, fuel flow — reported by a smart ECU.
- The status topic is streamed to a ground station as the MAVLink [EFI_STATUS](https://mavlink.io/en/messages/common.html#EFI_STATUS) message.
## See Also
- [`internal_combustion_engine_control`](../modules/modules_system.md#internal-combustion-engine-control) — module command line reference.
- [Actuator Configuration](../config/actuators.md) — assigning output functions.
- [DroneCAN Peripherals](../dronecan/index.md) — for engines with a smart ECU reporting over DroneCAN.
+20 -38
View File
@@ -411,54 +411,36 @@ Source: [modules/internal_combustion_engine_control](https://github.com/PX4/PX4-
### Description
The module controls internal combustion engine (ICE) features including:
ignition (on/off), throttle and choke level, starter engine delay, and user request.
Controls a spark-ignition internal combustion engine (ICE): ignition, throttle, choke, and
electric starter motor. A state machine sequences the start attempts, restarts the engine if
it stops in flight, and runs a closed loop idle RPM governor.
The throttle demand is taken from motor 1 of the control allocator. The resulting setpoints are
published in [InternalCombustionEngineControl.msg](../msg_docs/InternalCombustionEngineControl.md),
which the mixer maps to the four `IC Engine *` output functions (ignition, throttle, choke, starter).
In the "Stopped" state the throttle setpoint is NAN, which by definition drives the output to
the disarmed value configured for that output.
The engine speed is read from [Rpm.msg](../msg_docs/Rpm.md) and is required for operation: the
state machine only declares the engine running once the measured RPM exceeds ICE_MIN_RUN_RPM.
The state machine state is reported in
[InternalCombustionEngineStatus.msg](../msg_docs/InternalCombustionEngineStatus.md).
### Enabling
This feature is not enabled by default needs to be configured in the
build target for your board together with the rpm capture driver:
The module and the RPM capture driver are not in the default builds and have to be added to the
board configuration:
```
CONFIG_MODULES_INTERNAL_COMBUSTION_ENGINE_CONTROL=y
CONFIG_DRIVERS_RPM_CAPTURE=y
```
Additionally, to enable the module:
The module is then started at boot if
[ICE_EN](../advanced_config/parameter_reference.md#ICE_EN) is set.
- Set [ICE_EN](../advanced_config/parameter_reference.md#ICE_EN)
to true and adjust the other `ICE_` module parameters according to your needs.
- Set [RPM_CAP_ENABLE](../advanced_config/parameter_reference.md#RPM_CAP_ENABLE) to true.
The module outputs control signals for ignition, throttle, and choke,
and takes inputs from an RPM sensor.
These must be mapped to AUX outputs/inputs in the [Actuator configuration](../config/actuators.md),
similar to the setup shown below.
![Actuator setup for ICE](../../assets/hardware/ice/ice_actuator_setup.png)
### Implementation
The ICE is implemented with a (4) state machine:
![Architecture](../../assets/hardware/ice/ice_control_state_machine.png)
The state machine:
- Checks if [Rpm.msg](../msg_docs/Rpm.md) is updated to know if the engine is running
- Allows for user inputs from:
- Manual control AUX
- Arming state in [VehicleStatus.msg](../msg_docs/VehicleStatus.md)
- In the state "Stopped" the throttle is set to NAN, which by definition will set the
throttle output to the disarmed value configured for the specific output.
The module publishes [InternalCombustionEngineControl.msg](../msg_docs/InternalCombustionEngineControl.md).
The architecture is as shown below:
![Architecture](../../assets/hardware/ice/ice_control_diagram.png)
<a id="internal_combustion_engine_control_usage"></a>
See [Internal Combustion Engines](../actuators/internal_combustion_engine.md) for the hardware
setup, actuator configuration, start sequence timing, and idle governor tuning.
### Usage {#internal_combustion_engine_control_usage}
+4 -4
View File
@@ -1,16 +1,16 @@
# Internal combustion engine (ICE) actuator setpoints
#
# Published by the internal_combustion_engine_control module, which runs the engine
# Published by the `internal_combustion_engine_control` module, which runs the engine
# start/stop state machine and the idle RPM governor.
# The mixer maps these setpoints onto the IC Engine output functions (ignition,
# throttle, choke, starter), which are assigned to the flight controller outputs.
# The resulting state machine state is reported in InternalCombustionEngineStatus.
# The resulting state machine state is reported in `InternalCombustionEngineStatus`.
uint64 timestamp # [us] Time since system start
bool ignition_on # Activate/deactivate the ignition (spark plug)
float32 throttle_control # [norm] [@range 0, 1] [@invalid NaN Stops the engine, output goes to its disarmed value] Throttle actuator setpoint, rate limited by ICE_THR_SLEW. 0 is closed throttle
float32 throttle_control # [norm] [@range 0, 1] [@invalid NaN Stops the engine: output goes to its disarmed value] Throttle actuator setpoint, rate limited by `ICE_THR_SLEW`. 0 is closed throttle
float32 choke_control # [norm] [@range 0, 1] Choke actuator setpoint, 1 is fully closed
float32 starter_engine_control # [norm] [@range 0, 1] (Electric) starter motor setpoint
bool user_request_motor_on # User intent for the engine to be running, from the source selected by ICE_ON_SOURCE
bool user_request_motor_on # User intent for the engine to be running, from the source selected by `ICE_ON_SOURCE`
@@ -412,55 +412,15 @@ int InternalCombustionEngineControl::print_usage(const char *reason)
R"DESCR_STR(
### Description
The module controls internal combustion engine (ICE) features including:
ignition (on/off), throttle and choke level, starter engine delay, and user request.
Controls a spark-ignition internal combustion engine (ICE): ignition, throttle, choke and
electric starter motor. A state machine sequences the start attempts, restarts the engine if
it stops in flight, and runs a closed-loop idle RPM governor.
### Enabling
The module is not in the default builds, and is only started at boot if
[ICE_EN](../advanced_config/parameter_reference.md#ICE_EN) is set.
This feature is not enabled by default needs to be configured in the
build target for your board together with the rpm capture driver:
```
CONFIG_MODULES_INTERNAL_COMBUSTION_ENGINE_CONTROL=y
CONFIG_DRIVERS_RPM_CAPTURE=y
```
Additionally, to enable the module:
- Set [ICE_EN](../advanced_config/parameter_reference.md#ICE_EN)
to true and adjust the other `ICE_` module parameters according to your needs.
- Set [RPM_CAP_ENABLE](../advanced_config/parameter_reference.md#RPM_CAP_ENABLE) to true.
The module outputs control signals for ignition, throttle, and choke,
and takes inputs from an RPM sensor.
These must be mapped to AUX outputs/inputs in the [Actuator configuration](../config/actuators.md),
similar to the setup shown below.
![Actuator setup for ICE](../../assets/hardware/ice/ice_actuator_setup.png)
### Implementation
The ICE is implemented with a (4) state machine:
![Architecture](../../assets/hardware/ice/ice_control_state_machine.png)
The state machine:
- Checks if [Rpm.msg](../msg_docs/Rpm.md) is updated to know if the engine is running
- Allows for user inputs from:
- Manual control AUX
- Arming state in [VehicleStatus.msg](../msg_docs/VehicleStatus.md)
- In the state "Stopped" the throttle is set to NAN, which by definition will set the
throttle output to the disarmed value configured for the specific output.
The module publishes [InternalCombustionEngineControl.msg](../msg_docs/InternalCombustionEngineControl.md).
The architecture is as shown below:
![Architecture](../../assets/hardware/ice/ice_control_diagram.png)
<a id="internal_combustion_engine_control_usage"></a>
See [Internal Combustion Engines](../actuators/internal_combustion_engine.md) for the firmware
and hardware setup, actuator configuration, start sequence timing and idle governor tuning.
)DESCR_STR");
PRINT_MODULE_USAGE_NAME("internal_combustion_engine_control", "system");