Es/Joystick

¿Podrias imaginar un piloto en su Cessna controlando la máquina solo con el teclado? Para conseguir la sensación propia de volar necesitarás un joystick/yoke mas unos pedales rudder. Sin embargo, la combinación de numerosos tipos de joysticks, mandos de vuelo, cuernos, pedales etc. existentes en el mercado con objetivo de usarse en diferentes sistemas operativos, hacen del soporte de joystick una tarea nada trivial en FlightGear.

FlightGear ha integrado soporte de joystick, el cual automáticamente detecta cualquier palanca de mando, cuernos, pedales o volante conectados. Tan solo pruebalo! Si esto no te funciona, ponte comodo y se feliz! Puedes ver como FlightGear ha detectado tu joystick seleccionando Help -> Joystick Information desde el menu.

Desafortunadamente, dadas las diferentes combinaciones de sistemas operativos soportados por FlightGear (possiblemente en otros lenguajes) y joysticks disponibles, pueda hacer que tu joystick no funcione fuera del conjunto. Básicamente, hay dos accercamientos alternativos de hacerlo funcionar, siendo el primero como el preferido.

Incorporar soporte de joystick

Observaciones generales

Para hacer que la auto-detección del joystick funcione, un archivo xml vinculante debe existir para cada palanca de mando. Este archivo describe que ejes y que botones van a ser usados y las funciones para controlar en FlightGear. La asociación entre funciones de botones y ejes son llamadas “bindings”(vinculaciones). Este archivo de vinculaciones puede tener cualquier nombre tan largo como corresponda a las entradas existentes en el archivo de descripción de joystick

/FlightGear/joysticks.xml

el cual le dice a FlightGear donde buscar todos los archivos de vinculaciones. Miraremos ejemplos después..

FlightGear incluye varios tipos de archivos de vinculación para varios tipos de mandos de control en carpetas con el nombre de cada fabricante. Por ejemplo, si tienes un joystick CH Products, busca en la carpeta

/FlightGear/Input/Joysticks/CH

un archivo que pudiera funcionar para tu joystick. Si existe tal archivo y tu palanca de juego funciona con otras aplicaciones, entonces deberá funcionar en FlightGear la primera vez que lo ejecutes. Si tal archivo no existe, luego discutiremos en una section posterior como crear tal tipo de archivo copiando y pegando vinculaciones desde los ejemplos que estan incluidos en FlightGear.

Comprobando que tu joystick está funcionando

¿Ve tu computadora tu joystick? Una forma de responder esta pregunta sobre GNU/Linux es reiniciar tu sistema e inmediatamente entrar en la linea de comandos

dmesg | grep Joystick 

el cual entuba el mensaje de arranque al grep que imprime cada linea en los mensajes de arranque que contengan la cadena “Joystick”. Cuando haces esto con una palanca de mando Saitek conectada, verás una linea similar a esta:

input0: USB HID v1.00 Joystick [SAITEK CYBORG 3D USB] on usb2:3.0 

Esta linea nos indica que un joystick has sido identificado por si mismo como un SAITEK CYBORG 3D USB al sistema operativo. Este no nos dice que el driver vea tu joystick. Si esta trabajando bajo Windows, el metodo de arriba no funciona, pero aun puedes acudir al siguieente parrafo.

Confirmar que el driver reconoce tu joystick

FlightGear viene equipado con una utilidad que se llama js demo. Esta reporta el numero de joystick conectado al sistema, sus respectivos “nombres”, y sus capacidades. Bajo GNU/Linux, puedes ejecutar js demo desde la carpeta /FlightGear/bin como sigue:

$ cd /usr/local/FlightGear/bin 
$ js_demo 

Bajo Windows, abre la ventana de comandos (Start>All Programas>Accessorios>Simbolo de Sistema), ve a la carpeta binaria de FlightGear e inicia el programa como sigue (entendiendo que FlightGear este instalado en c:\Flightgear)

cd \FlightGear\bin\Win32 
fgjs.exe 

En tu sistema, las primeras lineas de salida son (para el programa con C si este hace scroll rápidamente y se sobrepasa la ventana!) como sigue:

Joystick test program. 
Joystick 0: “CH PRODUCTS CH FLIGHT SIM YOKE USB ” 
Joystick 1: “CH PRODUCTS CH PRO PEDALS USB” 
Joystick 2 not detected 
Joystick 3 not detected 
Joystick 4 not detected 
Joystick 5 not detected 
Joystick 6 not detected 
Joystick 7 not detected 
+——————–JS.0———————-+——————–JS.1———————-+ 
| Btns Ax:0 Ax:1 Ax:2 Ax:3 Ax:4 Ax:5 Ax:6 | Btns Ax:0 Ax:1 Ax:2 | 
+———————————————-+———————————————-+ 
| 0000 +0.0 +0.0 +1.0 -1.0 -1.0 +0.0 +0.0 . | 0000 -1.0 -1.0 -1.0 . . . . . | 

Primero has de notar que js demo reporta que numero es asignado a cada palanca de mando reconocida por el driver. Tambien, haz de notar que el “nombre” de cada joystick reportado está tambien incluido entre comillas. Necesitaremos los nombres para cada archivo de interconexión cuando comenzemos a escribir los archivos de interconexión xml para cada palanca de mandos.

Identificar el numero de ejes y botones

Los Ejes y el numero de botones pueden ser identificados usando js demo como sigue. Observando el mensaje de salida de js demo al trabajar con ejes y botones puedes determinar que ejes y que botones son los asignados a cada palanca de mando. Esto deberia notarse por numeros que por lo general empiezan en cero.

Los botones son najejados internamente como numeros binarios en los cuales el bit 0 (el menor bit significante) representa el botón 0, el bit 1 representa el botón 1, etc., pero este numero es visualizado en pantalla con notación hexadecimal, así:

• 0001 ⇒ button 0 pressed
• 0002 ⇒ button 1 pressed
• 0004 ⇒ button 2 pressed
• 0008 ⇒ button 3 pressed
• 0010 ⇒ button 4 pressed
• 0020 ⇒ button 5 pressed
• 0040 ⇒ button 6 pressed
• ... etcp to ...
• 8000 ⇒ button 15 pressed
• ... and ...
• 0014 ⇒ buttons 2 and 4 pressed simultaneously
• ... etc.

Para usuario de GNU/Linux, hay otra opción para identificar el “nombre” y los numeros asignados a cada eje y botón. La mayoria de las distribuciones GNU/Linux incluyen un programa muy manejable, “jstest”. Con unos cuernos de control de CH Product conectados al sistema, las siguientes lineas son mostradas por jstest:

jstest /dev/js3 
Joystick (CH PRODUCTS CH FLIGHT SIM YOKE USB ) has 7 axes and 12 buttons. Driver version is 2.1.0 
Testing…(interrupt to exit) 
Axes: 0: 0 1: 0 2: 0 3: 0 4: 0 5: 0 6: 0 Buttons: 0:off 1:off 2:off 3:on 4:off 5:off 6:off 7:off 8:off 9:off 10:off 11:off 

Notese el “nombre” entre parentesis. Este es el nombre que el sistema asocia a tu palanca de control.

Cuando mueves algun control, los numeros cambian después de pulsar cualquier boton o mover el control correspondiente, el “off” cambia a “on” después de pulsar el botón correspondiente. De esta forma, puedes anotar rápidamente los numeros de eje y de botón para cada función sin liarte con el binario.

Escribir o editar los archivos xml de interconexión de Joystick

En este punto, tienes confirmado que ambos, sistema operativo y driver reconocen tu(s) joystick(s). Tambien conoces varias formas de identificar el “nombre” de tu palanca de control que el joystick reporta al driver y al sistema operativo. Necesitarás una lista escrita de que función de control deseas tener asignada a cada eje y botón y sus correspondientes numeros.

Haciendo la siguiente tabla con lo que has aprendido arriba sobre js demo o jstest (lapiz y papel serán útiles). Aqui asumimos que hay 5 ejes incluyendo 2 ejes asociados al pivote (hat).

Axis	Button
elevator = 0	view cycle = 0
rudder = 1	all brakes = 1
aileron = 2	up trim = 2
throttle = 3	down trim = 3
leftright hat = 4	extend flaps = 4
foreaft hat = 5	retract flaps = 5
	decrease RPM = 6
	increase RPM = 7

Asumiremos que tu hipotético mando de control indica el “nombre” QUICK STICK 3D USB al sistema y al driver. Con todos los ejemplos incluidos en FlightGear, la manera más fácil de autodetectar una palanca de control no soportada, es editando un archivo xml de interconexión existente. Mira en los archivos xml en las sub-carpetas /FlightGear/Input/Joysticks/. Despues de evaluar varios de los archivos xml de interconexión incluidos en FlightGear, decidimos editar el archivo

/FlightGear/Input/Joysticks/Saitek/Cyborg-Gold-3d-USB.xml.

Este archivo tiene todas las funciones de eje y todas las funciones de botones arriba asignadas. Esto hace que nuestra edición sea casi trivial.

Antes de que comencemos a editar, necesitamos elegir un nombre para nuestro archivo xml de interconexión, crear la carpeta para el joystick QS, y copiar el archivo xml original en el directorio con este nombre.

$ cd /usr/local/FlightGear/Input/Joysticks 
$ mkdir QS 
$ cd QS 
$ cp /usr/local/FlightGear/Input/Joysticks/Saitek/ 
Cyborg-Gold-3d-USB.xml QuickStick.xml 

Aquí, obviamente hemos supuesto un sistema GNU/Linux/UNIX con FlightGear estando instalado en /usr/local/FlightGear. Para un procedimiento similar bajo Windows con FlightGear estando instalado en c:FlightGear, abre la ventana de comandos y escribe

c: 
cd /FlightGear/Input/Joysticks 
mkdir QS 
cd QS 
copy /FlightGear/Input/Joysticks/Saitek/ 
Cyborg-Gold-3d-USB.xml QuickStick.xml 

Lo siguiente, abre QuickStick.xml con tu editor favorito. Antes de que olvidemos cambiar el nombre de la palanca de control, busca la linea que contenga <name>. Deberás encontrar la línea

<name>SAITEK CYBORG 3D USB</name>

y cambiarla por

<name>QUICK STICK 3D USB</name>.

Esta línea ilustra la clave interpretada por los comandos xml. Empezarán con una etiqueta<tag> y finalizarán con otra etiqueta de cierre</tag>.

Ahora puedes comparar tu tabla con la tabla comentada en la parte de arriba de tu copia de archivo. Haz notar que los comentarios nos dicen que el elevador Saitek fué asignado al eje 1. Busca la cadena

<axis n=~1~>

y cambia esta por

<axis n=~0~>.

Lo siguiente, haz notar que el timón de dirección Saitek fué asignado al eje 2. Busca la cadena

<axis n=~2~>

y cambia esta por

<axis n=~1~>.

Continua comparando tu tabla con la tabla comentada del Saitek y cambia los numeros de eje y los numeros de botón correspondientes. Desde que el QUICKSTICK USB y el Saitek tienen el mismo numero de ejes pero diferentes numeros de botones, debes borrar los botonos sobrantes. Recuerda que tienes que comprobar que tienes las etiquetas de cierre de todas las etiquetas abiertas o recibirás un error usando el archivo.

Finalmente, se bueno contigo mismo (y con los otros cuando submitas tu nuevo archivo de interconexión a los desarrolladores de FlightGear o a los archivos de usuario!), tomate el tiempo de cambiar la tabla comentada del archivo editado para marcar tus cambios de eje y las asignaciones de botón. Los nuevos comentarios corresponderán a la tabla que has hecho por la salida dada por js demo. Salva tu edición.

Varios usuarios han reportado que los numeros de eje y botones asignados a funciones pueden ser diferentes con el mismo joystick en Windows o en GNU/Linux. El procedimiento de arriba permitiria a cada uno cambiar facilmente el archivo de interconexión xml creado para usar en los diferentes sistemas operativos.

Informar a FlightGear sobre tu nuevo archivo xml de interconexión

Antes de que FlightGear pueda usar tu nuevo archivo xml, necesitas editarlo

/FlightGear/joysticks.xml,

añadiendo una línea que incluya tu nuevo archivo si el “nombre” que introjiste entre las etiquetas de nombre corresponde a el nombre aportado al driver por tu joystick. Añade la siguiente linea a joysticks.xml.

<js-named include=~Input/Joysticks/QS/QuickStick.xml~/> 

Puedes decir como ha interpretado FlightGear tu configuración de palanca de mando seleccionando Help -> Joystick Information desde el Menú.

Algunas pistas para usuarios de Windows

Básicamente, los procedimientos descritos arriba deberian funcionar tambien para Windows. Si tu joystick/yoke/pedales work out of the box or if you get it to work using the methods above, fine. Desafortunadamente puede haber algunos problemas.

El primero concierne a los usuarios de Windows con versión no norteamericana. Como hemos indicado arriba, puedes conseguir el nombre de la palanca de mandos desde el programa js demo. Si tienes una version no norteamericana de Windows y los archivos joystick .xml nombrados arriba no contienen ese nombre especial, simplemente añadelo en la parte de arriba del corespondiente archivo de la siguiente forma

<name>Microsoft-PC-Joysticktreiber </name>

No es requerida una nueva entrada en el archivo base joysticks.xml.

Desafortunadamente, hay una laguna mas con el soporte de la palanca de mando con Windows. En el caso de que tengas dos desipositivos USB conectados (por ejemplo unos cuernos y unos pedales), puede haber casos, donde el mismo nombre de driver es reportado dos veces. En este caso, almenos puedes tener los cuernos funcionando asignandolo el numero 0 (en 0 o 1). Para este proposito, gira el control de (aileron de los cuernos) y observa la salida de js demo. Si figura en el primer grupo cambiado y formado por los dos puntos (:) (para el dispositivo 0), la asignación es correcta. Si figura en el segundo grupo cambiado y formado por los dos puntos (:) (para el dispositivo 1), primero bebes hacer que los cuernos sean el dispositivo preferido. Para hacerlo, entra al "Panel de control", abre "Controladores de juego" y selecciona el botón "avanzadas". Aqui puedes seleccionar los cuernos como dispositivo "Preferido". Después de esto puedes comprobar las asignaciones ejecutando de nuevo js demo. Los cuernos ahora deberán estar controlados en en el primer grupo de figuras.

Desafortunadamente, no hemos encontrado la forma de que funcionen los pedales tambien, de esta forma. Por tanto, en casos como este (y otros) tendrás que intentar un metodo alternativo para asignar los controles del joystick.

Soporte de Joystick usando entradas.fgfsrc

Afortunadamente, hay una herramienta ahora disponible, la cual lleva la mayor parte de la carga del usuario medio quien, quizas, no está esté experimentado con XML, el lenguaje con el cual esos archivos han sido escritos.

Para configurar tu palanca de mando usando esta aproximación, abre el interprete de comandos (la ventana de comandos bajo windows, se puede encontrar en Start|Todos los Programas|Accesorios). Cambia al directorio /FlightGear/bin de esta forma e.j. (modificado a tu ruta)

cd c:\FlightGear\bin

e invoca la herramienta fgjs de esta forma

./fgjs

en una máquina UNIX/Linux , o de esta forma

fgjs

en una máquina windows. El programa te dirá que palancas de mandos, si las hubiera, fueron detectadas. Ahora sigue los comandos dados en pantalla, por ejemplo mueve un eje y presiona los botones requeridos. Ten cuidado, un mínimo toque "cuenta" como un movimiento. Comprueba el informe en pantalla. Si notas que algo fué mal, reinicia el programa.

Despues de que lo hagas con todos los ejes y botones, el directorio de arriba colgará un archivo llamado fgfsrc.js. Si el directorio base de Flightgear no contiene un archivo de opciones .fgfsrc (bajo sistemas UNIX)/system.fgfsrc (bajo Windows) mencionado arriba, entonces copia

fgfsrc.js dentro de .fgfsrc (UNIX)/system.fgfsrc (Windows)

y colocalo dentro del directorio base de Flightgear. En caso de que hallas escrito un archivo de opciones, abrelo tambien como fgfsrc.js con un editor y copia las entradas desde fgfsrc.js adentro de .fgfsrc/system.fgfsrc. Una advertencia: La salida de of fgjs es formato UNIX. Como resultado, los editores Windows no deberian mostrarlo en la forma adecuada. Sugiero usar un editor que sea capaz de manejar tambien formatos UNIX (un viejo pero adorado en este respecto es PFE, para ello haz una busqueda en la red). Mi editor freeware de archivos favorito para este proposito, aunque algo añejado, todavia es PFE, que puede ser obtenido en

http://www.lancs.ac.uk/people/cpaap/pfe/.

La asignación eje/botón de fgjs debería, al menos, tomar las asignaciones de eje correctos, su salida podría necesitar algún ajuste. Pudiera haber ejes que se muevan en sentido contrario del que deberían, las zonas muertas pudieran ser muy pequeñas etc. Por ejemplo, Yo tuve que cambiar

–prop:/input/joysticks/js[1]/axis[1]/binding/factor=-1.0 

por esto

–prop:/input/joysticks/js[1]/axis[1]/binding/factor=1.0 

(USB CH Flightsim Yoke bajo Windows XP). Por tanto, aquí está una breve introducción para las asignaciones de las propiedades de la palanca de control.

Básicamente, todos los ajustes de eje son especificados por lineas que tienen la siguiente estructura:

--prop:/input/joysticks/js[n]/axis[m]/binding 
/command=property-scale (una linea) 
--prop:/input/joysticks/js[n]/axis[m]/binding 
/property=/controls/steering option (one line) 
--prop:/input/joysticks/js[n]/axis[m]/binding 
/dead-band=db (una linea) 
--prop:/input/joysticks/js[n]/axis[m]/binding 
/offset=os (una linea) 
--prop:/input/joysticks/js[n]/axis[m]/binding 
/factor=fa (una linea) 

en donde

n	numero de dispositivo (por lo general comienza con 0)
m	numero de ejes (por lo general comienza con 0)
opciones de gobierno de la nave	elevator, aileron, rudder, throttle, mixture, pitch
dead-band	rango, entre el cual las señales son descartadas; se usa para evitar el temblores con movimientos mínimos del joystick
offset	especifica, si el dispositivo no esta centrado en su posición neutral
factor	control de sensibilidad del eje; por defecto en +1, con un valor de -1 se invierte el comportamiento

Deberías poder al menos hacer funcionar tu joystick con estas líneas. Concerniente a los ajustes finos, por ejemplo, hacer funcionar los botones del joystick, John Check ha escrito un README muy útil incluido en el paquete base que puede ser encontrado en FlightGear/Docs/Readme/Joystick.html. En caso de algún problema con tu dispositivo de entrada, es altamente recomendado echar un vistazo a este documento.

Algo más sobre programación de archivos XML de joystick

Casos generales

• Cuando se prueba un nuevo archivo xml es mejor iniciar FlightGear a través de la ventana de comando (mejor que en la interfaz gráfica GUI). Cualquier mensaje de error será mostrado en la terminal. Los mensajes de error te darán el mensaje y el numero de linea, ayudandotea ubicar con exactitud cualquier error.

• Los errores pueden ser detectados en el arranque inicial o en tiempo de ejecución. Ambos tipos de errores serán mostrados en la terminal.

• Uno de los errores mas comunes es icluir algun caracter que se le atragante a XML. Estos caracteres incluyen

& < --

Esos caracteres causarán problemas incluso si simplemente son incluidos en comentarios o entre código.

• Si tus escritos de programación contienen alguno de esos caracteres, tienes que encerrar los escritos con <script><![CDATA[...]]></script>. Alternativamente, puedes 'escapar' de los caracteres, Ej. "<" convirtiendolo en "<".

• Notar que desde la versión 1.9.1 no hay forma de decirle a FlightGear que recargue los archivos de joystick en tiempo de ejecución. Por tanto para probar cualquier cambio en tus archivos debes salir de FlightGear y reiniciar, un proceso que ocupa algo de tiempo.

• Puedes encontrar algunos ejemplos con diferentes formas de programar joysticks simplemente examinando los archivos de joystick xml que están en el paquete de FlightGear. Mira en el directorio FlightGear/data/input/joysticks

• Algunas funciones avanzadas pueden ser programadas usando el lenguaje de programación NASAL. Estos escritos de programación son cerrados entre etiquetas <script></script> en el archivo XML. Será de ayuda:
  • Una guia del Nasal scripting language de FlightGear
  • Nasal FAQ
  • Howto: Write simple scripts in Nasal

• Puedes explorar el arbol de propiedades internas para ver algunas variables que pueden ser alteradas usando botones o ejes del joystick (File/Browse Internal Properties)

• Puedes probar pedacitos de código Nasal y hacer algunas otras cosas de ayuda usando la consola de Nasal (Debug/Nasal Console).

• Todos los códigos Nasal comparten un nombre-espacio común, por tanto es posible seleccionar una variable en una interconexión Nasal, y leerla en otra.

Pistas Útiles para scripts

Algunas ideas particulares útiles para programar scripts en archivos XML de palanca de mandos:

• getprop y setprop pueden ser usados para obtener y seleccionar propiedades desde el arbol de propiedades internas:

var brake = !getprop("/controls/gear/brake-parking");
setprop("/controls/gear/brake-parking", brake);

• Tambien puedes crear tus propios valores en el árbol de propiedades:

setprop("/input/joysticks/js[0]/myjoystick-modifier", 1);
var mod = getprop("/input/joysticks/js[0]/myjoystick-modifier");

• Puedes imprimirlo en la terminal usando la función print. Esto es muy útil para la depuración de errores.

print("Aquí", " va ", "el texto");

• Puedes sacar por pantalla información en FlightGear a través de pantalla emergente. Esto es muy útil para dar al usuario respuesta sobre cambios que no sean obvios a traves del panel. Esto tambien puede ser útil para la depuración de errores. Ejemplo:

gui.popupTip("Parking Brake ON");

Los argumentos para gui.popupTip deben ser cadenas de caracteres, por tanto si quieres sacar por pantalla otros tipos de variables tendran que ser formateadas con algo como sprintf:

gui.popupTip(sprintf("Elevator trim: %d", 100 * getprop("/controls/flight/elevator-trim")));

O

thv = getprop("/controls/engines/engine[0]/mixture");
gui.popupTip("Thrust vector " ~ int(thv * 120 - 20));

• Puedes inicializar el uso de variables, Ej,

x = 10;

Pero por varias razones generalmente es mejor declarar las variables con la sentencia "var":

var x = 10;

Debes saber que "var" crea variables en el ámbito local, la cual causaria problemas si estas intentando usar una variable globalmente entre todos tus archivos de interconexión de palanca de mando XML.

• Puedes incluir una sección de código que corra en el comienzo para inicializar variables, crear funciones, etc. Ejemplo:

<PropertyList>
  <name type="string">My joystick name</name>
  <name type="string">My joystick name #2</name>
  <nasal>
    <script>
       #initializar variables
       f1 = f2 = 0;
       left_brake = right_brake = 0;
       # crear una función para ser usada con todos los botones
       getmod = func { getprop("/input/joysticks/js[0]/t-flight-hotas-x-modifier" ) }
    </script>
  </nasal>

Recursos

• The FlightGear Manual