Editing Lua action API

An '''action''' is a tool run explicitly from '''Extensions''' > '''Tools'''. It can read or change documented transmitter settings, show a status or message, and start or stop transmissions.

== Declaration ==
<syntaxhighlight lang="lua">
simtx.action {
  name = "Quick Tune",
  description = "Applies a frequency, power, and modulation.",
  controls = {
    simtx.controls.text("frequency", {default = "7100000"}),
    simtx.controls.slider("power", {min = 1, max = 1000, default = 100}),
  },
  run = function(app)
    local values = app:controls()
    app:apply {
      ["rf.frequencyHz"] = values.frequency,
      ["rf.powerWatts"] = values.power,
      ["rf.modulation"] = "USB",
    }
    app:status("Quick Tune applied")
  end,
}
</syntaxhighlight>

<code>simtx.tool</code> is an alias of <code>simtx.action</code>. The <code>name</code> and <code>run</code> fields are required. <code>action</code> may be used as an alias of <code>run</code>. <code>description</code> and <code>controls</code> are optional. The application displays the controls before running the callback.

== Action context ==
{| class="wikitable"
! Method !! Effect or result
|-
| <code>app:control(id)</code> || Value of one action control, or <code>nil</code>.
|-
| <code>app:controls()</code> || Snapshot table of all action controls.
|-
| <code>app:get(key)</code> || Current value of one documented transmitter setting, or <code>nil</code> for an unknown key.
|-
| <code>app:settings()</code> || Snapshot table containing every documented setting.
|-
| <code>app:set(key, value)</code> || Changes one documented setting.
|-
| <code>app:apply(table)</code> || Changes each setting in a table.
|-
| <code>app:status(message)</code> || Places a message in the transmitter status line.
|-
| <code>app:notify(message)</code> || Shows an informational dialog.
|-
| <code>app:start()</code> || Starts a transmission with the current form values.
|-
| <code>app:stopAll()</code> || Stops all transmitter sessions.
|}

Setting values may be <code>nil</code>, Boolean, number, or string. Unknown keys and invalid values produce an error.

== Setting keys ==
{| class="wikitable"
! Group !! Keys !! Value
|-
| Station || <code>station.callsign</code> || String
|-
| Station || <code>station.lat</code>, <code>station.lon</code> || Number
|-
| RF basics || <code>rf.frequencyHz</code>, <code>rf.powerWatts</code>, <code>rf.bandwidthHz</code>, <code>rf.lowCutHz</code> || Number
|-
| RF selection || <code>rf.radioPreset</code>, <code>rf.modulation</code> || String
|-
| RF bandwidth || <code>rf.autoBandwidth</code> || Boolean
|-
| RF character || <code>rf.finalDriveDb</code>, <code>rf.paHeadroomDb</code>, <code>rf.audioCompressionDb</code>, <code>rf.paSoftness</code>, <code>rf.paAmPmDeg</code> || Number
|-
| RF suppression || <code>rf.carrierLeakDb</code>, <code>rf.sidebandSuppressionDb</code> || Number
|-
| RF oscillator and noise || <code>rf.frequencyOffsetHz</code>, <code>rf.mainsHumDb</code>, <code>rf.mainsHumHz</code>, <code>rf.txNoiseFloorDb</code>, <code>rf.oscillatorPhaseNoiseDb</code> || Number
|-
| Mode-specific RF || <code>rf.amModulationIndex</code>, <code>rf.paSupplySagDb</code>, <code>rf.cwKeyRiseMs</code> || Number
|-
| Source || <code>source.type</code> || String
|-
| Source || <code>source.gain</code>, <code>source.tone</code> || Number
|-
| Source || <code>source.repeat</code> || Boolean
|-
| Antenna || <code>antenna.type</code> || String
|-
| Antenna || <code>antenna.length</code>, <code>antenna.height</code>, <code>antenna.azimuth</code>, <code>antenna.feedlineLossDb</code> || Number
|-
| Appearance || <code>ui.theme</code> || String
|}

Built-in modulation values are <code>AM_DSB_FC</code>, <code>AM_DSB_SC</code>, <code>USB</code>, <code>LSB</code>, <code>CW</code>, <code>NFM</code>, <code>WFM</code>, <code>IQ</code>, <code>WSPR</code>, and <code>FT8</code>. A Lua modulation may be selected with <code>lua:</code> followed by its display name.

Source type values are <code>AUDIO_STREAM</code>, <code>MICROPHONE</code>, <code>WHITE_NOISE</code>, <code>PIPEWIRE</code>, <code>PIPEWIRE_STEREO</code>, and <code>GNU_RADIO_IQ</code>. Antenna type values are <code>DIPOLE</code>, <code>VERTICAL</code>, <code>YAGI_3EL</code>, <code>YAGI_5EL</code>, <code>LOOP</code>, <code>BEVERAGE</code>, <code>LONGWIRE</code>, <code>INVERTED_V</code>, and <code>EFHW_32M_49_1</code>.

Radio preset values accepted by <code>set</code> are <code>GENERIC_HF</code>, <code>CLEAN_LAB</code>, <code>ICOM_IC_7300</code>, <code>ICOM_IC_705</code>, <code>ICOM_IC_7610</code>, <code>YAESU_FTDX10</code>, <code>ELECRAFT_KX3</code>, <code>YAESU_FT_817</code>, <code>KENWOOD_TS_590</code>, <code>XIEGU_G90</code>, <code>USDX_QRP</code>, <code>MIL_MANPACK</code>, <code>VINTAGE_TUBE</code>, <code>COLLINS_KWM2</code>, <code>BOAT_ANCHOR_AM</code>, <code>CB_EXPORT_AM</code>, <code>VHF_HANDHELD_FM</code>, <code>HOME_BREW_CLASS_E_AM</code>, and <code>DIRTY_DRIVER</code>. Reading <code>rf.radioPreset</code> returns the display name shown in [[Radio Presets]].

The system theme is named <code>System</code>. Other theme values are installed Lua theme names.

The aliases <code>station.latitude</code>, <code>station.longitude</code>, <code>rf.frequency</code>, <code>rf.power</code>, <code>rf.bandwidth</code>, and <code>rf.auto_bandwidth</code> are accepted by <code>get</code> and <code>set</code>.

[[Category:Lua extensions]]