ARDref Arduino Library ( up to July, 2015)
ARDref project was initiated as alternative for XPData library and has different data exchange protocol.
- ARDref uses the plugin for data exchange between X-Plane and Arduino (without using built-in X-Plane UDP DATA protocol as XPData did). ARDref library works in conjunction with ARDref plugin using LAN UDP connection only.
- Opposed to previous XPData libray no need to use functions with commands/datarefs for each pin in Arduino program code, the program includes only a small base code and ARDref library.
- All configuration for Arduino inputs/outputs functions is presented as a simple "input and output config" text file. These two files for input and output are located in the plugin folder. All configuration for inputs (and outputs) was made using our "online configurator" for ARdref
- For additional inputs/outputs you can add more Arduino boards (Uno, Mega, Micro etc ...) connecting them to the "master" board using 2-wire I2C bus.
- No need to assign inputs (their modes) in Arduino and specify the input scan functions - the plugin will automatically send all configuration data to Arduino upon connection.
- Some functions was included to the Arduino library for easier handling of outputs, such as LEDs and Servos.
In online input configurator for ARDref you can easily assign any Arduini pin for the input action you need - for Toggle button, Increment button, Set button, Toggle switch or Encoder.
As a minimum, for basic input/output interface only one Arduino Mega with Ethernet Shield and with the little "master" program uploaded to it. All Arduino boards in the system should use the ARDref Library - you need to upload the program code to every board using this library, adding it to Arduino IDE.
All Arduino boards in the system should use the ARDref Library - you need to upload the program code to every board using this library, adding it to Arduino IDE.
Each additional Arduino board sends the status of their input pins, including analog, to the plugin only upon changing, so that the average program cycle takes just a few milliseconds (from 1 to about 5 ms). Each analog input is configured with its specified precision - from 2 to 1000 steps of sensitivity. The plugin also transmits dataref values to the Arduino only when they are changed, with specified precision for each.
If you have your main PC connected to remote internet router (which is unreachable) by WiFi or cable and the computer has another LAN adapter you may connect Arduino with Ethernet Shield to PC with a cross-link cable directly (or using a simple switch). In this case you have to assign IP Address for Arduino in the beginning of the master code.
Also, if the plugin cannot determine the IP-address of your PC or determines it incorrectly (see "ARDref-About" window), you may have to assign your X-Plane PC IP address in the "config.ini" file located in the ARDref plugin folder (the line IP_ADDRESS = auto, replace "auto" with your IP)
Download ARDref plugin for X-Plane with ARDref library for Arduino
(Linux, Windows, Mac OS)
In Arduino IDE menu "Examples" --> "ARDref" folder you will find the "master code" for the main Arduino (communication with plugin/X-Plane, master/slave connections, inputs processing, output data processing using "ARDref Library") and sample programs.
If you use more slave boards, upload the "ARDref_slave" code to every additional slave Arduino board.
- Download the ARDref plugin, and place it into /plugins folder (the new folder named "ARDref" has to appear in X-Plane-10 "Resources/plugins" folder).
- Download the "ARDref Library" zip file and install the library to your Arduino IDE (Use IDE version more than 1.0.5):
- If you will use only one Arduino Mega for Inputs only or Inputs/outputs - just connect your ethernet cable between the Ethernet shield and the router/switch (or cross-over direct).
- All analog inputs assigned for input in the config file (in_1.cfg) should be used, i.e. actuators (potentiometers, etc.) should be connected to them
(or, connect assigned but temporary unused analog inputs to the GND, else the program will constantly send fluctuated values to the plugin )
- If you will use digital pins #0 and #1 for switches (not for normally-open buttons) make sure the switch is in open position or disconnect it while uploading code to Arduino as these pins are shared for serial communication with the computer and could prevent upload (connect actuators to those pins again and use after the code has been uploaded).
- If your Arduino/Ehernet shield is powered through +5v USB cable it can be not enough to work. It is better to have external power supply (+9v) connected to the Arduino board's power jack (center-positive).
- If additional slave Arduino boards are used (for outputs or inputs) - you need to connect all boards with I2C link. (See the picture below).
(Mega and Uno board use different pins for I2C connection - (digital #21,21 for Mega and analog # A4,A5 for Uno)
- When you have the slave board conneced to I2C keep it powered. If the slave board is turned off but connected, the master Arduino will stop sending data to X-Plane. So, if you are not using a slave board at the moment, disconnect it from I2C or keep it powered.
The Diagram shows how to connect several Arduino using I2C bus:
I2C bus has 2 wires with pullup resistors. Also, all boards must have the common wire connected (GND). Each board is connected to the bus in any order, and devices can be "masters" or "slaves". Master can write data to a slave, or read data on request. Each device has a unique address (slave has, for master Arduino it is optional).
Changes in the plugin v 1.28:
Changes in the library version 2.2 and plugin v 1.27 include:
- The changes in the library version 2.0 include:
- no longer need to assign inputs (their modes) in Arduino and specify the input scan functions - the plugin will automatically send all configuration data to Arduino upon connection.
- improved handling of Arduino/X-Plane/Plugin start or reset. They will automatically reconnect in any case.
- new functions added to the Arduino library for easier handling of outputs, such as LEDs and Servos. (functions for other output devices will be added upon library progress)
- for more stable work the protocol of Arduino/plugin data exchange has been changed, so you will need to use the new plugin version together with the corresponding library version. Make sure to download both of them when the new version is released.