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/docand double-click on the filecontrol-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.
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).
|
Warning
|
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.
|
|
Note
|
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).
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.
|
Note
|
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 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.
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) >> shiftChanges 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
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).
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.
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.
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.
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.
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.
This section describes how to add support for another aircraft module.
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_modulessubdirectory. -
Each export module is loaded by
BIOS.lua.
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.
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!