Lua

Lua Scripting

TL;DR: Connect with TunerStudio, open the Lua tab (or use epicEFI Console), and edit your script there. Lua runs on the ECU for live scripting. The most popular use case is CAN bus integration.

Introduction

epicEFI gives you a lot of flexibility — enough to build user-defined control strategies for primary and auxiliary actuators. Boards with an F7 or H7 MCU (EpicECU, M144H7, M144F7RED, etc.) have the most headroom for Lua. F4 boards (MEGA100F4, UAEFI) also support Lua but with tighter memory limits.

Variable names and hashes

Calibration names, output channel names, variable types (CONFIG GETTER/SETTER, OUTPC GETTER/SETTER), and their djb2 hashes depend on your exact firmware build. Do not guess — look them up here:

Variable Status Selector

Use this tool when calling getCalibration() / setCalibration(), getOutput(), configuring user-table axes, or reading/writing variables over EPIC CAN.

Basics

epicEFI provides hooks to interface with the firmware, manipulate its state, and read/write configuration:

• Hooks for CAN bus communications
• Inputs from sensors can be read directly. You can also produce sensor values with Lua.
• ECU general purpose outputs
• Aspects of the engine can be controlled directly
• ECU configuration can be accessed (read/write) via getCalibration() and setCalibration().
  • Valid calibration names for your firmware are listed in the Variable Status Selector.
• ECU internal state (logic outputs / Live Data values) can be read via getOutput(), and some can be changed via dedicated setters (e.g. setClutchUpState()). See Output.
  • Valid output names for your firmware are listed in the Variable Status Selector.
• Hooks to read values from SENT sensors; see SENT protocol.
• Useful helper routines; see Utility.

Some example uses are in Examples.

Conventions

• The Lua interpreter reports errors when something is wrong; check epicEFI Console / TunerStudio Lua output for errors and print() output.
• Unless otherwise noted, all index parameters are zero-based (first element is index 0).

Writing Your Script

The entire Lua script is loaded at startup. After that, a function named onTick is called periodically by epicEFI.

Simple startup example:

<syntaxhighlight lang="lua"> print('Hello Lua startup!')

function onTick()

   print('Hello onTick()')

end </syntaxhighlight>

Controlling the tick rate

setTickRate(hz) sets how often epicEFI calls onTick. If your script does heavy work, it may run slower than the requested rate. The Lua VM runs at low priority relative to engine control, so you cannot starve critical ECU functions — set the rate to whatever your script needs. onCanRx runs at the same rate as onTick.

<syntaxhighlight lang="lua"> n = 0 setTickRate(5) -- 5 Hz function onTick()

   print('Hello Lua: ' .. n)
   n = n + 1

end </syntaxhighlight>

Editing scripts

An editor with Lua Language Server (LSP) support makes writing scripts much easier.

Hooks / function reference

User settings

getOutput(name)

Example: getOutput("clutchUpState") or getOutput("brakePedalState").

Valid output names for your firmware: Variable Status Selector.

setBrakePedalState(value)

Use setBrakePedalState to report a CAN-based brake pedal to epicEFI.

setAcRequestState(value)

Use setAcRequestState to report a CAN-based A/C request.

setIgnDisabled(value)

Use setIgnDisabled for cranking safety and other ignition-cut strategies.

setAcDisabled(value)

Disable/suppress A/C regardless of how it would otherwise be enabled.

getCalibration(name)

Returns the current value of a scalar calibration setting. Example: getCalibration("cranking.rpm").

Full list of valid names: Variable Status Selector.

setCalibration(name, value, needEvent)

Sets a calibration value. Optionally fires a calibration change event depending on needEvent.

Example: setCalibration("cranking.rpm", 900, false)

burnconfig

Schedules a write of current calibration to flash once the engine is stopped.

findSetting(name, defaultValue)

Finds a user setting by name and returns its numeric value. Useful when the script author and the tuner are different people, or when editing is done only through TunerStudio fields rather than the Lua editor.

• Parameters
  • name: Variable name (matches the configuration field name)
  • defaultValue: Returned if the setting is not found

isFirmwareError

Returns true if the ECU is in a critical/fatal error state.

Engine control

startCrankingEngine()

Starts cranking as if the physical start button were pressed.

isEngineStopRequested()

Returns true if an engine stop was requested (by Lua or the start/stop button) within the last five seconds.

setSparkSkipRatio(ratio)

• setSparkSkipRatio(0) — skip 0% of ignition events (no skip)
• setSparkSkipRatio(0.5) — skip half of ignition events (never two consecutive skips)

Useful for torque reduction.

setSparkHardSkipRatio(ratio)

• setSparkHardSkipRatio(0) — no skip
• setSparkHardSkipRatio(0.75) — skip 75% of ignition events

setIdleAdd(percent)

Percent added to idle (including open loop).

setFuelAdd(amount)

Currently not functional.

Fuel mass to add to injection, scaled by setFuelMult(); starts at 0.

setFuelMult(coeff)

Currently not functional.

Multiplier for added fuel mass; starts at 1.0.

setBoostTargetAdd(amount)

Additive offset for closed-loop boost target.

setBoostTargetMult(coeff)

Multiplier for closed-loop boost target.

setBoostDutyAdd(amount)

Additive offset for open-loop boost duty.

setTimingAdd(angle)

Use negative values to retard timing.

setTimingMult(coeff)

Useful for torque reduction.

setEtbAdd(percent)

ETB adder as a percent of wide-open: e.g. 10 adds +10%. Static offset on top of the computed position (TPS 5% + 10 → 15% ETB command).

Useful for torque reduction.

Timer

yourTimer = Timer.new() creates a timer object.

reset

yourTimer:reset() resets the timer.

getElapsedSeconds

yourTimer:getElapsedSeconds() returns seconds since last reset.

getTsButtonCount

getTsButtonCount(X) returns how many times Lua button X was pressed in TunerStudio. See ts-button-example.lua in the firmware examples.

CAN bus

enableCanTx(isEnabled)

Enabled by default. Use enableCanTx(false) to suppress CAN transmit from Lua.

txCan(bus, ID, isExt, payload)

• Parameters
  • bus: Hardware CAN bus index — typically 1 on single-CAN boards; 1 or 2 on dual-CAN boards (EpicECU, M144H7, etc.)
  • isExt: 0 for 11-bit standard ID

canRxAddMask(bus, id, mask, callback)

• Parameters
  • id: CAN ID to listen for
  • mask: Applied to the received ID before comparison. Example: id 3 and mask 0xFF matches any frame whose low 8 bits are 3. Omit the mask to match exactly one ID.
  • bus: Hardware CAN bus index. If omitted, frames from any bus are received.
  • callback: Function called when a matching frame arrives. If omitted, onCanRx is used.

CAN RX callback shape:

<syntaxhighlight lang="lua"> function onCanRx(bus, id, dlc, data)

   -- handle frame

end </syntaxhighlight>

For high-throughput RX, see enableCanRxWorkaround() in the firmware examples.

PID

deltaTime is measured automatically between successive pid:get calls.

<syntaxhighlight lang="lua"> -- p, i, d, min, max pid = Pid.new(2, 0, 0, -100, 100) pid:setOffset(0.3) pid:get(target, input) pid:reset()

industrialPid = IndustrialPid.new(2, 0, 0, -100, 100) industrialPid:setOffset(0.3) industrialPid:setDerivativeFilterLoss(0.3) industrialPid:setAntiwindupFreq(0.3) industrialPid:get(target, input) industrialPid:reset() </syntaxhighlight>

Utility

print(msg)

Prints a line to the ECU log.

• Parameters: msg — string or number
• Returns: none

vin(index)

Returns the VIN character at the given zero-based index.

Example:

<syntaxhighlight lang="lua"> n = 5.5 print('Hello Lua, number is: ' .. n) </syntaxhighlight>

Output: Hello Lua, number is: 5.5

setTickRate(hz)

Sets how often epicEFI calls onTick and onCanRx, in Hz. Default after reset is 10 Hz.

• Parameters: hz — clamped to 1–200 Hz
• Returns: none

mcu_standby()

Puts the MCU into standby (low current). Use with care.

interpolate(x1, y1, x2, y2, x)

Linear interpolation of x on the line through (x1, y1) and (x2, y2).

findTableIndex(name)

Returns the index of a script table by human-readable name.

table3d(tableIdx, x, y)

Looks up a value from a script 3D table.

• Parameters
  • tableIdx: Table index (1–4)
  • x: X-axis value (often RPM)
  • y: Y-axis value (often load)
• Returns: table output value

findCurveIndex(name)

Returns the index of a script curve by name.

curve(curveIdx, x)

Looks up a value from a script curve.

• Parameters
  • curveIdx: Curve index (1-based)
  • x: Axis value

setDebug(index, value)

Sets a debug channel when ECU debug mode is Lua.

• Parameters: index 1–7, value — channel value
• Returns: none

Input

getSensor(name)

Reads a sensor by name, e.g. getSensor("AcceleratorPedal").

• Parameters: name — sensor name (same names as TunerStudio Live Data, e.g. TPS, CLT, RPM, MAP)
• Returns: reading, or nil if the sensor is invalid or not configured

getSensorByIndex(index)

Reads a sensor by enum index.

• Returns: reading, or nil on failure

getSensorRaw(index)

Raw sensor value (usually pin voltage before scaling).

• Returns: raw value, or 0 if unsupported / not configured / failed

getAuxAnalog(index)

Like getSensorRaw but for aux analog inputs — always voltage.

• Parameters: index 0–3
• Returns: voltage, or nil if not configured

hasSensor(index)

Whether a sensor slot is configured (valid or not).

• Returns: boolean

getDigital(index)

Reads a built-in digital input.

Index	Channel
0	Clutch down
1	Clutch up
2	Brake switch
3	AC switch

getAuxDigital(index)

Reads a user-configured digital input (index 0–7). Configure pins under Lua Digital Aux Inputs in TunerStudio.

readPin(pinName)

Reads an MCU pin directly (e.g. "PD15"). Emergency/debug only — prefer Lua aux inputs for real logic.

Output

Not the same as Live Data “outputs” or GPPWM.

selfStimulateRPM(rpm)

Positive RPM starts injector clicking at that speed; 0 stops self-stimulation.

startPwm(index, frequency, duty)

Starts PWM on a Lua PWM output. Pin assignment: Lua PWM Outputs in TunerStudio.

• Parameters
  • index: 0–7
  • frequency: 1–1000 Hz
  • duty: 0.0 = off, 1.0 = full on

getGpPwm(index)

Current GPPWM output percent (index 0–3).

setLuaGauge(index, value)

Writes a Lua gauge (indices 1–8) for Live Data / logging.

setDacVoltage(index, value)

Only on boards with DAC hardware enabled.

Console commands

• luamemory — Lua memory usage
• luareset — reset Lua VM

Examples

Example scripts ship with the firmware under firmware/controllers/lua/examples/ (browse on GitHub).

Notable examples: honda-bcm.txt (VSS from CAN / gear detection), ford-focus-ii-pps.txt, bmw-idrive.txt.

Timer example

<syntaxhighlight lang="lua"> t = Timer.new() timingAdd = 0

function onTick()

  auxV = getAuxAnalog(0)
  tps = getSensor("TPS")
  -- check for nil if aux input is not assigned
  if auxV > 2 then
    t:reset()
  end

  val = t:getElapsedSeconds()

  if t:getElapsedSeconds() < 3 then
    timingAdd = 10
  else
    timingAdd = 0
  end
  setTimingAdd(timingAdd)

  print('Hello analog ' .. auxV .. " " .. val)

end </syntaxhighlight>

PWM

<syntaxhighlight lang="lua"> startPwm(0, 100, 0)

function onTick()

enable_pump = getSensor("RPM") > 700 and getSensor("BatteryVoltage") > 13 and getSensor("VehicleSpeed") < 60
setPwmDuty(0, enable_pump and 1 or 0)

end </syntaxhighlight>

CAN transmit

<syntaxhighlight lang="lua"> function onTick()

 clt = getSensor("CLT")
 print('CLT ' .. clt)
 voltage0 = getSensor("aux0")

 txPayload = {}
 txPayload[1] = math.floor(((voltage0/256) - math.floor(voltage0/256))*256)
 txPayload[2] = math.floor(voltage0 / 256)

 txCan(1, 0x600, 1, txPayload)

end </syntaxhighlight>

Set sensor value

Use standard sensor names from TunerStudio Live Data.

<syntaxhighlight lang="lua"> -- do not configure the same physical input elsewhere vssSensor = Sensor.new("VehicleSpeed") vssSensor:setTimeout(3000) function onTick()

injectedVssValue = 123.4
vssSensor:set(injectedVssValue)
valFromSensor = getSensor("VehicleSpeed")
print("VSS " .. valFromSensor)

end </syntaxhighlight>

CAN receive

<syntaxhighlight lang="lua"> canRxAdd(0x500) canRxAdd(0x570) function onCanRx(bus, id, dlc, data)

print('got CAN id=' .. id .. ' dlc=' .. dlc)
if id == 0x500 then
 canState = data[1]
end
if id == 0x570 then
 mcu_standby()
end

end </syntaxhighlight>

Table / curve

<syntaxhighlight lang="lua"> tableIndex = findTableIndex("duty")

TurbochargerSpeed = getSensor("TurbochargerSpeed") tps = getSensor("Tps1")

dutyCycle = table3d(tableIndex, TurbochargerSpeed, tps)

sparkCutCurve = findCurveIndex("sparkcut") sparkCutByTorque = curve(sparkCutCurve, torquex) </syntaxhighlight>

See also

• Variable Status Selector — names, types, and hashes for your firmware
• Lua examples — vehicle-specific scripts
• Lua ternary operator — Lua has no ?:; use and / or patterns