bjanders / dcs-master

Digital Combat Simulator cockpit integration server

dcs-master - Digital Combat Simulator cockpit integration server

dcs-master is a plugin to Digital Combat Simulator that provides a network socket through which aircraft gauge data and other information is exported and through which aircraft instruments and controls can be controlled. This implementation aims to achieve the following:

• It should be easy to add support for new aircraft without extensive coding. Most of the gauge (game output) and controls (input) are already described in the DCS game files in a structed machine readable format. This information is utilized as much as possible to avoid manual programming of the same information.

• A simple to use network protocol that can easily be integrated with various client software. This is achieved by sending all data as simple space separated text lines. Originally JSON was used, but it turned out that text lines was sufficient and even simpler. JSON and other formats can easily be enabled if needed. If a more compact data format is needed, then support for CBOR can easily be added, since JSON can be encoded as CBOR. Other compact formats could be used as well.

• Avoid sending more data than needed. This is achieved by allowing the client to request which parameters should be exported, at what maximum frequency and with which precision (per gauge). Data is only sent when the information changes at the requested precision. For example, the indicated airspeed (IAS) is within the game a floating point number that in practice changes for each rendered frame in the game. In most cases, it is sufficient for the client software to know the IAS without decimals, for example, at the resolution of 1 km/h or 1 knot. If the IAS stays with that one km/h then an update of the IAS is not sent to the client.

• Keep the server side implementation fairly simple.

DCS cockpit information

Aircraft cockspits in DCS are described in the DCS installation folder (typically C:\Program Files\Eagle Dynamics\DCS World\) in the Mods\aircraft\<aircraft name>\Cockpit\Scripts\ folder.

The cockpits consist of the following elements:

Devices

The devices of the aircraft. Taking the F/A-18C as an example, separate devices are the Up Front Controller (UFC), the armament computer and the environmental control system. The devices are listed in the devices.lua file.

Commands

The devices are controlled via commands. Each device typically has several commands. These represent the buttons and switches on the devices. For example, the UFC has a number keyboard and several other buttons. Each button is a command. The commands are listed in the command_defs.lua file.

The main panel

The main panel is a also a device, but is special, in that it contains all the gauge and other output information. This includes the position of knobs and switches. There are no commands associated with the main panel device. The main panel gauges are listed in the mainpanel_init.lua file which also includes the MainPanel\lamps.lua file where on/off style indicators are listed.

Devices and commands are numbered. The main panel is always device 0. So we have this structure:

• Devices

  • Device 0: Main panel

    • Gauge 1

    • Gauge 2

    • Gauge n

  • Device 1

    • Command 1

    • Command 2

    • Command n

  • Device n

    • Command 1

    • …​

Internally to the game the status of all gauges and commands are represented as floating point values between -1.0 and 1.0 inclusive.

The protocol

Warning

The protocol is not fully finalized yet and changes may still occur.

The protocol works by sending and receiving space separated text lines terminated by a new line character. The lines are exchanged over a TCP/IP session. By default the DCS master server plugin listens to port 4242, but this can changed in the LUA script. The first element of the text line is always the associated command defined by an integer. The general format is:

<command> <arg1> <arg2> ... \n

Five commands are currently implemented:

0

The server reports the name of the currently controlled aircraft

1

The client controls a device

2

The client subscribes to gauge value changes, and the server sends gauge values

3

The client subscribes to indicators (text output, which cannot be represented as number), and the server sends indicator values

4

The client requests a list of all known indicators, and the server responds with the indicators

Command 0: Report currently controlled aircraft

Command 0 is automatically sent by the server to the client:

• Immediately when the client connects if an aircraft is controlled

• Immediately when the controlled aircraft changes

The format of the command is:

0 <aircraft>

The aircraft name is always as defined by DCS.

For example, when the the F/A-18C is controlled, the following is sent by the server to the client:

0 FA-18C_hornet

Command 1: Control a device

With command 1 you control devices in the aircraft, like pushing a button, flicking a switch, turning a knob or pulling a lever. The format of the command is:

1 <device> <command> <value>

Where:

<device> and <command>

Device and command can either take an integer form or a string form. The integer form always works for any aircraft and for every device and command. This way any aircraft now and in the future can be controlled without any updates to the server software. To find the right device and command numbers, look in the DCS aircraft folder in the devices.lua and command_defs.lua files. To use the string form, the device and/or command must be defined in the aircraft specific JSON file in the dcs-master folder. To find the correct device and command names, look in this JSON file. The strings are not case sensitive, so you can capitalize them as you see fit. The names used are always as defined by DCS, even if they contain typos (as has happened), or if they are non-descriptive like "Button_42".

<value>

The value is always a floating point value between -1.0 and 1.0 inclusive. The value to send can most often be easily determined:

• On/off switches are 0, 1 and tri-state (down/middle/up) switches are -1, 0, 1.

• Multi-position rotational knobs are fractional numbers for the various positions (Information on how to determine the fractions will be added.)

• Encoders are fractional numbers of the amount to turn; positive for clockwise and negative for counter-clockwise

• Analog controls can use the whole floating point range

Examples

To press and release the TCN button on the UFC in the F/A-18C, send:

1 UFC FuncSwTCN 1
1 UFC FuncSwTCN 0

To increase the RADAR altimeter warning position on the right vertical panel in the F/A-18C, send:

1 ID2163A ID2163A_SetMinAlt 0.05

And to decrease it:

1 ID2163A ID2163A_SetMinAlt -0.05

Example of multi-position switch and other examples will be added.

Command 2: Subscribe to gauge values

With command 2 you subscribe the changes in the values of gauges, and receive the updated gauge values from the server. An update of the value of the gauge is sent by the server to the client when either of the following conditions occur:

• Immediately after the subscribe command has been sent by the client to the server, so the client gets a starting point

• When a value changes with the requested precision and no more often than at the requested frequency

Note that gauges are any kind of indicators that can be represented by a numerical value. This includes on/off lights, analog gauges and digitally displayed values.

Client to server

The format of the command is:

2 <gaugename> <id> <precision> <maxfrequency>

Where:

<gaugename>

The gauge name can either take an integer form or a string form. The integer form always works for any aircraft and for every gauge. This way you can receive gauge information for any aircraft now and in the future without any updates to the server software. To use the string form, the device and/or command must be defined in the aircraft specific JSON file in the dcs-master folder. To find the correct device and command names, look in this JSON file. The strings are not case sensitive, so you can capitalize them as you see fit. The names used are always as defined by DCS, even if they contain typos.

<id>

The ID is an arbitrary integer number assigned by the client. This ID will be used the server when sending gauge value updates to the client. The purpose of the ID is to make it easy for the client to implement a lookup array to update the physical gauges. A typical client would start assign IDs starting from 0 and then incrementing by one for each gauge that it has interest in.

<precision>

The precision is an integer number defining with how many decimals precision the client is interested in receiving updates. This has an effect on both the update frequency and the precision in which the value is returned. The default value precision is 0, meaning whole integers. A precision of 1 decimal, means that an update is sent of the value changes by 0.1 or more; A precision of 2, means changes of 0.01 or more and so on. Negative numbers are also allowed. For example -1, means to report changes of 10 or more.

<maxfrequency>

The maximum frequency defines the maximum frequency at which an update will be sent. The default value is 10, i.e., an update is sent at most ten times per second. If the value has not changed by more than the requested precision, then an update will not be sent no matter what the maximum frequency is set at.

Both <precision> and <maxfrequency> are optional, but to set <maxfrequency> you must also set <precision>. Most often you would keep <maxfrequency> the same for all gauges in your cockpit and only change the <precision> depending on the gauge type.

Server to client

Format:

2 <id> <rawvalue> <gaugevalue>

Description will come.

Command 4: Subscribe to indicators

Indicators are gauges that and screens that show output that shows text and cannot be represented by numbers, for example the output on a text display. Indicators grouped hierarchically within DCS. At the highest level are numbers, representing a device within the cockpit. The device can several displays. For example, in the Hornet, the UFC is device number 6, and the UFC has several displays. For an example of all indicators of the Hornet see hornetindicators.json.

If you don’t know the number and name of the indicator you need, you can send command 5, explained later.

The format of the command is:

3 <indicatornumber> <indicatorname> <id>

Where:

<indicator_number>

The indicator number of the device.

<indicatorname>

The name of the indicator. Although the indicators are in a hierarchy, the indicator name is just the name of the actual indicator, without any intermediates. For example the UFC scratch pad displays is on indicator device 6 and the full hierarchy is UFC_MainDummy → UFC_mask → UFC_ScratchPadNumberDisplay. To get this value, you would use an <indicatorname> of "UFC_ScratchPadNumberDisplay"

<id>

The ID is an arbitrary integer number assigned by the client. This ID will be used the server when sending gauge value updates to the client. The purpose of the ID is to make it easy for the client to implement a lookup array to update the physical gauges. A typical client would start assign IDs starting from 0 and then incrementing by one for each gauge that it has interest in.

The server will send to the client:

3 <id> <indicatorstring>

Where:

<id>

Is the ID given in the subscribe command

<indicatorstring>

Is the text displayed on the indicator.

Example

The client subscribes to the output of the Hornet UFC scratchpad:

3 6 UFC_ScratchPadNumberDisplay 0

Now the player types on the 1, 2, 3, 4, 5, 6, 7 on the number pad of the UFC, which will show the number on the scratch pad. The following is sent by the server to the client:

3 0
3 0       1
3 0      12
3 0     123
3 0    1234
3 0   12345
3 0  123456
3 0 1234567

Command 5: List all indicators

Use this command to get a list of all indicators in the cockpit. See hornetindicators.json for example of the output. The actual output is in a more compact form without spaces. The example has been formatted for readability.

The format of the command is:

4

See the above example for the format that the server replies with.

Example session

Installation and usage

How to add support for new aircraft

Related projects