DCS-BIOS Reference Tool

There are 3 DCS-BIOS reference tool alternatives for getting the information needed:

  • Install Bort

  • Install BIOSBuddy

  • Go to your saved Games folder/Scripts/DCS-BIOS/doc and double-click on the file control-reference.html. Your web browser will automatically open and display all sorts of colorful headings and code. If you see a red warning instead, you need to enable JavaScript in your web browser and reload the page.

The DCS-BIOS reference tools lists every single supported DCS module and all DCS-BIOS controls belonging to the module, every single panel found in that aircraft, and every single corresponding switch, push button and rotary knob or whatever associated with that panel and the corresponding code that you will use to create your sketch.

Connecting to DCS-BIOS

Controls in the cockpit can be manipulated by sending newline-terminated plain text commands to UDP port 7778. The syntax is described in the The DCS-BIOS Import Protocol section.

The current state of cockpit indicators and controls is exported from DCS using a binary protocol (see The DCS-BIOS Export Protocol). This data is sent via UDP to multicast address 239.255.50.10, port 5010 on the loopback interface (127.0.0.1).

When opening a UDP socket to listen on 239.255.50.10:5010, you must specify the allowreuseaddr socket option. Otherwise Windows will prevent other programs from listening to the same data stream.
The IPv4 multicast address block 239.255.0.0/16 is defined in RFC 2365 as the "IPv4 Local Scope". It is part of the "Administratively Scoped IPv4 Multicast Space", which is to multicast as the private address ranges 10.0.0.0/8, 192.168.0.0/16 and 172.16.0.0/12 are to unicast Ipv4.

If you cannot or do not want to deal with multicast UDP, you can also make DCS-BIOS send a copy of the export data stream to a unicast address by editing BIOSConfig.lua.

You can also use the socat or DCSBIOSBridge utility to connect a serial port (and just about anything else that can be read or written) to the DCS-BIOS import and export streams. For an example, take a look at the batch files that come with DCS-BIOS.

Another way is to open a TCP connection to port 7778. You can use this connection to send commands to DCS-BIOS and receive the export data. If you can, use UDP instead of TCP. Each TCP connection slightly increases the amount of work that is performed inside of DCS (blocking the rest of the simulation).

The DCS-BIOS Import Protocol

Commands are sent to DCS-BIOS as lines of plain text.

A command consists of a control identifier, a space, an argument and a newline character.

The import protocol does not use binary encodings. Handling binary data in Lua with only the libraries that come with DCS is cumbersome. Also, a plain text protocol is easier to explain, understand and debug. In the input direction, the added verbosity of a plain text protocol is no problem because a human pilot will not flip 20 switches 30 times a second.

To find out the arguments that a certain control accepts, refer to the reference documentation and look up input interfaces in the User Guide.

The DCS-BIOS Export Protocol

The export stream protocol is designed to be as space-efficient as possible to enable the export of the complete cockpit state over a 115200 bps serial connection.

Each piece of cockpit state is encoded as an integer or a string and is assigned an address within a 16-bit address space.

Integer Values

The location of an integer value is defined by a 16-bit word address which specifies the start of the 16-bit word in which the data is located, a 16-bit mask which specifies which bits in that word belong to the value, and a shift value (which can also be deduced from the mask).

Given the start address, mask and shift values, the following pseudo C code decodes a value:

char[] state;
unsigned int value = (((uint16_t*)state)[start_address/2] & mask) >> shift

Changes to the state data are encoded as write accesses to this address space and written to the export data stream in the following format:

<start address (16 bit)> <data length (16 bit)> data

Both the start address and the data length will always be even (internally, DCS-BIOS treats the data as a list of 16-bit integers). This ensures that no write access partially updates an integer value (an integer may occupy no more than 16 bit).

All integer values are written in litte-endian byte order.

The following byte sequence is an example of a write access of four bytes starting at address 0x1000:

0x00 0x10 0x04 0x00 0x41 0x2d 0x31 0x30

String Values

The location of a string is defined by its 16-bit start address and the length in bytes (all string values have a fixed maximum length and start on a 16-bit aligned address).

A string value with a maximum length greater than two characters can be updated partially. To avoid inconsistent intermediate states, an application that receives DCS-BIOS export data should apply changes to string values at the next frame synchronization sequence (see next section).

Synchronization sequence

DCS-BIOS tries to send 30 updates per second.

DCS-BIOS will send the four bytes 0x55 0x55 0x55 0x55 at the start of each update. These do not specify a 21845-byte write access to the address 0x5555. Instead, they are used by consumers of the data stream to find the start of a write access to synchronize to.

DCS-BIOS ensures that this byte sequence cannot appear in the normal data stream. In the event that the byte sequence 0x55 0x55 0x55 0x55 would appear in a single write access, DCS-BIOS will avoid that by splitting it up into two separate writes.

Beginning and End of Mission

At the beginning of every mission DCS-BIOS will publish the active aircraft module, _ACFT_NAME, in the MetaDataStart module, and at the end of a mission, DCS-BIOS will publish one final message with an empty string for the _ACFT_NAME.

An In-Depth Look at the Arduino Library

PollingInput

The DcsBios::PollingInput class is the base class of all input classes such as Switch2Pos or RotaryEncoder.

If your class inherits from PollingInput, its pollInput() method will be called whenever DcsBios::PollingInput::pollInputs() is called from the main loop.

To make this happen, the constructor of PollingInput maintains a global singly-linked list of all PollingInput instances.

ExportStreamListener

If your class inherits from ExportStreamListener, its onDcsBiosWrite(unsigned int address, unsigned int data) method will be called every time a ProtocolParser finishes receiving new export stream data.

Its onDcsBiosFrameSync() method will be called every time the synchronization sequence (0x55 0x55 0x55 0x55) is received. The StringBuffer class uses this to avoid calling your code with an inconsistent string mid-update.

ProtocolParser

If you feed the export stream data you receive from DCS-BIOS to the processChar method of a ProtocolParser instance, it will interpret the data and ensure that the global onDcsBiosWrite function as well as every ExportStreamListener’s `onDcsBiosWrite and onDcsBiosFrameSync methods are called with the results.

The DCS-BIOS Lua Code

DCS-BIOS is loaded by executing the BIOS.lua file. That file loads all other DCS-BIOS code.

The following is an overview of the other files and their purpose:

BIOSConfig.lua

This contains TCP/UDP settings

BIOS.lua

Sets up the export hooks to DCS and makes calls to write all modules to JSON.

lib/io

Contains all files needed for TCP/UDP transmission.

Protocol.lua

Writes modules to memory and JSON.

Module.lua

This is the main class which all aircraft modules inherits from. Contains all functions needed for creating input and export functions for a control.

lib/modules/air_craft/A-10C.lua, lib/modules/aircraft/UH-1H.lua, etc

Each aircraft module has its own file where all of its controls are defined.

Adding a New Aircraft Module

This section describes how to add support for another aircraft module.

Export Modules in DCS-BIOS

DCS-BIOS consists of several export modules (they are what you select in the "module" drop-down field in Bort or BIOSBuddy. Each export module is assigned to one or multiple aircraft and several export modules can be active at the same time.

The MetadataStart and MetadataEnd modules are special: they are always active, even if there is no active aircraft (e.g. in spectator mode in a multiplayer game). The CommonData module is always active when any of the aircraft in AircraftList.lua is active. It exports generic information like altitude, position and heading.

  • Each export module is defined in its own file in the aircraft_modules subdirectory.

  • Each export module is loaded by BIOS.lua.

Adding an Export Module for Your Aircraft

If this a new aircraft that doesn’t exist in dcs-bios then find out the exact name of your aircraft in DCS: World. To do this, open the Bort or BIOSBuddy while in your aircraft and look at the _ACFT_NAME value in the MetadataStart module.

Please visit the developer wiki for further instructions.

Tips

When developing you can log variables for a plane to the logfile (DCS-BIOS.log) which is in the same directory as dcs.log. Add this in the beginning of the file if it is not there already:

local Log = require("Scripts.DCS-BIOS.lib.common.Log")

Then call:

Log:log("YOUR DEBUG TEXT")

Log:log(your_variable)

Just remember to remove it after developing or the log file will be very big!