Tutorial for how to build a small palpable device using the PalCom device and service frameworks

Two projects under palcom/developer/frameworks contain framework classes for building palpable devices and services: In the project palcom/developer/tools/simulation/simulated-devices there are facilities for building simulated devices, that simulate the hardware of a device.

This small tutorial shows how to create a palpable device. It uses the EchoDevice example, that is checked in under palcom/developer/application-layer/services/echo. EchoDevice has a simple service that echoes its input back.

The first part of the tutorial explains the overall structure of the EchoDevice code. After that, we show how to compile and start EchoDevice. Then follows a part about how to interact with EchoDevice through the browser in the PalCom Developer's Browser (the EclipseBrowser Eclipse plugin). The last part goes through the EchoDevice code in more detail and explains how a simple palpable device can be written.

Overall structure of the code

The code for EchoDevice is in the package ist.palcom.services.echo under palcom/developer/application-layer/services/echo.

The class EchoService implements the service of echoing back what is sent to it. It extends AbstractService and has a service description, which means that it is a service that sends and receives commands.

EchoDevice is the "main class" of a device with the echo service. It extends AbstractDevice, which means that it handles the setup of communication and discovery on a device, and starts and stops services. EchoDevice is intended to be used both on the Pal-VM and on the JVM.

EchoDeviceGUI is a simulated device with the echo functionality. It shows a simple Swing window when run. EchoDeviceGUI extends AbstractSimulatedDeviceGUI, the base class of simulated devices. The idea is that you can implement simulated interaction with the device hardware in Swing. For EchoDeviceGUI there is no real interaction. It just shows a small text, for illustration.

Compiling and running the code

For building the EchoDevice classes, run the Ant script palcom/developer/dev-lib/build.xml. If you have the dev-lib project open in Eclipse, run the Ant script by right-clicking on build.xml, and choosing Run As->Ant Build. JastAdd classes will be generated, and Eclipse will automatically compile the Java classes.

If you work on the command-line, go to the dev-lib directory and run the command "ant". The Ant script will compile the code and place it in the file dev-lib/jars/generated/palcom-applications.jar.

For running the echo device, there are two main alternatives. One is to start the class EchoDevice, which runs like it was running on a small palpable device, with the Java main method as the entry point. The other alternative is to start EchoDeviceGUI, which shows up as a Swing window.

In Eclipse, you can start the EchoDevice by running the main method in EchoDevice.java (right-click on the file, choose Run As->Java Application). The device runs until you stop the program (press the red square in the Console view). For running from the command line, do the following, standing in the dev-lib/jars/generated directory:

java -cp palcom-applications.jar ist.palcom.services.echo.EchoDevice

Stop the device by pressing Ctrl+C.

EchoDeviceGUI is started the same way in Eclipse, by running EchoDeviceGUI.java instead. From the command-line, do the following, standing in the dev-lib/jars/generated directory:

java -cp palcom-applications.jar ist.palcom.services.echo.EchoDeviceGUI

The device can be stopped by closing the small window.

Interacting with EchoDevice in the PalCom Developer's Browser

The PalCom Developer's Browser is checked in under palcom/developer/tools/browsers. Follow the instructions in Section 7.2 of The PalCom Developer's Companion for how to set it up and start it.

When the PalCom Developer's Browser has started, the Browser view will show nearby devices and services. Start an EchoDevice using one of the methods described above. A device named EchoDevice (or with a name starting on EchoDevice for EchoDeviceGUI) will appear under Universe->Devices in the Browser view.

For interacting with the EchoDevice, expand it in the Browser view, right-click on EchoService and choose Control. This will establish a connection between the browser and the EchoService (the connection shows up under Connections). Right-click on EchoService again, and choose Open UI. A user interface will be shown in the browser. In the user interface, enter some text for the value parameter of the command In, and press the button. The service will echo your input, and it will show in the out-going command in the user interface.

The browser has more functionality for interacting with services, most importantly support for assemblies. See The PalCom Developer's Companion for information about how to work with assemblies.

Details about the EchoDevice code

The code in the echo device can be used as a starting point when writing a small palpable device.

EchoDevice

Figure 1 shows an overview of the classes used with EchoDevice.


Figure 1 EchoDevice and the classes it uses.

The EchoDevice class extends ist.palcom.device.AbstractDevice. In AbstractDevice, a run method is defined that runs a scheduler and initializes the device. The constructor of EchoDevice simply calls the super constructor with the DeviceID passed as a parameter (the DeviceID identifies the device).

The initDevice method is overridden for creating and starting the EchoService of the device. The service is also added to the DeviceContext of the device. The DeviceContext holds references to all services on a device, and to all managers used by services on the device. For creating a custom DeviceContext, the method createDeviceContext in AbstractDevice can be overridden, but that has not been done for EchoDevice - the intention is that the standard DeviceContext should suffice for most devices. At the end of EchoDevice's initDevice, super.initDevice is called for doing setup in the superclass.

The stopDevice method in EchoDevice has been overridden for a similar purpose as for initDevice: to stop the echo service. Also here, the method in the superclass is called last for doing general teardown.

The main method of EchoDevice could be the main method on a small palpable device. It creates an EchoDevice object and runs it.

EchoService

EchoService extends AbstractService and provides a service that is described by a service description. In the constructor of EchoService, the super constructor is called with the passed DeviceContext, a suitable name, a service proxy that is created by the createServiceProxy utility method, and a LocalSID that identifies the service. A service proxy is an instance of a service description. It is used for describing the command and parameter structure of the service, and also for receiving and sending out commands over a connection (the connection handling is set up by the superclass). The constructor also creates a thread that takes care of received commands, and adds it as an in-command receiver at the service proxy.

The start and stop methods are overridden for scheduling and terminating the command thread.

Finally, the CommandThread class repeatedly waits for command events and sends out command swith the same parameter value. The findItem method in ServiceProxy is called for looking up an out-going command by name. The invoke call makes the out-command go out over the connection.

EchoDeviceGUI

EchoDeviceGUI is a simplified example of a simulated device. Figure 2 shows an overview of the classes used with EchoDeviceGUI.


Figure 2 EchoDeviceGUI and the classes it uses.

EchoDeviceGUI has no real user interaction. A few things are important to note, though:

The main method uses AbstractDeviceFactory for starting the simulated device.

Other examples

Under palcom/developer/application-layer/services, there are a number of devices and services of different complexities. Some of them are simulated. The Timer example is very similar to EchoDevice, but it shows a service that uses push functionality, and does not follow a request-reply scheme.
David Svensson Fors, david@cs.lth.se