The TiltStick is a small acceleration sensing device in form of a USB stick. It's using a two axis acceleration sensor to measure acceleration (caused e.g. by motion and tilt). The device is emulating a USB joystick and can thus be used in conjunction with any USB equipped host (e.g. a standard PC or the Nokia N8XX family) without any special drivers. The TiltStick is the successor of the Tilt Dongle for Palm OS.
Two versions of the TiltStick have been designed based on different 2D accelerometer chips. The slightly smaller one is based on the Analog Devices XL203 (the XL202 may also be used). The bigger version is based on the Freescale MMA7261. The advantage of the freescale version is that a pin 3D chip exists. The hardware of the TiltStick is prepared to support the third axis.
The different accelerometers run at different voltages. Thus the ADI version runs at 5V and two zener diodes convert the voltages on the USB data pins to USB compatible 3.6V. The Freescale chip runs at max. 3.6V. This the supply voltage of the entire unit is reduced by two diodes to approx 3.6V. Thus no further conversion of the voltage on the USB data lines is required.
 |
 |
 |
 |
 |
 |
The current design V1.0 contains some design errors. Most important the USB data lines have to be swapped. This can easily be done by cutting the traces directly at the connector and replacing them with thin wires. Furthermore are the ADC6 and ADC7 pins used as GPIO. This doesn't affect the ADI solution as this isn't using those pins, but some changes are needed for the Freescale version. These aren't documented yet as the current firmware doesn't yet support the freescale chip. Finally the ADI version is missing a connection between PC3 and GND (can easily be fixed directly at the pin) which will allow future firmware versions to differ between the ADI and Freescale boards.
The USB interface of the TiltStick interface is based on a pure software implementation and uses two pins of the AVR (PB0 and PB2). This software implementation supports low speed USB only which is signalled to the PC by resistor R1. It is based upon the AVR-USB USB solution for the AVR family.
The accelerometers used on the TiltStick need to be calibrated in order to get accurate measurements in the range of -2G to +2G and to adjust the layout of the two axes to e.g. cope with the fact that the TiltStick may be oriented differently when attached to different host computers. Two ways for calibration exist:
The PC assisted calibration is available for the Linux host platform only. It uses the caltool application included with the source archives. This application will the ask you to move the TiltStick in certain ways to calibrate. Just follow these instructions and you are done.
Since the caltool application is only available for Linux, the self calibration mode has been added to allow for easy calibration without a special software tool running on the host. To perform a self calibration perform the following simple steps:
You can interrupt the self calibration at any time by either pressing one of the fire buttons instead of the calibration button or by waiting 15 seconds for the self calibration to time out. The values in the eeprom will not be touched in this case.
The TiltStick can be used in conjunction with any software that can be controlled using a simple two axis joystick with two fire buttons. However, the TiltStick is not a joystick and the user experience is most astonishing when being used with software that was specifically designed with the accelerometers in mind. The tiltstick_mass demo included with the downloads is such an application. It simulates a mass (the red circle) which is connected to two rubber bands (the yellow lines). If the TiltStick is attached and calibrated, the mass naturally follows the tiltsticks movements. E.g. tilting and shaking the computer with the attached TiltStick will make the mass move "downwards" or be shaken.
This demo software is also included with the Maemo download below.
The TiltStick comes with a single USB HID joystick interface. But the different operating systems come with different drivers to handle such joysticks. Some operating systems even come without any joystick drivers at all. Even on systems with a joystick driver, the TiltStick may need special treatment to work perfectly as e.g. the Linux kernel tends to modify the joystick events before forwarding them to an application.
The Linux joystick drivers detect the TiltStick out of the box and report appropriate events to the applications in user space. However, in the default state an extended zone is being created the zero position. This means that the joystick routines are unresponsive around the joysticks center position. The joystick has to be moved out of the center position to a certain extent to actually report values other than zero. This is useful for ordinary joysticks as they may not always return precisely to the same center position. For the TiltStick this is an unwanted effect as it makes the Tiltstick unresponsive to movements near the horizontal position. The second thing the linux kernel does by default is to reduce the active area a little bit so that the joystick does not have to be moved to its maximum position to report max possible values. This also is meant to compensate for mechanical limitations and is also unwanted with the TiltStick as it modifies the acceleration range the TiltStick reports.
The following command will disable all such translations for the joystick /dev/input/js0:
jscal -s 2,1,3,0,0,1000000,1000000,1,3,0,0,1000000,1000000 /dev/input/js0
This command changes the settings to values useful for the TiltStick. These settings aren't permanent and are reset whenever the TiltStick is unplugged and re-inserted or if the PC is rebooted or the joystick driver is reloaded for another reason. The following graphics visualizes what these settings do:
The TiltStick was designed not to require and special drivers as it is built as a HID joystick compatible USB device. Unfortunately the Maemo platform (at least the current os2008/Maemo 4.0) does not include the Linux joystick subsystem and thus cannot make direct use of any USB joystick.
Fortunately the USB HID drivers are included and joystick devices are detected and included into the input event subsystem. The only part missing is the handling of the actual joystick events and their forwarding to the application that wants to make use of the joystick. The following section explains how to access the TiltStick by directly interfacing to the linux input event subsystem. The same approach may be used to build a generic software interface to use a standard USB joystick or gamepad with Maemo.
The Linux kernel creates an input event interface for every input device it detects. These interfaces are named /dev/input/eventX where X is a number. Such a device is created for e.g. every keyboard, mouse, touchpad, touchscreen and joystick. Doing a hexdump /dev/input/event1 will e.g. dump the hex representation of all keyboard events to the screen. This is a very basic interface and the events are very "close to the hardware" and will need some conversion to have e.g. keyboard events translated into actual key mappings etc. Furthermore, these event interfaces are not setup using a fixed scheme. Therefore a method is required to actually find the event interface matching the desired device.
In a second step these event messages have to be parsed by the application and be translated into the desired actions. Unfortunately HID devices can be very complex. Fortunately we are going to do this for the TiltStick only and we know exactly what events the device will deliver. Using this very same approach for a generic joystick interface will be somewhat more complex as it requires to cope with different joystick layouts using different axis mappings, different button layouts and different resolutions on the analog axes. The information required to do this complex parsing can be requested from the event subsystem and then be used to translate the actual events. Furthermore a generic joystick detection routine is then needed to select all event interfaces that actually carry joystick information.
In case of the TiltStick this is rather simple as we even know the exact USB vendor and product ids of the TiltStick. The application therefore just opens all available /dev/input/eventX devices and requests the USB vendor and product id of each attached device. Once it find the values of the TiltStick (vendor id 1c40, product id 0533) it has found the right interface and can ignore all the remaining ones.
Parsing the events also is a snap as the events directly match the data generated by the TiltStick. The two axes are available as axes 0 and 1 reporting signed 10 bit values (-512 to +511) which directly match the output of the ATmega8's 10 bit ADC converters. Furthermore on and off events are being sent for the two application buttons present on the TiltStick (the calibration button is not reported to the host PC).
In case of the Maemo another hurdle has to be taken as the event interfaces are by default accessible by the root user only. But we want to access it from a standard user application. A special config file for the udev system will tell it to give the standard user access to the event interface generated for the TiltStick. The following file is automatically installed with the tiltstick demo application and takes care of this:
EMail
BlueMP3
# file: /etc/udev/rules.d/tiltstick.rules
# purpose: give user access to event interface of tiltstick
KERNEL=="event*", SUBSYSTEM=="input", SYSFS{idVendor}=="1c40", SYSFS{idProduct}=="0533", GROUP="users", OWNER="user"
The entire setup is available for the os2008 platform via one-click install from the harbaum.org repository:
Enigma is one of those games that just need an accelerometer or tilt sensor as input device. In this game you guide a marble through various mazes. It is usually controlled by mouse, but the tiltstick is a very intuitive input method for this type of game. Enigma as well as the Palm OS game Mulg (which also had a tilt sensor input option) are inspired by the Oxyd game initially written for the Atari ST.
The TiltStick comes with a patch to the enigma-1.01 source code which enables the use of a joystick together in enigma. Since the TiltStick emulates a joystick enigma can thus be played realistically by tilting.