Jump to: navigation, search

DSDP/TML/Creating TmL Plugins

< DSDP‎ | TML

Creating TmL devices

Purpose and Target audience

This tutorial provides directions on creating devices for TmL.

The target audience is anyone who wants to create a device 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 framework. 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 states. 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:

State-machine-graph.png

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 phones) 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 plug-in 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 plug-in to work with the TmL framework
    1. On Project Explorer view, right-click the plugin project entry and select PDE Tools > Open Manifest.
    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, right-click the plugin project entry and select PDE Tools > Open Manifest.
    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. Select the entry org.eclipse.tml.device just created.
    6. Add an ID to the device. The device ID must conform to the naming convention org.eclipse.tml.device.<DEVICE_NAME>.<DEVICE_NAME>Device.
    7. Add a name to the device: For example, "<DEVICE_NAME> Mobile Device".
    8. Fill description, version, provider and copyright fields.
    9. Create the handler class for the device. To do this, perform the following steps:
      1. Click [here] for the handler class template.
      2. Create the java package for this class and place the handler class at this package.
        The java package for the device hanler class should be named according to the convention: org.eclipse.tml.device.<DEVICE_NAME>.handler.
    10. Add an icon to your device.
      The device icon serves as decoration purpose when the device entry is show on eclipse IDE. It is not mandatory but it is highly recommended. You can edit your own icon (a 16x16 pixels gif file) or use this one: Standard-device-icon.gif.

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 framework

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 plug-in 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 that properly describes your status. They should be both named equally.
  7. Choose an image for the state.
    This icon serves as decoration purpose to represent the device state on the eclipse IDE. It is not mandatory but is highly recommended.
    Compose a 16x16 pixels gif image that represents the state you are creating.
  1. Leave canDeleteInstance field blank.
  2. Save changes.
    The state is now registered.

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 state transitions according to the events

Understanding how to register the state transitions on the TmL framework

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 possible 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 as well as 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 org.eclipse.tml.serviceDefinition. The term "Service Definition" comes from the fact that each event on the device state machine is associated with an operation that can be performed on the device. And on the TmL framework, the operations that can be performed on devices are referred as Services.

Thus, in our example, each of the 6 events (or services) on our state machine must have an extension on the org.eclipse.tml.serviceDefinition extension point. And each extension must be set up so as to contain all transitions associated with the event.

So, after this introductory part, we are ready to create the extensions that will represent the states transitions.

Registering the state transitions on the TmL framework

For each event on the device state machine, perform the following steps:

  1. Click the Extensions tab for the plug-in where you are creating the device.
  2. Click Add so as to add the extension org.eclipse.tml.serviceDefinition.
  3. Uncheck "Show only extension points from the required plug-ins" option, look for the org.eclipse.tml.serviceDefinition 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.serviceDefinition appears on the list of current extensions for this plug-in.
  4. Click the entry org.eclipse.tml.serviceDefinition just created.
  5. Add the Id to the service. IMPORTANT: The service ID must be the same as the device ID defined on section Instantiating the new device on the TmL framework. That is, org.eclipse.tml.device.<DEVICE_NAME>.<DEVICE_NAME>Device.
    This creates an association between the service definition and the device. That is, to which device state machine this transition belongs to.
  6. Click the entry org.eclipse.tml.serviceDefinition just created and expand its contents.
  7. Select the entry named (Service).
  8. Add an id to the service. [TBD: Simplify the convention]Use the naming convention org.eclipse.tml.service.<service_name>.<service_name>Service.
    By performing this, the event is created but it is still necessary to set up how this event affect the states on the device state machine.
  9. Create the handler class to this service and add its path to the handler field.
    The handler of a service consists basically of class that will contain a method which performs the operation related to the service on the device itself. For instance, a Turn On event would require a handler that issued a command to turn on the device.
  10. For each transition that occurs as a consequence of this event, perform the following steps:
    1. Expand the entry org.eclipse.tml.serviceDefinition (if not already expanded) on the list of extensions.
    2. Right-click the entry inside it.
      It should show a menu with the option New > Status.
    3. Choose New > Status.
      A new sub-entry is created. this entry represents a state transition.
    4. Select this entry and on the right, fill the three states that define a transition:
      The startId refers to the status the device is prior to the occurrence of the event.
      The endId refers to the status the device assumes in case the event occurs.
      Finally, the haltId is the state the device assumes in the case the service triggered by the handler does not complete successfully. [TBD:Exemplify a case where haltId is a new state] For most cases, the haltId is the same as the startId.
  11. Save changes.
    The event is now properly registered for the device.

After you have registered all events pertaining to the device state machine, the device is properly set up on the TmL framework and is ready to be used.


Inserting I18N support

[TBD: Write documentation]

Inserting LOG support

[TBD: Write documentation]

Inserting Exception support

[TBD: Write documentation]

Conclusion

[TBD: Write]