Sun Microsystems Small Programmable Object Technology User Manual

Sun™ Small Programmable Object Technology (Sun SPOT)

Developers’ Guide

This version of the Guide refers to V2.0

(updated 16-April-2007)

Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries.

U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements.

Use is subject to license terms.

This distribution may include materials developed by third parties.

Sun, Sun Microsystems, the Sun logo, Java and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S.embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

Sun Microsystems, Inc. détient les droits de propriété intellectuels relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plus des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats Unis et dans les autres pays.

L'utilisation est soumise aux termes de la Licence.

Cette distribution peut comprendre des composants développés par des tierces parties.

Sun, Sun Microsystems, le logo Sun, Java et le logo Java Coffee Cup sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans d'autres pays.

Ce produit est soumis à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.

Contents

Introduction .................................................................................................................................... 5

Building and deploying Sun SPOT applications .............................................................................. 6

Deploying and running a sample application................................................................................................ 6

Deploying a pre-existing jar .................................................................................................................................... 12

Incorporating utility classes into your application .................................................................................................. 12

Excluding files from the compilation...................................................................................................................... 13

Manifest and resources................................................................................................................................ 13

Other user properties ............................................................................................................................................... 13

Built-in properties ................................................................................................................................................... 14

Using the Basestation.................................................................................................................................. 14

Overview ................................................................................................................................................................. 14

Set up ...................................................................................................................................................................... 15

Base Station configuration ...................................................................................................................................... 16

Remote operation ........................................................................................................................................ 16

Introduction ............................................................................................................................................................. 16

Ensure that the remote Sun SPOT is executing the OTA Command Server ........................................................... 16

Connect a Sun SPOT base station ........................................................................................................................... 17

Launch the spot client to control a remote Sun SPOT via the base station ............................................................. 17

Using short names for SPOTs ................................................................................................................................. 18

Take suitable actions during over-the-air downloads.............................................................................................. 18

Managing keys and sharing Sun SPOTs ..................................................................................................... 18

Background ............................................................................................................................................................. 18

Changing the owner of a Sun SPOT ....................................................................................................................... 19

Sharing Sun SPOTs................................................................................................................................................. 19

What is protected?................................................................................................................................................... 20

Generating a new key-pair ...................................................................................................................................... 20

Limitations .............................................................................................................................................................. 20

Deploying and running a host application................................................................................................... 20

Example .................................................................................................................................................................. 20

Your own host application ...................................................................................................................................... 21

Incorporating pre-existing jars into your host application....................................................................................... 21

Configuring network features...................................................................................................................... 21

Mesh routing ........................................................................................................................................................... 21

Trace route .............................................................................................................................................................. 22

Logging ................................................................................................................................................................... 22

Hardware configurations and USB power .................................................................................................. 22

Developing and debugging Sun SPOT applications ....................................................................... 24

Overview of an application ......................................................................................................................... 24

Threads........................................................................................................................................................ 24

Thread priorities ...................................................................................................................................................... 24

The Sun SPOT device libraries ................................................................................................................... 25

Introduction ............................................................................................................................................................. 25

Sun SPOT device library......................................................................................................................................... 25

Persistent properties ................................................................................................................................................ 26

Overriding the IEEE address ................................................................................................................................... 27

Accessing flash memory ......................................................................................................................................... 27

Using input and output streams over the USB and USART connections................................................................ 28

The radio communication library................................................................................................................ 29

Radio properties ...................................................................................................................................................... 35

Monitoring radio activity ........................................................................................................................................ 37

Conserving power using deep sleep mode .................................................................................................. 37

Shallow Sleep.......................................................................................................................................................... 37

Deep Sleep .............................................................................................................................................................. 38

Activating deep sleep mode .................................................................................................................................... 38

USB inhibits deep sleep .......................................................................................................................................... 39

Preconditions for deep sleeping .............................................................................................................................. 39

Deep sleep behaviour of the standard drivers.......................................................................................................... 39

The deep sleep/wake up sequence........................................................................................................................... 39

Writing a device driver............................................................................................................................................ 40

http protocol support ................................................................................................................................... 41

Configuring the http protocol .................................................................................................................................. 41

Socket Proxy GUI mode ......................................................................................................................................... 42

Configuring projects in an IDE ................................................................................................................... 42

Classpath configuration........................................................................................................................................... 43

Javadoc/source configuration .................................................................................................................................. 43

Debugging................................................................................................................................................... 43

Limitations .............................................................................................................................................................. 44

Configuring NetBeans as a debug client ................................................................................................................. 45

Configuring Eclipse as a debug client..................................................................................................................... 45

Advanced topics.......................................................................................................................................... 46

Using library suites ................................................................................................................................................. 46

Using the spot client................................................................................................................................................ 49

Reference..................................................................................................................................................... 51

Persistent system properties .................................................................................................................................... 51

Memory usage......................................................................................................................................................... 52

SDK files................................................................................................................................................................. 52

Introduction

The purpose of this guide is to aid developers of applications for Sun SPOTs. The guide is divided into two sections.

Building and deploying Sun SPOT applications provides information about how to build, deploy and execute Sun SPOT applications. The topics covered include:

• Building and deploying simple applications

• Deploying applications you’ve received as jars from other developers

• Including properties and external resources through the manifest

• Setting up a base station to communicate with physically remote Sun SPOTs via the radio

• Using the base station to deploy and execute applications on remote Sun SPOTs

• Building and running your own application running on the host machine that communicates,

via the base station, with remote Sun SPOTs

• Managing the keys that secure your Sun SPOTs against unauthorised access

•

Sharing keys to allow a workgroup to share a set of Sun SPOTs.

Developing and debugging Sun SPOT applications provides information for the programmer. This includes

•

A quick overview of the structure of Sun SPOT applications

• Using the Sun SPOT libraries to

o Control the radio o

Read and write persistent properties

Read and write flash memory

Access streams across the USB connection

Use deep sleep mode to save power

Access http

•

Debug applications

• Configure your IDE

• Modify the supplied library

•

Write your own host-side user interface for controlling Sun SPOTs

This guide does not cover these topics:

•

The libraries for controlling the demo sensor board

• Installation of the SDK.

Building and deploying Sun SPOT applications

Deploying and running a sample application

The normal process for creating and running an application (assuming you are working from the command line rather than an IDE) is:

• Create a directory to hold your application.

• Write your Java code.

•

Use the supplied ant script to compile the Java and bind the resulting class files into a deployable unit.

• Use the ant script to deploy and run your application.

In this section we will describe how to build and run a very simple application supplied with the SDK. Each step is described in detail below.

1. The directory

Demos/CodeSamples/SunSpotApplicationTemplate

contains a very simple Sun

SPOT application that can be used as a template to write your own.

The complete contents of the

template

directory should be copied to the directory in which you wish to do your work, which we call the root directory of the application. You can use any directory as the root of an application. In the examples below we have used the directory

C:\MyApplication

All application root directories have the same layout. The root directory contains two files -

build.xml

The root directory also contains three sub-directories. The first, named source code tree for this application. The second, named your IDE is Netbeans. The third, named

build.properties –

and

that control the ant script used to build and run applications.

src,

is the root of the

resources

nbproject

, contains the manifest file that defines the

, contains project files used if

application plus any other resource files that the application needs at run time. Other directories will appear during the build process.

2. Compile the template example and create a jar that contains it by using the “ command. The created jar is called

C:\MyApplication>ant jar-app Buildfile: build.xml

-pre-init:

-init-user:

-init-system:

-do-init:

-post-init:

init:

-set-jar-name:

-pre-clean:

-do-clean:

imlet.jar

and is created in the

suite

ant jar-app

folder.

”

[delete] Deleting directory C:\MyApplication\build [delete] Deleting directory C:\MyApplication\suite [delete] Deleting directory C:\MyApplication\j2meclasses

-post-clean:

clean:

-pre-compile:

-do-compile: [mkdir] Created dir: C:\MyApplication\build [javac] Compiling 1 source file to C:\MyApplication\build

-post-compile:

compile:

-pre-preverify:

-make-preverify-directory: [mkdir] Created dir: C:\MyApplication\j2meclasses

-unjar-utility-jars:

-do-preverify:

-post-preverify:

preverify:

-pre-jar-app:

-find-manifest:

-do-jar-app: [mkdir] Created dir: C:\MyApplication\suite [jar] Building jar: C:\MyApplication\suite\imlet.jar

-post-jar-app:

jar-app:

BUILD SUCCESSFUL Total time: 1 second C:\MyApplication>

If you have any problems with this step you need to ensure your Java JDK and Ant distributions are properly installed, as per the instructions in the Installation Guide.

3. Connect the Sun SPOT to your desktop machine using a mini-USB cable.

4. Check communication with your Sun SPOT using the “

ant info

” command, which displays

information about the device.

C:\MyApplication>ant info Buildfile: build.xml

-pre-init:

-init-user:

-init-system:

-do-init:

-post-init:

init:

-override-warning-find-spots:

-main-find-spots: [echo] Using Sun SPOT device on port COM45

-do-find-spots:

slots:

-run-spotclient-with-optional-remoteId:

-run-spotclient-with-script-contents:

-run-spotclient: [java] Waiting for target to synchronise... [java] (please reset SPOT if you don't get a prompt) [java] [waiting for reset]

[java] Sun SPOT bootloader (1514-20060824) [java] SPOT serial number = 0014.4F01.0000.011D

[java] Application slot contents: [java] 0: C:\arm9\BounceDemo-OnSPOT/suite/image (Thu Aug 24 12:51:22 BST 2006) [java] 28196 bytes at 0x10140000 [java] 1: /home/Syntropy/SunSPOT/sdk-21Aug2006/tests/spottests/suite/image (Thu Aug 24 16:39:14 BST 2006) [java] 115452 bytes at 0x101a0000 (current)

[java] OTA Command Server is enabled [java] Not ignoring application suite at startup [java] Squawk startup command line: [java] -Xmx:470000 [java] -Xmxnvm:128 [java] -isolateinit:com.sun.spot.peripheral.Spot [java] -MIDlet-1 [java] Library suite hash: [java] 0x50b227

[java] Exiting [delete] Deleting: C:\SunSPOT\dev\temp\spot-temp-1808154274

info:

BUILD SUCCESSFUL Total time: 3 seconds C:\MyApplication>

If you don't see the expected output, try pressing the Sun SPOT’s control button.

You will notice that the communication port has been automatically detected (COM45 in this example). If you have more than one Sun SPOT detected, the ant scripts will present you with a menu of connected Sun SPOTs and allow you to select one.

You may not wish to use the interactive selection process each time you run a script. As an alternative, you can specify the port yourself on the command line:

ant -Dspotport=COM2 info

ant –Dport=COM2 info

The difference between these two commands is that the “ is a Sun SPOT connected to the specified port, whereas the “

spotport

port

” version will check that there

” version will attempt to

connect to a Sun SPOT on the specified port regardless. You should normally use the

spotport

“

” version. If you prefer, you may specify the port in the

build.properties

file of the

application:

spotport=COM2

port=COM2

On Unix-based systems, including Mac OS X, if you see an

UnsatisfiedLinkError

exception, this means that you need to create a spool directory for the communications driver RXTX to use, as locks are places in that directory. See the section notes on the RXTX driver in the Installation Guide for guidance on how to set up your spool directory.

5. To deploy the example application, use the “

C:\MyApplication>ant jar-deploy Buildfile: build.xml

-pre-init:

-init-user:

-init-system:

-do-init:

-post-init:

init:

-set-jar-name:

-check-for-jar:

-override-warning-find-spots:

-main-find-spots: [echo] Using Sun SPOT device on port COM45

-do-find-spots:

-pre-suite:

-do-suite: [exec] [loaded object memory from 'file://C:/SunSPOT/dev/lib/translator.suite'] [exec] [loaded object memory from 'file://C:/SunSPOT/dev/arm/transducerlib.suite'] [exec] [Loaded squawk.imlet.Startup] [exec] [Including resource: META-INF/MANIFEST.MF] [exec] [Adding property key: Manifest-Version value: 1.0] [exec] [Adding property key: Ant-Version value: Apache Ant 1.6.5] [exec] [Adding property key: Created-By value: 1.5.0_06-b05 (Sun Microsystems Inc.)] [exec] [Adding property key: MIDlet-Name value: Test] [exec] [Adding property key: MIDlet-Version value: 1.0.0]

ant jar-deploy

” command.

[exec] [Adding property key: MIDlet-Vendor value: Sun Microsystems Inc] [exec] [Adding property key: MIDlet-1 value: Spottests,, squawk.application.Startup] [exec] [Adding property key: MIDlet-2 value: TestMIDlet label,, com.sun.spot.TestIMlet] [exec] [Adding property key: MicroEdition-Profile value: IMP-1.0] [exec] [Adding property key: MicroEdition-Configuration value: CLDC-1.1] [exec] [Including resource: res1.txt] [exec] Created suite and wrote it into image.suite

[exec] ------------------------------------------------------------------- [exec] Hits - Class:98.07% Monitor:88.74% Exit:100.00% New:98.68% [exec] GCs: 3 full, 0 partial [exec] ** VM stopped: exit code = 0 ** [move] Moving 1 file to C:\MyApplication\suite [move] Moving 1 file to C:\MyApplication\suite [delete] Deleting: C:\MyApplication\image.suite.api

-post-suite:

-pre-deploy:

-do-deploy:

-run-spotclient-with-optional-remoteId:

-run-spotclient-with-script-contents:

-run-spotclient: [java] Waiting for target to synchronise... [java] (please reset SPOT if you don't get a prompt) [java] [waiting for reset]

[java] Sun SPOT bootloader (1321-20060816) [java] SPOT serial number = 0014.4F01.0000.012E [java] About to flash to slot 1 [java] Writing imageapp35015.bintemp(2065 bytes) to COM45

[java] .................

[java] Download operation completed successfully [java] Writing Configuration(1080 bytes) to COM45

[java] .........

[java] Download operation completed successfully

[java] Exiting [delete] Deleting: C:\SunSPOT\dev\temp\spot-temp-472249501

-post-deploy:

jar-deploy:

BUILD SUCCESSFUL Total time: 4 seconds C:\MyApplication>

If this step fails, this is most likely to be because your system does not know the location of the JavaVM. You can find out how to configure your system by running the following ant command and following the instructions given in the output.

C:\MyApplication>ant environment Buildfile: build.xml

-pre-init:

-init-user:

-init-system:

-do-init:

-post-init:

init:

environment:

[java] To configure the environment for Squawk, try the following command:

[java] set JVMDLL=C:\jdk1.5.0_06\jre\bin\client\jvm.dll

BUILD SUCCESSFUL Total time: 0 seconds C:\MyApplication>

6. Run the application. To run the application, use the “

C:\MyApplication>ant run Buildfile: build.xml

-pre-init:

-init-user:

-init-system:

-do-init:

-post-init:

init:

-override-warning-find-spots:

-main-find-spots: [echo] Using Sun SPOT device on port COM45

-do-find-spots:

-pre-run:

-do-run:

-run-spotclient-with-optional-remoteId:

-run-spotclient-with-script-contents:

-run-spotclient: [java] Waiting for target to synchronise... [java] (please reset SPOT if you don't get a prompt) [java] [waiting for reset]

[java] Sun SPOT bootloader (1321-20060816) [java] SPOT serial number = 0014.4F01.0000.012E

[java] Squawk VM Starting (2006-08-16:13:21)... [java] Detected hardware type eSPOT-P2 [java] PCTRL-1.67 [java] EDEMOBOARD_REV_0_2_0_0 [java] Starting OTACommandServer [java] My IEEE address is 0014.4F01.0000.012E [java] Registering protocol manager 'radiogram' [java] Adding radiogram connection for Server on port 8 [java] Hello world!

ant run

” command.

[java] ------------------------------------------------------------------- [java] Hits - Class:95.74% Monitor:92.38% Exit:100.00% New:98.43% [java] GCs: 2 full, 0 partial [java] ** VM stopped: exit code = 0 **

[java] Exiting [delete] Deleting: C:\SunSPOT\dev\temp\spot-temp-674916937

-post-run:

run:

BUILD SUCCESSFUL Total time: 10 seconds C:\MyApplication>

As you can see, this application just prints “Hello world!” However, it gives you a framework to use for your applications.

N.B. After your Sun SPOT has printed “Hello world!” it probably will not exit immediately. Instead, you will have to push the control button to force it to exit. This is because by default, Sun SPOTs run a background thread which listens for over-the-air commands. You can disable this behaviour if you wish. For more details, see the section Ensure that the remote Sun SPOT is executing the OTA Command Server.

As a shortcut, the ant command “

deploy

” combines

jar-app

and

jar-deploy

. Thus we could

build, deploy and run the application with the single command line:

ant deploy run

Deploying a pre-existing jar

To deploy an application that has already been built into a suitable jar (by using the “ command described earlier), use the “

ant jar-deploy

” command with a command line option to

ant jar-app

”

specify the path to the jar:

ant jar-deploy -Djar.file=myapp.jar

Incorporating utility classes into your application

You can include code from pre-existing jar files as part of your application. We refer to jars used in this way as utility jars. A utility jar is built in the normal way using “ utility jar as part of your application specify it using “

-Dutility.jars=<filename>

ant jar-app

”. To include a

”, e.g.

ant deploy –Dutility.jars=util.jar

You can specifiy multiple utility jars as a list separated by a classpath delimiter (“;” or “:”). Note that you may need to enclose the list in quotes. Also, the classes in the utility jars must all be preverified. One way to ensure this is to create the jar using

ant jar-app

Resource files in utility jars will be included in the generated jar, but its manifest is ignored.

If you have code that you want to include as part of all your applications you might consider building it into the system library – see the section Advanced topics in this document.

Excluding files from the compilation

To exclude files or folders matching a specific pattern from the java compilation, set the ant property

spot.javac.exclude.src

, either on the command line with –D or in the build.properties

file of the project. The value of the property should be specified using standard ant wildcarding.

For example, to exclude all source files in all “unittests” folders, use:

spot.javac.exclude.src=**/unittests/*

Manifest and resources

The file

MANIFEST.MF

in the VM1 to run the application. In particular it contains the name of the initial class. It can also contain user-defined properties that are available to the application at run time.

A typical manifest might contain:

MIDlet-Name: Air Text demo MIDlet-Version: 1.0.0 MIDlet-Vendor: Sun Microsystems Inc MIDlet-1: AirText, , org.sunspotworld.demo.AirTextDemo MicroEdition-Profile: IMP-1.0 MicroEdition-Configuration: CLDC-1.1 SomeProperty: some value

The syntax of each line is:

<property-name>:<space><property-value>

The most important line here is the one with the property name “ value a string containing three comma-separated arguments. The first argument is a string that provides a name for the application and the third defines the name of the application's main class. This class must be a subclass of an icon to be associated with the MIDlet, which is currently not used.

The application can access properties using:

myMidlet.getAppProperty("SomeProperty");

All files within the resources directory are available to the application at runtime. To access a resource file:

InputStream is = getClass().getResourceAsStream("/res1.txt");

This accesses the file named “

resources/META-INF

javax.microedition.midlet.MIDlet

res1.txt

” that resides at the top level with the resources directory.

directory contains information used by the Squawk

MIDlet-1

”. This line has as its

. The second argument defines

Other user properties

For properties that are not specific to the application you should instead use either

•

persistent System properties (see section Persistent properties) for device-specific properties

• properties in the library manifest (see section Library manifest properties

• Each library extension must contain a file named

The Squawk VM is the Java virtual machine that runs on the Sun SPOT. For more details, go to

http://research.sun.com/projects/squawk/.

resources/META-INF/MANIFEST.MF

within its root folder. The adderlib

extension

has such a file, whose content is

FavouriteSnake: Viper

This defines a property whose value will be available to all applications in a similar fashion to application-specific manifest properties. The

addertest

application demonstrates this by displaying the value of this property. The library suite is built to contain all the properties defined by the manifests of all its input jars. For more details on accessing these properties, see the section

Manifest and resources.

• Running startup code

• Some library extensions require initialisation to be performed at startup (for example, to

create daemon threads). To specify startup code that must be run, add one or more lines to the manifest properties of the library extension with the following format:

spot-startup-xxxx: my.fully.qualified.Classname

where

Classname.

xxxx

is a string that is provided as the single argument to the static

main()

method of

Startup code is run only in the master isolate. It is run after all normal spotlib initialisation is completed but before the OTACommandServer (if configured) is started and before the application is launched.

• Modifying the system library code) for properties that are constant for all your Sun SPOTs and applications.

Built-in properties

There are a number of properties with reserved names that the libraries understand. These are:

DefaultChannelNumber DefaultPanId DefaultTransmitPower com.sun.spot.io.j2me.socket.SocketConnection-BaseStationAddress com.sun.spot.io.j2me.socket.SocketConnection-BaseStationPort

The first three control the radio’s operation; see section Using manifest properties to adjust the radio. The last two control the socket connection that underpins http access: see the section Configuring the http protocol.

Using the Basestation

Overview

The purpose of the Sun SPOT Basestation software is to allow applications running on the Host to interact with applications running on Targets. The physical arrangement is:

Host

USB

Sun SPOT

(“base station”)

802.15.4 radio

Sun SPOT

(“Target”)

The Host can be any of the supported platforms (e.g. Windows PC, Mac). The Host application is a J2SE program. The Target application is a Squawk Java program.

In the SPOT SDK and documentation the 64-bit addresses that identify SPOTs are expressed as sixteen hexadecimal digits subdivided into four groups that are separated by dots for readability.

The Basestation may run in either dedicated or shared mode. In dedicated mode, it runs within the same Java VM as the host application and can only be used by that application. In this model, the host’s address is that of the basestation.

In shared mode, two Java virtual machines are launched on the host computer: one manages the base station and another runs the host application. In this model, the host application has its own system-generated address, distinct from that of the base station. Communication from host application to the target is therefore over two radio hops, in contrast to one hop in the dedicated case.

The main advantage of shared mode is that more than one host application can use the same basestation simultaneously. Shared mode also allows multiple host processes to communicate with each other using the radio communication stack, which makes it possible to simulate the communication behaviour of a group of SPOTs using host applications (this simulation has different timing characteristics).

The disadvantage of shared mode is that run-time manipulation of the basestation SPOT’s radio channel, pan id or output power is not possible.

By default, host applications will use the base station in dedicated mode. To switch to shared mode, insert this line into the

.sunspot.properties

file in your user root folder:

multi.process.basestation.sharing=true

Host applications that send or receive broadcasts, or that interact directly with the lower layers of the radio stack, will behave differently in the two modes. This issue is discussed in more detail in the section Broadcasting and basestations.

Set up

Connect a base station to your host computer. If you don't have a base station you can configure a Sun SPOT to be used as the base station by issuing the following command:

ant selectbasestation

Then press the Sun SPOT’s control button and the Sun SPOT will act as a base station.

Base Station configuration

It is possible to select a channel and pan id for the base station using command line properties in conjunction with

ant host-run

. The properties are:

-Dremote.channel=nn

-Dremote.pan.id=nn

Alternatively, if you are operating in dedicated mode, the

IRadioPolicyManager

interface provides operations to adjust the output power of the radio, the PAN Id and the channel number. To access the policy manager from your host program do:

Spot.getInstance().getRadioPolicyManager()

Remote operation

Introduction

Until now, in this manual, we have worked with Sun SPOTs connected directly to the host computer. In this section we show how it’s possible to carry out some, but not all, of the same operations on a remote Sun SPOT communicating wirelessly with the host computer via a base station.

The operations that can be performed remotely include:

• ant deploy

• ant jar-deploy

• ant run

• ant fork

• ant debug

• ant info

• ant settime

• ant deletepublickey

• ant set-system-property

• ant system-properties

• ant delete-system-property

In each case, the procedure is the same:

1. ensure that the remote Sun SPOT is executing the OTA (“over the air”) Command Server

2. connect a Sun SPOT base station

3. specify the remote Sun SPOT’s ID, either on the ant command line (using the

-DremoteId=<IEEE address>

remoteId=<IEEE address>

(

If you wish, you may also carry out a fourth step, which is:

4. program the remote Sun SPOT application to take suitable actions during over-the-air downloads.

Each of these four is now considered in more detail

switch) or in the application’s build.properties file

)

Ensure that the remote Sun SPOT is executing the OTA Command Server

The remote Sun SPOT must run a thread that listens for commands. To check whether or not the command server is enabled on a SPOT use the

ant info

command. Factory-fresh SPOTs have the

command server enabled by default (except for basestations).

To configure the SPOT so that this thread is started each time the SPOT starts issue this command via a USB connection:

ant enableota

The SPOT remembers this setting in its configuration area in flash memory.

To configure the SPOT so that the OTA Command Server is not started each time the SPOT starts issue this command:

ant disableota

Although the OTA Command Server thread runs at maximum Thread priority, parts of the radio stack run at normal priority. This means that if an application runs continuously in parallel with the OTA Command Server, it should not run at a priority greater than normal, otherwise OTA Command Server commands may not be processed.

Connect a Sun SPOT base station

For details, see the section Using the Basestation.

Launch the spot client to control a remote Sun SPOT via the base station

To deploy an application use:

ant -DremoteId=<IEEE_ADDRESS> deploy

To run the deployed application use:

ant -DremoteId=<IEEE_ADDRESS> run

Unless the feature has been explicitly disabled, any output generated by the application using

System.out

System.err

will be redirected over-the-air and displayed in the command window exactly as if the SPOT was connected by USB2. This feature is disabled by setting the system property:

spot.remote.print.disabled=true

In these commands,

<IEEE_ADDRESS>

is the 64-bit IEEE address of the form

xxxx.xxxx.xxxx.xxxx

. By default this is the same as the serial number printed on each Sun SPOT. Alternatively you can execute an ant command to a locally connected Sun SPOT such as

ant info

which will print the serial number, for example:

... [java] Sun SPOT bootloader (orange-20061120) [java] SPOT serial number = 0014.4F01.0000.02ED ...

It is also possible to specify which radio channel and pan id the base station should use to communicate with the remote SPOT. To do this, set the ant properties

remote.channel

and

The streams are not forwarded to the host until handshaking is complete. As a result, any output generated by your

application before this point will not be displayed. Handshaking is usually completed within 100ms of start-up.

+ 37 hidden pages

Sun Microsystems Small Programmable Object Technology User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual