Package: pysimconnect
Thepysimconnectpackage provides a simple, efficient wrapper for FlightSimulator 2020'sSimConnect SDK,
inspired byPython-SimConnect.If you're looking to build external instrument displays,
connect custom controllers to FS2020,
or just explore how the simulation works in more detail
thenpysimconnectis for you.
You might also be interested inG3,
a flexible Javascript framework for building steam gauge instrument panels.The package contains a python module calledsimconnectwhich exposes a simple pythonic interface
to read simulator variables,
set editable variables,
subscribe to variable changes,
and trigger simulator events.
It also exposes all of the low-level SDK methods,
constants and enumerations from theSimConnect.hSDK API based on a simple automated translation
from the C++ definitions to Python equivalents.The package also offers asimconnectcommand-line tool
which lets you search for
variables, events and measurement units from the SDK documentation;
inspect, change or watch variables over time;
and send simulator events,
all without writing any code.Quick startMaking sure you're using python 3.6+ and install the package:pip install pysimconnectTo use thesimconnectcommand-line tool,
installPowershell7and
set yourdefault terminalto Windows Terminal rather than Windows Console Host.
Start Powershell7 and install TAB auto-completion support by typingsimconnect --install-completion powershellthen restart your terminal as instructed:Now start a flight in FS2020, perhaps with the AI pilot flying.
Let's experiment with reading and modifying the altitude.
First let's find some relevant variables withsearch:Nice!  We get a list of results from the SDK documentation ranked by relevance.
Result categories are distinguished by different colors and symbols, e.g.
variables 🧭, events ⚙️ and units 📐, with a ✏️ marking variables which we can change.Now let's read the value of thePLANE ALTITUDEvariable using thegetcommand.
Start typingsimconnect get PLA<TAB>, hitting the TAB key part way through the variable name
to see contextual auto-complete options:Select the desiredPLANE_ALTITUDEoption and hit ENTER:Note that although the underlying SDK variables are space-separated
and events are underscore-separated,
the command-line tool recognizes either version.
Normally using underscore-separated everywhere will be easier for auto-completion
and avoids quoting in the terminal.We can read multiple variables by just appending them in a list.
We can also monitor multiple variables over time usingwatch:By default we'll see an update once every second,
highlighting the variables that change during each update.
Some commands support additional options,
for examplesimconnect watch --helpwill show us how to change the
monitoring interval time.
For general help, trysimconnect --help.Now let's change the plane's altitude during flight(!) using thesetcommand.
Here we'll add the--unitsoption to specify that our value is measured inmetersrather
than the defaultfeet:Lastly, let's send an event to FS2020.
A simple example is to bump the altimeter adjustment knob, like so.
If you send this event a few times, you'll see the indicated altitude adjust in response.This simple event needs no data, but with others you also need to provide a value.Working with pythonThe command-line tool is just a lightweight
wrapper for some features of thesimconnectpython package.
This means that you can write simple python code to do anything
the command-line tool does, and much more besides.
The best way to get started is to browse someexampleswhich show both low-level interaction with the SDK,
and some of the simplified sugar the package offers.With so many moving parts, debugging errors can sometimes be tricky.
One useful tool is to set theLOGLEVELenvironment variable
toDEBUGbefore running your code, rather than the defaultINFO:set LOGLEVEL=DEBUGAlso, be warned that the officialSDK documentationhas various errors (copy/paste gone wrong?)
which can make it difficult to understand some details.
Where possible refer directly to theSimConnect.hheader file definitions and comments
as a more authoritative source.What's what?Find the full source on github athttps://github.com/patricksurry/pysimconnect.
Thesimconnectfolder contains the package itself.The main interface is defined insc.pywhich wraps the raw
definitions from the auto-generatedscdefs.py,
providing access to both the low-level
SDK functions as well as some pythonic sugar.
The command line tool is implemented bycli.py.The package requires a copy ofSimConnect.dllto work.
This normally ships with FS2020 but a recent copy is also included here.
You can point to your own version by specifying thedll_pathargument
when initializingSimConnect(...).
Thescvars.jsonfile lists all the simulation variables (SimVars),
events and dimensional units, which were scraped from the SDK documentation pages
usingscripts/scrapevars.json.  This is useful for finding content
you want to interact with, inferring missing units and data-types
when querying simulation variables, and sanity-checking variable names.Theexamplesfolder contains various illustrations of how to use
the package, showing both low-level SDK access and the pythonic wrappers.
See theREADME.mdthere for more details.Thescriptsfolder includes several scripts used to generate
parts of the package.
Thegenscdefs.pyscript createsscdefs.pyfrom a post-processed
version of theSimConnect.hC++ header that ships with the SDK
(which can be installed via the Options > General > Developer tools help menu).
This generates a python translation of all the SDK function declarations, data structures
and enumerated constants.  The automated translation is quite fragile:
it assumes the header is formatted in a particular way, and has been
pre-processed withcpptoSimConnect_cpp.hfrom the raw header.
This approach makes it easy to tweak the rules for mapping from C++
to Python, as long as header format doesn't change significantly.Packaging and distributionBump version insetup.cfgthen followinghttps://packaging.python.org/en/latest/tutorials/packaging-projects/python3 -m build
git commit -am ...
git push origin
git tag v0.2.6
git push origin --tags
python3 -m twine upload dist/*0.2.6*
# login with username: __token__ / password: pypi-...