Documentation MSFS - mpaperno/MSFSTouchPortalPlugin GitHub Wiki
MSFS Touch Portal Plugin Documentation
This plugin provides tools for Touch Portal macro launcher software to build two-way interactive interfaces with Microsoft Flight Simulator 2020 and 2024.
Set to 1 to automatically attempt connection to flight simulator upon Touch Portal startup. Set to 0 to only connect manually via the Action "MSFS - Plugin -> Connect & Update".
Check For New Plugin Version on Startup (0/1)
Type
Default Value
Min. Value
Max. Value
boolean (on/off)
0
0
1
Set to 1 to check for new versions of this plugin when it starts, or 0 to disable update checks.
A version check is also performed when this value is changed from 0 to 1 and the settings are saved.
The minimum time between update checks is 6 hours, even if the plugin is restarted. It will never check more often than that.
Update checks require an active Internet connection.
Sim Variable State Config File(s) (blank = Default)
Type
Default Value
Max. Length
text
Default
255
Here you can specify one or more custom configuration files which define SimConnect variables to request as Touch Portal States. This plugin comes with an extensive default set of states, however since the possibilities between which variables are requested, which units they are displayed in,and how they are formatted are almost endless. This option provides a way to customize the output as desired.
Enter a file name here, with or w/out the suffix (".ini" is assumed). Separate multiple files with commas (and optional space). To include the default set of variables/states, use the name Default as one of the file names (in any position of the list).
Files are loaded in the order in which they appear in the list, and in case of conflicting state IDs, the last one found will be used.
The custom file(s) are expected to be in the folder specified in the "User Config Files Path" setting (see below).
SimConnect.cfg Index (0 for MSFS, 1 for FSX, or custom)
Type
Default Value
Min. Value
Max. Value
number
0
0
20
A "SimConnect.cfg" file can contain a number of connection configurations, identified in sections with the [SimConnect.N] title. A default "SimConnect.cfg" is included with this plugin (in the installation folder). You may also use a custom configuration file stored in the "User Config Files Path" folder (see below).
The index number can be specified in this setting. This is useful for:
Compatibility with FSX.
Custom configurations over network connections (running Touch Portal on a different computer than the sim).
The default configuration index is zero, which (in the included default SimConnect.cfg) is suitable for MSFS (2020). Use the index 1 for compatibility with FSX (or perhaps other sims).
The system path where plugin settings are stored, including custom user State configuration files for sate definitions & the "SimConnect.cfg" configuration file.
Keep it blank for default, which is "C:\Users<UserName>\AppData\Roaming\MSFSTouchPortalPlugin".
Note that using this plugin's installation folder for custom data storage is not recommended, since anything in there will likely get overwritten during a plugin update/re-install.
Ignore Local Number Format Rules (0/1)
Type
Default Value
Min. Value
Max. Value
boolean (on/off)
1
0
1
Touch Portal cannot perform math or numeric comparison operations on decimal numbers formatted with comma decimal separator, even in locations where this is the norm. Set this setting to 1 (one) to always format numbers in "neutral" format with period decimal separators.
NOTE that this affects input number formatting as well (the plugin will expect all numbers with period decimal separators regardless of your location).
Update HubHop Data on Startup (0/1)
Type
Default Value
Min. Value
Max. Value
boolean (on/off)
0
0
1
Set to 1 (one) to automatically load latest HubHop data when plugin starts. Set to 0 (zero) to disable. Updates can always be triggered manually via the Action "MSFS - Plugin -> Connect & Update".
Updates require a working Internet connection!
HubHop Data Update Timeout (seconds)
Type
Default Value
Min. Value
Max. Value
number
60
0
600
Maximum number of seconds to wait for a HubHop data update check or download via the Internet.
Sort Local Variables Alphabetically (0/1)
Type
Default Value
Min. Value
Max. Value
boolean (on/off)
1
0
1
Set to 1 (one) to have all Local ('L') simulator variables sorted in alphabetical order within selection lists. Setting to 0 (zero) will keep them in the original order they're loaded in on the simulator (by ascending ID).
This setting only applies when using WASimModule integration since there is no other way to get a list.
Default Held Action Repeat Delay (milliseconds)
Type
Default Value
Min. Value
Max. Value
number
0
25
4294967295
Default delay period before a held action starts repeating.
A value of 0 will make the delay be the same as the current repeat interval
(this is the default value for this setting).
If set to > 0, the smallest effective value is 25ms, same as the repeat interval.
This is how often the plugin checks for events to fire.
Typically the delay would be same or longer than the repeat interval.
For example with a very short interval it may be possible to get unintentional repeating if a button is pressed for a little too long. Introducing a longer delay time before the repeat starts would help the issue.
A delay can also be specified per action when it is used in the "On Hold" button setup area, which would override this setting.
Maximum Length of Descriptions in Action Lists
Type
Default Value
Min. Value
Max. Value
number
75
0
300
Some plugin actions and connectors allow selecting Variables and Events from lists. These may have some informative descriptions (imported from the FS documentation or HubHop data).This setting controls how much of that description will be shown in the selection lists along with the variable/event name. The longer they are, the more space they will need in the TP button editor.
Enter zero (0) to disable showing descriptions entirely. Maximum value is 300.
Maximum Recent Log Messages to Send
Type
Default Value
Min. Value
Max. Value
number
12
0
50
Maximum number of log messages to include in the "Most recent plugin log messages" State value.
Enter zero (0) to disable sending any log entries. Maximum value is 50.
Control connection to the Simulator, or perform various data update tasks.
Plugin Action:
Toggle Simulator Connection
Connect to Simulator
Disconnect from Simulator
Reload State Files
Re-Send All State Values
Re-Send All Connector Feedback Values
Update Airplane Local Vars List
Update Airplane Input Events List
Re-Submit Input Event Value Requests
Update HubHop Data
Action Repeat Interval
Set the default held action repeat rate, in milliseconds. The minimum value is 25ms.
Repeat Interval:
Set
Increment
Decrement
to/by: [number (25)]
☑
Activate a Selected Simulator Event
Activate a Selected Simulator Event. Parameter values are optional and event-specific. The list is imported from MSFS SDK Event IDs Docs (may contain errors or omissions).
The value(s), if any, should evaluate to numeric or remain blank if the value is unused by the event. Using basic math operators and dynamic states in values is possible.
System /
Category
[plugin not connected]
Event
Name
[select a category]
with
Value(s) 0: [number]
1: [number]
2: [number]
☑
Activate a Named Simulator Event
Trigger any Simulator Event by name with optional parameter value(s). See MSFS SDK Documentation 'Event IDs' for reference.
The value(s), if any, should evaluate to numeric or remain blank if the value is unused by the event. Using basic math operators and dynamic state values is possible.
** Requires WASimModule or MobiFlight. **
Trigger a Simulator Event from loaded HubHop data. "Potentiometer" type events are indicated with (@) in the name and are only supported with WASimModule (using the provided numeric value).
Aircraft/Device:
[plugin not connected]
System:
[select an aircraft]
Event Name:
[select a system]
with value [number] (if any)
☑
Set a Selected Simulator Variable
Set a Selected Simulator Variable.
The list of Sim Vars is imported from MSFS SDK Simulator Variables Docs (may contain errors or omissions). Variables with ":N" in the name require an Index value.
System /
Category
[plugin not connected]
Variable:
[select a category]
Index
(if req'd): [number (0 99)] Unit:
[select a variable]
Value: [number]
☑
Set a Selected Airplane Local Variable
Sets a value on a Local variable from currently loaded aircraft.
The Unit type is usually "number" and will be ignored except in a few specific instances for some 3rd-party models.
Set Variable:
[plugin not connected]
To Value: [number] in Units:
(opt)
number
☑
Set a Selected Input Event Value
Sets a value on an Input Event from currently loaded aircraft. These are sometimes also referred to as 'B' type variables and are always model-specific.
The value meaning and type (numeric/string) depends entirely on the specific event. A list of Input Events can be found in the MSFS Dev Mode 'Behaviors' window.
Set Input Event:
[plugin not connected]
To Value: [number]
☑
Set a Named Variable
Set a Named Variable. Sets a value on any named variable of various types. ** Using 'C', 'H', 'K', and 'Z' types require WASimModule. **
'L' type variables can also be created. 'A' and 'C' types require a Unit, for 'B' and 'L' it is optional (default is 'number'). For SimVars requiring an index, include it in the name after a : (colon), eg. "VARIABLE NAME:1".
Variable
Type
A: SimVar
B: Input Event
C: GPS
H: HTML Event
K: Key Event
L: Local
Z: Custom SimVar
Variable
Name [text] Unit
[plugin not connected]
Value [number]
☑
Execute Calculator Code
Execute Calculator Code. ** Requires WASimModule **
Runs any entered string of RPN code through the 'execute_calculator_code' Gauge API function. You may use TP state value macros to insert dynamic data.
Execute this code: [text] (must be valid RPN format)
☑
Connectors
Name
Description
Format
Action Repeat Interval
Set the default held action repeat rate, in milliseconds. The minimum value is 25ms.
Set Repeat Interval Milliseconds in Range (min: 25ms): [number (25)] - [number (25)]
Activate a Selected Simulator Event
Activate a Selected Simulator Event, setting one parameter value with a slider, with optional extra parameter value(s). The list is imported from MSFS SDK Event IDs Docs.
The extra value(s), if any, should evaluate to numeric or remain blank if the value is unused by the event. Using basic math operators and dynamic states in the extra values is possible.
System /
Category
[plugin not connected]
Event
Name
[select a category]
in Value
Range [number] - [number] | With Other
| Values (opt) [number][number] Connector
Value Index
0-first
1-mid
2-last
Activate a Named Simulator Event
Trigger any Simulator Event by name setting one parameter value with a slider, with optional extra parameter value(s). See MSFS SDK Documentation 'Event IDs' for reference.
The extra value(s), if any, should evaluate to numeric or remain blank if the value is unused by the event. Using basic math operators and dynamic state the extra values is possible.
Set Event: [text] in Value
Range [number] - [number] | With Other
| Values (opt) [number][number] Connector
Value Index
0-first
1-mid
2-last
Activate an Input Event From HubHop
** Requires WASimModule or MobiFlight. **
Trigger a Simulator Event from loaded HubHop data. "Potentiometer" type events are indicated with (@) in the name and are only supported with WASimModule (using the provided numeric value).
Aircraft
Device:
[plugin not connected]
System:
[select an aircraft]
Event
Name:
[select a system]
Value
Range: [number] - [number]
Set a Selected Simulator Variable
Set a Selected Simulator Variable.
The list of Sim Vars is imported from MSFS SDK Simulator Variables Docs (may contain errors or omissions). Variables with ":N" in the name require an Index value.
System /
Category
[plugin not connected]
Variable:
[select a category]
Index
(if req'd): [number (0 99)] Unit:
[select a variable]
in Value
Range: [number] - [number] | With
Set a Selected Airplane Local Variable
Sets a value on a Local variable from currently loaded aircraft.
The Unit type is usually "number" and will be ignored except in a few specific instances for some 3rd-party models.
Set Variable:
[plugin not connected]
Unit:
(opt)
number
in Value
Range: [number] - [number]
Set a Selected Input Event Value
Sets a value on an Input Event from currently loaded aircraft. These are sometimes also referred to as 'B' type variables and are always model-specific.
The value meaning and type (numeric/string) depends entirely on the specific event. A list of Input Events can be found in the MSFS Dev Mode 'Behaviors' window.
Set Input Event:
[plugin not connected]
in Value
Range: [number] - [number]
Set a Named Variable
Set a Named Variable. Sets a value on any named variable of various types. ** Using 'C', 'H', 'K', and 'Z' types require WASimModule. **
'L' type variables can also be created. 'A' and 'C' types require a Unit, for 'B' and 'L' it is optional (default is 'number'). For SimVars requiring an index, include it in the name after a : (colon), eg. "VARIABLE NAME:1".
Variable
Type
A: SimVar
B: Input Event
C: GPS
H: HTML Event
K: Key Event
L: Local
Z: Custom SimVar
Variable
Name [text] Unit
[plugin not connected]
Value
Range: [number] - [number]
Execute Calculator Code
Runs any entered string of RPN code through the 'execute_calculator_code' Gauge API function. Use a '@' placeholder for the connector value.
Calculator Code:
(use @ as placeholder(s) for slider value) [text] Value
Range: [number] - [number]
Visual Feedback Connector
This connector provides only visual feedback by setting the position of a slider based on an existing State/variable value.
Set Connector Value Based on
Feedback From Category:
[plugin not connected]
Variable:
[select a category]
Value Range: [number] - [number]
States
Base Id: MSFSTouchPortalPlugin.Plugin.State.
Id
SimVar Name
Description
Unit
Format
DefaultValue
LoadedStateConfigFiles
List of currently loaded state configuration file(s).
string
LogMessages
Most recent plugin log messages.
string
UserConfigFilesPath
Plugin configuration files path.
string
RunningState
Plugin running state (stopped/starting/started)
string
stopped
WasmStatus
Status of WASM module (unknown/undetected/disconnected/connected)
string
unknown
ActionRepeatInterval
The current Held Action Repeat Rate (ms)
millisecond
450
EntryVersion
The loaded entry.tp plugin version number.
number
0
CurrentTouchPortalPage
The most recently loaded Touch Portal page name.
string
RunningVersion
The running plugin version number.
number
0
Connected
The status of SimConnect (true/false/connecting)
string
false
TouchPortalConfigPath
Touch Portal configuration files path.
string
Events
Name
Details
Plugin Message Event
When the plugin sends an important informational message
Local States
State ID
State Name
MSFS.PluginMessageEvent.Type
Event Type (PluginInfo, PluginError, SimError)
MSFS.PluginMessageEvent.Message
Event Message
This event is emitted when the plugin logs an informative message. This could be an error, warning, or simply informational. These are the same messages as contained in the 'Most recent plugin log messages' State, but arrive individually.
Type - source and severity of the message; Can be one of PluginInfo, PluginError, or SimError.
Message - the message text.
Simulator Connection Change
When simulator connection status changes
Local States
State ID
State Name
MSFS.SimConnectionEvent.Status
Status (disconnected/connecting/connected)
This event is emitted when connection to the simulator changes. Using this event is an alternative to watching the 'The status of SimConnect' State for changes, or using the individual event types in 'Simulator System Event'.
Status - the current simulator connection status, which can be one of disconnected, connecting, or connected.
Touch Portal Device Page Change
When the current page on a Touch Portal device changes
Local States
State ID
State Name
MSFS.PageChangeEvent.PageName
New Page Name
MSFS.PageChangeEvent.PreviousPage
Previous Page Name
MSFS.PageChangeEvent.DeviceName
Device Name
MSFS.PageChangeEvent.DeviceId
Device ID
MSFS.PageChangeEvent.DeviceIP
Device IP Address
This event is emitted when the plugin detects a new page has been loaded on a Touch Portal device. The local states contain the new and previous page names and information about the device, all forwarded from the original Touch Portal notification the plugin received.
New Page Name - Name of the page that was loaded, including the full folder path, if any.
Previous Page Name - Name of the page that was unloaded, including any folder path.
Device Name - Name of the TP device on which the page was loaded.
Device ID - ID of the TP device on which the page was loaded.
Device IP Address - IP Address of the TP device on which the page was loaded.
Request a Selected Simulator Variable.
The list of Sim Vars is imported from MSFS SDK Simulator Variables Docs (may contain errors or omissions). Variables with ":N" in the name require an Index value.
Request an Airplane Local Variable. ** Requires WASimModule for list (otherwise use "Request Named Variable") **
The list of variables is loaded live from the Simulator.The Unit type is usually "number" and will be ignored except in a few specific instances for some 3rd-party models.
Request an "Input Event" Value.
The list of available variables is loaded live from the Simulator. Input Events are a.k.a. 'B' variables and are always model-specific.
Request a Named Variable. ** Using types other than 'A', 'B', or 'L' requires WASimModule. **
'A', 'C', & 'E' types require a Unit type, and for 'L' it is optional (default is 'number'). For SimVars requiring an index, include it in the name after a : (colon), eg. "VARIABLE NAME:1".
This action affects any value previously "selected" with some other action (such as AP settings, frequencies, etc).
Increase
Decrease
Selected Value
Increase
PLUS
Decrease
MINUS
☑
Failures
Toggle Failure -
Electrical
Vacuum
Pitot
Static Port
Hydraulic
Total Brake
Left Brake
Right Brake
Engine 1
Engine 2
Engine 3
Engine 4
Electrical
TOGGLE_ELECTRICAL_FAILURE
Vacuum
TOGGLE_VACUUM_FAILURE
Pitot
TOGGLE_PITOT_BLOCKAGE
Static Port
TOGGLE_STATIC_PORT_BLOCKAGE
Hydraulic
TOGGLE_HYDRAULIC_FAILURE
Total Brake
TOGGLE_TOTAL_BRAKE_FAILURE
Left Brake
TOGGLE_LEFT_BRAKE_FAILURE
Right Brake
TOGGLE_RIGHT_BRAKE_FAILURE
Engine 1
TOGGLE_ENGINE1_FAILURE
Engine 2
TOGGLE_ENGINE2_FAILURE
Engine 3
TOGGLE_ENGINE3_FAILURE
Engine 4
TOGGLE_ENGINE4_FAILURE
Pause - Full
A "full" pause stops the simulation completely, including any time passing in the simulated world. Same as "Dev Mode Pause."
Set Full Pause to [number (0.00 1.00)] (0/1)
PAUSE_SET
Pause - Simulator
A "simulator" pause stops some aspects of the simulation, but not time. Same as the "Menu (ESC) Pause" but w/out the actual menu.
Enable
Disable
Simulator Pause
Enable
PAUSE_ON
Disable
PAUSE_OFF
Simulation Rate Adjust
Increase
Decrease
Select (for +/- adjustment)
Simulation Rate
Increase
SIM_RATE_INCR
Decrease
SIM_RATE_DECR
Select (for +/- adjustment)
SIM_RATE
☑
Simulation Rate Set
Set Simulation Rate to [number (0.00 50000.00)]
SIM_RATE_SET
☑
Connectors
Name
Description
Format
Sim Event Mappings
Simulation Rate Set
Set Simulation Rate
in Value Range: [number] - [number]
SIM_RATE_SET
States
Base Id: MSFSTouchPortalPlugin.SimSystem.State.
Id
SimVar Name
Description
Unit
Format
DefaultValue
AtcId
ATC ID
Aircraft Id used by ATC
string
AircraftTitle
TITLE
Aircraft Title
string
AtcAirline
ATC AIRLINE
Airline used by ATC
string
SimSystemEventData
Data from the most recent Simulator System Event, if any.
string
AtcFlightNumber
ATC FLIGHT NUMBER
Flight Number used by ATC
string
AtcModel
ATC MODEL
Model of aircraft used by ATC
string
SimSystemEvent
Most recent Simulator System Event name.
string
SimPauseState
Simulator Pause State Flag(s) (OFF
FULL
ACTIVE
SIM)
SimVersion
Simulator Version (10/11/12)
number
0
SimulationRate
SIMULATION RATE
The current simulation rate
number
AtcType
ATC TYPE
Type of aircraft used by ATC
string
Events
Name
Details
Simulator System Event
On Simulator Event [ select ]
Connecting - Upon every connection attempt to the Simulator.
Connected - Upon successful connection to the Simulator.
Disconnected - Upon disconnection from the Simulator.
Connection Timed Out - When a connection attempt to the Simulator times out, eg. when sim is not running.
SimConnect Error - When a Simulator (SimConnect) error or warning is detected. Error details (log entry) are sent in the SimSystemEventData state value.
Plugin Error - When a Plugin-specific error or warning is detected (eg. could not parse action data, load a file, etc). Error details (log entry) are sent in the SimSystemEventData state value.
Plugin Information - When a notable plugin informational ("success") action is detected. Information details (log entry) are sent in the SimSystemEventData state value.
Paused - When the flight is paused in any mode.
Unpaused - When the flight is unpaused completely (Pause State if OFF).
Pause Toggled - When any pause mode is toggled or sim is unpaused completely (i.e. the Pause State changes).
Full Pause - "full" Pause (sim + traffic + etc...)
Active Pause - Pause was activated using the "Active Pause" Button.
Simulator Pause - Pause the player sim but traffic, multi, etc... will still run.
Full Pause (FSX Legacy) - FSX Legacy Pause (not used in FS2020)
Flight Started - The simulator is running. Typically the user is actively controlling the aircraft on the ground or in the air. However, in some cases additional pairs of SimStart/SimStop events are sent. For example, when a flight is reset the events that are sent are SimStop, SimStart, SimStop, SimStart.
Flight Stopped - The simulator is not running. Typically the user is loading a flight, navigating the shell or in a dialog.
Flight Toggled - When the flight changes between running and not.
Crashed - When the user aircraft crashes.
Crash Reset - When the crash cut-scene has completed.
Aircraft Loaded - When the aircraft flight dynamics file is changed. These files have a .AIR extension. The filename is sent in the SimSystemEventData state value.
Flight Loaded - When a flight is loaded. Note that when a flight is ended, a default flight is typically loaded, so these events will occur when flights and missions are started and finished. The filename of the flight loaded is sent in the SimSystemEventData state value.
Flight Saved - When a flight is saved correctly. The filename of the flight saved is sent in the SimSystemEventData state value.
Flight Plan Activated - When a new flight plan is activated. The filename of the activated flight plan is sent in the SimSystemEventData state value.
Flight Plan Deactivated - When the active flight plan is de-activated.
Position Changed - When the user changes the position of their aircraft through a dialog or loading a flight.
Sound Toggled - When the master sound switch is changed.
View 3D Cockpit - When the view changes to the 3D virtual cockpit view.
View External - When the view changes to an external view.
Simulator Pause State Change
When the simulator's Pause State changes
Local States
State ID
State Name
MSFS.SimPauseEvent.NewState
New Pause State (numeric)
MSFS.SimPauseEvent.NewStateStr
New Pause State (string)
MSFS.SimPauseEvent.PrevState
Previous Pause State (numeric)
MSFS.SimPauseEvent.PrevStateStr
Previous Pause State (string)
Describes the Pause State of the simulator.
The numeric status is a 4-bit Flag (bit-field) type which may be OR'd together when multiple pause states are active (eg. 'active' and 'sim' = 12 (0xC), or 1100 in binary) .
The string version contains text representations of the bit values, possibly joined with | character when there are multiple set flags (eg. ACTIVE|SIM).
Possible values, numeric and text:
0 (OFF): No Pause
1 (FULL): Full Pause with time (sim + traffic + etc...) (SET_PAUSE 1 / Dev -> Options -> Pause)
2 (FULL_WITH_SOUND): FSX Legacy Pause (not used anymore)
4 (ACTIVE): Pause was activated using the "Active Pause" Button (position/attitude freeze)
8 (SIM): Pause the player sim but traffic, multi, etc., will still run (SET_PAUSE_ON / ESC menu pause)
Simulator System Filename Event
When the simulator sends a system event containing a file name
Local States
State ID
State Name
MSFS.SimFilenameEvent.Type
Event Type (AircraftLoaded/FlightLoaded/FlightSaved/FlightPlanActivated)
MSFS.SimFilenameEvent.Filename
File Name
This event is emitted in response to any simulator system event which has an associated file name, such as when loading aircraft, flights, or flight plans.It has two local states which describe the event and contain the file name.
Using this event is an alternative to the "Simulator System Event" where the file name is delivered as a separate state value (with possible timing issues).
Event Type - Type of simulator system event; Can be one of: AircraftLoaded, FlightLoaded, FlightSaved, or FlightPlanActivated.
File Name - The name of the file being loaded/saved/activated.