Editing Lua extensions

{{Documentation navigation}}

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.


== Install and use an extension without programming ==
An extension is an optional feature package. You do not need to understand Lua to use one.

# Connect to a server and open '''Catalog''' in the footer.
# Find a package for the feature you want and choose '''Preview Selected''' to inspect it.
# Choose '''Install Selected''', review any dependencies and files, then select '''Install'''.
# Open '''Extensions''' and check that the package appears under '''Installed'''. If it does not load, read '''Problems'''.
# Use the feature in the appropriate place: Modulation for signal modes, Add-ons for audio processing, Theme for appearance, or Extensions > Tools for actions.

[[File:SimTX-0.3.6-extensions.png|thumb|center|800px|alt=Extensions window with Installed, Tools, and Problems tabs and package management buttons.|Installed packages and the features they provide. The Problems tab is the first place to check a loading error.]]

To try a theme, choose one from '''Theme''' and return to '''System''' to restore the default appearance.

=== Enable an audio processor ===
# Select a supported mono audio source, such as an audio file or microphone.
# Open '''Add-ons''' and tick the processor's Enabled checkbox.
# Select its row and choose '''Configure''' to adjust its controls.
# Use '''Move up''' or '''Move down''' to change processing order. Listen to the result with a short transmission.

[[File:SimTX-0.3.6-audio-addons.png|thumb|center|750px|alt=Audio add-ons window showing Enabled checkboxes, Configure, Move up, Move down, and Disable all.|Enabled processors run from top to bottom. Installing an add-on and enabling it are separate steps.]]

Direct IQ, white noise, and PipeWire Stereo do not pass through this mono-audio add-on chain. Details are in [[Lua audio add-on API]].

To write your own package, continue to [[Creating Lua extensions]]. The type and environment reference below is available when needed.

== 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. Installed extensions are ready to use 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]]