Home · All Classes · Grouped Classes · Annotated · Functions

Tutorial: Implementing a Device Plug-in

• Keypad
• Implementation Steps
• Touchscreen/Mouse
• Implementation Steps
• Creating a Custom Screen Driver
• Running Qtopia on the device using qpe.env and qpe.sh

This document describes the process required to implement a plug-in for a new device. All directory references are relative to the example provided in the <qtopia-root-dir>/devices/example directory.

Qtopia also provides Device Profiles to simplify the task of configuring Qtopia for a device and providing the plug-ins required.

The following directories are of particular interest:

This tutorial assumes that debugging using qLog() is enabled. To activate debugging:

• edit <image directory>/etc/default/Trolltech/Log.conf and enable Input
• restart Qtopia to implement the change and qLog() messages will be displayed.

This functionality is available in both debug and release builds.

The steps taken to implement a new plug-in depend on whether you are implementing a keypad plug-in or a touchscreen/mouse plug-in. The following tutorial provides the steps for both.

The initial steps for either type of plug-in are:

1. Copy the directory named example to <device-name>.
2. Rename all sub-directories called example to <device-name>.
3. Replace all occurrences of Example with <device-name>.
4. Replace all occurrences of example with <device-name>.
5. Replace all occurrences of EXAMPLE with <DEVICE-NAME>.
6. Customize src/devtools/startup/qpe.{env,sh} to suit the device
7. Decide if a custom screen driver is required, see Creating a Custom Screen Driver

Note:The value chosen for <device-name> must only contain alpha-numeric characters.

Keypad

The functionality required to implement a keypad device plug-in is found in the source file: /src/<device-name>kbdhandler.cpp, which implements a class to handle keypad input inheriting QWSKeyboardhandler. Then the constructor/destructor readKbdData() functions are overloaded to match your device.

Implementation Steps

1. Set environment variable: QWS_KEYBOARD=examplekbdhandler
2. Implement qLog() to output the data being read to standard output.
3. Edit the keyboard plug-in code to suit your device as follows:
   • Identify the device node and update <device-name>kbdhandler.cpp to open the correct data node.
   • Identify the data format(for example, 4-byte packets) and update <device-name>kbdhandler.cpp to read the correct number of bytes.
   • Update the structure <device-name>Input in <device-name>kbdhandler.cpp with the correct data format for the device.
4. Build Qtopia using: ./configure -device <device-name>.
5. Run Qtopia.
6. To determine the correct key mappings, use the keypad to input strokes and then identify the byte-values displayed by qLog().
7. In <device-name>kbdhandler.cpp update the switch statement in function readKbdData() with the correct key mappings.

Touchscreen/Mouse

The functionality required to implement a touchscreen/mouse device plug-in is found in the source file: /src/<device-name>mousehandler.cpp which implements a class to handle mouse input inheriting QWSCalibratedMousehandler. The constructor/destructor readMouseData() and calibrate() functions are then overloaded to match your device.

Implementation Steps

1. Set environment variable: QWS_MOUSE_PROTO=<examplemousehandler>
2. Implement qLog() to output the data being read to standard output.
3. Edit the mouse plug-in code to suit your device as follows:
   • Identify the device node and update <device-name>mousehandler.cpp to open the correct data node.
   • Identify the data format(for example, 4-byte packets) and update <device-name>mousehandler.cpp to read the correct number of bytes.
4. Build Qtopia using: ./configure -device <device-name>.
5. Run Qtopia.
6. To determine the correct Y-coord, Y-coord and pressure (press or release) move the mouse, click the mouse buttons and then identify the values displayed by qLog().
7. Update the structure ts_packet in <device-name>mousehandler.cpp with the correct data format for the device.
8. Update the switch statement in function readMouseData() in <device-name>mousehandler.cpp with the correct X-coord, Y-coord, and pressure value from the qLog() output.

Note: When creating a plug-in it is not necessary to rebuild all of Qtopia to enable it. Simply rebuild the plug-in and copy the files to the image/Qtopia directory and restart Qtopia.

Creating a Custom Screen Driver

For some hardware there is a need to make minor changes to how the screen is written to the device. One such example is where there needs to be an ioctl sent to the framebuffer device after each frame update. To see how one might create a QScreenDriverPlugin plugin to do that, see src/plugins/qtopiacore/gfxdrivers/example/ and modify the ExampleScreen::exposeRegion function to send the ioctl required.

To make use of this created screen driver plugin set QWS_DISPLAY, for example:

    export QWS_DISPLAY=examplescreen

Running Qtopia on the device using qpe.env and qpe.sh

After customizing src/devtools/startup/qpe.{env,sh} to suit the device and Qtopia is installed into the device it is then possible to:

• start an application without Qtopia running

      . /opt/Qtopia/qpe.env
      cd /opt/Qtopia
      bin/textedit -qws

• start Qtopia running

      /opt/Qtopia/qpe.sh

  A common practice is to append the above /etc/init.d/rc.local so that Qtopia is started upon bootup.

See also Running Qtopia.