MATRIC Blog

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.

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": false

"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:

{
	"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

Basically, with the hack above we faked steps 1-3. Full integration demo can be found on Github

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).

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

	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/

Posted 5 years ago by Tomislav