|
|
| Line 1: |
Line 1: |
| − | =Creating TmL devices= | + | =The TmL Device Framework= |
| | | | |
| | == Purpose and Target audience == | | == Purpose and Target audience == |
| − | This tutorial provides directions on creating devices:LINK_CONCEPT for TmL. | + | This tutorial provides an introduction to the main concepts related to the TmL Device Framework. |
| | | | |
| − | The target audience is anyone who wants to create a device:LINK_CONCEPT in TmL context. | + | The target audience is anyone who wants to know more about the TmL Device Framework and/or wishes to use it. |
| | | | |
| − | == Initial requirements == | + | == Introduction == |
| − | Here follows the steps necessary to prepare the environment to create TmL devices.
| + | The TmL Device Framework is a critical piece of the TmL development environment. It is responsible for providing an extensible platform to support mobile devices and their aggregate services. Therefore, the main purpose of the TmL Device Framework is to integrate devices and emulators on the IDE. |
| | | | |
| − | # Download and install the most recent Eclipse Europa (3.3) version. Click [http://www.eclipse.org/downloads/ here] for the eclipse download site.
| + | The main concepts that will be presented in this tutorial are the following: |
| − | # Connect to Eclipse CVS Repository and get the project set for Common utilities (see instructions [http://www.eclipse.org/dsdp/tml/development/cvs_setup.php here]).
| + | * Service |
| | + | * Mobile Device |
| | + | * State Machine |
| | | | |
| − | After that, your workspace should contain a new project named '''org.eclipse.tml.common.utilities'''.
| + | == Service == |
| | + | The Device Framework defines a set of actions called services and associates them to the device. To understand this, first you need to know what is a 'state' and how it relates to a service. |
| | | | |
| − | == Creating a TmL device ==
| + | A state represents the status of a device, such as "started", "idle" and "stopped". To change from state to state, you need to define a service. Therefore, a service represents the transition between a pair of states. A same service can be used by more than one pair of states. |
| − | The process of creating a TmL device consists of the following:
| + | |
| | | | |
| − | # Defining the state machine which describes the device behavior in what concerns the TmL framework.
| + | Regarding the implementation, a service is implemented as a plug-in. A service also provides implementations that are either general enough, such as the VNC viewer, or that must be extended by specific plugins, like the status state machine. |
| − | # Instantiating the new device on the TmL framework.
| + | |
| − | # Setting up the device state machine on the TmL framework. This comprises the following steps:
| + | |
| − | ## Creating one eclipse extension to represent each of the states pertaining to the device state machine.
| + | |
| − | ## 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.
| + | |
| | | | |
| | + | === Mobile Device === |
| | | | |
| | + | A mobile device represents an abstract description of a real device or a device emulator. It must be implemented as a plug-in that extends the device extension point defined by the Device Framework. The device object typically contains binary executables that emulate the mobile device or a collection of scripts that manage the connection between the host computer and the mobile device itself. |
| | | | |
| − | === Instantiating the new device on the TmL framework ===
| + | Before using a mobile device, you need to create an instance of it. Several instances of the same device must be created as long as they have non-conflicting properties. For instance, they must each have different ports. |
| − | 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.
| + | Every mobile device must support a set of services. This set is what defines the state machine that rules your mobile device. |
| | | | |
| − | The following steps guide you in creating this extension point.
| + | === State Machine === |
| | | | |
| − | # Create the eclipse plug-in where the extension point is going to be created. To do this, perform the following steps:
| + | As mentioned earlier, a service connects a pair of states. A set of states and their respective services is what we call a state machine. |
| − | ## Choose '''File''' > '''New''' > '''Project...'''.
| + | |
| − | ## Under '''Plug-in Development''' folder, select '''Plug-in Project''' and click '''Next'''.
| + | |
| − | ## Type a name for the project.<br />'''NOTE''': If this plug-in will be contributed to TmL, certify that it is using the naming conventions in [http://wiki.eclipse.org/index.php/Development_Conventions_and_Guidelines Development Conventions and Guidelines] or check with TmL committer the best name for that. (ex: org.eclipse.tml.sampledevice).
| + | |
| − | ## On the '''Target Platform''' section, set '''Eclipse Version''' to '''3.3'''. Click '''Next'''.
| + | |
| − | ## Fill '''Plug-in Version''', '''Plug-in Name''' and '''Plug-in Provider'''.
| + | |
| − | ## Change the default name for '''Activator''' to the format "<your-plugin-name>Plugin". (ex: SampledevicePlugin). Click '''Next'''.
| + | |
| − | ## Uncheck '''"Create a plug-in using one of the templates"''' option. Click '''Finish'''.
| + | |
| − | ## 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).
| + | |
| − | # Configure the plug-in to work with the TmL framework
| + | |
| − | ## On '''Project Explorer''' view, right-click the plugin project entry and select '''PDE Tools''' > '''Open Manifest'''.
| + | |
| − | ## Click the '''Dependencies''' tab.
| + | |
| − | ## Add '''org.eclipse.tml.common.utilities''' as a dependency.
| + | |
| − | # Create the extension point that instantiates the new device. To do this, perform the following steps:
| + | |
| − | ## On '''Project Explorer''' view, right-click the plugin project entry and select '''PDE Tools''' > '''Open Manifest'''.
| + | |
| − | ## Click the '''Extensions''' tab.
| + | |
| − | ## Click '''Add''' so as to add the extension '''org.eclipse.tml.device'''.
| + | |
| − | ## 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'''.<br /> If you are asked to add new plug-in dependencies as a consequence of creating this extension point, click '''Yes'''.
| + | |
| − | ## Fill '''description''', '''version''', '''provider''' and '''copyright''' fields.
| + | |
| − | ## Create the >>>>>>>>>>>>>>> CONCEPT ->handler class for the device. To do this, perform the following steps:
| + | |
| − | ### Click [[http://wiki.eclipse.org/DSDP/TML/Creating_TmL_Plugins/device_handler_class_template here]] for the handler class template.
| + | |
| − | ### Create the java package for this class and place the handler class at this package.<br />The java package for the device hanler class should be named according to the convention: '''org.eclipse.tml.device.'''<DEVICE_NAME>'''.handler'''.
| + | |
| − | ### >>>>>>>>>>>>>> What is this handler purpose? <- put this on the concept section.
| + | |
| − | ## Add an icon to your device.<br /> >>>>>>>>>>>>>> Is the icon mandatory?<br /> >>>>>>>>>>>>>> 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.
| + | Therefore, the state machine defines basically how your mobile device works. It shows not only the possible states the mobile device can achieve, but also if such achievement has any prerequisites. So, a good way to think of the state machine is as a diagram where the states are represented as circles and the services are arrows. An arrow pointing from one state to another means that the mobile device needs to be in the first state before changing to the second state. |
| − | | + | |
| − | === 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:
| + | |
| − | # Click the '''Extensions''' tab for the plug-in where you are creating the device.
| + | |
| − | # Click '''Add''' so as to add the extension '''org.eclipse.tml.status'''.
| + | |
| − | # 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'''.<br /> If you are asked to add new plug-in dependencies as a consequence of creating this extension point, click '''Yes'''.<br />A new entry named '''org.eclipse.tml.status''' appears on the list of current extensions for this plug-in.
| + | |
| − | # Click the entry '''org.eclipse.tml.status''' just created and expand its contents.
| + | |
| − | # Select the entry inside it, should be something like '''org.eclipse.tml.sampledevice.status1'''.
| + | |
| − | # Change '''id''' and '''name''' to a label that properly describes your status. They should be both named equally.
| + | |
| − | # Choose an image for the state.<br /> >>>>>>>>>>>>>>>> What's its purpose?<br /> >>>>>>>>>>>>>>>> Is it mandatory?
| + | |
| − | # Leave '''canDeleteInstance''' field blank.
| + | |
| − | # Save changes.<br />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 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'''<br />'''Turn Off'''<br />'''Start Phonebook'''<br />'''Close Phonebook'''<br />'''Start Calendar'''<br />'''Close Calendar'''<br />
| + | |
| − | | + | |
| − | | + | |
| − | 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'''.<br />'''Turn Off''' event leads device to '''Off''' if its current state is '''Running Phonebook'''.<br />'''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.
| + | |
| − | | + | |
| − | For each event on the device state machine, perform the following steps:
| + | |
| − | | + | |
| − | # Click the '''Extensions''' tab for the plug-in where you are creating the device.
| + | |
| − | # Click '''Add''' so as to add the extension '''org.eclipse.tml.serviceDefinition'''.
| + | |
| − | # 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'''.<br /> If you are asked to add new plug-in dependencies as a consequence of creating this extension point, click '''Yes'''.<br />A new entry named '''org.eclipse.tml.serviceDefinition''' appears on the list of current extensions for this plug-in.
| + | |
| − | # Click the entry '''org.eclipse.tml.serviceDefinition''' just created and expand its contents.
| + | |
| − | # Select the entry named '''(Service)'''.
| + | |
| − | # Add an '''id''' to the service. >>>>>>>>>>>>>> Use the naming convention '''org.eclipse.tml.service.<service_name>.<service_name>Service'''.<br /> 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.
| + | |
| − | # Create the handler class to this service and add its path to the '''handler''' field.<br />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.
| + | |
| − | # For each transition that occurs as a consequence of this event, perform the following steps:
| + | |
| − | ## Expand the entry '''org.eclipse.tml.serviceDefinition''' (if not already expanded) on the list of extensions.
| + | |
| − | ## Right-click the entry inside it.<br />It should show a menu with the option '''New''' > '''Satus'''.
| + | |
| − | ## Choose '''New''' > '''Satus'''.<br />A new sub-entry is created. this entry represents a state transition.
| + | |
| − | ## Select this entry and on the right, fill the three states that define a transition:<br />The '''startId''' refers to the status the device is prior to the occurrence of the event.<br />The '''endId''' refers to the status the device assumes in case the event occurs.<br />Finally, the '''haltId''' is the state the device assumes in the case the service triggered by the handler does not complete successfully. >>>>>>>>>>>>>>> For most cases, the '''haltId''' is the same as the '''startId'''.
| + | |
| − | # Save changes.<br />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.
| + | |
| − | | + | |
| − | == Defining Icons ==
| + | |
| − | | + | |
| − | == Inserting I18N support ==
| + | |
| − | | + | |
| − | == Inserting LOG support ==
| + | |
| − | | + | |
| − | == Inserting Exception support ==
| + | |
| − | | + | |
| − | == Conclusion ==
| + | |
This tutorial provides an introduction to the main concepts related to the TmL Device Framework.
The target audience is anyone who wants to know more about the TmL Device Framework and/or wishes to use it.
The TmL Device Framework is a critical piece of the TmL development environment. It is responsible for providing an extensible platform to support mobile devices and their aggregate services. Therefore, the main purpose of the TmL Device Framework is to integrate devices and emulators on the IDE.
The Device Framework defines a set of actions called services and associates them to the device. To understand this, first you need to know what is a 'state' and how it relates to a service.
A state represents the status of a device, such as "started", "idle" and "stopped". To change from state to state, you need to define a service. Therefore, a service represents the transition between a pair of states. A same service can be used by more than one pair of states.
Regarding the implementation, a service is implemented as a plug-in. A service also provides implementations that are either general enough, such as the VNC viewer, or that must be extended by specific plugins, like the status state machine.
A mobile device represents an abstract description of a real device or a device emulator. It must be implemented as a plug-in that extends the device extension point defined by the Device Framework. The device object typically contains binary executables that emulate the mobile device or a collection of scripts that manage the connection between the host computer and the mobile device itself.
Before using a mobile device, you need to create an instance of it. Several instances of the same device must be created as long as they have non-conflicting properties. For instance, they must each have different ports.
Every mobile device must support a set of services. This set is what defines the state machine that rules your mobile device.
As mentioned earlier, a service connects a pair of states. A set of states and their respective services is what we call a state machine.
Therefore, the state machine defines basically how your mobile device works. It shows not only the possible states the mobile device can achieve, but also if such achievement has any prerequisites. So, a good way to think of the state machine is as a diagram where the states are represented as circles and the services are arrows. An arrow pointing from one state to another means that the mobile device needs to be in the first state before changing to the second state.
