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.

How to use this reference

Use an action for a button-like tool, such as filling in several settings. It runs when the user invokes it, rather than once per audio block. The Quick Tune example below changes the form and reports a status; it does not start transmitting because it does not call app:start().

Declaration

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,
}

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

Action context

Method	Effect or result
app:control(id)	Value of one action control, or nil.
app:controls()	Snapshot table of all action controls.
app:get(key)	Current value of one documented transmitter setting, or nil for an unknown key.
app:settings()	Snapshot table containing every documented setting.
app:set(key, value)	Changes one documented setting.
app:apply(table)	Changes each setting in a table.
app:status(message)	Places a message in the transmitter status line.
app:notify(message)	Shows an informational dialog.
app:start()	Starts a transmission with the current form values.
app:stopAll()	Stops all transmitter sessions.

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

Setting keys

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

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

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

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

The system theme is named System. Other theme values are installed Lua theme names.

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