AG-SpdGa.lua

-- AG-SpdGa.lua — Speed Gauge: speed callouts, stall/overspeed warnings and a speedometer telemetry window.
-- Copyright (c) 2026 Aaron George
-- SPDX-License-Identifier: MIT
--
-- Based on DFM Speed Announcer v2.1 by DFM (Dave McQueeney),
-- https://github.com/davidmcq137/JetiLuaDFM
-- Portions Copyright (c) 2018, 2019 DFM (Dave McQueeney), MIT License.
-- Full license text in CREDITS.md.
--
-- Listen-and-inform only: it reads a speed sensor and switches, speaks,
-- vibrates the sticks and draws. It never controls the model
-- (constitution principle I).
--
-- Design: specs/001-speed-gauge/ (plan.md, research.md, data-model.md,
-- contracts/). Research decisions are cited as R1..R17.

local gauge = require("ag_gauge")
local dens = require("ag_dens")

local APP_NAME = "Speed Gauge"
local APP_VERSION = "0.3.0"
local AUDIO_DIR = "/Apps/AG-SpdGa/"
local TICK_MS = 100         -- loop logic runs at most 10x per second (R9)
-- The JETI Studio emulator draws each window's title bar inside the reported
-- canvas and clips the bottom, so about 25 px of h never shows (2026-09-27:
-- 60 -> ~34, 127 -> ~101, 260 -> ~236). The transmitter draws the title
-- above the window and reports only what is visible: 150 x 23, 150 x 68,
-- 316 x 159 (2026-10-03). The emulator's widths (157, 320) tell them apart.
local TITLE_H = 26
local HOLD_MS = 1000        -- a reading held this long counts as real for the max (R5)

local SND_STALL = AUDIO_DIR .. "stall_warning.wav"
local SND_OVER = AUDIO_DIR .. "overspeed.wav"
local SND_ALIVE = AUDIO_DIR .. "airspeed_alive.wav"
local SND_CAL = AUDIO_DIR .. "airspeed_cal_factor.wav"
local SND_STALL_AT = AUDIO_DIR .. "stall_speed_warning_at.wav"

-- App voice (Piper "Amy"), generated by tools/voice/ (FR-030, FR-035,
-- R13; the files are CC BY-SA 4.0). DFM's files above are the fallback
-- (FR-037).
-- Grouped in one table: the main chunk is close to Lua's 200-local limit.
local VOICE = { dir = AUDIO_DIR .. "voice/", maxNum = 500 }  -- maxNum: highest number in the set
VOICE.units = {             -- indexed by units, like UNITS_TEXT
  VOICE.dir .. "mph.wav", VOICE.dir .. "kmh.wav", VOICE.dir .. "kt.wav",
  VOICE.dir .. "ms.wav", VOICE.dir .. "fts.wav",
}
VOICE.pct = VOICE.dir .. "pct.wav"
VOICE.stall = VOICE.dir .. "stall.wav"
VOICE.over = VOICE.dir .. "over.wav"
VOICE.alive = VOICE.dir .. "alive.wav"
VOICE.stallAt = VOICE.dir .. "stallat.wav"
VOICE.cal = VOICE.dir .. "cal.wav"
VOICE.max = VOICE.dir .. "max.wav"         -- max-speed callout (FR-019a)

-- Units. The sensor value is m/s, as in DFM v2.1 (R3).
local UNITS_TEXT = { "mph", "km/h", "kt", "m/s", "ft/s" }
local UNITS_SPOKEN = { "mph", "km/h", "kt.", "m/s", "ft./s" }  -- must match numbers.jsn
local UNITS_MULT = { 2.23694, 3.6, 1.94384, 1.0, 3.28084 }
local UNITS_IMPERIAL = { true, false, true, false, true }

-- Color presets for a dark dial face; none red, orange or yellow (R8).
-- Yellow was added last so earlier saved indices keep their color.
local COLOR_NAMES = { "Cyan", "Blue", "White", "Green", "Lime", "Magenta", "Purple", "Grey", "Yellow" }
local COLORS = {
  { 0, 190, 255 }, { 40, 110, 255 }, { 255, 255, 255 }, { 0, 210, 100 },
  { 170, 240, 0 }, { 230, 60, 230 }, { 150, 100, 255 }, { 170, 170, 170 },
  { 255, 225, 0 },
}
-- Fixed dial colors (R6).
local C_BG = { 8, 10, 14 }       -- window background behind the dial face
local C_FACE = { 20, 24, 32 }
local C_TRACK = { 70, 78, 90 }
local C_ZONE = { 255, 80, 0 }
local C_SCALE = { 200, 200, 200 }
local C_MINOR = { 110, 118, 130 }
local C_TEXT = { 255, 255, 255 }
-- Glow inside the value arc: bands fading toward the dial center (reference
-- image), from GLOW[1] alpha at the arc to GLOW[2] at the innermost band.
-- Many thin bands with a gentle fade read as a gradient; each band is a
-- renderer polyline, and the glow is the biggest drawing cost (R6).
local GLOW = { 0.36, 0.02 }
-- Diagnostic, off for release: true shows this call's and the worst
-- system.getCPU() on the full-screen gauge (used to measure the glow on the
-- transmitter, 2026-10-03; worst 14% at speed).
local DEBUG_CPU = false     -- off after transmitter testing (T080, 2026-10-04)

local TXT_NOTICE = "Speed Gauge needs DS-24 II"
local TXT_MAX = "MAX"
-- Full-screen panel labels: short, because label and value share one line
-- in a ~124 px panel (transmitter 316 x 159, 2026-10-03).
local TXT_STALL = "STALL"
local TXT_OVERSPEED = "OVER"
local TXT_DENSITY = "DENSITY"
local TXT_SENSOR = "RAW"
local TXT_ELEVATION = "ELEV"
local TXT_OFF = "OFF"
local TXT_GPS = "GPS"
local TXT_NO_DATA = "---"

------------------------------------------------------------------------------
-- Settings (persisted per model; data-model.md). Integers, strings and
-- SwitchItems only; booleans are stored as 0/1 (constitution IV).
------------------------------------------------------------------------------

local KEYS = {
  "sId", "sPar", "sLbl", "sType", "swOn", "swCont", "tMin", "tMax", "sens",
  "vLand", "vStall", "vOver", "cal", "units", "numOnly", "startAnn", "densOn",
  "elev", "temp", "tSrc", "tId", "tPar", "tLbl", "colCur", "colMax", "fScale",
  "voice", "vArm", "landOn", "cfgV",
}  -- 30 keys: the limit (constitution IV). Make room before adding another.
local DEFAULTS = {
  sId = 0, sPar = 0, sLbl = "", sType = 1, tMin = 2, tMax = 40, sens = 10,
  vLand = 60, vStall = 45, vOver = 200, cal = 100, units = 1, numOnly = 0,
  startAnn = 1, densOn = 0, elev = 0, tSrc = 1, tId = 0, tPar = 0, tLbl = "",
  colCur = 1, colMax = 9, fScale = 0, voice = 0, vArm = 30, landOn = 1, cfgV = 2,
}  -- swOn / swCont default to nil; temp depends on units

-- Input limits (FR-020, R16). One source for the intboxes, the units
-- conversion and the clamp on load.
local LIM = {
  elevFt = { -300, 10000 }, elevM = { -90, 3050 },
  tempF = { -20, 130 }, tempC = { -29, 54 },
}
local RANGES = {
  sType = { 1, 2 }, tMin = { 1, 10 }, tMax = { 2, 60 }, sens = { 1, 100 },
  vLand = { 0, 1000 }, vStall = { 0, 1000 }, vOver = { 0, 1000 },
  cal = { 1, 200 }, units = { 1, 5 }, numOnly = { 0, 1 }, startAnn = { 0, 1 },
  densOn = { 0, 1 }, tSrc = { 1, 3 }, voice = { 0, 2 }, colCur = { 1, 9 },
  colMax = { 1, 9 }, fScale = { 0, 2000 }, vArm = { 0, 1000 }, landOn = { 0, 1 },
}

local cfg = {}

local function save(key, value)
  cfg[key] = value
  system.pSave(key, value)
end

local function clamp(v, lo, hi)
  if v < lo then
    return lo
  elseif v > hi then
    return hi
  end
  return v
end

local function clampKey(key, lo, hi)
  local v = clamp(cfg[key], lo, hi)
  if v ~= cfg[key] then
    save(key, v)
  end
end

local function loadSettings()
  for _, key in ipairs(KEYS) do
    cfg[key] = system.pLoad(key, DEFAULTS[key])
  end
  if cfg.temp == nil then
    cfg.temp = UNITS_IMPERIAL[cfg.units] and 59 or 15
  end
  -- cfgV 1 -> 2 (0.1.0 had a "Use standard temperature" checkbox, R16). A
  -- fresh install runs this too and ends with the default, Standard.
  if system.pLoad("cfgV", 1) < 2 then
    save("tSrc", system.pLoad("tStd", 1) == 1 and 1 or 2)
    system.pSave("tStd", nil)
    save("cfgV", 2)
  end
  -- Values saved by an older version may be outside today's limits (Edge Cases).
  for key, r in pairs(RANGES) do
    clampKey(key, r[1], r[2])
  end
  if cfg.fScale ~= 0 and cfg.fScale < 10 then
    save("fScale", 10)
  end
  if cfg.tMax < cfg.tMin then
    save("tMax", cfg.tMin)    -- longest is never below shortest (FR-005)
  end
  if UNITS_IMPERIAL[cfg.units] then
    clampKey("elev", LIM.elevFt[1], LIM.elevFt[2])
    clampKey("temp", LIM.tempF[1], LIM.tempF[2])
  else
    clampKey("elev", LIM.elevM[1], LIM.elevM[2])
    clampKey("temp", LIM.tempC[1], LIM.tempC[2])
  end
end

------------------------------------------------------------------------------
-- Derived values: recomputed only when a setting changes, never per tick.
------------------------------------------------------------------------------

local kSensor = 1           -- sensor m/s -> calibrated speed in the user's units
local kDens = 1             -- true airspeed / sensor speed (R1)
local fullScale = 230
local fStall, fLand, fOver = 0, 0, 1   -- dial fractions (FR-016a)
local scaleStep = 50
local scaleLabels = {}      -- major tick label strings
local scaleVer = 0          -- bumped whenever the dial scale changes
local unitText = "mph"
local unitSpoken = "mph"
local densPctText = "+0%"
local densActive = false    -- correction on and an airspeed sensor
local densRowText = "OFF"   -- full-screen AIR DENSITY row: "+8%", "OFF" or "GPS"
local elevText, elevUnitText = "0", "ft"
local stallText, overText = "45", "200"

-- Callout floor and max-speed callout (FR-008b, FR-019a, 2026-10-04), in
-- one table because the main chunk is near Lua's 200-local limit.
local pk = {
  minSpoken = 5,            -- no callouts below this (5 mph in the user's units)
  holdMs = 1000,            -- announce a new max once it hasn't risen for this long
  at = nil,                 -- when the session max last rose; nil = nothing pending
  said = 0,                 -- last max announced (rounded), 0 = none yet
}

local function recomputeSensor()
  kSensor = UNITS_MULT[cfg.units] * cfg.cal / 100
end

-- Temperature from a sensor (R15). Declared here because recomputeDensity
-- reads it; reset by resetTempSensor, advanced by readTemp in the loop.
local ts = {
  periodMs = 5000,          -- read the sensor at most every 5 s (FR-041)
  stat = 0,                 -- 0 not in use, 1 waiting (rejected), 2 in use
  useC = nil,               -- accepted sensor temperature, deg C
  good = 0,                 -- consecutive good reads while waiting
  ever = false,             -- a read was accepted or rejected since (re)start
  nextRead = 0,
}

local TXT_TEMP = {
  std = "TEMP STD", man = "TEMP MAN", sens = "TEMP SENS", out = "SENSOR OUT",
}
local tempText, tempUnitText = "59", "°F"   -- full-screen TEMPERATURE row (FR-044)
local tempLabel = TXT_TEMP.std
local tStatText = ""        -- settings status line (FR-042)

local function recomputeDensity()
  local imperial = UNITS_IMPERIAL[cfg.units]
  densActive = cfg.densOn == 1 and cfg.sType == 1
  local elevM = imperial and dens.ftToM(cfg.elev) or cfg.elev
  local tempC = nil         -- nil = standard temperature for the elevation
  if cfg.tSrc == 2 then
    tempC = imperial and dens.fToC(cfg.temp) or cfg.temp
  elseif cfg.tSrc == 3 and ts.stat == 2 then
    tempC = ts.useC
  end
  if densActive then
    kDens = dens.factor(elevM, tempC)
  else
    kDens = 1
  end
  -- Temperature in use, for the full-screen row and the settings status.
  local t = tempC or dens.stdTempC(elevM)
  if imperial then
    t = dens.cToF(t)
  end
  tempText = tostring(math.floor(t + 0.5))
  tempUnitText = imperial and "°F" or "°C"
  local inUse = "Temp: " .. tempText .. " " .. tempUnitText
  if cfg.tSrc == 1 then
    tempLabel, tStatText = TXT_TEMP.std, inUse .. " standard"
  elseif cfg.tSrc == 2 then
    tempLabel, tStatText = TXT_TEMP.man, inUse .. " manual"
  elseif ts.stat == 2 then
    tempLabel, tStatText = TXT_TEMP.sens, inUse .. " from " .. cfg.tLbl
  else
    tempLabel, tStatText = TXT_TEMP.out, "Sensor not available - using standard"
  end
  local pct = math.floor((kDens - 1) * 100 + 0.5)
  densPctText = (pct >= 0 and "+" or "") .. pct .. "%"
  if cfg.sType == 2 then
    densRowText = TXT_GPS
  elseif densActive then
    densRowText = densPctText
  else
    densRowText = TXT_OFF
  end
  elevText = tostring(cfg.elev)
  elevUnitText = imperial and "ft" or "m"
end

local function recomputeScale()
  local fs = cfg.fScale
  if fs == 0 then
    fs = math.ceil(cfg.vOver * 1.15 / 10) * 10
  end
  fs = math.max(fs, 10)
  fullScale = fs
  fStall = clamp(cfg.vStall * kDens / fs, 0, 1)
  fLand = clamp(cfg.vLand * kDens / fs, 0, 1)
  fOver = clamp(cfg.vOver / fs, 0, 1)
  scaleStep = gauge.scaleStep(fs)
  local labels = {}
  for i = 0, fs // scaleStep do
    labels[i + 1] = tostring(math.floor(i * scaleStep))
  end
  scaleLabels = labels
  stallText = tostring(cfg.vStall)
  overText = tostring(cfg.vOver)
  scaleVer = scaleVer + 1
end

local function recomputeUnitText()
  unitText = UNITS_TEXT[cfg.units]
  unitSpoken = UNITS_SPOKEN[cfg.units]
  -- No callout is ever spoken below 5 mph, in any units (FR-008b, 2026-10-04).
  pk.minSpoken = 2.2352 * UNITS_MULT[cfg.units]
end

-- Which voice speaks (R14). voiceOk is set once in init().
local voiceOk = false
local useAppVoice = false
local snd = { stall = SND_STALL, over = SND_OVER, alive = SND_ALIVE, unit = VOICE.units[1] }

-- Jeti's io is function-style (constitution III).
local function fileExists(path)
  local f = io.open(path, "r")
  if f then
    io.close(f)
    return true
  end
  return false
end

-- Every phrase and unit file plus the ends of the number range (R14).
local function checkVoiceFiles()
  for _, p in ipairs(VOICE.units) do
    if not fileExists(p) then
      return false
    end
  end
  for _, p in ipairs({ VOICE.pct, VOICE.stall, VOICE.over, VOICE.alive, VOICE.stallAt, VOICE.cal, VOICE.max,
    VOICE.dir .. "0.wav", VOICE.dir .. VOICE.maxNum .. ".wav" }) do
    if not fileExists(p) then
      return false
    end
  end
  return true
end

local function recomputeVoice()
  -- voice: 0 = not chosen (app voice if installed), 1 = Speed Gauge, 2 = Transmitter
  useAppVoice = voiceOk and cfg.voice ~= 2
  if useAppVoice then
    snd.stall, snd.over, snd.alive = VOICE.stall, VOICE.over, VOICE.alive
  else
    snd.stall, snd.over, snd.alive = SND_STALL, SND_OVER, SND_ALIVE
  end
  snd.unit = VOICE.units[cfg.units]
end

-- App-voice number file for n, or nil to fall back to the transmitter voice
-- for this phrase (over 500, or the file is missing: FR-033). Builds a path
-- and opens a file, so call it only when something is about to be spoken.
local function numFile(n)
  if not useAppVoice or n < 0 or n > VOICE.maxNum then
    return nil
  end
  local path = VOICE.dir .. n .. ".wav"
  if fileExists(path) then
    return path
  end
  return nil
end

local function recomputeAll()
  recomputeSensor()
  recomputeDensity()
  recomputeScale()
  recomputeUnitText()
  recomputeVoice()
end

-- Start over with the temperature sensor: on load, and whenever the source,
-- the sensor or whether correction is active changes (R15). Callers then
-- recompute density.
local function resetTempSensor()
  ts.stat = (cfg.tSrc == 3 and densActive) and 1 or 0
  ts.useC, ts.good, ts.ever = nil, 0, false
  ts.nextRead = system.getTimeCounter()
end

------------------------------------------------------------------------------
-- Session state (not persisted; reset by init on every model load).
------------------------------------------------------------------------------

local sensorSpd = nil       -- calibrated sensor speed; nil = no data
local shownSpd = nil        -- sensorSpd * kDens: shown, spoken, max, overspeed
local maxSpd = 0
local prevDistinct = nil    -- previous distinct shownSpd, for spike filtering (R5)
local distinctSince = 0     -- when shownSpd last changed
local armed = false         -- sensor speed has exceeded vArm this session (latched)
local everAboveLanding = false
local belowLanding = false
local aliveSaid = false
local stallArmed = true
local STALL_MAX = 2         -- stall warnings per slowdown (FR-010, 2026-10-03)
local stallCount = 0        -- stall warnings since last above landing speed
local overArmed = true
local lastSpokenSpd = 0
local lastSpokenAt = nil    -- nil = nothing spoken yet this session
local lastTick = 0
local curRounded, maxRounded, sensRounded = nil, 0, nil
local curText, maxText, sensText = TXT_NO_DATA, "0", TXT_NO_DATA
local gaugeOk = false       -- device is a DS-24 II (R12)

local function resetSession()
  sensorSpd, shownSpd = nil, nil
  maxSpd, prevDistinct, distinctSince = 0, nil, 0
  armed, everAboveLanding, belowLanding, aliveSaid = false, false, false, false
  stallArmed, overArmed, stallCount = true, true, 0
  lastSpokenSpd, lastSpokenAt = 0, nil
  lastTick = system.getTimeCounter()
  curRounded, maxRounded, sensRounded = nil, 0, nil
  curText, maxText, sensText = TXT_NO_DATA, "0", TXT_NO_DATA
  pk.at, pk.said = nil, 0
  resetTempSensor()
  recomputeDensity()
end

local function resetMax()
  maxSpd, prevDistinct = 0, nil
  maxRounded, maxText = 0, "0"
  pk.at, pk.said = nil, 0
end

------------------------------------------------------------------------------
-- Loop logic
------------------------------------------------------------------------------

-- Unassigned switch = off. "On" is above half travel (R10).
local function switchOn(item)
  if item == nil then
    return false
  end
  local v = system.getInputsVal(item)
  return v ~= nil and v > 0.5
end

-- Session max, filtered so a single-sample spike is ignored (R5): a value
-- counts once two distinct readings in a row reach it, or once it has held
-- for HOLD_MS (a steady speed). Also rebuilds the cached number strings, only
-- when their rounded value changes.
local function updateMax(now)
  local confirmed = nil
  if shownSpd ~= prevDistinct then
    if prevDistinct ~= nil then
      confirmed = math.min(prevDistinct, shownSpd)
    end
    prevDistinct = shownSpd
    distinctSince = now
  elseif now - distinctSince >= HOLD_MS then
    confirmed = shownSpd
  end
  if confirmed ~= nil and confirmed > maxSpd then
    maxSpd = confirmed
    pk.at = now               -- max-speed callout waits until it stops rising
  end
  local r = math.floor(shownSpd + 0.5)
  if r ~= curRounded then
    curRounded = r
    curText = tostring(r)
  end
  r = math.floor(maxSpd + 0.5)
  if r ~= maxRounded then
    maxRounded = r
    maxText = tostring(r)
  end
  r = math.floor(sensorSpd + 0.5)
  if r ~= sensRounded then
    sensRounded = r
    sensText = tostring(r)
  end
end

-- Stall, overspeed and "airspeed alive" (data-model.md state transitions).
-- Stall uses sensor speed, overspeed uses shown speed (FR-011).
local function checkWarnings(anySwitch)
  -- Stall (FR-010, changed 2026-10-03): at most STALL_MAX warnings per
  -- slowdown, so speed wobbling around the stall setting on landing can't
  -- keep triggering it. Back above landing speed (flying again, e.g. a
  -- go-around) resets the count.
  if sensorSpd > cfg.vLand then
    stallCount = 0
  end
  if sensorSpd > cfg.vStall and stallCount < STALL_MAX then
    stallArmed = true
  end
  if shownSpd <= cfg.vOver then
    overArmed = true
  end
  if not anySwitch then
    return
  end
  if stallArmed and everAboveLanding and sensorSpd <= cfg.vStall then
    stallArmed = false
    stallCount = stallCount + 1
    system.playFile(snd.stall, AUDIO_IMMEDIATE)
    system.vibration(true, 4)
  end
  if overArmed and shownSpd > cfg.vOver then
    overArmed = false
    system.playFile(snd.over, AUDIO_IMMEDIATE)
    system.vibration(true, 3)
  end
  if armed and not aliveSaid then
    aliveSaid = true
    system.playFile(snd.alive, AUDIO_IMMEDIATE)
  end
end

-- Variable-interval callouts, formula from DFM v2.1 (R9).
local function checkCallout(now, onSw, contSw)
  -- Continuous callouts speak only while above "Callouts start above"
  -- (FR-009, changed 2026-10-03): they stop when slowing below it.
  -- Below it, the on/off switch's normal callouts still apply.
  contSw = contSw and sensorSpd > cfg.vArm
  if not (onSw or contSw) then
    return
  end
  if not armed then
    return                  -- FR-009: silent until first above the arming speed
  end
  -- Max speed (FR-019a): once the session max hasn't risen for pk.holdMs, and
  -- beats the last announced max by at least the callout sensitivity (so
  -- small creeps in cruise don't chatter), say "max", the number and unit.
  if pk.at ~= nil and now - pk.at >= pk.holdMs and maxRounded >= pk.said + cfg.sens
    and not system.isPlayback() then
    pk.at, pk.said = nil, maxRounded
    lastSpokenAt = now
    local nf = numFile(maxRounded)
    if nf then
      system.playFile(VOICE.max, AUDIO_QUEUE)
      system.playFile(nf, AUDIO_QUEUE)
      system.playFile(snd.unit, AUDIO_QUEUE)
    else
      system.playNumber(maxRounded, 0, unitSpoken)   -- the voice pack has no "max"
    end
    return
  end
  if shownSpd < pk.minSpoken then
    return                  -- FR-008b: never a callout below 5 mph
  end
  local interval
  -- Landing speed callouts (landOn, added 2026-10-03): when off, landing
  -- speed doesn't change the callouts; it still arms the stall warning.
  local landing = cfg.landOn == 1
  if contSw or (landing and belowLanding) then
    interval = cfg.tMin * 1000
  else
    local d = math.abs(shownSpd - lastSpokenSpd) / cfg.sens
    d = clamp(d, 0.5, 10)
    interval = math.min(cfg.tMin * 10000 / d, cfg.tMax * 1000)
  end
  -- Compare time differences only: the ms counter is a 32-bit integer that
  -- wraps and can be negative (seen in the emulator), so now - then is safe
  -- where now < then + interval is not.
  if (lastSpokenAt ~= nil and now - lastSpokenAt < interval) or system.isPlayback() then
    return
  end
  local n = math.floor(shownSpd + 0.5)
  lastSpokenSpd = n
  lastSpokenAt = now
  local short = cfg.numOnly == 1 or contSw
    or (landing and (belowLanding or not everAboveLanding))
  -- App voice: number file, then unit file, queued as one phrase (FR-031).
  -- Either the whole phrase is in the app voice or none of it is (R14).
  local nf = numFile(n)
  if nf then
    system.playFile(nf, AUDIO_QUEUE)
    if not short then
      system.playFile(snd.unit, AUDIO_QUEUE)
    end
  elseif short then
    system.playNumber(n, 0)
  else
    system.playNumber(n, 0, unitSpoken, "Speed")
  end
end

------------------------------------------------------------------------------
-- Settings form (contracts/settings-form.md)
------------------------------------------------------------------------------

local sensorLabels, sensorIds, sensorPars = {}, {}, {}
local notFoundIdx = 0
local tempLabels, tempIds, tempPars = {}, {}, {}
local tempNotFoundIdx = 0
local formOpen = false      -- loop may update the temperature status only while true (R17)
local idxGpsHint, idxDensOn, idxDensStatus = nil, nil, nil
local idxTMan, idxTSens, idxTStat = nil, nil, nil
local idxAutoHint, idxOrder = nil, nil

local LABEL_W = 210
local CHECK_W = 270

-- A temperature value reports "°C" or "°F": 3 bytes in UTF-8, 2 in Latin-1
-- (the transmitter's encoding is unverified, R15).
local function isTempUnit(unit)
  local last = string.sub(unit, -1)
  return (#unit == 2 or #unit == 3) and (last == "C" or last == "F")
end

-- Adds the "<label> (not found)" entry for a saved sensor that isn't present
-- (R4). Returns its index.
local function addNotFound(labels, ids, pars, label, id, par)
  local n = #labels + 1
  labels[n], ids[n], pars[n] = label .. " (not found)", id, par
  return n
end

-- Rebuilds the speed and temperature sensor lists in one pass (late sensors
-- appear, R4, R15). Returns both selections.
local function buildSensorList()
  sensorLabels, sensorIds, sensorPars = { "(none)" }, { 0 }, { 0 }
  tempLabels, tempIds, tempPars = { "(none)" }, { 0 }, { 0 }
  notFoundIdx, tempNotFoundIdx = 0, 0
  local selected, tSelected = 1, 1
  local parent = ""
  for _, s in ipairs(system.getSensors()) do
    if s.param == 0 then
      parent = s.label
    elseif s.type ~= 5 and s.type ~= 9 then
      local text = (parent ~= "") and (parent .. " / " .. s.label) or s.label
      local n = #sensorLabels + 1
      sensorLabels[n], sensorIds[n], sensorPars[n] = text, s.id, s.param
      if s.id == cfg.sId and s.param == cfg.sPar then
        selected = n
      end
      if isTempUnit(s.unit or "") then
        n = #tempLabels + 1
        tempLabels[n], tempIds[n], tempPars[n] = text, s.id, s.param
        if s.id == cfg.tId and s.param == cfg.tPar then
          tSelected = n
        end
      end
    end
  end
  if cfg.sId ~= 0 and selected == 1 then
    notFoundIdx = addNotFound(sensorLabels, sensorIds, sensorPars, cfg.sLbl, cfg.sId, cfg.sPar)
    selected = notFoundIdx
  end
  if cfg.tId ~= 0 and tSelected == 1 then
    tempNotFoundIdx = addNotFound(tempLabels, tempIds, tempPars, cfg.tLbl, cfg.tId, cfg.tPar)
    tSelected = tempNotFoundIdx
  end
  return selected, tSelected
end

local function heading(text)
  form.addRow(1)
  form.addLabel({ label = text, font = FONT_BOLD })
end

local function hint(text, visible)
  form.addRow(1)
  return form.addLabel({ label = text, font = FONT_MINI, visible = visible ~= false })
end

local function addInt(label, key, lo, hi, default, step, after, params)
  form.addRow(2)
  form.addLabel({ label = label, width = LABEL_W })
  return form.addIntbox(clamp(cfg[key], lo, hi), lo, hi, default, 0, step, function(value)
    save(key, value)
    if after then
      after()
    end
  end, params)
end

local function addCheck(label, key, after, params)
  form.addRow(2)
  form.addLabel({ label = label, width = CHECK_W })
  local idx
  idx = form.addCheckbox(cfg[key] == 1, function(value)
    -- The callback gets the old state; toggle it, as DFM v2.1 does.
    local on = not value
    if idx then
      form.setValue(idx, on)
    end
    save(key, on and 1 or 0)
    if after then
      after()
    end
  end, params)
  return idx
end

local function orderIsBad()
  return cfg.vStall >= cfg.vLand or cfg.vLand >= cfg.vOver
    or (cfg.fScale ~= 0 and cfg.vOver > cfg.fScale)
end

-- FR-026: flag, don't block, an illogical threshold order.
local function checkOrder()
  if idxOrder then
    form.setProperties(idxOrder, { visible = orderIsBad() })
  end
end

local function updateAutoHint()
  if idxAutoHint then
    local text = ""
    if cfg.fScale == 0 then
      text = "Auto (overspeed + 15%): " .. fullScale
    end
    form.setProperties(idxAutoHint, { label = text })
  end
end

local function updateDensityRows()
  if idxDensStatus then
    local text = ""
    if cfg.sType == 2 then
      text = "Not used with GPS"
    elseif cfg.densOn == 1 then
      text = "Correction: " .. densPctText
    end
    form.setProperties(idxDensStatus, { label = text })
  end
  if idxDensOn then
    form.setProperties(idxDensOn, { enabled = cfg.sType == 1 })
  end
  if idxTMan then
    form.setProperties(idxTMan, { enabled = cfg.tSrc == 2 })
  end
  if idxTSens then
    form.setProperties(idxTSens, { enabled = cfg.tSrc == 3 })
  end
  if idxTStat then
    form.setProperties(idxTStat, { label = densActive and tStatText or "" })
  end
end

local function onThresholdChanged()
  recomputeScale()
  checkOrder()
  updateAutoHint()
end

local function onDensityChanged()
  recomputeDensity()
  recomputeScale()
  updateDensityRows()
end

-- Source, sensor or "correction active" changed: the sensor starts over (R15).
local function onTempSourceChanged()
  recomputeDensity()        -- densActive first: resetTempSensor reads it
  resetTempSensor()
  onDensityChanged()
end

-- Units change converts every unit-bearing setting (data-model.md).
local function onUnitsChanged(newUnits)
  local old = cfg.units
  if newUnits == old then
    return
  end
  local ratio = UNITS_MULT[newUnits] / UNITS_MULT[old]
  local function convert(key, lo, hi)
    save(key, clamp(math.floor(cfg[key] * ratio + 0.5), lo, hi))
  end
  convert("sens", 1, 100)
  convert("vLand", 0, 1000)
  convert("vArm", 0, 1000)
  convert("vStall", 0, 1000)
  convert("vOver", 0, 1000)
  if cfg.fScale ~= 0 then
    save("fScale", clamp(math.floor(cfg.fScale * ratio / 10 + 0.5) * 10, 10, 2000))
  end
  if UNITS_IMPERIAL[newUnits] ~= UNITS_IMPERIAL[old] then
    if UNITS_IMPERIAL[newUnits] then
      save("elev", clamp(math.floor(dens.mToFt(cfg.elev) / 10 + 0.5) * 10, LIM.elevFt[1], LIM.elevFt[2]))
      save("temp", clamp(math.floor(dens.cToF(cfg.temp) + 0.5), LIM.tempF[1], LIM.tempF[2]))
    else
      save("elev", clamp(math.floor(dens.ftToM(cfg.elev) / 10 + 0.5) * 10, LIM.elevM[1], LIM.elevM[2]))
      save("temp", clamp(math.floor(dens.fToC(cfg.temp) + 0.5), LIM.tempC[1], LIM.tempC[2]))
    end
  end
  save("units", newUnits)
  recomputeAll()
  form.reinit(1)
end

local function initForm()
  formOpen = true
  local u = UNITS_TEXT[cfg.units]
  local imperial = UNITS_IMPERIAL[cfg.units]

  -- Sensor and switches
  heading("Sensor and switches")
  form.addRow(2)
  form.addLabel({ label = "Speed sensor", width = 120 })
  local selected, tSelected = buildSensorList()   -- rebuilds both lists; call before passing them
  form.addSelectbox(sensorLabels, selected, true, function(i)
    save("sId", sensorIds[i])
    save("sPar", sensorPars[i])
    if i == 1 then
      save("sLbl", "")
    elseif i ~= notFoundIdx then
      save("sLbl", string.sub(sensorLabels[i], 1, 63))
    end
  end, { width = 200 })

  form.addRow(2)
  form.addLabel({ label = "Sensor type", width = LABEL_W })
  form.addSelectbox({ "Airspeed (pitot)", "GPS" }, cfg.sType, false, function(i)
    save("sType", i)
    onTempSourceChanged()
    if idxGpsHint then
      form.setProperties(idxGpsHint, { visible = i == 2 })
    end
  end)
  idxGpsHint = hint("GPS: warnings use ground speed, wind shifts them", cfg.sType == 2)

  form.addRow(2)
  form.addLabel({ label = "Units", width = LABEL_W })
  form.addSelectbox(UNITS_TEXT, cfg.units, false, onUnitsChanged)

  addInt("Sensor calibration (%)", "cal", 1, 200, 100, 1, recomputeSensor)
  hint("100 = unchanged")

  form.addRow(2)
  form.addLabel({ label = "Callouts on/off switch", width = LABEL_W })
  form.addInputbox(cfg.swOn, true, function(v) save("swOn", v) end)
  hint("Speaks speed: more often as it changes, every")
  hint("shortest time below landing speed")
  form.addRow(2)
  form.addLabel({ label = "Continuous callouts switch", width = LABEL_W })
  form.addInputbox(cfg.swCont, true, function(v) save("swCont", v) end)
  hint("Number only, every shortest time, while above")
  hint("'Callouts start above'; works without on/off")
  hint("Either switch also turns on the warnings")

  -- Callouts
  heading("Callouts")
  addInt("Callout sensitivity (" .. u .. " change)", "sens", 1, 100, 10, 1)
  hint("Speak sooner when speed changes by this much")
  -- Longest 2-60 s, never below shortest (FR-005, changed 2026-10-04):
  -- it stops at the shortest, and raising the shortest past it raises it.
  local idxTMax
  local function keepTMax()
    if cfg.tMax < cfg.tMin then
      save("tMax", cfg.tMin)
      if idxTMax then
        form.setValue(idxTMax, cfg.tMax)
      end
    end
  end
  addInt("Shortest time between callouts (s)", "tMin", 1, 10, 2, 1, keepTMax)
  idxTMax = addInt("Longest time between callouts (s)", "tMax", 2, 60, 40, 1, keepTMax)
  addInt("Callouts start above (" .. u .. ")", "vArm", 0, 1000, 30, 1)
  hint("No callouts or 'airspeed alive' until first this fast")
  addCheck("Landing speed callouts", "landOn")
  addInt("Landing speed (" .. u .. ")", "vLand", 0, 1000, 60, 1, onThresholdChanged)
  hint("If on: short callouts every shortest time below")
  hint("this. Also arms the stall warning once exceeded")
  addCheck("Speak number only (no units)", "numOnly")
  addCheck("Announce stall speed at startup", "startAnn")
  -- Voice (FR-032): an unset choice shows what is actually used.
  form.addRow(2)
  form.addLabel({ label = "Voice", width = LABEL_W })
  local vSel = cfg.voice
  if vSel == 0 then
    vSel = voiceOk and 1 or 2
  end
  form.addSelectbox({ "Speed Gauge", "Transmitter" }, vSel, false, function(i)
    save("voice", i)
    recomputeVoice()
  end)
  hint("Voice files missing - using transmitter voice", not voiceOk)

  -- Warnings
  heading("Warnings")
  idxOrder = hint("Check: stall < landing < overspeed < full scale", false)
  addInt("Stall warning at (" .. u .. ")", "vStall", 0, 1000, 45, 1, onThresholdChanged)
  addInt("Overspeed warning at (" .. u .. ")", "vOver", 0, 1000, 200, 1, onThresholdChanged)

  -- Air density
  heading("Air density")
  idxDensOn = addCheck("Correct for air density", "densOn", onTempSourceChanged,
    { enabled = cfg.sType == 1 })
  idxDensStatus = hint("")
  if imperial then
    addInt("Field elevation (ft)", "elev", LIM.elevFt[1], LIM.elevFt[2], 0, 10, onDensityChanged)
  else
    addInt("Field elevation (m)", "elev", LIM.elevM[1], LIM.elevM[2], 0, 10, onDensityChanged)
  end
  form.addRow(2)
  form.addLabel({ label = "Temperature source", width = LABEL_W })
  form.addSelectbox({ "Standard", "Manual", "Sensor" }, cfg.tSrc, false, function(i)
    save("tSrc", i)
    onTempSourceChanged()
  end)
  if imperial then
    idxTMan = addInt("Temperature, manual (°F)", "temp", LIM.tempF[1], LIM.tempF[2], 59, 1,
      onDensityChanged, { enabled = cfg.tSrc == 2 })
  else
    idxTMan = addInt("Temperature, manual (°C)", "temp", LIM.tempC[1], LIM.tempC[2], 15, 1,
      onDensityChanged, { enabled = cfg.tSrc == 2 })
  end
  form.addRow(2)
  form.addLabel({ label = "Temperature sensor", width = 120 })
  idxTSens = form.addSelectbox(tempLabels, tSelected, true, function(i)
    save("tId", tempIds[i])
    save("tPar", tempPars[i])
    if i == 1 then
      save("tLbl", "")
    elseif i ~= tempNotFoundIdx then
      save("tLbl", string.sub(tempLabels[i], 1, 63))
    end
    onTempSourceChanged()
  end, { width = 200, enabled = cfg.tSrc == 3 })
  hint("Sensors inside the model can read warmer than outside air")
  idxTStat = hint("")
  hint("Leave correction off if your sensor already corrects for air density")

  -- Gauge
  heading("Gauge")
  -- Renamed from "Gauge full scale" after transmitter testing (2026-10-03).
  addInt("Gauge max limit (" .. u .. ", 0 = auto)", "fScale", 0, 2000, 0, 10, onThresholdChanged)
  hint("Highest speed on the dial. To use your sensor's")
  hint("whole range, enter its top speed:")
  hint("MSpeed: 20-350 km/h (12-215 mph)")
  hint("MSpeed 450 EX: 80-450 km/h (50-280 mph)")
  idxAutoHint = hint("")
  form.addRow(2)
  form.addLabel({ label = "Current speed color", width = LABEL_W })
  form.addSelectbox(COLOR_NAMES, cfg.colCur, false, function(i) save("colCur", i) end)
  form.addRow(2)
  form.addLabel({ label = "Max speed color", width = LABEL_W })
  form.addSelectbox(COLOR_NAMES, cfg.colMax, false, function(i) save("colMax", i) end)
  form.addRow(1)
  form.addLink(resetMax, { label = "Reset max speed" })

  form.addRow(1)
  form.addLabel({ label = APP_NAME .. " " .. APP_VERSION .. " - Based on DFM Speed Announcer by Dave McQueeney",
    font = FONT_MINI, alignRight = true })

  checkOrder()
  updateAutoHint()
  updateDensityRows()
end

local function keyForm()
end

-- The form is gone: drop its indices so nothing calls form.* on them (R17).
local function closeForm()
  formOpen = false
  idxGpsHint, idxDensOn, idxDensStatus = nil, nil, nil
  idxTMan, idxTSens, idxTStat = nil, nil, nil
  idxAutoHint, idxOrder = nil, nil
end

------------------------------------------------------------------------------
-- Telemetry windows (contracts/telemetry-window.md). The only place lcd is used.
------------------------------------------------------------------------------

local roundDial, faceCircle, glowDial = nil, nil, nil   -- glowDial: coarse copy for the soft glow
local rend = nil            -- one renderer, created lazily and reused (R6)
local cpuPeak = 0           -- DEBUG_CPU only

-- JETI Studio's simulator crashes (access violation in Qt6Core) once the
-- speed arc and its glow are drawn as filled polygons (2026-10-03); the
-- transmitter draws them fine. Its windows (widths 157, 320) therefore use
-- polylines for arcs and glow, as 0.1.0 did. Set per frame in printGauge.
local liveLines = false

-- One layout cache per layout, rebuilt when the window size or scale changes.
local layStrip = { w = 0 }
local layRound = { w = 0 }
local layFull = { w = 0 }

local function setColor(c)
  lcd.setColor(c[1], c[2], c[3])
end

local function round(v)
  return math.floor(v + 0.5)
end

-- Largest of the given fonts where sample text fits in maxW x maxH.
local function fitFont(fonts, sample, maxW, maxH)
  for i = 1, #fonts do
    local f = fonts[i]
    if lcd.getTextWidth(f, sample) <= maxW and lcd.getTextHeight(f) <= maxH then
      return f
    end
  end
  return fonts[#fonts]
end

local NUM_FONTS = { FONT_MAXI, FONT_BIG, FONT_NORMAL, FONT_MINI }

-- Tick end points and label positions for a dial layout.
local function buildScale(L, dial, minorPer, withLabels)
  local mx1, my1, mx2, my2 = {}, {}, {}, {}
  local nx1, ny1, nx2, ny2 = {}, {}, {}, {}
  local lx, ly = {}, {}
  local font = L.labelFont
  local hLabel = lcd.getTextHeight(font)
  local rOut, rMaj, rMin = L.tickOut, L.tickOut - L.majorLen, L.tickOut - L.minorLen
  for i = 1, #scaleLabels do
    local v = (i - 1) * scaleStep
    local c, s = gauge.point(dial, v / fullScale)
    mx1[i], my1[i] = round(L.cx + c * rOut), round(L.cy + s * rOut)
    mx2[i], my2[i] = round(L.cx + c * rMaj), round(L.cy + s * rMaj)
    if withLabels then
      local tw = lcd.getTextWidth(font, scaleLabels[i])
      lx[i] = round(L.cx + c * L.labelR - tw / 2)
      ly[i] = round(L.cy + s * L.labelR - hLabel / 2)
    end
    for m = 1, minorPer do
      local f = (v + scaleStep * m / (minorPer + 1)) / fullScale
      if f < 1 then
        c, s = gauge.point(dial, f)
        local k = #nx1 + 1
        nx1[k], ny1[k] = round(L.cx + c * rOut), round(L.cy + s * rOut)
        nx2[k], ny2[k] = round(L.cx + c * rMin), round(L.cy + s * rMin)
      end
    end
  end
  L.mx1, L.my1, L.mx2, L.my2 = mx1, my1, mx2, my2
  L.nx1, L.ny1, L.nx2, L.ny2 = nx1, ny1, nx2, ny2
  L.lx, L.ly = lx, ly
  L.labels = withLabels
end

-- Glow bands for a layout: n bands step px apart, alpha falling
-- geometrically from GLOW[1] to GLOW[2] so neighbors differ only slightly.
-- The bands are nested filled ring segments, all starting at the arc:
-- layer k reaches k * step inward, so the glow builds up toward the arc
-- and neighbors share no seams. Each layer's alpha is solved so the total
-- in band k is the target A_k: (1 - A_k) = (1 - a_k)(1 - A_k+1).
local function buildGlow(L, step, n)
  L.glowStep, L.glowN = step, n
  local A, a = {}, {}
  local k = (GLOW[2] / GLOW[1]) ^ (1 / (n - 1))
  for i = 1, n do
    A[i] = GLOW[1] * k ^ (i - 1)
  end
  a[n] = A[n]
  for i = n - 1, 1, -1 do
    a[i] = 1 - (1 - A[i]) / (1 - A[i + 1])
  end
  L.glowA, L.glowT = a, A
end

-- Double window (transmitter 150 x 68): a small 270-degree dial on the left
-- without scale numbers (too small to read), current speed and MAX on the
-- right. Stall and overspeed stay as rim marks only (FR-016 "SHOULD").
local function buildRound(L, w, h)
  local R = math.floor(math.min((h - 4) / 1.707, w * 0.55 / 2))
  L.R, L.cx = R, 2 + R
  L.cy = math.floor((h - R * 1.707) / 2 + R)
  L.arcR, L.arcW, L.markW = R - 3, 4, 3
  buildGlow(L, 2, 6)
  L.tickOut, L.majorLen, L.minorLen = R - 7, 4, 2
  L.labelFont = FONT_MINI
  L.dial, L.face, L.showMarks = roundDial, true, true
  buildScale(L, roundDial, 0, false)
  L.hMini = lcd.getTextHeight(FONT_MINI)
  L.colX = 2 * R + 8
  local colW = w - L.colX - 2
  L.numFont = fitFont(NUM_FONTS, "888", colW, h - 2 * L.hMini - lcd.getTextHeight(FONT_NORMAL))
  L.hNum = lcd.getTextHeight(L.numFont)
  L.maxValY = h - lcd.getTextHeight(FONT_NORMAL)
  L.maxLabelY = L.maxValY - L.hMini
end

-- Full screen (transmitter 316 x 159): dial about 180 px across on the
-- left, MAX in its open bottom; one-line panel rows on the right.
local function buildFull(L, w, h)
  local R = math.floor(math.min((h - 4) / 1.707, (w - 130) / 2 - 2))
  local big = R >= 110        -- emulator-sized dial: larger scale text
  L.R, L.cx = R, 2 + R
  L.cy = math.floor((h - R * 1.707) / 2 + R)
  L.arcR, L.arcW, L.markW = R - 5, 7, 5
  buildGlow(L, 3, 9)
  L.tickOut, L.majorLen, L.minorLen = R - 11, 9, 5
  L.labelFont = big and FONT_NORMAL or FONT_MINI
  L.unitFont = L.labelFont
  L.labelR = R - (big and 36 or 28)
  L.dial, L.face, L.showMarks = roundDial, true, true
  buildScale(L, roundDial, big and 4 or 1, true)
  L.numFont = fitFont(NUM_FONTS, "888", R, R // 2)
  L.hNum, L.hMini = lcd.getTextHeight(L.numFont), lcd.getTextHeight(FONT_MINI)
  L.hBig, L.hNorm = lcd.getTextHeight(FONT_BIG), lcd.getTextHeight(FONT_NORMAL)
  L.maxValY = h - L.hBig - 1
  L.maxLabelY = L.maxValY - L.hMini
  -- Panel: up to six one-line rows, label left and value right-aligned.
  L.panelX, L.panelR = 2 * R + 10, w - 2
  L.rowH = math.min(h // 6, L.hNorm + 12)
  L.rowY = (h - 6 * L.rowH) // 2
end

-- Single window (transmitter 150 x 23): no room for an arc. Current speed
-- and MAX on one line over a thin horizontal bar: value in the current-speed
-- color, overspeed zone at the end, max tick in the max color.
local function buildStrip(L, w, h)
  L.hMini = lcd.getTextHeight(FONT_MINI)
  L.barH = 4
  L.barY = h - L.barH - 1
  L.barX, L.barW = 2, w - 4
  L.numFont = fitFont(NUM_FONTS, "888", w // 3, L.barY - 1)
  L.hNum = lcd.getTextHeight(L.numFont)
  L.numY = math.max(0, (L.barY - 1 - L.hNum) // 2)
  L.miniY = L.numY + L.hNum - L.hMini   -- bottom-aligned with the number
  L.maxValW = lcd.getTextWidth(FONT_MINI, "888")
end

-- Glow inside an arc from f0 to f1 in the current color, drawn with renderer
-- r: bands fading toward the dial center, as in the reference image.
local function drawGlow(L, r, f0, f1)
  local step = L.glowStep
  local top = L.arcR - L.arcW / 2    -- the arc's inner edge
  if liveLines then
    -- Emulator: side-by-side translucent polylines, every other band at
    -- double width, to keep the full-screen redraw within its CPU budget
    -- (full screen stopped there with all nine, 2026-10-03).
    local A = L.glowT
    for i = 1, L.glowN, 2 do
      gauge.arc(r, glowDial, L.cx, L.cy, top - i * step, f0, f1, 2 * step + 1, A[i])
    end
    return
  end
  local a = L.glowA
  for i = 1, L.glowN do
    gauge.band(r, glowDial, L.cx, L.cy, top, top - i * step, f0, f1, a[i])
  end
end

-- The transmitter draws lines at Lua resolution and enlarges them ~1.45x
-- without smoothing, so curved edges step (2026-10-03). Arcs are filled
-- ring segments (no overlapping polyline joints), with a slightly wider
-- translucent segment under each to give the edge pixels in-between
-- colors, which hides the steps much as anti-aliasing would.
local SOFT_ALPHA = 0.35

local function softArc(r, dial, cx, cy, radius, f0, f1, width)
  if liveLines then
    gauge.arc(r, dial, cx, cy, radius, f0, f1, width + 2, SOFT_ALPHA)
    gauge.arc(r, dial, cx, cy, radius, f0, f1, width)
    return
  end
  local hw = width / 2
  gauge.band(r, dial, cx, cy, radius + hw + 1, radius - hw - 1, f0, f1, SOFT_ALPHA)
  gauge.band(r, dial, cx, cy, radius + hw, radius - hw, f0, f1)
end

-- Smooth images drawn in advance by tools/dial/make_dial.py for each
-- transmitter window size, as DFM-InsP does for its dials: the face and
-- track (dial-WxH.png), and full 270-degree rings for the overspeed zone
-- (ring-WxH-z.png), the speed arc past the limit (-o) and the speed arc in
-- each color preset (-1 .. -9). Loaded once per size, the speed arc again
-- when its color changes. nil (other sizes, such as the emulator's, or a
-- missing file) means draw that part live.
local function loadDialImages(L, w, h)
  if L.imgW ~= w or L.imgH ~= h then
    local ring = AUDIO_DIR .. "ring-" .. w .. "x" .. h .. "-"
    L.img = lcd.loadImage(AUDIO_DIR .. "dial-" .. w .. "x" .. h .. ".png")
    L.ringZone = lcd.loadImage(ring .. "z.png")
    L.ringOver = lcd.loadImage(ring .. "o.png")
    L.ringPath, L.ringCurIdx = ring, nil
    L.imgW, L.imgH = w, h
  end
  if L.ringCurIdx ~= cfg.colCur then
    L.ringCur = lcd.loadImage(L.ringPath .. cfg.colCur .. ".png")
    L.ringCurIdx = cfg.colCur
  end
end

-- Dial fractions where the sweep crosses the center lines: 180 deg (left),
-- 90 deg (top) and 0 deg (right). They split the sweep into four quadrants.
local QUAD = { 0, 1 / 6, 1 / 2, 5 / 6, 1 }

-- Narrows the clip rectangle (x0, y0)-(x1, y1) to one side of the cut at
-- fraction f: keepLarger keeps the part with larger fractions. The cut is
-- horizontal where the radius at f is closer to horizontal, else vertical.
local function clipCut(L, f, keepLarger, x0, y0, x1, y1)
  local c, s = gauge.point(L.dial, f)   -- s is the screen sine (y points down)
  if math.abs(c) >= math.abs(s) then
    -- Horizontal cut: on the right half (c > 0), y grows with f.
    local y = round(L.cy + s * L.arcR)
    if (c > 0) == keepLarger then
      y0 = math.max(y0, y)
    else
      y1 = math.min(y1, y)
    end
  else
    -- Vertical cut: on the top half (s < 0), x grows with f.
    local x = round(L.cx + c * L.arcR)
    if (s < 0) == keepLarger then
      x0 = math.max(x0, x)
    else
      x1 = math.min(x1, x)
    end
  end
  return x0, y0, x1, y1
end

-- Shows the part of a pre-drawn ring image (ring and glow) from fraction
-- f0 to f1 through clip rectangles, one per quadrant of the dial. Quadrants
-- meet on the center lines, which run along the radius, so neighbors join
-- exactly, glow included; only the cuts at f0 and f1 are straight edges.
-- lcd.setClipping also moves the drawing origin to the clip rectangle's
-- top-left corner (transmitter, 2026-10-03), so the image is drawn at minus
-- that corner to stay in place.
local function drawRing(L, img, f0, f1)
  if f1 <= f0 then
    return
  end
  local w, h, cx, cy = L.imgW, L.imgH, L.cx, L.cy
  for q = 1, 4 do
    local qa, qb = QUAD[q], QUAD[q + 1]
    local fa, fb = math.max(f0, qa), math.min(f1, qb)
    if fb > fa then
      local left, bottom = q <= 2, q == 1 or q == 4
      local x0, x1 = left and 0 or cx, left and cx or w
      local y0, y1 = bottom and cy or 0, bottom and h or cy
      if fa > qa then
        x0, y0, x1, y1 = clipCut(L, fa, true, x0, y0, x1, y1)
      end
      if fb < qb then
        x0, y0, x1, y1 = clipCut(L, fb, false, x0, y0, x1, y1)
      end
      if x1 > x0 and y1 > y0 then
        lcd.setClipping(x0, y0, x1 - x0, y1 - y0)
        lcd.drawImage(-x0, -y0, img)
      end
    end
  end
  lcd.resetClipping()
end

-- Fixed parts of the dial: background, face, track, overspeed zone and its
-- glow, ticks, stall and landing marks. Drawn every frame: off-screen images
-- did not work on the DS-24 II emulator (research R6).
local function drawStatic(L, w, h)
  local r = rend
  local cx, cy, arcR, dial = L.cx, L.cy, L.arcR, L.dial
  setColor(C_BG)
  lcd.drawFilledRectangle(0, 0, w, h)
  loadDialImages(L, w, h)
  if L.img then
    lcd.drawImage(0, 0, L.img)
  else
    setColor(C_FACE)
    gauge.face(r, faceCircle, cx, cy, L.R, h - 1)
    -- Soften the face's round edge along the dial's sweep (the open bottom
    -- is cut flat anyway, and the renderer doesn't clip to the window).
    gauge.arc(r, dial, cx, cy, L.R, 0, 1, 2, SOFT_ALPHA)
    setColor(C_TRACK)
    softArc(r, dial, cx, cy, arcR, 0, 1, 3)
  end
  setColor(C_ZONE)
  -- Ring images include their glow; drawing the glow live cost too much
  -- CPU on the transmitter (a redraw hit the limit at speed, 2026-10-03).
  if L.ringZone then
    drawRing(L, L.ringZone, fOver, 1)
  else
    drawGlow(L, r, fOver, 1)
    softArc(r, dial, cx, cy, arcR, fOver, 1, 4)
  end
  setColor(C_MINOR)
  for k = 1, #L.nx1 do
    lcd.drawLine(L.nx1[k], L.ny1[k], L.nx2[k], L.ny2[k])
  end
  setColor(C_SCALE)
  for k = 1, #L.mx1 do
    lcd.drawLine(L.mx1[k], L.my1[k], L.mx2[k], L.my2[k])
  end
  if L.showMarks then
    gauge.tick(dial, cx, cy, L.R - 1, arcR - 4, fStall)
    gauge.tick(dial, cx, cy, L.R - 1, arcR - 4, fLand)
  end
end

local function layoutFor(L, w, h, build)
  if L.w ~= w or L.h ~= h or L.ver ~= scaleVer then
    build(L, w, h)
    L.w, L.h, L.ver = w, h, scaleVer
  end
  return L
end

-- Everything that moves: value arc and its glow, tip, max marker.
local function drawValue(L)
  local cx, cy, arcR, dial = L.cx, L.cy, L.arcR, L.dial
  if shownSpd ~= nil then
    local f = shownSpd / fullScale
    -- Up to the overspeed mark in the current-speed color; past it the arc
    -- (and its glow) switch to the overspeed color. Glow first, so the solid
    -- arc sits on top of its brightest band.
    local fBelow = math.min(f, fOver)
    setColor(COLORS[cfg.colCur])
    if L.ringCur then
      drawRing(L, L.ringCur, 0, fBelow)
    else
      drawGlow(L, rend, 0, fBelow)
      softArc(rend, dial, cx, cy, arcR, 0, fBelow, L.arcW)
    end
    if f > fOver then
      setColor(C_ZONE)
      if L.ringOver then
        drawRing(L, L.ringOver, fOver, math.min(f, 1))
      else
        drawGlow(L, rend, fOver, f)
        softArc(rend, dial, cx, cy, arcR, fOver, f, L.arcW)
      end
    end
    setColor(C_TEXT)
    gauge.mark(rend, dial, cx, cy, arcR - L.arcW, arcR + 2, f, 2)
  end
  if maxSpd > 0 then
    setColor(COLORS[cfg.colMax])
    -- Thick and long enough to stand out: from inside the value arc to the rim.
    gauge.mark(rend, dial, cx, cy, arcR - L.arcW - 4, L.R, maxSpd / fullScale, L.markW)
  end
end

-- The dial for one frame: fixed parts, moving parts, then the scale numbers.
local function drawDial(L, w, h)
  drawStatic(L, w, h)
  drawValue(L)
  if L.labels then
    setColor(C_SCALE)
    for i = 1, #L.mx1 do
      lcd.drawText(L.lx[i], L.ly[i], scaleLabels[i], L.labelFont)
    end
  end
end

-- Small grey label at x over a value in the max color, bottom part of a column.
local function drawMax(x, labelY, valueY, valueFont)
  setColor(C_MINOR)
  lcd.drawText(x, labelY, TXT_MAX, FONT_MINI)
  setColor(COLORS[cfg.colMax])
  lcd.drawText(x, valueY, maxText, valueFont)
end

local function drawRound(w, h)
  local L = layoutFor(layRound, w, h, buildRound)
  drawDial(L, w, h)
  local x = L.colX
  setColor(C_TEXT)
  lcd.drawText(x, 0, curText, L.numFont)
  setColor(C_SCALE)
  lcd.drawText(x, L.hNum, unitText, FONT_MINI)
  drawMax(x, L.maxLabelY, L.maxValY, FONT_NORMAL)
end

-- One full-screen panel row: small label left, value right-aligned with its
-- unit, both bottom-aligned.
local function drawPanelRow(L, i, label, value, unit, labelColor)
  local y = L.rowY + i * L.rowH
  local x = L.panelR
  if unit then
    x = x - lcd.getTextWidth(FONT_MINI, unit)
    setColor(C_MINOR)
    lcd.drawText(x, y + L.hNorm - L.hMini, unit, FONT_MINI)
    x = x - 3
  end
  x = x - lcd.getTextWidth(FONT_NORMAL, value)
  setColor(C_TEXT)
  lcd.drawText(x, y, value, FONT_NORMAL)
  setColor(labelColor or C_MINOR)
  lcd.drawText(L.panelX, y + L.hNorm - L.hMini, label, FONT_MINI)
end

local function drawFull(w, h)
  local L = layoutFor(layFull, w, h, buildFull)
  drawDial(L, w, h)
  setColor(C_TEXT)
  local tw = lcd.getTextWidth(L.numFont, curText)
  lcd.drawText(L.cx - tw // 2, L.cy - L.hNum // 2 - 2, curText, L.numFont)
  setColor(C_SCALE)
  tw = lcd.getTextWidth(L.unitFont, unitText)
  lcd.drawText(L.cx - tw // 2, L.cy + L.hNum // 2, unitText, L.unitFont)
  -- MAX in the open bottom of the dial, centered under the speed.
  local lw = lcd.getTextWidth(FONT_MINI, TXT_MAX)
  local vw = lcd.getTextWidth(FONT_BIG, maxText)
  setColor(C_MINOR)
  lcd.drawText(L.cx - lw // 2, L.maxLabelY, TXT_MAX, FONT_MINI)
  setColor(COLORS[cfg.colMax])
  lcd.drawText(L.cx - vw // 2, L.maxValY, maxText, FONT_BIG)
  -- Side panel (spec US3 #2a). DENSITY is always shown; ELEV, TEMP (FR-044)
  -- and the uncorrected RAW speed only while correction is active. A rejected
  -- sensor shows "SENSOR OUT" in the overspeed color, with the standard
  -- temperature in use as its value.
  drawPanelRow(L, 0, TXT_STALL, stallText, unitText)
  drawPanelRow(L, 1, TXT_OVERSPEED, overText, unitText)
  drawPanelRow(L, 2, TXT_DENSITY, densRowText, nil)
  if densActive then
    drawPanelRow(L, 3, TXT_ELEVATION, elevText, elevUnitText)
    drawPanelRow(L, 4, tempLabel, tempText, tempUnitText,
      tempLabel == TXT_TEMP.out and C_ZONE or nil)
    drawPanelRow(L, 5, TXT_SENSOR, sensText, unitText)
  end
  if DEBUG_CPU then
    -- This call's CPU share at its end, and the worst seen (top-left corner).
    local c = system.getCPU()
    if c > cpuPeak then
      cpuPeak = c
    end
    setColor(C_ZONE)
    lcd.drawNumber(2, 0, c, FONT_MINI)
    lcd.drawNumber(26, 0, cpuPeak, FONT_MINI)
  end
end

local function drawStrip(w, h)
  local L = layoutFor(layStrip, w, h, buildStrip)
  setColor(C_FACE)
  lcd.drawFilledRectangle(0, 0, w, h)
  -- Current speed and unit on the left, MAX and its value on the right.
  setColor(C_TEXT)
  lcd.drawText(L.barX, L.numY, curText, L.numFont)
  setColor(C_SCALE)
  lcd.drawText(L.barX + lcd.getTextWidth(L.numFont, curText) + 3, L.miniY, unitText, FONT_MINI)
  local vx = w - 2 - lcd.getTextWidth(FONT_MINI, maxText)
  setColor(COLORS[cfg.colMax])
  lcd.drawText(vx, L.miniY, maxText, FONT_MINI)
  setColor(C_MINOR)
  lcd.drawText(vx - 3 - lcd.getTextWidth(FONT_MINI, TXT_MAX), L.miniY, TXT_MAX, FONT_MINI)
  -- Bar: track, overspeed zone, value (overspeed color past the mark), max tick.
  local x0, y, bw, bh = L.barX, L.barY, L.barW, L.barH
  local xo = x0 + round(bw * fOver)
  setColor(C_TRACK)
  lcd.drawFilledRectangle(x0, y + 1, bw, bh - 2)
  setColor(C_ZONE)
  lcd.drawFilledRectangle(xo, y + 1, x0 + bw - xo, bh - 2)
  if shownSpd ~= nil then
    local xv = x0 + round(bw * math.min(shownSpd / fullScale, 1))
    setColor(COLORS[cfg.colCur])
    lcd.drawFilledRectangle(x0, y, math.min(xv, xo) - x0, bh)
    if xv > xo then
      setColor(C_ZONE)
      lcd.drawFilledRectangle(xo, y, xv - xo, bh)
    end
  end
  if maxSpd > 0 then
    setColor(COLORS[cfg.colMax])
    local xm = x0 + round(bw * math.min(maxSpd / fullScale, 1))
    lcd.drawFilledRectangle(xm - 1, y - 2, 2, bh + 3)
  end
end

local function printGauge(w, h)
  if not gaugeOk then
    -- FR-013a: not a DS-24 II. Callouts and warnings still run in loop().
    local r, g, b = lcd.getFgColor()
    lcd.setColor(r, g, b)
    local tw = lcd.getTextWidth(FONT_MINI, TXT_NOTICE)
    lcd.drawText((w - tw) // 2, (h - lcd.getTextHeight(FONT_MINI)) // 2, TXT_NOTICE, FONT_MINI)
    return
  end
  if not rend then
    rend = lcd.renderer()
  end
  -- Only the emulator hides a title bar inside the window (see TITLE_H).
  liveLines = w == 157 or w == 320
  if liveLines then
    h = h - TITLE_H
  end
  if h < 45 then
    drawStrip(w, h)
  elseif w < 250 then
    drawRound(w, h)
  else
    drawFull(w, h)
  end
end

------------------------------------------------------------------------------
-- Lifecycle
------------------------------------------------------------------------------

-- Temperature sensor, every ts.periodMs (R15, data-model.md). A bad read falls
-- back to standard at once; after a rejection, two good reads in a row are
-- needed to resume. The first read after (re)start needs only one. Changes
-- only the density factor, never callout state (FR-041, FR-043).
local function readTemp(now)
  if ts.stat == 0 or now - ts.nextRead < 0 then
    return
  end
  ts.nextRead = now + ts.periodMs
  local e = nil
  if cfg.tId ~= 0 then
    e = system.getSensorByID(cfg.tId, cfg.tPar)   -- through system (R3); unit needed
  end
  local rc = nil            -- good reading, deg C
  if e ~= nil and e.valid then
    local isF = string.sub(e.unit or "", -1) == "F"
    -- Limits in the system the user sees (FR-023).
    local v = e.value
    if UNITS_IMPERIAL[cfg.units] then
      v = isF and v or dens.cToF(v)
      if v >= LIM.tempF[1] and v <= LIM.tempF[2] then
        rc = dens.fToC(v)
      end
    else
      v = isF and dens.fToC(v) or v
      if v >= LIM.tempC[1] and v <= LIM.tempC[2] then
        rc = v
      end
    end
  end
  local oldStat, oldUse = ts.stat, ts.useC
  if ts.stat == 1 then
    if rc == nil then
      ts.good, ts.ever = 0, true
    elseif not ts.ever then
      ts.stat, ts.useC, ts.ever = 2, rc, true
    else
      ts.good = ts.good + 1
      if ts.good >= 2 then
        ts.stat, ts.useC = 2, rc
      end
    end
  elseif rc == nil then
    ts.stat, ts.good, ts.useC, ts.ever = 1, 0, nil, true
  elseif math.abs(rc - ts.useC) >= 1 then
    ts.useC = rc              -- 1 deg C hysteresis (FR-041)
  end
  if ts.stat ~= oldStat or ts.useC ~= oldUse then
    recomputeDensity()
    recomputeScale()
    if formOpen then
      updateDensityRows()
    end
  end
end

local function init()
  loadSettings()
  voiceOk = checkVoiceFiles()   -- once: 13 file opens (R14)
  recomputeAll()
  resetSession()

  -- 3-degree steps for visible edges: 5-degree steps looked choppy on the
  -- transmitter, which enlarges Lua drawing about 1.45x (2026-10-03).
  -- 10-degree steps for the translucent glow bands, where they don't show
  -- and save renderer calls every frame.
  roundDial = gauge.newDial(90, 225, 270)
  faceCircle = gauge.newCircle(90)
  glowDial = gauge.newDial(54, 225, 270)   -- 5-degree steps (10 looked polygonal)
  gaugeOk = string.find(system.getDeviceType() or "", "24 II", 1, true) ~= nil

  system.registerForm(1, MENU_APPS, APP_NAME, initForm, keyForm, nil, closeForm)
  system.registerTelemetry(1, APP_NAME, 0, printGauge)
  -- Size 4 (no status bar), as DFM-InsP uses: size 3 is covered by the desktop's
  -- model tile on the DS-24 II (emulator, 2026-09-27).
  -- Distinct name so the pilot can tell the two apart in Displayed telemetry
  -- (transmitter test, 2026-10-03). Size 4 has no title bar, so it shows
  -- only in that list.
  system.registerTelemetry(2, APP_NAME .. " (full screen)", 4, printGauge)

  -- FR-028: tell the pilot the app is running and configured.
  -- Each announcement is wholly in the app voice or wholly in the fallback.
  if cfg.startAnn == 1 then
    if cfg.cal ~= 100 then
      local nf = numFile(cfg.cal)
      if nf then
        system.playFile(VOICE.cal, AUDIO_QUEUE)
        system.playFile(nf, AUDIO_QUEUE)
        system.playFile(VOICE.pct, AUDIO_QUEUE)
      else
        system.playFile(SND_CAL, AUDIO_QUEUE)
        system.playNumber(cfg.cal, 0, "%")
      end
    end
    local nf = numFile(cfg.vStall)
    if nf then
      system.playFile(VOICE.stallAt, AUDIO_QUEUE)
      system.playFile(nf, AUDIO_QUEUE)
      system.playFile(snd.unit, AUDIO_QUEUE)
    else
      system.playFile(SND_STALL_AT, AUDIO_QUEUE)
      system.playNumber(cfg.vStall, 0, unitSpoken)
    end
  end
end

local function loop()
  local now = system.getTimeCounter()
  if now - lastTick < TICK_MS then
    return
  end
  lastTick = now
  readTemp(now)             -- before the early return: tracked even with no speed

  -- Always call through system: Emulator Telemetry replaces it (R3).
  local s = nil
  if cfg.sId ~= 0 then
    s = system.getSensorValueByID(cfg.sId, cfg.sPar)
  end
  if s == nil or not s.valid then
    if sensorSpd ~= nil then
      sensorSpd, shownSpd = nil, nil
      curRounded, curText = nil, TXT_NO_DATA
      sensRounded, sensText = nil, TXT_NO_DATA
    end
    return                  -- no data: no flags, max, warnings or callouts
  end

  sensorSpd = s.value * kSensor
  shownSpd = sensorSpd * kDens

  -- Flight flags use sensor speed (FR-011).
  -- Arming speed (FR-009, changed 2026-10-03): callouts, continuous
  -- callouts and "airspeed alive" wait until this is first exceeded.
  if sensorSpd > cfg.vArm then
    armed = true
  end
  if sensorSpd > cfg.vLand then
    everAboveLanding = true
    belowLanding = false
  elseif everAboveLanding then
    belowLanding = true
  end

  local onSw, contSw = switchOn(cfg.swOn), switchOn(cfg.swCont)
  updateMax(now)
  checkWarnings(onSw or contSw)
  checkCallout(now, onSw, contSw)
end

local function destroy()
end

---@type JetiApp
return {
  init = init,
  loop = loop,
  destroy = destroy,
  author = "Aaron George",
  version = APP_VERSION,
  name = APP_NAME,
}