|Oracle® Java Micro Edition Software Development Kit Developer's Guide
Release 3.4 for Eclipse on Windows
The JSR 256 Mobile Sensor API allows Java ME application developers to fetch data from sensors. A sensor is any measurement data source. This chapter describes how to work with JSR 256 in Oracle Java ME SDK.
Sensors can vary from physical sensors, such as magnetometers and accelerometers, to virtual sensors that combine and manipulate the data they have receive from various kinds of physical sensors. An example of a virtual sensor might be a level sensor indicating the remaining charge in a battery or a field intensity sensor that measures the reception level of the mobile network signal in a mobile phone.
JSR 256 supports many different types of sensor connection (wired, wireless, embedded and more) but Oracle Java ME SDK provides only preconfigured support for sensors embedded in the device.
The Oracle Java ME SDK GUI provides sensor simulation. The emulator's External Events Generator Sensors tab enables you to run a script that simulates sensor data.
You can use the API available with the SDK to create a custom sensor implementation with additional capabilities and support for different connection types.
Follow these steps to create a mobile sensor project:
Select File > New > MIDlet Project and fill in the information in the Create a MIDlet Project dialog box. Click Next.
On the MIDlet Project Content page, change the Microedition Configuration version to 1.1. Ensure that the MIDP version is 2.1. Click Finish.
Expand the finished project in the Package pane and double-click Application Descriptor to open the Overview pane.
Click the Application Descriptor tab at the bottom of the Overview pane and add configuration values for the embedded sensors shipped with the ME SDK as described below.
A sensor project freely detects sensors, but this does not imply you can get data from the sensors you find. You might need to explicitly set permissions in your project so you can interact with certain sensors. To see an example, open the Sensors sample project. Right-click Samples and select Properties, select the Application Descriptor category and select the API Permissions tab.
The following permissions work with the preconfigured embedded sensors shipped with the SDK:
Required to open a sensor connection and start measuring data.
Required to access a protected sensor.
Required to access a private sensor.
A sensor is private or protected if the sensor's security property has the value private or protected. The security property is an example of a sensor property you might create for yourself in your own sensor configuration. You can create your own optional properties using
.prop.any_name, where N is the sensor number and any_name is the name of your property. The security sensor property was created as follows:
# add security into proplist com.sun.javame.sensor<N>.proplist: security # add security property value com.sun.javame.sensor<N>.prop.security: private
The sample Sensor project can be installed over the air. To install the application into the emulator, follow these steps:
Expand the Sensors project node and double-click the Application Descriptor node.
Click Launch as emulated Java ME OTA under the Running section.
Alternatively, you can right-click a device and select Run Project via OTA and then select Sensors.
In the emulator window, click the Tools menus and select External Events Generator. In the External Events Generator, click the Sensors tab. In this tabbed pane, you can view all sensors that are currently available in the emulator (sensor ID, name, and availability are listed). If the sensor supports change to availability you can click on the check box to change it. As mentioned earlier, the provided implementation does not support availability change, but a custom implementation you create might do so.
When you select a sensor row, the bottom of the dialog displays any custom sensor controls. For example, the acceleration sensor, has three channels: axis_x, axis_y, and axis_z. Each channel has a slider that changes the current channel value, and an edit box you can use to input a value. The channel unit label is displayed on the far right.
Under the channels there is a script player control that enables you to play sensor value events from a script file of the format discussed in "Creating a Sensor Script File." See "SensorBrowser" for a description of how to use the Sensors demo.
To simulate sensor inputs, provide a sensor script. The file format is as follows:
Example 25-1 Sensor Script File Format Example
<sensors> <value time="0"> <channel id="0" value="0" /> <channel id="1" value="0" /> </value> <value time="100"> <sensor active="false"/> </value> <value time="100"> <channel id="0" value="-50" /> <channel id="1" value="10" /> <sensor active="true"/> </value> </sensors>
marbles.xml in the Sensors project directory is an example of a sensor script file. The attributes are as follows:
The attribute time in the value tag is the delay from the previous command in milliseconds.
channel tag sets the value of the channel with the specified id value, to value. The channel ignores the id if the value of id is not specified or if the value is out of the channel range.
sensor tag is a true or false value that makes the sensor available or unavailable. The preconfigured sensors provided with this release are embedded, so they cannot be deactivated. If you configure your own sensor that is not embedded, it is possible to deactivate it.
The SensorBrowser application displays the sensor detail information for reach channel defined for the demo.
In the emulator, select SensorBrowser and use the soft key to select Launch the application.
Depending on your security settings you might see the warning: "Sensors" wants to connect to sensor <#>. Is it OK to use sensor? For test purposes, select "Ask once per application use" and select the Yes soft button.
The emulator displays a list of sensors.
Use the navigation keys to highlight a sensor, then use the soft key to select Detail.
For example, the following screen shows the details for the acceleration sensor.
Figure 25-1 The Acceleration Sensor Screen
Click Back, then click Exit to return to the application menu.
This demonstration uses the Marbles game to provide visual feedback for sensor inputs provided in a script.
From the application menu select Marbles and use the soft key to launch the application.
In the emulator, click the Tools menu and select External Events Generator. Click the Sensors tab to display a list of the sensors in this application.
Select the Acceleration Sensor row (ID 3).
Click the Browse button, and in the Sensors project directory select
Observe the movement of the marbles on the emulator screen. On the external events screen you can see the sliders move as the script runs. You can use the familiar controls to play, pause, and stop the script.