Revision as of 12:35, 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:
   1. >>>>>>>>>>>>>> On Project Explorer view, double click plugin.xml file for the plug-in project.
   2. Click the Extensions tab.
   3. Click Add so as to add the extension org.eclipse.tml.device.
   4. Uncheck "Show only extension points from the required plug-ins" option, look for the org.eclipse.tml.device extension on the list, select it and click Finish.
      If you are asked to add new plug-in dependencies as a consequence of creating this extension point, click Yes.
   5. Fill description, version, provider and copyright fields.
   6. Create the handler class for the device. To do this, perform the following steps:
      1. Create the handler class.
      2. >>>>>>>>>>>>>> What is this handler purpose?
      3. >>>>>>>>>>>>>> Can we have a template for it ans pos it here?
   7. Add an icon to your device.
      >>>>>>>>>>>>>> Is the icon mandatory?
      >>>>>>>>>>>>>> What's its purpose?

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

For each state you identified in the device state machine it is necessary to create an extension at the org.eclipse.tml.status extension point. Each extension will represent a state.

Thus, for each state on the device state machine, perform the following steps:

1. Click the Extensions tab for the plugin where you are creating the device.
2. Click Add so as to add the extension org.eclipse.tml.status.
3. Uncheck "Show only extension points from the required plug-ins" option, look for the org.eclipse.tml.status extension on the list, select it and click Finish.
   If you are asked to add new plug-in dependencies as a consequence of creating this extension point, click Yes.
   A new entry named org.eclipse.tml.status appears on the list of current extensions for this plug-in.
4. Click the entry org.eclipse.tml.status just created and expand its contents.
5. Select the entry inside it, should be something like org.eclipse.tml.sampledevice.status1.
6. Change id and name to a label thar porperly describes your status. They should be both named equally.
7. Choose an image for the state.
   >>>>>>>>>>>>>>>> What's its purpose?
   >>>>>>>>>>>>>>>> Is it mandatory?
8. Leave canDeleteInstance field blank.
9. Save changes.
   The state is now registered.

>>>>>>>>>>>>>>>>> Where is the connection of the state with the device?

After you have set up all states for your device state machine, you can proceed to setting up the transitions between states. This is explained in the next section.

Setting up the sate transitions according to the events

Once you have registered all states pertaining to the device state machine, you can proceed to setting up the transitions between states. That is, what are the possible events and how states will change according to these events.

As we did on registering the possible states on the previous section, we have to list all possbible events that can occur in our state machine. For instance, in the state machine example given on section Defining the device state machine we have the following events:

Turn On
Turn Off
Start Phonebook
Close Phonebook
Start Calendar
Close Calendar

Also, we have to list how states are affected by each event. In our example the relationships would be:

Turn On event leads device to Idle if its current state is Off.

Turn Off event leads device to Off if its current state is Idle.
Turn Off event leads device to Off if its current state is Running Phonebook.
Turn Off event leads device to Off if its current state is Running Calendar.

Start Phonebook event leads device to Running Phonebook if its current state is Idle.

Close Phonebook event leads device to Idle if its current state is Running Phonebook.

Start Calendar event leads device to Running Calendar if its current state is Idle.

Close Calendar event leads device to Idle if its current state is Running Calendar.

After preparing these lists, we know all events that can occur on our state machine, and what are the transitions associated with each event.

Again on the example, The Turn Off event has three transitions associated with it. The rest of the events have only one.

Once we have these transitions well defined, we can proceed to registering them on the TmL framework.

As with the states, each event will need its own extension. And for the case of the events, the extension point is the org.eclipse.tml.serviceDefinition

Start Phonebook
Close Phonebook
Start Calendar
Close Calendar

Before we begin creating the state transitions, it is important to clarrify some facts.

First, when the talk about an event

Defining Icons

Inserting I18N support

Inserting LOG support

Inserting Exception support

Conclusion