See CHANGELOG.md

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.2.0 - 2024-07-07
+
+### Changed
+
+- Make log messages on master tag more helpful for debugging
+- Handle the speed of data processing more consistently. The maximum speed for \<sequence\> tags is your MSFS fps divided by 2
+- Clarify instructions on testing the \<master\> tag
+- Insert a lot of comments into several files
+- Improve the instructions on testing the SHIFT indicator
+- Make it possible to compile .cpp files individually by better arranging dependencies between them
+
+### Added
+
+- Print helpful error message when application is terminated with an error
+- Enforce the presence of switch_dataref and brightness_dataref tags in the \<master\> tag
+- Clear the LED colors and MFD text on start to reset settings made by other applications, particularly the Saitek driver
+- Control joystick LEDs with \<indicators\> tag and define blinking patterns with \<sequences\> tag
+- Add calculator code to XML configuration files. WASimCommander module must be installed in MSFS
+- Use Saitek driver instead of cmd_handler.lua to change joystick LED colors and write text to MFD
+- New --mfddelayms command line parameter to avoid garbled characters on the MFD
+
 ## 0.1.1 - 2024-06-23
 
 ### Changed

README.md

@@ -16,6 +16,8 @@ Follow the install instructions of X52LuaOut for Windows (see PDF among the extr
 
 Download the latest x52msfsout Release from the right hand side of this page and copy the .exe file into `the folder where you extracted X52LuaOut.zip/x52LuaOut/internals` or `the folder of X-Plane.exe\Resources\plugins\FlyWithLua\Scripts\x52LuaOut\internals\`.
 
+Download [WASimModule-v1.2.0.0.zip](https://github.com/mpaperno/WASimCommander/releases/download/1.2.0.0/WASimModule-v1.2.0.0.zip), extract it and copy the `wasimcommander-module` folder to your MSFS [community folder](https://docs.flightsimulator.com/html/Introduction/#community). This module is needed to do special things in MSFS like executing calculator code. It is similar to FSUIPC, but it is free.
+
 # XML configuration files
 
 After installation, you have to prepare XML configuration file(s). They determine how your joystick will react to events in MSFS  (including shifted buttons and Mode 1-3). You can define your own MFD pages, LED states with custom blinking patterns, etc. The included `default.xml` file has example configurations for all tags which are currently supported.
@@ -33,12 +35,17 @@ In the included `default.xml` file you can find example configuration for all ta
 - [x] \<shift_states\> fully supported.
 
 - [ ] \<assignments\>, clear_all attribute not supported. Not all types of \<button\> tags are supported inside \<assignments\>:
-  - [x] \<button type="trigger_pos"\> fully supported. Can handle dataref (SimVar in MSFS), and command (inputevent in MSFS).
+  - [x] \<button type="trigger_pos"\> fully supported. Can handle dataref (SimVar in MSFS), command (inputevent in MSFS), and MSFS calculator code.
   - [x] \<shifted_button\> fully supported with dataref and command attributes.
   - [ ] \<button type="trigger_neg"\>
   - [ ] \<button type="hold"\>
   - [ ] \<button type="toggle"\>
   - [ ] \<button type="repeater"\>
+- [x] \<sequences\> fully supported.
+- [x] \<indicators\> fully supported.
+  - [x] \<led\> fully supported.
+    - [x] \<state\> fully supported, except index attribute not needed, because it is included in dataref name.
+- [ ] \<mfd\> support is planned.
 
 ## Differences between X-Plane datarefs and MSFS SimVars
 
@@ -65,6 +72,18 @@ You use InputEvents in command attributes. They command the plane to do somethin
 
 To find available InputEvents for a given aircraft, enable Development mode in MSFS in Options → General Options → Developers. During a flight, from the top Devmode menu select Tools → Behaviors. At the top of the page select AIRCRAFTNAME_INTERIOR.XML (for example CESSNA152_INTERIOR.XML) from the dropdown. Then on the InputEvents tab you can drill down into several event groups. At the lowest level everything written in light blue are InputEvent names, like ELEV_TRIM_UP or ELEVATOR_TRIM_SET. Find the documentation of the Behaviors tool [on this page](https://docs.flightsimulator.com/html/Developer_Mode/Menus/Tools/Behaviors_Debug.htm).
 
+## What is calculator code?
+
+This is a very powerful new feature, specific to MSFS, only available in x52msfsout. Calculator codes are small "scripts" which can read, manipulate, modify simulator values. They are written in [RPN notation](https://docs.flightsimulator.com/html/Additional_Information/Reverse_Polish_Notation.htm). They are normally used in MSFS XML configuration files but with x52msfsout and the WASimCommander module you can use it with your X52 Pro.
+
+Currently you can use the `calculator_code` attribute in \<button\> tags.
+
+Make sure to replace > with \&gt; and < with \&lt; in calculator code.
+
+There is a page called [HubHop](https://hubhop.mobiflight.com/presets/) where you can find a lot of RPN example code for your calculator code scripts.
+
+Here is [another useful page](https://github.com/MobiFlight/MobiFlight-Connector/wiki/MSFS2020-RPN-Tips-and-Tricks) which has various RPN examples for different simulator situations.
+
 ## Joystick button numbers in MSFS
 
 X52 Pro has 39 buttons. MSFS recognizes all buttons but SimConnect gives an error for buttons above 32. This bug has been reported [on the developer forum](https://devsupport.flightsimulator.com/t/7708). So currently you cannot use buttons above 32 in x52msfsout.
@@ -93,12 +112,15 @@ x52msfsout has command line options:
 - `xmlconfig` Mandatory! Tells the program which XML config file to use (you can have different files for different aircrafts). The XML files are not opened automatically based on the aircraft’s name like in X52LuaOut.
 - `joystick` is an integer number which is the ID of your X52 joystick in MSFS. MSFS does not provide a way to find out your joystick’s ID automatically. This number can change depending on how many peripherals you have connected. Start with 0 and then go up from there until your button presses are registered in `x52msfsout_log.txt`.
 
+# Contributing
+
+Since I’m not very experienced in Lua or C++, your help is much appreciated. The task is to rewrite the X52LuaOut script (written in Lua) into C++ using SimConnect and WASimCommander. The good news is the program’s skeleton is ready. You don’t have to start from scratch. The aim is to support X52LuaOut XML config files with minimal modifications.
 
 ## Development environment
 
 The project was created using Visual Studio 2022.
 
-To compile it yourself, you will need the SimConnect SDK, the [fmt lib](https://github.com/fmtlib/fmt/), and the Boost headers. If you need help setting up your dev environment, open an Issue and I can hopefully help.
+To compile it yourself, you will need the SimConnect SDK, the [fmt lib](https://github.com/fmtlib/fmt/), the [WASimCommander_SDK-v1.2.0.0](https://github.com/mpaperno/WASimCommander/) and the Boost headers. If you need help setting up your dev environment, open an Issue and I can hopefully help.
 
 ## Architecture
 
@@ -111,6 +133,7 @@ This program is a rewrite of only the X52LuaOut script for FlyWithLua. But X52Lu
 - Only 32 joystick buttons are supported instead of 39. Bug reported.
 - The MFD Shift indicator is constantly on.
 - At some exit statements the cmd_handler is not closed.
+- Future improvement: Execute calculator code „as either a data request or a registered event” as suggested [here](https://wasimcommander.max.paperno.us/class_w_a_sim_commander_1_1_client_1_1_w_a_sim_client.html#a289fcb4566f6f44714412e8e27bbd361).
 - Nice to have: MapClientEventToSimEvent does not allow re-use of Event IDs. Workaround already implemented. Bug reported.
 
 # Online presence

Testing.md

@@ -7,15 +7,20 @@
 - Load a flight with C152 at a parking spot.
 - Open Devmode -> Tools -> SimConnect Inspector.
 - Start x52msfsout.
-- Battery Master switch ON should switch LEDs on
-- Dome light should change MFD brightness
+- Battery Master switch ON. LEDs and MFD should stay off, because currently their brightness is zero.
+- Dome light should change the brightness of the MFD, the Mode LED, the pov LED, and the blinking d LED.
+- LED's brightness should be 50% when dome light is at maximum.
 - When Battery Master switch is switched off, MFD and LEDs should switch off and MFD texts should be cleared.
-- Pressing Pinkie button should write ‘mode1_shiftStick’ into x52msfsout_log.txt. If it does not happen, make sure you use the correct number for the --joystick parameter.
+- Pressing Pinkie button should write ‘mode1_shiftStick’ into x52msfsout_log.txt. If it does not happen, make sure you use the correct number for the --joystick parameter. Another reason can be that you have not opened „USB game controllers”.
 
-- Moving the Mode Wheel should write New shift state: mode1, 2, 3 into logfile
+- Moving the Mode Wheel to 2 should write only "Joy Button 29 was pressed" into logfile without "New shift state". Also, the SHIFT indicator on the MFD should switch off.
+- Moving the Mode Wheel to 3 should write New shift state: mode3 into logfile, and the SHIFT indicator on the MFD should switch on.
 - Throttle scrollwheel down should move elevator trim nose down. This is done using an InputEvent.
 - Throttle scrollwheel up should move elevator trim nose up. This is done using an InputEvent.
+- Throttle scrollwheel up (or down) in Mode 1 with Pinkie button should move elevator trim nose up (or down) in big increments. This is done using calculator code.
 - Throttle scrollwheel press should reset elevator trim to middle position. This is done by setting a SimVar to a value.
+- Led D on the throttle should be flashing red twice quickly, because parking brake is set.
+- Disengaging parking brake with the mouse should flash Led D 4 times in amber, then flashing should stop.
 - Throttle scrollwheel press in Mode 1 with Pinkie shift should toggle parking brakes on. This is done using an InputEvent.
 - SimConnect Inspector must show no exceptions for "x52 msfs out client", except
   - one ClearDataDefinition EXCEPTION_UNRECOGNIZED_ID

default.xml

@@ -1,20 +1,34 @@
+<!--
+The master tag contains target tags which control the brightness of leds and mfd.
+All tags and attributes below are mandatory. Copy this example and change the attribute values as you like.
+Default is given in percentage 0-100.
+If default is not 100 then brightness will move between 0% and default percent.
+-->
   <master>
-    <target id="mfd" default="70" switch_dataref="ELECTRICAL MASTER BATTERY%Bool" op="==1" index="0" brightness_dataref="LIGHT GLARESHIELD:1%number" min="0" max="1">
+    <target id="mfd" default="100" switch_dataref="ELECTRICAL MASTER BATTERY%Bool" op="==1" brightness_dataref="LIGHT GLARESHIELD:1%number" min="0" max="100">
 	</target>
-    <target id="led" default="70" switch_dataref="ELECTRICAL MASTER BATTERY%Bool" op="==1" brightness_dataref="LIGHT PANEL POWER SETTING%Percent" min="0" max="1">
+    <target id="led" default="50" switch_dataref="ELECTRICAL MASTER BATTERY%Bool" op="==1" brightness_dataref="LIGHT GLARESHIELD:1%number" min="0" max="100">
 	</target>
   </master>
+<!--
+The shift_states tag defines that when certain combination of joystick buttons is pressed then it activates a "shift" state which has a name.
+Joystick buttons can have a certain function in "non-shift" mode and a different function in each shift state.
+These shift states can be referenced in shifted_button tags inside button tags.
+Button tags themselves can appear inside assignment, page, and row tags.
+-->
   <shift_states>
     <shift_state name="mode1" button="28">
       <shift_state name="mode1_shiftStick" button="6"></shift_state>
     </shift_state>
-    <shift_state name="mode2" button="29">
-      <shift_state name="mode2_shiftStick" button="6"></shift_state>
-    </shift_state>
     <shift_state name="mode3" button="30">
       <shift_state name="mode3_shiftStick" button="6"></shift_state>
     </shift_state>
   </shift_states>
+<!--
+The assignments tag contains button tags which define what will a joystick button do in MSFS. This is already possible to do in MSFS,
+but assignments have much more functionality, like executing calculator code or repeating a command.
+Assignments is a mandatory tag, so you should have at least <assignments></assignments> in your XML file.
+-->
   <assignments clear_all="false">
     <!-- Throttle wheel press resets the elevator trim to zero -->
     <!-- This sets the value of a SimVar (dataref) to a constant value. -->
@@ -25,8 +39,58 @@
     <!-- Elevator trim one step Nose up -->
     <!-- This triggers an Input (Key) Event (command). -->
     <button nr="18" command="ELEV_TRIM_UP" type="trigger_pos" >
+      <!-- Move elevator trim up a bigger step. This is done by adding 0.005 radians to the trim position using calculator code written in RPN notation. -->
+      <shifted_button shift_state="mode1_shiftStick" calculator_code="(A:ELEVATOR TRIM POSITION, Radians) 0.005 + (&gt;A:ELEVATOR TRIM POSITION, Radians)" ></shifted_button>
     </button>
     <!-- Elevator trim one step Nose down -->
     <!-- This triggers an Input (Key) Event (command). -->
-    <button nr="17" command="ELEV_TRIM_DN" type="trigger_pos" />
-</assignments>
+    <button nr="17" command="ELEV_TRIM_DN" type="trigger_pos" >
+      <!-- Move elevator trim down a bigger step. This is done by subtracting 0.005 radians from the trim position using calculator code written in RPN notation. -->
+      <shifted_button shift_state="mode1_shiftStick" calculator_code="(A:ELEVATOR TRIM POSITION, Radians) 0.005 - (&gt;A:ELEVATOR TRIM POSITION, Radians)" ></shifted_button>
+    </button>
+  </assignments>
+<!--
+The indicators tag contains led tags with nested state tags. They define what will a joystick led indicate when a value changes in MSFS.
+The dataref attribute of every state tag is evaluated and if true the led is set to the given light value (on or off, or a color, or a blinking sequence).
+Be aware that you cannot control the color of the led on the silver POV hat and the led next to the Mode wheel. You can only control their brightness via the <master> tag. If the <target id=led> is on then these two leds remain on. Unlike other leds, you cannot switch them off selectively.
+-->
+  <indicators>
+    <!--
+    SimVar FLAPS HANDLE PERCENT possible values
+    0.0122 = Flaps up - T1 led off
+    33.345 = Flaps 1 - T1 led green
+    66.672 = Flaps 2 - T1 led amber
+    99.672 = Flaps 3 - T1 led red
+    Innermost state is evaluated first. If that is true, other states are discarded. If false, the state above it will be evaluated.
+    -->
+    <led id="t1">
+      <state light="off" dataref="FLAPS HANDLE PERCENT%percent" op="--5">
+        <state light="green" dataref="FLAPS HANDLE PERCENT%percent" op="++30">
+          <state light="amber" dataref="FLAPS HANDLE PERCENT%percent" op="++60">
+            <state light="red" dataref="FLAPS HANDLE PERCENT%percent" op="++98">
+            </state>
+          </state>
+        </state>
+      </state>
+    </led>
+    <!--
+    SimVar BRAKE PARKING POSITION possible values
+    0 = Brake off - D led flashes amber 4 times then stops
+    100 = Brake applied - D led flashes red twice indefinitely
+    This is a test of a (flashing) sequence.
+    -->
+    <led id="d">
+      <state light="amber_four_times" dataref="BRAKE PARKING POSITION%percent" op="--5">
+        <state light="red_dbl_short" dataref="BRAKE PARKING POSITION%percent" op="++5"/>
+      </state>
+    </led>
+  </indicators>
+<!--
+The sequences tag contains sequence tags which define named blinking sequences.
+The "speed" means that one character in the "pattern" is equivalent to 1/speed seconds of time.
+Do not set "speed" higher than half of your fps in MSFS. This is the fastest "speed" x52msfsout can handle without delay.
+-->
+  <sequences>
+    <sequence name="red_dbl_short" pattern="r  r           " speed="12"></sequence>
+    <sequence name="amber_four_times" pattern="a " speed="2" loop="4"></sequence>
+  </sequences>