Skip Headers
Oracle® Java Micro Edition Software Development Kit Developer's Guide
Release 3.0.5 for Windows
  Go To Table Of Contents
Go To Index


30 JSR 256: Mobile Sensor API Support

The JSR 256 Mobile Sensor API allows Java ME application developers to fetch data from sensors. A sensor is any measurement data source. Sensors can vary from physical sensors such as magnetometers and accelerometers to virtual sensors that combine and manipulate the data they have received 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 this SDK release only provides preconfigured support for sensors embedded in the device.

The SDK GUI provides sensor simulation. The emulator's External Events Generator Sensors tab allows you to run a script that simulates sensor data.

You can use the custom API available with the SDK to create a custom sensor implementation with additional capabilities and support for different connection types.

The Sensors demonstration has two MIDlets, SensorBrowser and Marbles that demonstrate the SDK's implementation of the Mobile Sensor API. Use the Run via OTA feature to install the application into the emulator.

30.1 Creating a Mobile Sensor Project

To use this API, create a project with the target platform Custom. You must select MIDP 2.0 or higher and CLDC 1.1 before you can select the Mobile Sensor API optional package.

To set permissions, click the Settings button and choose the Permissions icon.

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.

The following permissions work with the preconfigured embedded sensors shipped with the SDK:

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 com.sun.javame.sensorN.proplist and com.sun.javame.sensorN.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> private

30.2 Using a Mobile Sensor Project

A Sensor project can be installed over the air. In the emulator window, select Device > Sensors. In this tab you can view all sensors currently available in the emulator, with the sensor ID, name, and availability. 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 script player control that allows you to play sensor value events from a script file of the format discussed in Section 30.3, "Creating a Sensor Script File". See Section 30.4, "SensorBrowser" for a description of how to use the Sensors demo.

30.3 Creating a Sensor Script File

To simulate sensor inputs, provide a sensor script. The file format is as follows:

   <value time="0">
      <channel id="0" value="0" />
      <channel id="1" value="0" />
   <value time="100">
      <sensor active="false"/>
   <value time="100">
      <channel id="0" value="-50" />
      <channel id="1" value="10" />
     <sensor active="true"/>

The file installdir\apps\Sensors\marbles.xml is an example of a sensor script file. The attributes are as follows:

30.4 SensorBrowser

The SensorBrowser application displays the sensor detail information for reach channel defined for the demo.

  1. In the emulator select SensorBrowser and use the soft key to select Launch the application.

    The emulator displays a list of sensors.

  2. 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.

    Description of sensors-browse.gif follows
    Description of the illustration sensors-browse.gif

    Click Back, then click Exit to return to the application menu.

30.5 Marbles

This demonstration uses the Marbles game to provide visual feedback for sensor inputs provided in a script.

  1. From the application menu select Marbles and use the soft key to launch the application.

  2. In the emulator, select Device > Sensors.

    The emulator displays a list of the sensors in this application.

  3. Click the Browse button and choose the following file: installdir\apps\Sensors\marbles.xml.

  4. 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.