Integrating MATRIC with DCS - proof of concept
The Goal
In this tutorial, we will integrate Ka-50 autopilot channel switches with MATRIC so that their state reflects the game state and vice-versa. Although this post might look really long, the procedure itself is not complicated, basically you will change one "false" to "true" and do two copy & paste actions.
Additional info is given in dashed frames.
Additional info is given in dashed frames.
This is a proof-of-concept and is not ment to teach best coding practices nor represent a bulletproof solution. Some shortcuts have been taken to focus on the important things.
Prerequisites
- Download and install MATRIC version 1.22 or higher installed on Windows. Version thing is important as the script uses extended integration API introduced in 1.22
- Install MATRIC for Android from Google Play Store
- MATRIC DCS demo integration script. Get it here.
- Ka-50 deck that we will use in the demo. Get it here (just download it and click on it, MATRIC will import it automatically)
1. MATRIC configuration
1.1 Open the config file
We will edit MATRIC configuration file which is in your Documents folder (C:\Users\<your username >\Documents\.matric\config.json).Open the file in thext editor (like notepad or even better Notepad++)
If we were making a real plugin instead of just a proof of concept demo, of course we would make a setup program which would do these steps.
1.2 Enable integration API
MATRIC provides an API which enables 3rd party apps to control buttons on MATRIC user interface. It is disabled by default and we need to enable it.
Change the line
"EnableIntegrationAPI": falseto
"EnableIntegrationAPI": true
1.3 Grant the permission to our DCS script
In order for MATRIC to obey our commands, we will have to do another small hack, we will add a permission in config.json like so:
We will need this Id in the next step as we will use this Id to tell MATRIC we want to integrate with this particular device.
{
"AuthorizedClients": [
{
"Name": "Galaxy A70",
"IP": "192.168.1.28",
"Id": "ivUP0l+n06oCAR6XYzZPdclCSURAVjGSyv27b42aT+o=",
"MatricVersion": 2,
"LastContact": "2019-10-15T17:40:35.5818578+02:00"
}
],
"AuthorizedApps": [
{
"appName": "MATRIC4DCS",
"appPIN": "9087"
}
],
"LastOpenedDeckId": "medium sized gibberish",
"ApiKey": "medium sized gibberish",
"MatricWebToken": "some really long gibberish",
"Author": "The MATRIC Team",
"LastReadMessageId": 1,
"EnableIntegrationAPI": true
}
This is another simplification. In general, "by the book way" would be:
- 1) 3rd party app says "Hey, I'd like to connect!
- 2) MATRIC shows popup with random PIN
- 3) You enter that PIN into 3rd party app
- 4) 3rd party app issues commands indentifying itself with name and PIN
1.4 Get the device id we want to use in the demo
If you have already connected to MATRIC with your Android device, you will find something similar to this (if not, then connect at least once):
"AuthorizedClients": [
{
"Name": "Galaxy A70",
"IP": "192.168.1.28",
"Id": "ivUP0l+n06oCAR6XYzZPdclCSURAVjGSyv27b42aT+o=",
"MatricVersion": 2,
"LastContact": "2019-10-15T17:40:35.5818578+02:00"
},
...
We will need this Id in the next step as we will use this Id to tell MATRIC we want to integrate with this particular device.
Although MATRIC integration API has a method which answers the question "Hey MATRIC, which devices are currently connected?" we will not use it, but will instead just hard-code the client device id in our DCS export script.
1.5 Save config and restart MATRIC
Save the config and restart MATRIC (right click on tray icon, choose "Quit" and the start it again)
2. The DCS side of things
DCS allows you to add code which can read the game data and do something with it. It is done by writing an export script in LUA language.
It is simple, I learned enough of it in an hour to create this proof of concept (and I'm no coding ninja).
It is simple, I learned enough of it in an hour to create this proof of concept (and I'm no coding ninja).
2.1 matricka50.lua
Copy the matricka50.lua to your C:\Users\<your username >\Saved Games\DCS\Scripts", open it in notepad and modify the line
Save matricka50.lua
MATRIC.clientId = "some gibberish"You need to paste the Id from the step 1.4 between the "". In our example the Id was ivUP0l+n06oCAR6XYzZPdclCSURAVjGSyv27b42aT+o=
Save matricka50.lua
2.2 Export.lua
This is a script you already have, it gets executed when DCS runs it can also be found in "C:\Users\<your username >\Saved Games\DCS\Scripts". We will just need to add a single line at the end and save it:
dofile(lfs.writedir()..[[Scripts\matricka50.lua]])
Wrapping it up
Start DCS, open the Ka-50 deck on your smartphone and ADI channel buttons should work like in this video
Further information
More info about MATRIC Integration API and c# example can be found on github: https://github.com/tgudelj/MATRICIntegrationDemo/