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
						
to
"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/

Version 1.21 released

This release solves the following issues:

  • fixes a bug related to page navigation (go to page action)

Version 1.20 released

This release solves the following issues:

  • fixes a bug related to button delete

Version 1.19 released

This release solves the following issues:

  • fixes a bug related to editing multipage decks

First public release!

The first public release of MATRIC is out, check it out

Today is a great day for the MATRIC Team, our first public release is out. You can join our discord https://discord.gg/HjEZnfe and ask as anything, we'd be more than happy to receive feedback and answer your questions.

Version 1.18 released

This release solves the following issues:

  • Handle corrupted config file issue
  • Refresh the decks list when new deck is imported

Version 1.16 released

Below are the highlights of release version 1.16:

  • Integration API - 3rd party integration
    Integration API allows 3rd party applications to use MATRIC as output device, deck can be loaded, page set and button properties can be changed via API to reflect the state of the application.

    For example: media player could display the name of the song in MATRIC, shooter game could display ammo/health etc.
  • We created a simple demo project on Github MATRIC Integration API Demo to get you started with integrating your application with MATRIC.

Version 1.15 released

Below are the highlights of release version 1.15:

  • Deck sharing - You can share your creations on community gallery
  • Haptic feedback - implemented vibration feedback for button presses, can be turned off in client settings
  • Connected clients list - View connected devices, disconnect and unpair devices
  • Dynamic font scaling - Button text size is now relative to button unit size
  • Server UI enhancements - for more consistent user experience (font sizes, controls dimensions), highlighted some key controls and Ui hints (selected deck and page highlighted in accent color)
  • Other - Various bugfixes and performance improvement in both client and server