Input2Ivy

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. In order to use it you need type 'make' in this folder after building the whole paparazzi sources (it will be added in the default set of compile program in the future).

The compiled programs are:

• the C library usb_stick (we are planing to use SDL in the future for better cross-platform integration)
• input2ivy (ocaml main program that uses usb_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="BOOZ_NAV_STICK">
   <field name="vx_sp" value="-pitch"/>
   <field name="vy_sp" value="roll"/>
   <field name="vz_sp" value="(up-down)*127"/>
   <field name="r_sp" value="(right-left)*127"/>
  </message>
  <message class="ground" name="JUMP_TO_BLOCK" on_event="shoot && button1"/>
   <field name="block_id" value="IndexOfBlock('land')"/>
  </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

TBD

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_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.

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)