Revision as of 11:07, 6 December 2008

Creating TmL devices

Purpose and Target audience

This tutorial provides directions on creating devices:LINK_CONCEPT for TmL.

The target audience is anyone who wants to create a device:LINK_CONCEPT in TmL context.

Initial requirements

Here follows the steps necessary to prepare the environment to create TmL devices.

1. Download and install the most recent Eclipse Europa (3.3) version. Click here for the eclipse download site.
2. Connect to Eclipse CVS Repository and get the project set for Common utilities (see instructions here).

After that, your workspace should contain a new project named org.eclipse.tml.common.utilities.

Creating a TmL device

The process of creating a TmL device consists of the following:

1. Defining the state machine which describes the device behavior in what concerns the TmL framework.
2. Instantiating the new device on the TmL framework.
3. Setting up the device state machine on the TmL framwork. This comprises the following steps:
   1. Creating one eclipse extension to represent each of the states pertaining to the device state machine.
   2. For each possible event on the device state machine, create an eclipse extension to represent the state changes which occur as a consequence of this event.

Defining the device state machine

In order to define the device state machine you should consider three points:

• The operations that can be performed on the device. That is, the events. Examples of events: turn device on, turn device off, start phonebook application.
• The status the device assumes as a consequence of these operations. That is, the sates. Examples of states: turned on, turned off, running phonebook application.
• The operations that can be performed when the device is at a given status. That is, how the possible states constrain the operations. Examples of such constraints: The turn on operation can be performed only if the device is on turned off state, start phonebook application operation cannot be performed if device is on turned off state.

With all this information well known, you are ready to define the state machine for the device you want to configure to use with TmL.

It is good practice to draw a graph which represents the device state machine you are creating. As an example, see the following state machine graph:

This state machine considers four states that the device can be at: Off, Idle, Running Phonebook and Running Calendar.

It also contains the information regarding the operation constraints according to the device state. For instance, from this state machine you can tell that in order to start an application (Phonebook or Calendar) the phone has to be on Idle state. It also tells that you can turn the device off regardless of its state (except if the device is already on Off state). Another conclusion is that you would not be able to start Calendar and Phonebook simultaneously. You can tell even more by looking at the state machine graph.

It might have occurred to you that although this example is simple, real devices have much more states, and defining a state machine for them would require a lot of work.

It is true that real devices (emulators or fones) have a huge number of states and operations, and consequently a very complex state machine. The good news is that, concerning TmL, you will only have to work on a small subset of these states and operations, leading to a much simpler state machine, just like in the example given.

Once you have defined the state machine for your device, you are ready to instantiate the device on the TmL framework and set-up its state machine. You can learn how to do it in the next steps.

Instantiating the new device on the TmL framework

Instantiating the device in the TmL framework is the first step in turning TmL aware of the existence of the new device.

In terms of the TmL framework, a device is nothing more than an extension at the org.eclipse.tml.device extension point.

The following steps guide you in creating this extension point.

1. Create the eclipse plugin where the extension point is going to be created. To do this, perform the following steps:
   1. Choose File > New > Project....
   2. Under Plug-in Development folder, select Plug-in Project and click Next.
   3. Type a name for the project.
      NOTE: If this plug-in will be contributed to TmL, certify that it is using the naming conventions in Development Conventions and Guidelines or check with TmL committer the best name for that. (ex: org.eclipse.tml.sampledevice).
   4. On the Target Platform section, set Eclipse Version to 3.3. Click Next.
   5. Fill Plug-in Version, Plug-in Name and Plug-in Provider.
   6. Change the default name for Activator to the format "<your-plugin-name>Plugin". (ex: SampledevicePlugin). Click Next.
   7. Uncheck "Create a plug-in using one of the templates" option. Click Finish.
   8. Plug-in is now created. You should see the entry "org.eclipse.tml.sampledevice" on Project Explorer view (or a different entry in case you chose a different name for the plug-in).
2. Configure the plugin to work with the TmL framework
   1. >>>>>>>>>>>>>> On Project Explorer view, double click plugin.xml file for the plug-in project.
   2. Click the Dependencies tab.
   3. Add org.eclipse.tml.common.utilities as a dependency.
3. Create the extension point that instantiates the new device. To do this, perform the following steps:

At this point you have created the device. However, this device does not have any behavior associated. It exists but is not able to provide an interface for the real device (a phone or an emulator). In order to being able to do this, you have to set up the state machine for this device. You can learn how to accomplish this in the next steps.

Setting up the device state machine on the TmL framwork

Creating the states

Setting up the sate transitions according to the events

1. Create a new Plug-in project using the Eclipse New Project Wizard.
   
2. If this plug-in will be contributed to TmL certify that it is using the naming conventions in Development Conventions and Guidelines or check with TmL committer the best name for that. (ex: org.eclipse.tml.sample)
   
3. Fill provider, version and name and change the default name for activator to this format "<your-plugin-name>Plugin". (ex: SamplePlugin)
   
4. Uncheck option to select a code template.
   

Configuring the plugin to work with the TmL framework

1. Open plugin.xml in the dependencies tab
2. Add org.eclipse.tml.common.utilities
   

Defining Icons

Inserting I18N support

Inserting LOG support

Inserting Exception support

Conclusion