Skip to content

Latest commit

 

History

History
239 lines (166 loc) · 16.2 KB

README.md

File metadata and controls

239 lines (166 loc) · 16.2 KB
Raw

MSFS/SimConnect Touch Portal Plugin

Made for Touch POrtal GitHub release (latest by date including pre-releases) Downloads Downloads of latest release License Discord

Overview

This plugin provided tools to build two-way interactive interfaces between Touch Portal macro launcher software and Flight Simulators which use SimConnect, such as Microsoft Flight Simulator 2020 (MSFS) and FS-X. The plugin makes available new Touch Portal Actions, Connectors, States, and Events for creating buttons and pages suitable for virtually any simulated aircraft, component, or system.

This project is a continuation of the original MSFSTouchPortalPlugin by Tim Lewis.

Features

  • Connects to local or remote simulators with SimConnect.
  • Allows getting data variables from simulator at regular intervals, such as flight instrument readings, control surface positions, or switch states.
  • Allows triggering any interactive aircraft event via Touch Portal Actions, such as setting switches, adjusting control surfaces, radio frequencies, and so on.
  • Use Touch Portal "Sliders" to control a value within any range, and/or provide visual feedback to simulator variable changes (eg. a throttle slider can both control the sim throttle and show the actual position when the throttle is moved with mouse/joystick/keyboard).
  • Completely configurable to request any variable or trigger any event supported by the connected simulator, including with custom extensions like MobiFlight.
  • Supports simulator system events (such as "flight loaded" or "sim started") as Touch Portal Events.
  • Set and read model-specific "Input Event" values (new in plugin v1.5 and MSFS SU13).
  • Allows simultaneous usage from multiple networked Touch Portal devices.
  • Optional WASM (Web ASseMbly) module integration allows even greater expansion, with access to many variable types and events/actions not normally accessible via SimConnect alone.
  • Categorized lists of all SimConnect Event IDs and Simulator Variables to choose from, custom imported from MSFS online documentation (exclusive feature!).
  • Integrates live HubHop data for activating thousands of available Input Events provided by the community (requires WASM integration).
  • Separate plugins available for MSFS 2020 and older sims supporting FS-X versions of SimConnect.

Editions

There are two separate plugins available here, one for MSFS 2020 (and eventually 2024), and another for "legacy" sims like FSX, which should work with any sim which supports the older SimConnect SDK.

  • The "MSFS" edition is recommended for use with MSFS 2020 since it provides features specific to this version (like setting 'L' vars and WASM integration).
  • The "FSX" edition will connect to FSX Deluxe SP2 or newer simulators (including Steam and Acceleration editions). This also includes MSFS 2020, but will not support certain features like WASM and HubHop integration or setting multiple SimConnect Event values.
  • The two plugin editions are completely separate and can be installed and run in Touch Portal at the same time.
  • Pages and buttons made for one edition will not work in the other (because they're separate plugins as far as TP is concerned).

Installation

Note: As with all plugins, this requires the Touch Portal Pro (paid) version to function. Use the latest available Touch Portal version for best results.

  1. Get the latest release of this plugin(s) you want to install from the Releases page.
  2. The plugins are distributed and installed as a standard Touch Portal .tpp plugin files. If you know how to import a plugin, just do that and skip to step 4.
  3. Import the plugin:
    1. Start/open Touch Portal.
    2. Click the Settings "gear" icon at the top-right and select "Import plugin..." from the menu.
    3. Browse to where you downloaded this plugin's .tpp file and select it.
    4. When prompted by Touch Portal to trust the plugin startup script, select "Trust Always" or "Yes" (the source code is public!).
      • "Trust Always" will automatically start the plugin each time Touch Portal starts.
      • "Yes" will start the plugin this time and then prompt again each time Touch Portal starts.
      • If you select "No" then you can still start the plugin manually from Touch Portal's Settings -> Plug-ins dialog.
  4. By default the plugin will not attempt to connect to a flight simulator on startup. You have two options:
    1. Recommended: Create/import a Touch Portal button which triggers the "MSFS - Plugin - Connect & Update -> Toggle Simulator Connection" action. (Also a good place to show the current connection status.)
    2. Change the plugin's settings: Click the Touch Portal "gear" icon at top right of the main screen, then navigate to Settings -> Plugins -> "MSFS Touch Portal Plugin". Set the "Connect To Flight Sim on Startup" setting to a value of 1 (one) and save the settings. The plugin will keep attempting to connect to the simulator every 30 seconds.

Optional WASM Module (only for MSFS 2020 on PC)

  1. The optional WASimModule MSFS component is highly recommended as a companion to this plugin. It it not required to use most of the basic plugin features, but it will provide a more advanced feature set (such as access to local "L" variables and HubHop Input Events) and further optimizations.
    1. Download the WASimModule .zip file from the same published Release as the plugin.
    2. Extract the contents into your MSFS Community folder (so that the folder wasimcommander-module is directly inside the Community folder).
    3. If already running, MSFS would need to be restarted after adding the module.

Updates

The plugin can be updated to a new version by following the same installation procedure described above. It is not necessary to remove any previous version first. The only thing to be aware of is that any old plugin log files will be removed during the update process.

Installation Guides

Keep in mind that while guides can be helpful as an overview and to get started, they do get outdated and also may not cover all that is possible to do or configure.

Documentation

See the Wiki for guides, tips, and example pages and buttons to get started with

Auto-generated documentation on all actions, connectors, events, settings, and default included states can be found in DOCUMENTATION.md.

Pages and Examples

Check out the Pages, Buttons, & Graphics for examples to get started with.

The list of known pages has also moved to the Wiki: List of Published Touch Portal Pages for MSFS Plugin

Troubleshooting

The plugin logs errors and warnings to a plain-text file. 7 days worth of logs are kept by default (a new file is started for each day). The log files are located within the plugin's installation folder, which is in Touch Portal's configuration directory:
C:\Users\<User_Name>\AppData\Roaming\TouchPortal\plugins\MSFS-TouchPortal-Plugin\logs folder, where <User_Name> is your Windows user name.

If something isn't working as expected, check the log.

Another way to quickly see latest log entries is by using the provided TP States and displaying them in a button area.

  • MSFS - Plugin -> Most recent plugin log messages (MSFSTouchPortalPlugin.Plugin.State.LogMessages) - Shows the last dozen logged messages. Give this one a good size "button" (eg. cell size 4x3 or so).
  • MSFS - System -> Data from most recent Simulator System Event (MSFSTouchPortalPlugin.SimSystem.State.SimSystemEventData) - Shows one line of text from the last significant "simulator event." In case an error or warning is logged, the log entry with the error should show here.

You could also monitor the MSFS - System -> Simulator System Event for the Plugin Error and/or SimConnect Error events. For example you could have a button light up red when this event happens, so you can know to go check the log.

Here's a Windows PowerShell command to show the last 20 entries from the current day's log file:

Get-Content -Tail 20 $Env:APPDATA\TouchPortal\plugins\MSFS-TouchPortal-Plugin\logs\MSFSTouchPortalPlugin$(Get-Date -format 'yyyyMMdd').log

Support and Discussion

Please use the GitHub Issues pages for bug reports and concise feature requests. Use the Discussions pages for general conversation on any related topic like suggestions or support questions.

There is also a Discord support forum on my server, an announcements channel, and discussion rooms on my server channel #msfs-general and at Touch Portal's Discord server channel #msfs2020

Update Notifications

The latest version of this software is always published on the GitHub Releases page.

You have several options for getting automatically notified about new releases:

  • If you have a GitHub account, just open the Watch menu of this repo in the top right of this page, then go to Custom and select the Releases option, then hit Apply button.
  • The plugin and updates are published on Flightsim.to where one could "subscribe" to release notifications (account required).
  • If you use Discord, subscribe to notifications on my server channel #msfs-plugin.
  • If you already use an RSS/Atom feed reader, just subscribe to the feed URL.
  • Use an RSS/Atom feed notification service, either one specific for GitHub or a generic one, such as (a list of services I found, I haven't necessarily tried nor do I endorse any of these):

Related Plugin(s)

My TJoy Touch Portal Plugin is an interface between Touch Portal and several virtual joystick/game pad emulation drivers like vJoy, vXBox, and ViGEm Bus.

My Dynamic Script Engine Plugin is a great companion for anything from custom data formatting and math operations to a full-blown scripting using JavaScript.

TouchPortal-Dynamic-Icons can be used to create a wide variety of dynamic images and animations, from basic shapes and styled text to beautiful multi-layered gauges animated in real-time based on Simulator data.

References

Credits

Currently maintained by Maxim Paperno at https://github.com/mpaperno/MSFSTouchPortalPlugin ; see copyright and licensing details below.

Originally created by Tim Lewis at https://github.com/tlewis17/MSFSTouchPortalPlugin and published under the MIT License.

Uses components of the WASimCommander project under terms of the GNU Public License v3 (GPLv3).

Uses tools and data from MSFS Tools project under terms of the GNU Public License v3 (GPLv3).

Uses the Touch Portal C# and .NET API library, under terms of the MIT License.

Uses a modified version of SharpConfig library, under terms of the MIT License. Change log is included in this repo alongside the library files.

Uses the Microsoft SimConnect SDK under the terms of the MS Flight Simulator SDK EULA (11/2019) document.

Uses several publicly available Microsoft .NET component libraries under the MIT License.

Uses the Newtonsoft Json.NET library under terms of the MIT License.

Uses Serilog Logging Extensions components under terms of the Apache-2.0 License.

Uses the SQLite-net library from Krueger Systems, Inc. under terms of the MIT License.

Copyright, License, and Disclaimer

MSFSTouchPortalPlugin Project
Copyright (c) 2020 Tim Lewis;
Copyright Maxim Paperno, all rights reserved;
Copyright MSFSTouchPortalPlugin Project Contributors

This program and associated files may be used under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included in this repository and is also available at http://www.gnu.org/licenses/.

This project may also use 3rd-party Open Source software under the terms of their respective licenses. The copyright notice above does not apply to any 3rd-party components used within.