From PaparazziUAV
Jump to: navigation, search

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:


Start with the node 'joystick', no DTD yet.

   <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"/>

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
   <var name="mode" default="0"/>
   <set var="mode" value="0" on_event="button1"/>
   <set var="mode" value="1" on_event="button2 && shoot"/>

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 class="ground" name="JUMP_TO_BLOCK" on_event="shoot && button1"/>
    <field name="block_id" value="IndexOfBlock('land')"/>
   <message class="ground" name="DL_SETTING" on_event="button2">
     <field name="index" value="IndexOfSetting(kill_throttle)"/>
     <field name="value" value="1"/>

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)

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


First calibrate your joystick as described on the Joystick page.

In flight trimming is to be done...


$ ./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 -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)