HOME Blog SimVimCockpit SimVimPanel Baron-58 sim ArdSimX About/Donate

ArdSim 4.x library function list


The functions described on this page are related to ArdSim library ONLY.

The latest ArdSimX Interface doesn't require any custom I/O functions.


ArdSim base code structure
The base code for ArdSim library includes these minumum required lines to start working with X-Plane. With this minimum you can assign all direct pins as buttons/switches in your input configuration file. Use example sketch named "ArdSim_Base":

Optional configuration:

With these options you can change default ArdSim configuration if you will need this or if you will have a problems with default settings.
Any of these lines should be placed in the "setup() { }" section only!:

USB_Serial 115200;      // change default 115200 baud USB serial speed to any allowable (you should set the same speed in the "config.ini" file of plugin too! )

XPLANE_IP (192,168,0,104);   // set IP address of X-Plane PC if you need it or you have a problem with autodetection

ARDUINO_IP (192,168,0,3);    //  set IP address of Arduino if you need it or you have a problem with autodetection

ARDSIM_PORT 5080;				 // change UDP port number if nedeed (you should set the same port in the "config.ini" file of plugin too! )

MAC_ADDR ( 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xFF );    // If you have a label with MAC address on your Ethernet shield use theis line, otherwise omit it!


List of user functions

SETUP FUNCTIONS

Matrix Inputs / Encoder port setup

You can use these two functions only if you need to extend your Arduino inputs or you don't want to add more Arduino boards to your system. To increase the number of digital inputs for buttons and switches use the "InputMatrix" function. Use less Arduino pins for more rotary encoders with "EncoderPort" function:

InputMatrix ( X1, X2, Y1, Y2);

Initial configuration function for the key matrix. Place in the "setup()" section. Use only if you have key matrix input.

X1 - First row pin number
X2 - Last row pin number
Y1 - First column pin number
Y2 - Last column pin number

For example: InputMatrix ( 22, 29, 30, 36); - the 48-input matrix (8x6) is using 8 pins for rows (22-29)
and 6 pins for columns (30-35)

Each input can act as a simple momentary button with "on-push" or "on-release" reaction or as toggle switch . To add repeating-on-hold function to specific input (button), use the function "RepeatBtn ()"

EncoderPort (PIN);

Initial configuration function for encoders input port. (place in the "setup()" section).
Used with following "EncoderPin" function.

PIN - encoders input port first pin number

This function reserves three Arduino pins for encoders input - PIN, PIN+1, PIN+2
EncoderPort ( 6 ); Example - Encoders port assigned on pins #6, 7 and 8.

Set OUTPUT mode for Arduino Pin function

Since all digital Arduino pins that are not used in key-matrix, encoder port and ArdSim library output functions are auto-assigned as INPUTS for buttons/switches, you can not use them for output. With this function you can reserve any pin or pin range for OUTPUT to use in your custom code for output devices.

OutputPin ( Pin, Pin1 );

Set pin to OUTPUT mode if you need it to be reserved for your output devices. Should be placed in the "setup()" section
OutputPin ( 6 ); - Reserve one Pin #6 for OUTPUT (it will not be used in the library input functions and will not be scanned as input)
OutputPin ( 6, 9 ); - Reserve pins #6...9 for OUTPUT (this pin range will not be used by the library and will not be scanned as inputs)

Set INPUT mode for Arduino Pin function

As default, all digital Arduino pins that are not used in key-matrix, encoder port and ArdSim library output functions are auto-assigned as INPUTS for buttons/switches. If you don't need to use any or all of the free Arduino pins as inputs use this function to assign only specific pins or pin range for INPUT to exclude excessive program inputs scan.

InputPin ( Pin, Pin1 );

Set pin to INPUT mode. Should be placed in the "setup()" section
InputPin ( NOINPUT ); - NO any free pins will be scanned as inputs (excluding thouse assigned as Encoders or Matrix inputs)
InputPin ( 22 ); - Assign one Pin #6 for INPUT (it will be used in the library input functions and scanned as button/switch input)
InputPin ( 33, 45); - Assign pins #33..45 for INPUT (this pin range will be scanned as inputs)




Inputs setup

These functions should be used for initial inputs configuraton and placed in the "setup" section of Arduino program.

Encoder input setup

Since version 2.1 of ArdSim library the encoder functions provide non-linear increment value for datarefs depending on the encoder rotation speed. For example, when a dataref value increments by one unit for each encoder step on low rotation speed, then on higher encoder rotation speed this increment will multiply for each step by a factor depending on the speed and ensures that you will always add the minimum increment on one step when you rotate encoder step by step and independed on encoder type

EncoderPin ( PIN, BM )

Assign input Pin numbers (2-3pins) for direct Encoder connection or one output pin number if encoder port is used and internal button mode (Location - in the "setup()" section)

PIN - pin number
BM - encoder internal button mode


- first of a 2...3-pin number for direct connection OR one output pin number for "port" connection.
- mode for the inbuilt encoder button ( 0, 1, 2-8 )

EncoderPin ( 22, 4 ); For direct encoder connection, buttons with 4 modes. Input pins used: #22, 23, 24
EncoderPin ( 22, 4 ); For "port" encoder connection - buttons with 4 modes. One Output pin used: #22
EncoderPin ( 5 ); Encoder with no button. Input pins used: #5, 6 if direct input used, or pin #5 if encoder port is used

Read encoder Mode

EncMode ( Enc )

This function returns current mode of chosen encoder.EncMode ( 4 );
EncMode (4);
// -- Read current mode of encoder #4
Note: The function "EncMode" returns value>0 only when the mode has been changed, otherwise it returns "0". I.e., you can check first if the EncMode(n) is not "0" to execute your code only upon encoder's mode change.

For Mode indication use the EncModeLED function - (below on this page)

Analog Inputs setup functions

Analog Axis Inputs setup function

To configure analog inputs as axis control only one function is used, that is located in the setup section and includes all needed parameters - analog pin number, sensitivity, and optional input value range.

AnalogIn ( pin, pre, min, max);

Configuration function for the analog input. Located in the "setup()" section
You can use this function as common analog inputs with potentiometers, such as flight controls, and as emulation of multi-position levers using potentiometers.

pin - Arduino analog pin number
pre - precision 2-1000
min - min. potentiometer value
max - max. potentiometer value


Arduino analog pin number from 0 to 16 for Mega
Precision, or number of steps, 2-1000 (1000 - maximum sensitivity, 2 - two-position lever)
(Optional, default=0) - min. potentiometer value, if you have to use the pot with partial stroke range
(Optional, default=1023) - max. potentiometer value, if you have to use the pot with partial stroke range


AnalogInput ( 1, 200 );
AnalogInput ( 5, 2 );
AnalogInput ( 0, 3 );
AnalogInput ( 0, 3, 0, 300 );


- A simple analog input with the precision of 200 steps for a full-stroke potentiometer (from 0 to 1023)
- A simple 2-position "switch" with potentiometer
- A 3-position lever (as flaps lever) with potentiometer
- A 3-position lever for a partial-stroke potentiometer (flaps)

Analog Multi-position Input setup function

With this function you can configure analog pin as input for multi-position switch, setting the number of fixed position for it. To assign control dataref or command to each rotary switch position you should use A0/1, A0/2 etc. IDs in your config file.

AnalogSwitch ( pin, step, mode);

Configuration function for the analog input that is used for multi-position switch, see Analog input as digital. Located in the "setup()" section

pin - Arduino analog pin number
step - number of positions
mode - repeat mode (for one position)


Arduino analog pin number from 0 to 16 for Mega
Number of positions for the rotary switch,
(Optional, default=0) - use this as a number of the position that is used for repeated command

AnalogSwitch ( 2, 6 );
AnalogSwitch ( 0, 5, 5 );
- A 6-position rotary switch for analog pin A2
- A 5-position (magneto) rotary switch on pin A0, the 5-th position used for repeated ignition command

Counter Mode Button

This is a button that cyclically switches between several modes for some custom actions. This button can be connected either directly to any free Arduino pin or to a matrix input. Place this function anywhere in your main loop code for the pin used as counter mode button.

Description is here
External Encoder Mode Buttons

Along with the encoders built-in button you can use any other input as external button for switching between various modes of the encoder. This button can be connected either directly to any free Arduino pin or to a matrix input. Place this function anywhere in your main loop code for each pin used as mode button. Note: Don't place this function in the "setup" section

EncModeBtn ( IN, Enc, "Mod", MX )

Button sets mode ("ModD") for chosen encoder when clicked. "MX" - is the keyword for matrix button (if button is connected to the matrix node). Description is here: Input Modes

IN - Arduino pin number (or node)
EN - encoder number
'M' - mode name (unique symbol)
"MX" - keyword for matrix button


- Pin number (button on the pin - D# ) or matrix node number (button is connected to this node - B# )
- number of the affected encoder (starting from 1)
- mode name should consist of one letter of alphabet except numbers ( numbers 1-8 are used for built-in encoder button mode). I.e. use symbols 'A', 'a', 'B', ...'W', 'Z', etc.


EncModeBtn ( 5, 3, 'A' ) // - Button on pin #5 sets mode "A' for encoder #3
EncModeBtn ( 6, 3, 'H' ) // - Button on pin #6 sets mode "H' for encoder #3
EncModeBtn ( 7, 3, 'V' ) // - Button on pin #7 sets mode "V' for encoder #3
EncModeBtn ( 8, 3, 'N' ) // - Button on pin #8 sets mode "N' for encoder #3
EncModeBtn ( 3, 5, 'R', MX ) // - Button on matrix in #3 sets mode "R' for encoder #5
EncModeBtn ( 60, 5, 'W' ) // - Button on matrix in #60 sets mode "W' for encoder #5 ( MX can be omited if the matrix node number is more than last number of Arduini pins)

For Mode indication use the EncModeLED function - (below on this page)
To read current mode use the EncMode function - (above on this page)


Custom functions

ReadInput ( IN, Act, MX )

Read an input current static state (On/Off) or dynamic state changes. This function returns "1" or "0" as a result of its static or dinamic state reading. You can use this result in your custom code.
in = ReadInput ( 5 ); // -- returns "1" if pin #5 is in "ON" state or "0" if pin state is "Off". The result is placed in the variable "in".
in = ReadInput ( 13, MX ); // -- the same as above, but for matrix input #13...
in = ReadInput ( 8, ON ); // -- returns "1" if the pin #8 state was changed from Off to On in the current program loop, "0" if not
in = ReadInput ( 22, OFF ); // -- returns "1" if the pin #22 state was changed from On to Off in the current program loop, "0" if not
in = ReadInput ( 6, OFF, MX ); // -- returns "1" if the matrix iput #6 state was changed from On to Off in the current program loop
in = ReadInput ( 66, ON ); // -- returns "1" if the matrix iput #66 state was changed from Off to On in the current program loop
MX keyword can be omited if the matrix node number is more than last number of Arduino pins ( e.g. for MEGA > 53, for UNO >13 etc.)


Send custom ID for command or dataref

SimInput (ID);

Direct input - send to X-Plane ID for specific command/dataref from your code.
SimInput ( 33 );

The corresponding line in the input config file:

C33 sim/radios/nav1_standy_flip




All major functions are the same for the LAN and USB connection but the LAN version has some additional functions for sending datarefs, commands, menu items and keyboard symbols directly to X-Plane by UDP, without configuring these actions in the input config file (beside plugin).


For the LAN vesion Only! Send command, dataref, symbol or open menu item

These basic functions that you can use for your custom code - send commands without using the output config file!

XPDref ( DRef, Val )

Send dataref and its value to X-Plane XPDref ( "cockpit2/controls/flap_ratio", 1 ); // Flaps Full position

XPCmnd ( Com )

Send command to X-Plane. XPCmnd ( "ice/pitot_heat0_on" ); // Pitot heat switch
XPCmnd ( "v" ); // Toggle parking brake (keyboard emulation)

XPMenu ( MenuNum )

Open X-Plane menu item. XPMenu ( 1800 ); // Send decimal menu number (1800 = view forward)






Output control

You don't need get data from X-Plane to control some outputs. ArdSim library includes functions that let you easily configure your output devices for a specific dataref value output. You can assign which dataref will be "linked" with a specific LED, servo, analog gauge etc.

Otherwise, if you need to get a specific dataref value for further output using your specific program code you can call the "GetData()" function of the library with just one argument - the number of the parameter in the out_#.cfg output list

Output - LEDs

LEDout ( NAME )

LEDout ( P, D, V, M, I )

Control the LED output with specific dataref. You can use this function with one argument that is previously defined constant "NAME" ( it is preferable), or use all 2-5 arguments directly without defining the named constantLEDout ( Pitot );
LEDout ( Flaps)
LEDout (8, 5, 0.5)
LEDout (10, 6, 0.4, 0,8, 1)
When defining the constant "NAME" in the beginning of the code you should assign at least two elements - the pin number for this LED output (P) and the dataref number (D). Next optional elements is the value of dataref on wich the LED should light up (V), another value of dataref for the value range (M). Last optional element "I" used to set inversion. Default V = 1, it means the LED is on when value =1.

#define NAME P, D, V, M, I


#define Pitot 10, 5
#define PitotHeat 10, 5, 0
#define Flaps1 11, 6, 0.5
#define Flaps2 12, 6, 0.4, 0.7
#define Flaps3 13, 6, 0.4, 0.7, 1


- Define Pitot LED connected to pin #10 and controlled by dataref #5
- The same as above but inverted output - the LED is on when value of dataref is 0
- Flaps LED on the pin #11, dataref #6, controlling dataref value = 0.5
- Flaps LED on the pin #12, dataref #6, controlling dataref range is 0.4-0.7
- Flaps LED on the pin #13, dataref #6, controlling dataref range is 0.4-0.7, inverted

LEDout ( Pitot )
LEDout ( Flaps1 )
LEDout ( Flaps2 )
LEDout ( Flaps3 )
// - Pitot LED on the pin #10, dataref #5. LED is on when value of dataref is 1
// - LED is ON only when flaps position = 0.5 ( useful for mutiple LEDs for one data range )
// - LED is ON when dataref value is in 0.4-0,7 range
// - LED is ON when dataref value is outside of 0.4-0,7 range

LEDout ( Pin, State )

Direct control of the LED. You can use this function if you need control the LED from your codeLEDout ( 13, ON );
LEDout ( 12, OFF)

if (your_condition==1) LEDout (13, ON);
if (your_condition==0) LEDout (13, OFF);


// -- Turn the LED on the pin #13 ON if your condition is 1
// -- Turn the LED on the pin #13 OFF if your condition is 0

Encoder Mode Indication - LEDs

EncModeLED ( Pin, Enc, Mode )

LED will be turning on or off, according to encoder mode.EncModeLED ( 13, 1, 4 );

EncModeLED (13, 1, 2);
EncModeLED (5, 4, 'D');


// -- Turn the LED (pin #13) ON if encoder#1 mode = 2
// -- Turn the LED (pin #5) OFF if encoder#4 mode = 'D'


Output control - Servo

servoGauge ( Dref, ServoName )

Assign which dataref (number "Dref") will be "linked" with a specific predefined servo ("ServoName"). servoGauge ( 6, Flaps );
The first argument (Dref) is the dataref number which is assigned for this dataref in the "out_1.cfg" file:

The second argument in this function ("ServoName") is the name of the preliminary defined construction in the beginning of your Arduino code. For example define the "Flaps" servo with control pulse range of 600-2200 mcsec connected to the pin #40, and dataref value range to control this servo 0.00 to 1.00 :

#define    Flaps        40, 0, 1, 600, 2200

.. where after the defined name ( Flaps ) you have to write five numbers:

1) Number of the Arduino Pin to which this servo is connected (pin #40 here)
2) Minimum value for the given dataref (0.00)
3) Maximum value for the given dataref (1.00)
4) The microseconds number which corresponds to the minimum value of dataref (560 here)
4) The microseconds number which corresponds to the maximum value of dataref (2100 here)

How to define the range of your particular servo: Servo control

Then place the servoGauge function for this example in the main code loop:

servoGauge ( 6, Flaps )



Output control - Coil ammeters

Gauge ( Dref, GaugeName )

Assign which dataref (number "Dref") will be "linked" with a specific predefined servo ("GaugeName"). Gauge ( 6, Flaps );
The first argument (Dref) is the dataref number which is assigned for this dataref in the "out_1.cfg" file:

The second argument in this function ("ServoName") is the name of the preliminary defined construction in the beginning of your Arduino code. For example define the "Flaps" servo with dataref value range to control this servo 0.00 to 1.00 :

#define    Flaps        5, 0, 1

.. where after the defined name ( Flaps ) you have to write 3 numbers:

1) Number of the Arduino Pin to which this servo is connected (pin #5 here)
2) Minimum value for the given dataref (0.00)
3) Maximum value for the given dataref (1.00)


Then place the Gauge function for this example in the main code loop:

Gauge ( 6, Flaps )


Output control - Get Data Values

If you need to get a specific dataref value for you output devices using your specific program code you can call the "GetData()" function (in conjunction with "NewData" function):

GetData ( DrefNum );

You can get the specific dataref value placing this function anywhere in your code
Nav1st = GetData(30);
// read dataref #30 every time, no matter if it changes or not.

NewData ( DrefNum );

You can check if the dataref value was changed in last loop with this function before reading value with the "GetData" function. It is very preferable to use this function to prevent excessive same data reading and sending them to output device.
if ( NewData (30) ) { 
  
  Nav1st = GetData ( 30 );
  
      // your code here
      }
Check if the dataref #30 value has been changed since last reading and if was, read this value and execute your program code








© Copyright 2012-2016 - SimVim Design