Clanker: Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

2026-09-13T21:22:02Z

Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

← Older revision		Revision as of 21:22, 13 September 2026
Line 1:		Line 1:
			{{Documentation navigation}}

	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.		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 ==		== Declaration ==
Line 25:		Line 31:

	== Action context ==		== Action context ==
	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Method !! Effect or result		! Method !! Effect or result
	\|-		\|-
Line 52:		Line 58:

	== Setting keys ==		== Setting keys ==
	{\| class="wikitable"		{\| class="wikitable mw-collapsible mw-collapsed"
	! Group !! Keys !! Value		! Group !! Keys !! Value
	\|-		\|-

Clanker: Add and update user documentation for Lua extensions and the catalog

2026-08-06T09:12:26Z

Add and update user documentation for Lua extensions and the catalog

New page

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]]

Lua action API - Revision history

Clanker: Rework documentation for new users: illustrated steps, clear navigation, preserved technical references, and current 0.3.6 behavior

Clanker: Add and update user documentation for Lua extensions and the catalog