ljjoy microlibrary: Use a LabJack anywhere you would use a joystick.

(c) 2014, LabJack Corp..
Released under the GNU GPL v3.
Lead developer / contact: Sam Pottinger.
joysticks.py resused under BSD license from fscode by Nils Maier.

• ljjoy currently only supports Windows XP and up.
• Currently only the T7 is supported.

Sorry *nix / mac users and UD device owners, star the project and ping us in the issue tracker to let us know you are out there.

• Download and install Python.
• Download and install LJM Python module.
• Download and install PyYAML.
• Download and install vjoy.
• Run the vjoy device setup and configure which axes and buttons you want your joystick to have.
• Download and extract ljjoy from our GitHub repo.

We are trying to guage our user base and interest. If you want a self-contained executable, star the project to let us know you are out there!

Just execute Python on ljjoy and provide 1 command line argument: the path to the YAML configuration file (see example and API section below).

• Opens a LabJack T7 over USB with the serial number 123456789.
• Links the value of digital input FIO0 to joystick button 4.
• Reports analog input AIN0 (from 0V to 10V) as joystick x axis position.
• Reads from the device and updates ever 10 milliseconds.

mappings:
  - deviceRegister: AIN0
    joystickOutputChannel: axis:0
    outputStrategy:
      name: linear
      minDeviceVal: 0
      maxDeviceVal: 10
  - deviceRegister: FIO0
    joystickOutputChannel: button:4
    outputStrategy:
      name: binary
labjack:
  deviceType: T7
  connectionType: USB
  identifier: '123456789'
  refreshRate: 10
joystick:
  name: vJoy Device
  debug: yes

Structure

mappings:
  ...
labjack:
  ...
joystick:
  ...

• The mappings indicate which values from the LabJack should be routed as joystick input.
• The labjack section indicates which device to use to get joystick values.
• The joystick section indicates which joystick to pretend to be.

• deviceRegister indicates which device value ljjoy should read.
• joystickOuputChannel indicates where ljjoy should use the specified device value in the virutal joystick. Expects (axis|button)[\d+] or, in other words, "axis" or "button" followed by a colon and then the axis or button number. See the axis map section for more info.
• outputStrategy tells ljjoy how to convert the device reading to joystick output. See the scaling strategies section for more info.

• deviceType indicates what type of LabJack device ljjoy should open. Currently the only valid option is T7.
• connectionType tells ljjoy through which connection medium to open the device. Valid options include ALL, USB, ETHERNET, and WIFI.
• identifier identifies the target device for ljjoy to use if more than one LabJack is available. Can be the device's serial number or, if connecting over the network, IP address (XXX.XXX.X.X). Can also pass ANY for opening the first found device over the specified connection type.
• refreshRate indicates how frequently ljjoy should query the device for new values. The 10 in the above example tells ljjoy to query the device and update joystick output every 10 milliseconds.

• name indicates the system-level name of the joystick to control (vJoy Device should be used if unsure).
• debug indicates the verbosity level. ljjoy will print joystick values to the terminal if yes and will remain quiet if no.

Linear Scaling

outputStrategy:
  name: linear
  minDeviceVal: 0
  maxDeviceVal: 5
  minJoystickVal: 0
  maxJoystickVal: 100

Using name:linear, ljjoy will create a linear equation to convert LabJack to joystick values. A device reading of 1 in the above example would output 20 to the virtual joystick.

• minDeviceVal tells ljjoy the lowest value to expect from the device.
• maxDeviceVal tells ljjoy the highest value to expect from the device.
• minJoystickVal tells ljjoy the minimum value to report to the virtual joystick. Optional, defaults to 1.
• maxJoystickVal tells ljjoy the maximum value to report to the virtual joystick. Optional, defaults to 32767.

Choosing min and max joystick values: most axes and joystick configurations range from 1 (low) to 32767 (high).

• activeThreshold tells ljjoy the minimum device value that should be reported before outputing the activeValue. Optional, defaults to 0.5.
• inactiveValue tells ljjoy what value to report to the virtual joystick when the device value falls under under the activeThreshold. Optional, defaults to 0.
• inactiveValue tells ljjoy what value to report to the virtual joystick when the device reading equals or execeeds the activeThreshold. Optional, defaults to 1.

Running automated tests
Run tests: python test_ljjoy.py

Adding scaling strategies
All scaling strategies must implement the following ScalingStrategy interface.

class ScalingStrategy:
    """Semi-non-pythonic interface for LabJack to joystick device scaling.

    Somewhat non-pythonic interface for stratgies to scale a LabJack device
    value to a value to send to the joystick emulator.
    """

    def process(self):
        """Scale the LabJack device value to the appropriate joystick value.

        @param device_val: The value read from the device.
        @type device_val: float
        @return: The scaled joystick output value.
        @rtype: float
        """
        raise NotImplementedError

To then add your strategy to ljjoy, add AVAILABLE_OUTPUT_STRATEGIES['name'] = YourScalingStrategy at the end of your class definition.

Everything else
Engage us here on GitHub with the issue tracker. We do ask that patches please unit test when reasonable and follow the epydoc docstring convention.