Skip to content

Latest commit

 

History

History
889 lines (612 loc) · 40.6 KB

userguide.adoc

File metadata and controls

889 lines (612 loc) · 40.6 KB
Raw

DCS-BIOS User Guide

Table of Contents

Welcome to the DCS-BIOS User Guide.

This manual will explain how you can use DCS-BIOS to connect the clickable cockpit of a DCS: World aircraft to real-world hardware such as toggle switches, push buttons, rotary encoders, potentiometers and displays.

Note
 If you want to add a new aircraft module or use your own software with DCS-BIOS, please refer to the Developer Guide.

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.

Introduction

So you want to build a panel for your DCS: World aircraft. Whether you own a CNC machine or just a drill and a hot glue gun, you probably have some idea of how to use the tools available to you to mount controls such as push buttons, toggle switches, rotary encoders and potentiometers to a faceplate.

Once you have done that, you need a way to connect these controls to your DCS: World aircraft. If your aircraft is supported by DCS-BIOS, read on to find out if DCS-BIOS is right for you.

Why Use DCS-BIOS?

The Home Cockpit section on the ED forums provides numerous examples of how to connect a switch panel to DCS. This section explains why you should pick DCS-BIOS over the alternatives.

DCS-BIOS is "easy to use".

You’ve heard of people trying to learn Lua just to write their own Export.lua file. In many cases this was an exercise in frustration. DCS-BIOS was produced so you don’t have to worry about learning how to make your own Lua files. If you can connect two wires together, copy and paste text and follow step-by-step instructions, you can make a functioning panel.

DCS-BIOS is fully documented

We understand the frustrations when you try to build something or use something that has little or no instructions. This document was produced to ensure you have the help you need. It was written in easy to understand terminology aimed specifically at the novice. You do not have to be a programmer or an electrical engineer to understand it. After you read this User Guide, you will be able to connect a simple switch panel to DCS.

If you do have a programming background or simply want to know more, we have a Developer Guide that explains the internal workings of DCS-BIOS in greater detail.

No noticeable performance impact

On a low-end system (running DCS at 10 to 15 fps), we did not notice any measurable performance impact. On a high-end system, running DCS-BIOS reduced the framerate from 55 fps to 52 fps (about 5% slower). The additional computation it requires of your PC or its precious resources is negligible.

DCS-BIOS will protect your switch panel from ED updates

"So ED just broke my switch panel with their latest update". DCS-BIOS will not let that happen. DCS-BIOS isolates your switch panel from the impact of any changes that Eagle Dynamics might introduce in an update. In the extremely rare event that Eagle Dynamics does make a change that breaks something, we will ensure DCS-BIOS is immediately updated. Your panels will always maintain their functionality.

DCS-BIOS has an extremely efficient protocol design

The communication protocol that DCS-BIOS uses to talk to your panel was designed with slow serial ports in mind. Your indicators, gauges and displays will never stutter or lag during a flurry of activity in the cockpit. Pressing the signal lamp test button when spooling up the engines, or when half your caution lights panel is blinking after a SAM hit will have no impact on how fast your cockpit instruments respond.

DCS-BIOS covers everything.

There are a variety of interface boards available that allow you to connect switches or rotary encoders or maybe even both to DCS. DCS-BIOS however, extends way beyond any solution you might presently find. In fact, it is the most comprehensive means of connecting your switch panel to any combination of your DCS aircrafts' buttons, switches, rotary encoders, potentiometers, push buttons, three way switches etc., etc. In short, if it can be manipulated using Lua, DCS-BIOS supports it.

DCS-BIOS makes use of the extremely popular Arduino ecosystem

DCS-BIOS was designed to work with the Arduino family of microcontroller boards. Why? The choice was easy. By using a popular, general-purpose microcontroller development board instead of designing a custom PCB, we benefit from the low cost associated with mass production and economics of scale. Suitable boards can be bought for approximately $25 from the official Arduino store. 100% compatible clones can be purchased on eBay or Amazon for just a few dollars each.

The popularity of the Arduino platform has also spawned a huge number of online tutorials, guides and blog posts. There is an almost endless supply of support available. In fact, you may also find numerous other uses for it besides controlling your cockpit.

No matter what you wish to connect to your Arduino board, its more than probable someone out there has already done it and documented the results for you to use.

Connecting your First Panel

The purpose of this next section is to demonstrate how easy it is to use DCS-BIOS to create a working switch panel and have it connect to your DCS aircraft. As an example, we will use a button and an indicator from the A-10C, but the principles are the same for other aircraft.

Before you start

The following prerequisites are necessary for the successful completion of this section:

Skills

  • Have a basic understanding of what an electric circuit is.

  • Know what a short-circuit is, why it is a Bad Thing™ and how to avoid creating one by accident

  • Have some way to make electrical connections. That can mean a "breadboard" and jumper wires, a soldering iron, a wire wrap tool, …​

Equipment

We will assume you have access to the following:

  • A computer that has DCS: World and the A-10C module installed with access to the internet and a free USB port

  • An Arduino board (the Arduino UNO is a good choice for beginners)

  • A momentary on push button (the kind that stays on as long as you are pressing it)

  • An LED (any colour and/or size) but not one of those super high powered, go blind if you look at it, types.

  • A 220ohm 1/4 watt resistor

  • 24 gauge wire or jumper wires

Step by Step Instructions:

Step 1: Setting up DCS-BIOS

1.1 Download the latest release of DCS-BIOS from GitHub and extract the ZIP file somewhere on your hard drive

1.2 Open a new Explorer window (for example by opening "My Computer"), paste the following into the address bar and press return:

%USERPROFILE%\Saved Games\DCS

This should take you to your DCS configuration folder (it has several subfolders including Logs and Missions).

1.3 If there is no Scripts subfolder in your Saved Games\DCS folder, create it.

1.4 Copy the Scripts\DCS-BIOS folder from the DCS-BIOS download to your Scripts folder.

1.5 If you do not have an existing Export.lua file in your Scripts folder, copy Scripts\Export.lua from the DCS-BIOS download to your Scripts folder. Then continue with step 2.

1.6 If you already have an Export.lua file, open it in a text editor (we recommend Notepad++) and append the following line to the end:

dofile(lfs.writedir()..[[Scripts\DCS-BIOS\BIOS.lua]])
Warning
 You should never use any word processing software to edit text files. Word processing software saves formatting information in the file which will render it unusable.

Note: If you use the Raygun Software from Buddyfox (A-10C UFC), this entry must be before the DCS-BIOS entry in the Export.lua !

Step 2: Connecting your LED and Push Button Switch

Before you start plugging in wires and resistors, take a few minutes and have a look at the Arduino board you are using. Get familiar with the pin designations printed on your board. It would be well worthwhile spending a few minutes on the Arduino web site and do a bit of reading on the basics of using Arduino boards. There are numerous YouTube videos that will introduce you to the world of Arduino. This will all help as you move forward to more complex types panels. So lets start…​

2.1 Connect your push button switch to your Arduino board at pin 10 and pin GND (ground).

Note
 There are several pins designated as GND (ground) on the board. They are all connected together. It doesn’t matter which one you choose.

2.2 Connect your LED and current limiting resistor to the Arduino board at pin 13 and pin GND (ground). Pay attention to the polarity of the LED before you connect it. The cathode, which is the negative side always goes to pin GND. Nothing will start smoking if you connect it backwards. It just won’t work until its connected properly.

When complete your curcuit should look like this:

651

  • Plug your Arduino board into a USB port. If any drivers are required there will be instructions as to how to install them. It does vary between Arduino boards but it’s no different really than installing a headset or joystick. The USB port provides power to the Arduino board but you can use a wallwart providing its 12v. There is an onboard jack to plug into.

You have now completed all of the required wiring for you first switch panel.

Note
 The USB port provides power to the Arduino board but many boards also have a jack that allows you use an external power supply such as a wallwart providing it supplies 7 to 12V and the centre pin is positive.

Step 3: Set up the Arduino IDE

I imagine your next question is "what is an IDE". The Arduino IDE is a program that you will download and install on to your PC. You use it to write small programs (they are called "sketches") and upload them to your Arduino board. You should probably read the page describing how to use the IDE on the Arduino web site. It is very simple and you should have little to no difficulty understanding what to do. So to continue…​

  1. Download and install the Arduino IDE from the Arduino website.

The Arduino IDE uses what are referred to as "Libraries" to help you make various types of devices work properly using a minimum of commands. There are libraries for using LCD displays, stepper motors, servos etc. It’s a long list. We have produced such a library for using DCS-BIOS and it is called the DCS-BIOS Arduino library. As with all libraries, it was developed to make your life easier when it comes to writing a sketch. However, libraries need to be installed and this next step will guide you through that process.

  • Download the DCS-BIOS Arduino library from GitHub. DO NOT extract it. It also doesn’t matter where you download the file to as long as YOU know where it is as you will need to point to its location in the next step.

  • Start the Arduino IDE

  • Click Sketch → Import Library → Add Library…​ and then go find the ZIP file you downloaded and select it. The Arduino IDE will do the rest. That’s all there is to importing libraries into the IDE.

  • Close and re-open your Arduino IDE. You are now ready to start you first sketch.

Congratulations, you have completed all of the one-time setup steps. From now on any panel that you create will only require you to complete steps 4 and 5.

Step 4: Create a sketch for your Arduino board

You are now going to create a sketch for your Arduino board that connects it to DCS and makes your switch and LED work as in your DCS aircraft cockpit. In order to simplify this process you will begin your sketch by opening a "template" that we have provided. Until such day as you become an Arduino programming expert you will start every new sketch with this template. It provides all of the essential code necessary to communicate with DCS. It automatically reads the state of your connected switches and reports this to DCS-BIOS which then updates the switches of your DCS aircraft.

Another function of this template is to automatically gather output data from DCS. You can use this data to make gauges function, displays work or indicator lights to light up. We will provide you with several examples in the appendix.

Note
 Take special care not to alter any of the existing code that comes with this template as you work on your sketch.

So lets begin:

  • Click File → Examples → DcsBios → IRQSerial to open the template program that comes with the DCS-BIOS Arduino library.

To develop a sketch for your panel, you are going to copy pieces of example code from a reference source.

  • Select "A-10C" in the "Module" dropdown menu and "UFC" as "Category Filter".

The first entry should be the one for the Master Caution Light.

  • In Bort make sure Show arduino scaffold code is checked.

  • In BIOSBuddy click API.

  • Select DcsBios::LED masterCaution(A_10C_MASTER_CAUTION_AM, PIN); and press CTRL+C

  • Now move to the Arduino IDE and paste this line in the space just below where it says "paste your code below here".

  • Now go back to your reference tool again, find the UFC_MASTER_CAUTION / Master Caution Reset entry.

  • As before, select the code snippet copy it to your clipboard.

  • Move to the Arduino IDE and paste this line in the space below the last one.

Did you notice the keywords referencing pins? These are temporary placeholders that you will be changing. PIN PIN_A PIN_B

  • Lets start with the switch that you are using to reset the Master Caution. You attached it to Pin 10 on the Arduino board. You now need to go into the Arduino IDE, to the line of code you pasted for the Master Caution Reset switch. Change the placeholder "PIN" to the pin that switch is connected to. In this particular case it was Pin 10. The word "PIN' gets replaced with 10. The line of code for the Master Caution switch should have changed as follows:

DcsBios::Switch2Pos ufcMasterCaution("UFC_MASTER_CAUTION", PIN);
DcsBios::Switch2Pos ufcMasterCaution("UFC_MASTER_CAUTION", 10);

  • You now do the same for the LED that respresents the Master Caution warning. As before, you go into the Arduino IDE, to the line of code you pasted for it. Change the word "PIN" to the pin number you connected the LED to. The word "PIN' gets replaced with 13. The line of code for the LED Master Caution warning should change as follows:

DcsBios::LED masterCaution(0x1012, 0x0800, PIN);
DcsBios::LED masterCaution(0x1012, 0x0800, 13);

  • Using address, mask and shift value macros In the code above you can see that there is a address (0x1012), mask (0x0800). These values can sometimes change which leads to the sketch not working anymore. You will find macros for all DCS-BIOS controls in Addresses.h. This file is auto-generated when DCS-BIOS starts. If you reference these macros instead you will have it easier when for some reason these values changes. You will still need to re-upload the sketch with the changed Addresses.h but you won’t have to modify your sketches. With macros the above code will look like this:

DcsBios::LED masterCaution(A_10C_UFC_MASTER_CAUTION_AM, 13);

Look carefully which macro to use.

  • Macro without special ending contains address, mask, shift

  • _A contains only address

  • _AM contains address and mask

When you have completed these changes, the beginning of your sketch should look like this:

#include <DcsBios.h>
#include <Servo.h>

/**** Paste your code below here ****/

DcsBios::LED masterCaution(0x1012, 0x0800, 13);
DcsBios::Switch2Pos ufcMasterCaution("UFC_MASTER_CAUTION", 10);

/**** Do not change anything below this line ****/

  • Click File → Save As to save it under a new name.

Note
 The Arduino IDE prevents you from saving changes to a library example. You will have to save your changes under a new name.

Your sketch is now finished and ready for the next step.

Step 5: Copy your program to your Arduino board

Now that your sketch is done, you need to load it onto your Arduino board.

The specifics of this process may vary slightly for different Arduino boards but for the most part they all follow the same basic routine. We use the Arduino UNO in this example.

Note
 The Arduino website has step-by-step instructions for each board.

  • With your sketch open in the Arduino IDE you need to tell the IDE what board you are using. Do this by Clicking on Tools → Board and then select your board from the list that is displayed.

  • Next, you will need to specify the COM port your board is connected to. Click Tools → Port and select the port from the list.

Note
 If you are unsure of the port number, it is identified in the Control Panel/Devices and Printers page.

  • The final step is to initiate the upload. This is done by clicking on the Arrow in the circle just below the Edit drop down menu. When the upload begins, a green bar will apear and show the progress of the upload. When it disappears the upload is complete.

  • After loading your program onto your Arduino board, you can close the Arduino software.

Step 6: Test your new panel

To connect DCS-BIOS with your serial ports you can either install DCSBIOSBridge or follow the instructions below.

DCS-BIOS comes with a script that connects a serial port to DCS. This serial port is the means by which your PC and your Arduino Board communicate. To initiate this connection you need specify the COM Port to use. You will use the same COM Port that the Arduino IDE used to program your board.

  • Double-click connect-serial-port.cmd which must be downloaded seperate at the release Page. Choose Source code(zip) and in the Programms folder you find it. A console window should pop up. Type in the number of the COM port that your Arduino board is connected to and press Return. Leave the console window open.

You can now start DCS and try your new panel in action!

If you don’t want to type in the COM port number every time you run the script, you can edit the script (or a copy of it) so it always uses the same port:

  • Start Notepad++. Open the connect-serial-port.cmd file which is in the DCS-BIOS folder you previously downloaded. Near the top of the file, you will see a line that says set COMPORT=ASK. Replace ASK with the number of the COM port you wish this script to use. For example, to use COM5, the line should look like this:

set COMPORT=5

  • Save the file and close Notepad++.

Warning
 If you make a copy of the script, you need to place it in the same folder as the original. Otherwise it will not find the socat executable.

Summary

You can make any panel you like using this template file.

  • Add the lines of code from any of the DCS-BIOS Reference Tool to your sketch for the switches and/or LED’s you wish to use.

  • Upload that sketch to your Arduino board.

  • Connect the appropriate switch type and/or LED to the appropriate pin number on the Arduino board.

  • Initiate the serial connection to DCS.

  • Begin using your switches and LED’s in your DCS aircraft.

What this Guide IS NOT

If your intent is to include displays and/or analog gauges with your panels you will need to have additional programming knowledge. There are displays in the aircraft that could incorporate LCD displays, LED displays or OLED displays. In addition there are analog Gauges in the cockpit that could be built using stepper motors, servos or even air core motors. With such a wide choice of components available, it really is beyond the scope of this particular document to provide instruction on every possible solution.

In Conclusion…​

What we are providing is the means to allow any novice cockpit builder to create a functioning switch panel and/or LED Indicators that will interact with their DCS aircraft. Most importantly, you do not need to be a programmer or electronic engineer to accomplish this task. With DCS-BIOS, it’s straight forward.

A Closer Look at The DCS-BIOS Arduino Library

This tutorial will show you how to read the DCS-BIOS references tools to create a sketch for any panel in the cockpit.

It will cover all of the different control types that are supported by the Arduino library. The information provided at this point may require some level of knowledge with Arduino programming.

The MasterCaution Example Sketch

This section takes a closer look at the different parts of the MasterCaution example sketch.

/* use '#define DCSBIOS_DEFAULT_SERIAL' instead if your Arduino board
 *  does not feature an ATMega328 or ATMega2650 controller.
 */
#define DCSBIOS_IRQ_SERIAL // (1)
#include "DcsBios.h" // (2)

DcsBios::LED masterCaution(0x1012, 0x0800, 13); // (3)
DcsBios::Switch2Pos ufcMasterCaution("UFC_MASTER_CAUTION", 10); // (4)

void setup() {
  DcsBios::setup(); // (5)
}

void loop() {
  DcsBios::loop(); // (6)
}


}

  1. Before including DcsBios.h, you have to define a preprocessor macro that tells the DCS-BIOS Arduino Library what mode it should operate in. If you are using an Arduino board that has either an ATMega328 or an ATMega2560 chip, such as the Uno, Pro Mini, Nano or Mega 2650 boards, use DCSBIOS_IRQ_SERIAL. If your board has a different microcontroller, you can use DCSBIOS_DEFAULT_SERIAL instead, which should work with any Arduino-compatible board but can cause problems if your sketch spends a long time updating outputs, either because you are outputting to something "slow" like displays or you are using a lot of outputs (such as trying to run a Caution Lights Panel with 48 instances of DcsBios::LED).

  2. This line adds the DCS-BIOS Arduino Library to your sketch.

  3. This line tells the DCS-BIOS Arduino Library to use the built-in LED on your Arduino board, which is connected to pin 13, as a master caution light. (For some Arduinos the built-in LED may be 13, 15 or 17 - check your Arduino model documentation for the correct pin)

  4. This line tells the DCS-BIOS Arduino Library that there is a switch connected to pin 10 that should be mapped to the master caution reset button. Use your DCS-BIOS Reference Tool to get more examples.

  5. In your setup() function, you have to call DcsBios::setup() to initialize the DCS-BIOS Arduino Library.

  6. In your loop() function, you have to call DcsBios::loop(). This causes the DCS-BIOS Arduino library to notify DCS if any inputs (push buttons, switches, etc.) have changed, and to update any outputs (LEDs, servo motors, displays, etc.) with the latest data from DCS.

Using the DCS-BIOS Reference Tools

Recall the following part from the MasterCaution example:

DcsBios::Switch2Pos masterCautionBtn("UFC_MASTER_CAUTION", 10);
DcsBios::LED masterCaution(0x1012, 0x0800, 13);

Unless you are doing something more advanced such as using something other than a serial port to talk to your DCS computer, this is the only part you need be concerned with.

Even without knowing much about DCS-BIOS, you might have guessed that this says there is a push button connected to pin 10 that should operate the master caution button and that the LED on pin 13 should light up then the master caution button does.

But how do you know what to put here for other controls? You will find this information from the DCS-BIOS Reference Tool you want to use.

Finding the Control You Are Looking For

First, select the module. Second, select category.

Supported Controls

DCS-BIOS refers to switches, rotary encoders, potentiometers, push buttons etc. as "CONTROLS". The following are all of the supported Controls available in DCS-BIOS:

  • DcsBios::ActionButton

  • DcsBios::Switch2Pos. defines a 2 position swich

  • DcsBios::Switch3Pos. defines a 3 position switch

  • DcsBios::SwitchMultiPos. defines a rotary switch, you provide how many positions

  • DcsBios::Pot. defines a potentiometer

  • DcsBios::RotaryEncoder. defines a rotary encoder

DCS-BIOS also includes indicator LED’s in the Controls as follows:

  • DcsBios::LED. defines an LED

Each control is identified by a unique identifier and is associated with a category, which is usually the panel it is found on in the DCS aircraft cockpit.

example:

DcsBios::SwitchPos2 ahcpCicu("AHCP_CICU", PIN);

  • whereas ahcpCicu indicates the CICU switch on the AHCP panel.

  • The first notation between the brackets "AHCP_CICU" is a placeholder for a piece of data that gets sent to DCS when a change occurs to a pin on the Arduino board.

  • The second notation PIN is also a placeholder however, you have to replace it with the pin number that your control is attached to. There also a few knobs/switches in your cockpit represented with two separate controls. For example, the volume controls on the A-10C intercom panel have one DCS-BIOS control for the volume and a separate control for the mute function.

Input Interfaces

Note
 To make sense of the following, select "Advanced" in the "View" dropdown box at the top of the page.

An input interface describes the means by which controls in the cockpit can be manipulated. .Types of input interfaces

set_state

If a control supports the set_state interface, its current state can be set by sending it a number as an argument. For example, you can set the TACAN mode dial in the A-10C to the A A REC position by sending TACAN_MODE 3.

Note
 The range of acceptable values is 0 to the maximum value of the control’s first output.

The DCS-BIOS Reference Tool will offer example code for a DcsBios::SwitchMultiPos and (where appropriate) a DcsBios::Switch2Pos or DcsBios::Switch3Pos.

fixed_step

If a control supports the fixed_step interface, you can increase its position with an INC argument and decrease its position with a DEC argument. An example would be a rotary encoder used to change the frequency of a VHF radio.

The DCS-BIOS Reference Tool will offer example code for a DcsBios::RotaryEncoder.

action

This represents an action such as toggling a toggle switch or changing the X/Y digit of the TACAN channel.

The DCS-BIOS Reference Tool will offer example code for a DcsBios::ActionButton.

variable_step

If a control supports the variable_step interface, you can increase or decrease its position by a certain amount by sending +NUMBER or -NUMBER as an argument, where NUMBER is an integer.

The DCS-BIOS Reference Tool will offer example code for a DcsBios::RotaryEncoder. The default step size is 3200. You will need to experiment to get the right sensitivity.

Outputs

Each DCS-BIOS control can have multiple related outputs. An output represents a piece of information that is exported from DCS, for example the position of the flaps position indicator.

Outputs come in two types:

Integer outputs

Most outputs are integers. Each integer output has an associated maximum value and a minimum value of 0.

The DCS-BIOS Reference Tool will offer code examples for DcsBios::LED and DcsBios::ServoOutput where appropriate.

The first code snippet for integer outputs is meant to be inserted into the onDcsBiosWrite function if the DCS-BIOS Arduino library cannot do what you want. It shows you how to extract the value using the address, mask and shift value of the output.

Note
 To learn about the meaning of the address, mask and shift value of an output, please refer to the developer guide.
String outputs

Some values (such as radio frequencies) are exported as character strings. The DCS-BIOS Reference Tool will provide a code example that uses a DcsBios::StringBuffer to execute a piece of code whenever the value changes.

Note
 Because there are many different types of displays (7-segment, character, graphical) and different ways to connect them to a microcontroller (direct, I2C, SPI), the DcsBios library does not include code to handle them. For most common combinations of display type and connection method, you can find other Arduino libraries online that allow you to talk to them.

Copy and Paste Example Code

To use the example code from the DCS-BIOS Reference Tool in your Arduino sketch, you first have to choose which code example to copy. That depends on what type of control you want to connect.

For example, you might want to use a rotary switch for the TACAN mode dial in the A-10C and use the DcsBios::SwitchMultiPos code snippet. For the same control, you could also choose to use a rotary encoder.

After choosing a code example, copy it to your Arduino sketch (refer back to the MasterCaution example to see where to copy it) and replace all the parts in red with your own values (usually the pin numbers that this control is connected to).

Refer to the next section for more detailed information on the individual classes, including example circuits.

Arduino Library Reference

Switch2Pos

DcsBios::Switch2Pos(char* message, char pin)

The Switch2Pos class handles inputs that have two states, such as toggle switches and push buttons.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

pin

The number of the Arduino pin the button or switch is connected to

Circuit

Connect the toggle switch or push button between the Arduino pin and ground.

DCS-BIOS Reference Tool Code Examples
DcsBios::Switch2Pos ahcpCicu("AHCP_CICU", PIN);
DcsBios::Switch2Pos ufcHack("UFC_HACK", PIN);

Switch3Pos

DcsBios::Switch3Pos(char* message, char pinA, char pinB)

The Switch3Pos class handles inputs that have three states, such as three-position toggle switches or rotaries.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

pinA

The number of the Arduino pin that the first switch position is connected to

pinB

The number of the Arduino pin that the last switch position is connected to

Circuit

Connect your three-position toggle or rotary switch so that the first (left or down) position connects pinA to ground and the last (right or up) position connects pinB to ground.

The Switch3Pos class defaults to the center position, so (if your switch even has a pin for that) you don’t have to connect it to anything.

500
DCS-BIOS Reference Tool Code Examples
DcsBios::Switch3Pos aapSteer("AAP_STEER", PIN_A, PIN_B);

SwitchMultiPos

DcsBios::SwitchMultiPos(char* message, const byte* pins, char numberOfPins);

The SwitchMultiPos class handles rotary switches.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

pins

An array of pin numbers that the rotary switch positions are connected to. The first pin number corresponds to state 0 of the input, the second to state 1, etc.

numberOfPins

The length of the array passed in the pins parameter.

Circuit

Connect the rotary switch so that it connects the Arduino pin for the currently selected position to ground.

DCS-BIOS Reference Tool Code Examples
const byte aapSteerptPins[3] = {PIN_0, PIN_1, PIN_2};
DcsBios::SwitchMultiPos aapSteerpt("AAP_STEERPT", aapSteerptPins, 3);
Example
// A rotary switch that controls the A-10C steerpoint mode (FLTPLAN / MARK / MISSION)
// is connected to digital pins 10, 11 and 12
const byte aapSteerptPins[3] = {10, 11, 12};
DcsBios::SwitchMultiPos aapSteerpt("AAP_STEERPT", aapSteerptPins, 3);

Potentiometer

DcsBios::Potentiometer(char* message, char pin);

The Potentiometer class handles potentiometers connected to an analog pin.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

pin

The number of the pin that is connected to the potentiometer.

Circuit

Connect the outer pins of the potentiometer to +5V and ground. Connect the middle pin to the Arduino.

500

To reverse the direction, swap +5V and GND.

DCS-BIOS Reference Tool Code Example
DcsBios::Potentiometer cmscBrt("CMSC_BRT", PIN);

RotaryEncoder

DcsBios::RotaryEncoder(const char* message, const char* decArg, const char* incArg, char pinA, char pinB);

The RotaryEncoder class handles standard rotary encoders, 2-bit grey code, 20 position detents.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

decArg

The argument that should be sent when the encoder is turned one step to the left.

incArg

The argument that should be sent when the encoder is turned one step to the right.

pinA

The first pin that is connected to the encoder.

pinB

The second pin that is connected to the encoder.

Circuit

Rotary encoders usually have three pins (the ones with an integrated push button have two extra pins for a momentary on push button). Connect the left pin and right pins to any two of the Arduino pins 2 through 12, A0 through A5, and the middle pin to ground. If you find it is functioning opposite to what you want you can just swap Pin A and B on the board or in the sketch.

500

To reverse the direction, either swap decArg and incArg or swap pinA and pinB.

DCS-BIOS Reference Tool Code Example
DcsBios::RotaryEncoder tacan1("TACAN_1", "DEC", "INC", PIN_A, PIN_B);

ActionButton

The ActionButton class is used to send a single command to DCS when its input pin goes low.

Constructor Parameters
message

The message that should be sent. Set this to the identifier of the control.

argument

The argument that should be sent.

pin

The number of the Arduino pin the button is connected to.

Circuit

Connect a push button between the Arduino pin 10 and ground.

500

The button on pin 10 toggles the CICU switch

DCS-BIOS Reference Tool Code Example
DcsBios::ActionButton ahcpCicuToggle("AHCP_CICU", "TOGGLE", PIN);
Code Examples
DcsBios::ActionButton ahcpCicuToggle("AHCP_CICU", "TOGGLE", 10);

LED

DcsBios::LED(unsigned int address, unsigned int mask, char pin)

The LED class is used for indicator lights.

Constructor Parameters
address

The address of the integer output

mask

The mask of the integer output

pin

The number of the Arduino pin that the LED (and current-limiting resistor) are connected to. Prior to connecting multiple LED’s to your Arduino board, it would be advisable to read the section on LED’s on the Arduino web site.

500
Figure 1. Circuit
DCS-BIOS Reference Tool Code Example
DcsBios::LED tacanTest(0x10da, 0x0400, PIN);
Note
 Arduino boards are only capable of providing 40mA of current per pin. Multiple LED’s connected to a single pin will require additional circuitry to avoid damaging the board.

ServoOutput

DcsBios::ServoOutput (unsigned int address, char pin, int minPulseWidth, int maxPulseWidth)
Circuit

Servos have 3 wires which are black, red and orange or yellow. Black and red are for 5V power in. The orange or yellow wire is the signal and must be plugged into one of the PWM pins having the ~designation. On the Uno those pins are ~3, ~5, ~6, ~9, ~10, ~11.

500

The ServoOutput class handles standard "hobby servos".

Constructor Parameters
address

The address of the integer output

pin

The number of the Arduino pin that is connected to the servo’s control input

minPulseWidth

The pulse width (in microseconds) that corresponds to the lowest servo position

maxPulseWidth

The pulse width (in microseconds) that corresponds to the highest servo position

A DCS-BIOS output value of 0 will be mapped to minPulseWidth, the maximum output value of 65535 will be mapped to maxPulseWidth. You will have to choose these values so that the minimum and maximum positions are at the beginning and end of your gauge’s scale.

DCS-BIOS Reference Tool Code Example
DcsBios::ServoOutput vvi(0x106e, PIN, 544, 2400);
Note
 Servos are devices which have the potential to demand more current than a single Arduino board can safely provide. Connecting multiple servos to one Aduino board will require an external power supply. Further reading at the Arduino site will be required to ensure the board does not get damaged.

IntegerBuffer

DcsBios::IntegerBuffer(unsigned int address, unsigned int mask, unsigned int shift, void (*)(unsigned int) callback)

The IntegerBuffer class is used to handle integer outputs in a generic way. You have to supply your own code to do something useful with the data.

Constructor Parameters
address

The address of the integer output (found in the DCS-BIOS Reference Tool)

mask

The mask of the integer output (found in the DCS-BIOS Reference Tool)

shift

The number of bits to shift left (found in the DCS-BIOS Reference Tool)

callback

A function which accepts an argument of type unsigned int. This function will be called whenever the integer output has changed. It will be passed the new value as an argument.

void onAlt10000ftCntChange(unsigned int newValue) {
    /* your code here */
}
DcsBios::IntegerBuffer alt10000ftCntBuffer(0x1080, 0xffff, 0, onAlt10000ftCntChange);

StringBuffer

DcsBios::StringBuffer<MAXLENGTH>(unsigned int address, void (*)(char*) callback)

The StringBuffer class is used to handle string outputs in a generic way. You have to supply your own code to do something useful with the data. A common use case is to use another Arduino Library to write it to some kind of display, such as a character LCD with a HD44780 compatible controller chip (LiquidCrystal library), a small OLED display with an SSD1306 controller chip (Adafruit SSD1306 library) or a 7-segment display driven by a MAX7219 chip (LedControl library).

Constructor Parameters
MAXLENGTH

The maximum length of the string output

address

The address of the string output

callback

A function which accepts an argument of type char*. This function will be called whenever the string output has changed. It will be passed the new value as an argument.

DCS-BIOS Reference Tool Code Example
void onUhfFrequencyChange(char* newValue) {
    /* your code here */
}
DcsBios::StringBuffer<7> uhfFrequencyBuffer(0x1180, onUhfFrequencyChange);

Aircraft-Specific Notes

A-10C

CMSP, CMSC and UHF Frequency Export in external view

These values will not be updated by DCS when the cockpit is not rendered (e.g. in external view or HUD-only view).

The solution is to assign another viewport to these indicators (through MonitorSetup.lua), so they exist even when the cockpit is not shown. You can make the viewport 1x1 pixels in size and place it outside of your visible screen area. For example, if you have no monitor above the primary one, you could place the viewport at coordinates (0, -10).

Arduino compatible Hardware

Stepper Motors

X27-168 - Stepper Motors working fine

Good Sites for Stepper Motors Tutorials: