The `pysimconnect` package provides a simple, efficient wrapper for FlightSimulator 2020's
[SimConnect SDK](https://docs.flightsimulator.com/html/index.htm?#t=Programming_Tools%2FSimConnect%2FSimConnect_SDK.htm),
inspired by [Python-SimConnect](https://github.com/odwdinc/Python-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
then `pysimconnect` is for you.
You might also be interested in [G3](https://github.com/patricksurry/g3),
a flexible Javascript framework for building steam gauge instrument panels.
The package contains a python module called `simconnect`
which 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 the `SimConnect.h`
SDK API based on a simple automated translation
from the C++ definitions to Python equivalents.
The package also offers a `simconnect` command-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 start
---
Making sure you're using python 3.6+ and install the package:
pip install pysimconnect
To use the `simconnect` command-line tool,
install [Powershell7](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2) and
set your [default terminal](https://devblogs.microsoft.com/commandline/windows-terminal-as-your-default-command-line-experience/)
to Windows Terminal rather than Windows Console Host.
Start Powershell7 and install TAB auto-completion support by typing
`simconnect --install-completion powershell`
then 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 with `search`:
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 the `PLANE ALTITUDE` variable using the `get` command.
Start typing `simconnect get PLA<TAB>`, hitting the TAB key part way through the variable name
to see contextual auto-complete options:
Select the desired `PLANE_ALTITUDE` option 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 using `watch`:
By default we'll see an update once every second,
highlighting the variables that change during each update.
Some commands support additional options,
for example `simconnect watch --help` will show us how to change the
monitoring interval time.
For general help, try `simconnect --help`.
Now let's change the plane's altitude during flight(!) using the `set` command.
Here we'll add the `--units` option to specify that our value is measured in `meters` rather
than the default `feet`:
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 python
---
The command-line tool is just a lightweight
wrapper for some features of the `simconnect` python 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 some [examples](examples/README.md)
which 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 the `LOGLEVEL` environment variable
to `DEBUG` before running your code, rather than the default `INFO`:
set LOGLEVEL=DEBUG
Also, be warned that the official
[SDK documentation](https://docs.flightsimulator.com/html/index.htm?#t=Programming_Tools%2FSimConnect%2FSimConnect_SDK.htm_)
has various errors (copy/paste gone wrong?)
which can make it difficult to understand some details.
Where possible refer directly to the `SimConnect.h`
header file definitions and comments
as a more authoritative source.
What's what?
---
Find the full source on github at https://github.com/patricksurry/pysimconnect.
The `simconnect` folder contains the package itself.
The main interface is defined in `sc.py` which wraps the raw
definitions from the auto-generated `scdefs.py`,
providing access to both the low-level
SDK functions as well as some pythonic sugar.
The command line tool is implemented by `cli.py`.
The package requires a copy of `SimConnect.dll` to work.
This normally ships with FS2020 but a recent copy is also included here.
You can point to your own version by specifying the `dll_path` argument
when initializing `SimConnect(...)`.
The `scvars.json` file lists all the simulation variables (SimVars),
events and dimensional units, which were scraped from the SDK documentation pages
using `scripts/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.
The `examples` folder contains various illustrations of how to use
the package, showing both low-level SDK access and the pythonic wrappers.
See the `README.md` there for more details.
The `scripts` folder includes several scripts used to generate
parts of the package.
The `genscdefs.py` script creates `scdefs.py` from a post-processed
version of the `SimConnect.h` C++ 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 with `cpp` to `SimConnect_cpp.h` from 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 distribution
---
Bump version in `setup.cfg` then following https://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-...
Raw data
{
"_id": null,
"home_page": "https://github.com/patricksurry/pysimconnect",
"name": "pysimconnect",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "pysimconnect,SimConnect,SimVars,ctypes,SDK,API,FS2020,Microsoft Flight Simulator",
"author": "Patrick Surry",
"author_email": "patrick.surry@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6e/69/e9ddbf0f5e0242557beced68414b769d6f31f3f0288da0eae3d0efd932b9/pysimconnect-0.2.6.tar.gz",
"platform": null,
"description": "The `pysimconnect` package provides a simple, efficient wrapper for FlightSimulator 2020's\r\n[SimConnect SDK](https://docs.flightsimulator.com/html/index.htm?#t=Programming_Tools%2FSimConnect%2FSimConnect_SDK.htm),\r\ninspired by [Python-SimConnect](https://github.com/odwdinc/Python-SimConnect).\r\n\r\nIf you're looking to build external instrument displays,\r\nconnect custom controllers to FS2020,\r\nor just explore how the simulation works in more detail\r\nthen `pysimconnect` is for you.\r\nYou might also be interested in [G3](https://github.com/patricksurry/g3),\r\na flexible Javascript framework for building steam gauge instrument panels.\r\n\r\nThe package contains a python module called `simconnect`\r\nwhich exposes a simple pythonic interface\r\nto read simulator variables,\r\nset editable variables,\r\nsubscribe to variable changes,\r\nand trigger simulator events.\r\nIt also exposes all of the low-level SDK methods,\r\nconstants and enumerations from the `SimConnect.h`\r\nSDK API based on a simple automated translation\r\nfrom the C++ definitions to Python equivalents.\r\n\r\nThe package also offers a `simconnect` command-line tool\r\nwhich lets you search for\r\nvariables, events and measurement units from the SDK documentation;\r\ninspect, change or watch variables over time;\r\nand send simulator events,\r\nall without writing any code.\r\n\r\n\r\nQuick start\r\n---\r\n\r\nMaking sure you're using python 3.6+ and install the package:\r\n\r\n pip install pysimconnect\r\n\r\nTo use the `simconnect` command-line tool,\r\ninstall [Powershell7](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.2) and\r\nset your [default terminal](https://devblogs.microsoft.com/commandline/windows-terminal-as-your-default-command-line-experience/)\r\nto Windows Terminal rather than Windows Console Host.\r\nStart Powershell7 and install TAB auto-completion support by typing\r\n`simconnect --install-completion powershell`\r\nthen restart your terminal as instructed:\r\n\r\n\r\n\r\nNow start a flight in FS2020, perhaps with the AI pilot flying.\r\nLet's experiment with reading and modifying the altitude.\r\nFirst let's find some relevant variables with `search`:\r\n\r\n\r\n\r\nNice! We get a list of results from the SDK documentation ranked by relevance.\r\nResult categories are distinguished by different colors and symbols, e.g.\r\nvariables \ud83e\udded, events \u2699\ufe0f and units \ud83d\udcd0, with a \u270f\ufe0f marking variables which we can change.\r\n\r\nNow let's read the value of the `PLANE ALTITUDE` variable using the `get` command.\r\nStart typing `simconnect get PLA<TAB>`, hitting the TAB key part way through the variable name\r\nto see contextual auto-complete options:\r\n\r\n\r\n\r\nSelect the desired `PLANE_ALTITUDE` option and hit ENTER:\r\n\r\n\r\n\r\nNote that although the underlying SDK variables are space-separated\r\nand events are underscore-separated,\r\nthe command-line tool recognizes either version.\r\nNormally using underscore-separated everywhere will be easier for auto-completion\r\nand avoids quoting in the terminal.\r\n\r\nWe can read multiple variables by just appending them in a list.\r\nWe can also monitor multiple variables over time using `watch`:\r\n\r\n\r\n\r\nBy default we'll see an update once every second,\r\nhighlighting the variables that change during each update.\r\nSome commands support additional options,\r\nfor example `simconnect watch --help` will show us how to change the\r\nmonitoring interval time.\r\nFor general help, try `simconnect --help`.\r\n\r\nNow let's change the plane's altitude during flight(!) using the `set` command.\r\nHere we'll add the `--units` option to specify that our value is measured in `meters` rather\r\nthan the default `feet`:\r\n\r\n\r\n\r\nLastly, let's send an event to FS2020.\r\nA simple example is to bump the altimeter adjustment knob, like so.\r\nIf you send this event a few times, you'll see the indicated altitude adjust in response.\r\n\r\n\r\n\r\nThis simple event needs no data, but with others you also need to provide a value.\r\n\r\n\r\nWorking with python\r\n---\r\n\r\nThe command-line tool is just a lightweight\r\nwrapper for some features of the `simconnect` python package.\r\nThis means that you can write simple python code to do anything\r\nthe command-line tool does, and much more besides.\r\nThe best way to get started is to browse some [examples](examples/README.md)\r\nwhich show both low-level interaction with the SDK,\r\nand some of the simplified sugar the package offers.\r\n\r\n\r\nWith so many moving parts, debugging errors can sometimes be tricky.\r\nOne useful tool is to set the `LOGLEVEL` environment variable\r\nto `DEBUG` before running your code, rather than the default `INFO`:\r\n\r\n set LOGLEVEL=DEBUG\r\n\r\nAlso, be warned that the official\r\n[SDK documentation](https://docs.flightsimulator.com/html/index.htm?#t=Programming_Tools%2FSimConnect%2FSimConnect_SDK.htm_)\r\nhas various errors (copy/paste gone wrong?)\r\nwhich can make it difficult to understand some details.\r\nWhere possible refer directly to the `SimConnect.h`\r\nheader file definitions and comments\r\nas a more authoritative source.\r\n\r\n\r\nWhat's what?\r\n---\r\n\r\nFind the full source on github at https://github.com/patricksurry/pysimconnect.\r\nThe `simconnect` folder contains the package itself.\r\n\r\nThe main interface is defined in `sc.py` which wraps the raw\r\ndefinitions from the auto-generated `scdefs.py`,\r\nproviding access to both the low-level\r\nSDK functions as well as some pythonic sugar.\r\nThe command line tool is implemented by `cli.py`.\r\n\r\nThe package requires a copy of `SimConnect.dll` to work.\r\nThis normally ships with FS2020 but a recent copy is also included here.\r\nYou can point to your own version by specifying the `dll_path` argument\r\nwhen initializing `SimConnect(...)`.\r\nThe `scvars.json` file lists all the simulation variables (SimVars),\r\nevents and dimensional units, which were scraped from the SDK documentation pages\r\nusing `scripts/scrapevars.json`. This is useful for finding content\r\nyou want to interact with, inferring missing units and data-types\r\nwhen querying simulation variables, and sanity-checking variable names.\r\n\r\nThe `examples` folder contains various illustrations of how to use\r\nthe package, showing both low-level SDK access and the pythonic wrappers.\r\nSee the `README.md` there for more details.\r\n\r\nThe `scripts` folder includes several scripts used to generate\r\nparts of the package.\r\nThe `genscdefs.py` script creates `scdefs.py` from a post-processed\r\nversion of the `SimConnect.h` C++ header that ships with the SDK\r\n(which can be installed via the Options > General > Developer tools help menu).\r\nThis generates a python translation of all the SDK function declarations, data structures\r\nand enumerated constants. The automated translation is quite fragile:\r\nit assumes the header is formatted in a particular way, and has been\r\npre-processed with `cpp` to `SimConnect_cpp.h` from the raw header.\r\nThis approach makes it easy to tweak the rules for mapping from C++\r\nto Python, as long as header format doesn't change significantly.\r\n\r\n\r\n\r\nPackaging and distribution\r\n---\r\n\r\nBump version in `setup.cfg` then following https://packaging.python.org/en/latest/tutorials/packaging-projects/\r\n\r\n python3 -m build\r\n git commit -am ...\r\n git push origin\r\n git tag v0.2.6\r\n git push origin --tags\r\n python3 -m twine upload dist/*0.2.6*\r\n # login with username: __token__ / password: pypi-...\r\n\r\n",
"bugtrack_url": null,
"license": "",
"summary": "Python wrapper for Microsoft FlightSimulator 2020 SimConnect SDK",
"version": "0.2.6",
"project_urls": {
"Bug Tracker": "https://github.com/patricksurry/pysimconnect/issues",
"Homepage": "https://github.com/patricksurry/pysimconnect"
},
"split_keywords": [
"pysimconnect",
"simconnect",
"simvars",
"ctypes",
"sdk",
"api",
"fs2020",
"microsoft flight simulator"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0f619274b33462461d52a80547076cabcac7147d8e9981ecad1ea6f11593dd0b",
"md5": "a3584451d89a24233679fb0298e2ac05",
"sha256": "4161d859d2931a249987d5507b5e469d042944f69fe2ac9b109ba48eb8cde43a"
},
"downloads": -1,
"filename": "pysimconnect-0.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a3584451d89a24233679fb0298e2ac05",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 621176,
"upload_time": "2023-06-12T21:49:24",
"upload_time_iso_8601": "2023-06-12T21:49:24.131075Z",
"url": "https://files.pythonhosted.org/packages/0f/61/9274b33462461d52a80547076cabcac7147d8e9981ecad1ea6f11593dd0b/pysimconnect-0.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e69e9ddbf0f5e0242557beced68414b769d6f31f3f0288da0eae3d0efd932b9",
"md5": "d3014f3f281b088452f77a2350e2dcfb",
"sha256": "3703e373991c77816047d0d7bc883bda8156f24b139a35122d9f007d112ca896"
},
"downloads": -1,
"filename": "pysimconnect-0.2.6.tar.gz",
"has_sig": false,
"md5_digest": "d3014f3f281b088452f77a2350e2dcfb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 628006,
"upload_time": "2023-06-12T21:49:25",
"upload_time_iso_8601": "2023-06-12T21:49:25.973778Z",
"url": "https://files.pythonhosted.org/packages/6e/69/e9ddbf0f5e0242557beced68414b769d6f31f3f0288da0eae3d0efd932b9/pysimconnect-0.2.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-12 21:49:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "patricksurry",
"github_project": "pysimconnect",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pysimconnect"
}
JSON
