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

2026-08-06T09:12:22Z

Add and update user documentation for Lua extensions and the catalog

New page

A '''Lua extension''' adds user-defined features to the SimTX Transmitter. An extension may provide modulation modes, audio add-ons, tools, themes, reusable libraries, or several of these features in one package. Extensions are stored as folders and can be created, edited, and reloaded without restarting the application.

== Extension types ==
{| class="wikitable"
! Type !! Purpose !! Where it appears
|-
| Modulation || Produces complex IQ or mono audio for a transmission. A mode may use ordinary audio, generate a signal, or consume an image, video, or data file. || '''Modulation''' list in the RF Signal section
|-
| Audio add-on || Processes mono audio before RF modulation. Examples include gain control, filtering, CTCSS, and identification tones. || '''Add-ons''' button in the footer
|-
| Tool or action || Reads or changes documented transmitter settings and may start or stop transmissions. || '''Extensions''' > '''Tools'''
|-
| Theme || Changes the application colors and fonts. || '''Theme''' list in the footer
|-
| Library || Provides Lua modules to other installed extension packages. || Used by declared dependent packages
|}

One package may register several items and may combine several types.

== Managing installed extensions ==
The '''Extensions''' button opens three tabs:
* '''Installed''' lists each package, its version, and the items it provides.
* '''Tools''' lists user-invoked actions and provides a button for running the selected action.
* '''Problems''' lists packages that could not be loaded and gives the reason.

The same window provides '''Create extension''', '''Edit package''', '''Open user folder''', and '''Reload now'''. Changes made in the built-in editor or in the extension folder take effect after reloading. The application also detects ordinary file changes and reloads extensions automatically.

The first creation of the extension folder includes editable example packages. These demonstrate modulation, generated CW, image input, audio add-ons, actions, themes, multi-type packages, libraries, and dependencies.

== Using extension features ==
Extension modulation modes are selected in the normal '''Modulation''' list. Their controls and required media pickers appear below the standard transmission fields. Audio-output modes also provide an '''RF modulation''' selector. IQ-output modes bypass the built-in modulator.

Audio add-ons are enabled and ordered through the '''Add-ons''' window. Enabled add-ons run from top to bottom. Their order, enabled state, and control values are retained between application runs. Add-ons require a mono audio source or an audio-producing Lua modulation.

Themes are selected from the '''Theme''' list. Tools are run from the '''Tools''' tab of the '''Extensions''' window.

== Obtaining extensions ==
The [[Extension catalog]] is the normal way to preview and install shared packages. Catalog extensions are checked before installation, placed in the user extension folder, and loaded immediately. Required library packages can be installed as part of the same operation.

== Creating extensions ==
[[Creating Lua extensions]] describes the package structure and a minimal example. The public interface is divided among these references:
* [[Lua extension manifest]]
* [[Lua extension API]]
* [[Lua modulation API]]
* [[Lua audio add-on API]]
* [[Lua action API]]
* [[Lua theme API]]

== Execution environment ==
Extensions run in a restricted Lua environment intended for computation. Standard Lua base, table, string, coroutine, bit32, and mathematical facilities are available. Direct file access, operating-system commands, network access, Java access, the debug library, <code>dofile</code>, and <code>loadfile</code> are not available. Files selected through declared inputs are exposed as read-only objects described in [[Lua modulation API]].

Extension callbacks have execution limits. Signal processing should use the block operations supplied by the API where possible. An extension that exceeds a limit, returns an invalid value, or raises an error is stopped with a diagnostic.

[[Category:Lua extensions]]

Lua extensions - Revision history

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