Input2Ivy

Tools
__TOC__
Input2Ivy is an Ivy agent written in Ocaml/C used to read inputs coming from joysticks or joypads and to send Ivy messages accordingly.
= Compiling Input2Ivy =
The program is located in sw/ground_segment/joystick. It should already be compiled with the top level make, you also can explicitly build it with make in sw/ground_segment/joystick
* the C library sdl_stick (using SDL)
* input2ivy (ocaml main program that uses sdl_stick)
* test_stick (a small C test program that display raw values of your joystick)
= Configuration and use =
== Xml configuration file ==
Input2Ivy reads the configuration of your input device in a xml file located in conf/joystick. The format is as follow:
 <joystick>
Start with the node 'joystick', no DTD yet.
 <input>
 <axis index="0" name="roll"/>
 <axis index="1" name="pitch"/>
 <axis index="2" name="throttle"/>
 ...
 <button index="0" name="shoot"/>
 <button index="1" name="button1"/>
 <button index="2" name="button2"/>
 ...
 </input>
In this section, all the axis and buttons are described with an index and a name. Both have to be unique.
* the index is the actual axis or button number of your input device (you can use 'test_stick' to determine each index)
* the name is chosen by the user
 <variables>
 
 <set var="mode" value="0" on_event="button1"/>
 <set var="mode" value="1" on_event="button2 && shoot"/>
 ...
 </variables>
The section 'variables' allows to declare local variables to the program, those value can be changed based on inputs event. First you need to declare the variable with a default value (integer) and then each event is describe with the 'set' node. It is possible to use logical "C-like" expression for the event (&&, ||, <, >, ...).
 <messages period="0.1">
 <message class="datalink" name="RC_4CH" send_always="true">
 <field name="mode" value="mode"/>
 <field name="throttle" value="Bound(0-ly,0,127)"/>
 <field name="roll" value="roll"/>
 <field name="yaw" value="yaw"/>
 <field name="pitch" value="pitch"/>
 </message>
 <message class="ground" name="JUMP_TO_BLOCK" on_event="shoot && button1"/>
 <field name="block_id" value="IndexOfBlock('land')"/>
 </message>
 <message class="ground" name="DL_SETTING" on_event="button2">
 <field name="index" value="IndexOfSetting(kill_throttle)"/>
 <field name="value" value="1"/>
 </message>
 ...
 </messages>
The 'messages' section describes the messages sent to Ivy.
* the 'period' attribute define the period for sending the messages. A message is send only the at least one of its field has changed since last sending. Only messages with 'send_always="true"' are always sent.
* the 'message' node attributes are:
** class: the class of the message (defined in conf/messages.xml) (mandatory)
** name: the name of the message (defined in conf/messages.xml) (mandatory)
** send_always: always send message the 'period' frequency if set to "true" (optional)
* the 'messages' children are the field of the message as describe in conf/messages.xml, except for the field 'ac_id' that is automatically set if needed.
* the 'field' node attributes are:
** name: the name of the field (mandatory)
** value: the value to be sent (here, expressions can be used, see below) (mandatory)
 </joystick>
Close 'joystick' node.
== Expressions and functions ==
* parenthesis: (, )
* operators: +, -, *, % (divide, / is not allowed)
* logical, comparator: &&, ||, <, >
* functions:
** Scale(x, min, max): scale the value in the given bounds (input bounds are [-127, 127]
** Fit(x, min, max, min_input, max_input): some as 'Scale' with custom input bounds
** Bound(x, min, max): bound the value between [min,max]
** PprzMode(x): returns 0 if input is less than -127/2, 2 if greater than 127/2, 1 otherwise
** JoystickId(): returns the joystick ID
== Trims ==
First calibrate your joystick as described on the Joystick page.
In flight trimming is to be done...
= Usage =
 $ ./sw/ground_segment/joystick/input2ivy [options] config_file.xml
The options are:
* -ac <AC name> the name of your aircraft (mandatory)
* -b <ivy_bus> the an ivy bus address (default address used if not set)
* -d <device_index> set the SDL device index (default is 0)
** for paparazzi versions older than v4.2 use: -d <device_name> set the device name (default is /dev/input/js0))
* -v verbose mode (can also be used to identify the channels)
* -id set the joystick ID (in range [0,255], a random value is chosen if not set)
Do not forget the configuration file name after the options.
Example invocation on Mac OS X using a SNES gamepad configuration as input:
 $ ./sw/ground_segment/joystick/input2ivy -b 224.255.255.255:2010 -ac Teensy_Fly_Quad_Elle0_v1_2_214 -d 0 snes_gamepad.xml 
Input2Ivy can be launched from the Paparazzi Center if your conf/control_panel.xml have the correct 'program' entry. (See conf/control_panel.xml.example)
Category:Tools