NOTE: |
---|
The fsmapper User's Guide is available here. Please refer to this guide for instructions on how to use fsmapper |
fsmapper is a Windows application designed to connect a variety of input and output devices to flight simulators.
Originally, the development of fsmapper began to connect my DIY controller device, SimHID G1000, to Microsoft Flight Simulator 2020. However, it has now evolved to encompass functionalities that allow the creation of a home cockpit using a wide range of devices.
fsmapper targets not only home cockpit builders aiming for an exact replica of a specific aircraft's cockpit,
but also general flight simulator players who have limited equipment and space but want to efficiently operate a wide range of aircraft
(The truth is, I fall into the latter category as well).
Although fsmapper offers a multitude of functions, it can be summarized into following three main aspects when viewed from the perspective of improving device and space utilization efficiency, as mentioned earlier.
-
Interaction between devices and Flight Simulators
You can reflect the operation of various devices, including custom-made ones, in the operation of various cockpit systems within the flight simulator. Conversely, you can also retrieve the state of instruments and the position of switches in the flight simulator and reflect them on physical devices. Currently, the only simulator that can be perfectly integrated is the Microsoft Flight Simulator series, which supports SimConnect. However, I'm also working on implementing features for integration with the DCS World. -
Changes to Input Device Characteristics
You can flexibly modify the characteristics and behaviors of input devices, such as altering the linearity of analog axes, changing polarity for alternate switch, generating events that account for the position and hysteresis of analog axes, and so on. This allows for consistent handling of the same throttle device across aircraft with and without afterburners, or enables adjustments for actions like fuel cut-off and thrust reversal. -
Virtual instrument panel utilizing Touchscreen Monitors
In a multi-monitor environment, you can construct virtual instrument panels on the screen. Particularly when using a touchscreen monitor, intuitive actions like tapping or flicking can be used to manipulate switches and knobs displayed on the screen. By configuring popped-out windows, such as the PFD, as elements of the virtual instrument panel, you can effectively build a glass cockpit.
fsmapper excels in handling pop-out windows, allowing you to hide title bars and window frames to seamlessly integrate them as part of the instrument panel. It also provides a workaround for the well-known issue where pop-out windows in MSFS2020 cannot be touch-operated.
If you watch this video, you'll get a better understanding of what can be achieved with fsmapper as described above.
In this video, A320's virtual instrument panels are assembled on a 10.5-inch touchscreen by combining six popup windows
(FCU, PFD, ND, ECAM x 2, MCDU) and user-defined instruments and switches.
Additionally, by dynamically switching and displaying the instrument panels,
it enables diverse information representation and manipulation even on a small screen.
All the functionalities mentioned earlier are accessed through Lua 5.4 scripts. Although fsmapper is implemented as a Windows GUI application, it actually only features a dashboard to display operational status and a console function to show messages during script execution, particularly error messages. If there wasn't a necessity to allow users to select pop-out windows in Microsoft Flight Simulator 2020, I believe it would have been implemented as a command-line interface (CLI).
The diagram above illustrates how fsmapper works. fsmapper patiently waits for events (green arrows) such as operations from various input devices, touchscreen interactions, and changes in the aircraft's status within a flight simulator. Upon detecting an event, fsmapper executes the corresponding action. These actions are Lua function objects that allow interaction (orange arrows) with various objects such as aircraft controls within a flight simulator, graphical representation on the screen, and data output to devices, facilitated through Lua functions and Lua objects provided by fsmapper.
The 'Configuration File' specified by the user during fsmapper execution refers to the definition of the correspondence between these events and actions as a Lua script.
It’s easier to download and install the pre-compiled package from here.
However, you can also build it yourself by follow the steps below.
-
Requirements
Make sure that the following softwares are installed in advance.- Visual Studio 2022 whilch is instaled with folowing workloads:
- Universal Windows Platform development
- C++ desktop development
- C++ game development
- Flight Simulator 2020 SDK
- nuget.exe should be placed at the folder which is indicated by PATH environment variable.
- Visual Studio 2022 whilch is instaled with folowing workloads:
-
Running a console
Runcmd.exe
orPowerShell.exe
on any console. Note that environment variables must be set to complie x64 binaries.
The one of easiest way is using the following shortcut made when Visual Studio was installed.- x64 Native Tools Command Prompt for VS 2022
-
Downloading source codes
$ git clone --recursive https://github.com/opiopan/fsmapper.git
-
Preparing dependent modules
Downloading and compiling Lua source codes and downloading vJoySDK will be done by following step.$ cd fsmapper\modules $ .\prepare_modules.bat
-
Compiling
$ cd ..\src $ nuget restore fsmapper.sln $ msbuild /p:Configuration=Release
-
Making deployable package
$ cd ..\deploy $ .\deploy.bat
-
Installing
Copy fsmmapper folder to any folder you want.$ xcopy fsmapper <DESTINATION_FOLDER_PATH>
While not mandatory for running fsmapper, it's highly recommended to additionally install the following two pieces of software. fsmapper provides users with more convenient features by integrating with these softwares.
-
vJoy (Dwonload)
vJoy is a device driver that functions as a virtual joystick. fsmapper offers multiple functions to alter button status, axis positions, and POV settings of the vJoy device.
Through the use of the vJoy device, fsmapper provides highly flexible configurability for human interface devices. -
MobiFlight WASM Module (GitHub)
This WASM module, functioning as an add-on for FS2020, enables an external-process utility to execute arbitrary RPN script and monitor changes in the aircraft's internal state stored in local variables like LVARs. fsmapper gains unrestricted access to retrieve and modify aircraft states by communicating with the MobiFlight WASM Module operating within the FS2020 process.
The easiest way to install the MobiFlight WASM Module is by downloading and installing the MobiFlight Connector from here.The vanilla fsmapper communicates with FS2020 through the SimConnect API, which allows an external process to access only SimVars and Event IDs. However, this access isn't sufficient to control all operable objects in a cockpit or retrieve all gauge statuses to display on another DIY gauge or virtual instrument panel.
To control and access all cockpit gauges, accessing local variables within an aircraft module is necessary, and the Gauge API serves this purpose. Regrettably, this API can only be used within the WASM module.
The MobiFlight WASM Module addresses this limitation, enabling fsmapper to access all local variables by communicating with this WASM module.
Please refer the Tutrial and the Configuration Guide.
fsmapper only supports Direct Input gaming devices and SimHID devices, but it provides a plugin API to support other devices.
A sample code of a simple plugin module and an example Lua script for its usage are prepared, so please refer to it.
The plugin DLL can be utilized by placing it in a folder named plugins
under the folder where fsmapper.exe is located, or by placing it in the folder specified in the settings page.
Note that the sample code above will result in compilation errors in this location. The include
folder and libraries referenced by this sample will be correctly placed via the deploy.bat
script.
In other words, building the sample module included in this installation package here is straightforward.
This repository includes several configuration scritps for practical use of SimHID G1000 at here.
To use these scripts, vJoy driver and MobiFlight WASM module must be installed. In addition, it's assumed that the virtual serial Port for SimHID G1000 is recognaized as COM3 and the display for SimHID G1000 is secondary monitor (moniter No. is 2).
If your environment is not same, change config
table defined at the top of each script as below according to your environment.
local config = {
simhid_g1000_identifier = {path = "COM3"},
simhid_g1000_display = 2,
}
Alternatively, you can define the override_config
global variable in the Pre-run script of fsmapper's Settings page to override the contents of the config
variable without directly modifying the script.
This method also supports those who do not own the SimHID G1000 but want to try the operation of the virtual instrument panel.
Here is an example of a script to specify in the Pre-run script.
override_config = {
simhid_g1000_display = 1,
simhid_g1000_display_scale = 0.5,
simhid_g1000_mock = true,
simhid_g1000_mock_proxy = {
type = 'dinput',
identifier = {name = 'your_device_name_here'},
aux_up = 'button1',
aux_down = 'button2',
aux_push = 'button3',
},
}
Please replace placeholders like "your_device_name_here" and specific button names with appropriate values for your setup. This script will override the configuration variables accordingly when fsmapper is launched.
Here is the meaning of each parameter.
Parameter | Description |
---|---|
simhid_g1000_display |
Specify the display number for showing the virtual instrument panel. This display should ideally be a touchscreen, but it can also be operated using a mouse. |
simhid_g1000_display_scale |
Specify the size of the virtual instrument panel display. Use 1 to use the entire screen. |
simhid_g1000_mock |
If you are not using SimHID G1000 or do not own it at all, specify true . |
simhid_g1000_mock_proxy |
The following sample scripts allow you to operate multiple virtual instrument panels by switching between them. This switching operation is assigned to the left and right AUX switches of SimHID G1000. If you are not using SimHID G1000, you can assign the switching operation to another device using this parameter. Specify the device to use for this purpose in the identifier parameter. Refer to this guide for descriptions of the identifier parameters corresponding to the devices you own.Specify which buttons of the device identified by identifier to use for switching virtual instrument panels using aux_up , aux_down , and aux_push parameters. |
NOTE: More complex scripts can be found in this repository. I actually use the scripts stored in that repository, and the way how to switch the configuration correspond to current aircraft can be found in those scripts.
This script can be used with all aircrafts which install Garmin G1000.
This script handles two poped out windows as captured windows, one is the PFD of G1000 and the other one is the MFD of G1000.
The contents displayed on the monitor of SimHID G1000 can be switched between the PFD and the MFD by operationg the switches placed at the right end of the SimHID G1000 housing and left end one.
All buttons and knobs of the SimHID G1000 are work for every displayed contents. For example, pushing the "menu" button cause displaying the menu on the PFD when the monitor of SimHID G1000 shows the PFD.
In this script, you can see the following example usage of fsmapper.
- Basic eveent handling for SimHID device
- Cockpit operable utits of a FS2020 aircraft by sending Event IDs
- Poped out window of FS2020 handling (captured window function)
- Switchable views
This script is added some codes to the aboeve script.
The deference between both scripts is only the part to handle logicool X56.
In this script, you can see the following example usage of fsmapper.
- Basic event handling for USB gaming controller
- Feeding values to vJoy device
- Deferred event handling
This script was written for FlyByWire A32NX.
This is more complex than the above two scripts. This script provides the integrated virtual cockpit which contains physical operable units such as buttons and knobs, touch controllable units on the monitor, and poped out window contents such as PFD.
This script includes several sub-module scripts at here, and it also uses several bitmap image at here to render each operable units.
In this scrit, you can see the following example usage of fsmapper in addition to g1000_x56.lua
case.
- Observing the aircraft status represented by RPN script
- Changing the aircraft status by executing RPN script
- Drawing graphics on the screen
- Handling the touch events and mouse events occured on the screen
This script defines following 6 views. Every view consist a FS2020 poped out instrument window and self rendered operable gauges.
Poped out instruments | Self rendered operable units | |
---|---|---|
1 | PFD | FCU display buttons on the FCU BARO indicator |
2 | ND | buttons and toggle switches on the EFIS control unit auto brake buttons etc |
3 | Upper ECAM | engine mode selectors, master engine switch and engine status indicators APU control switches battery control switches and voltage indicators |
4 | Lower ECAM | ECAM page selector buttons |
5 | MCDU | MCDU buttons |
6 | EFB | - |
The width of every view except EFB is a half width of the SimHID monitor width. So two views can be displayed simultaneously side by side.
By pressing soft-keys placed at bottom of SimHID G1000, two views to show can be specified.
And the switches placed on the left end and the right end of SimHID G1000 housing (AUX switches) can also control views to show.
When you operate the AUX switch up or down, it will sequentially switch between three preset left-right view combinations.
Pressing the AUX switch toggles between EFB display mode and other instrument display modes.
The pushbuttons rendered on each view can be operated by tapping them. The toggle switches include engine master switches and the selector knobs can be operated by flicking them. The correspondence between SimHID G1000 operations and A32NX operations are shown below.
SimHID G1000 | A32NX |
---|---|
NAV volume knob | SPD/Mac knob on FCU The pull operation is emulated by a long press |
NAV swap button | Pulling Speed Knob on FUC |
HDG knob | HDG/TRK knob on FCU The pull operation is emulated by a long press |
HDG button | Pulling HDG/TRK knob on FCU |
AP button | AP1 button on FCU |
FD button | FD button on EFIS |
APR button | APPR button on FCU |
ALT outer knob | Increase / Decrease altitute indicator on FCU by 1000 feet |
ALT inner knob | Increase / Decrease altitute indicator on FCU by 100 feet |
ALT knob push button | Pushing ALT knob on FCU The pull operation is emulated by a long press |
FLC button | Pulling ALT knob on FCU |
COM volume knob | V/S or FPA knob on FCU The pull operation is emulated by a long press |
COM swap button | Pulling V/S or FPA knob on FCU |
COM knob | Freequency selector knob on RMP panel |
BARO knob rotation | Manipuration of the value displayed in the barometer reference window |
BARO knob push button | Switching barometer reference mode between QNH and standard barometer reference |
Range knob rotation | Range selector switch on EFIS |
Range knob joystick | Changing the mode displayed on the respective ND |
NAV inner knob | Adjusting the brightness of PFD, ND, upper ECAM, and lower ECAM in sync |
NAV outer knob | Adjusting the brightness of both the weather rader image and the EGPWS terrain image on ND |
FMS inner knob | Adjusting the brightness of FCU display |
FMS outer knob | Adjusting the brightness of all glareshields in sync |
This script was written for Cessna 172 Skyhawk analogue instruments version that contains in delux edition.
This is the example how to implement reusable visual component.
The following instruments are implemented as a component and each component written as one lua script at here.
- Garmin GNS530 (GPS and NAVCOM)
- Garmin GNS430 (GPS and NAVCOM)
- Bendix King KAP 140 (Autopilot Control)
- Bendix King KT 76C (Transponder)
- Bendix King KR 87 (ADF)
- Heading Indicator with Heading Bug
- Cource Diviation Indicator
- ADF Indicator
- Buttons and Indicators whch is used to select navigation source (Sorry, I don't know the model name or official name)
This script defines three views.
The above components are placed in different positions, different sizes, and different combinations on each view.
You can switch between these views with the switches placed on the left end and the right end of SimHID G1000 housing.
Almost component can be activated with tapping it. Component in active state can be distinguished by some areas turning emerald green.
A part of phisical buttons and knobs on SimHID G1000 will only affect component in active state.
For example, Course of CDI for NAV1 can be changed by rotationg course knob on SimHID G1000 only when CDI for NAV1 is activated.
Other various components can be found at here.