Sun SPOT SDK Release Notes

Sun SPOT Development Kit: blue-080827

This is release 4.0 of the Sun SPOT SDK (a.k.a. Blue)

When reporting problems or bugs please be sure to specify which version of the SDK you are using.

Version compatibility

This release has been tested against Power-Control-AVR firmware version 1.101. It may not work correctly with another version.

Summary of Major Changes

Upgrading a SPOT to Blue will delete any user set properties because the section of SPOT flash memory used to store properties has changed.
Can now deploy multiple application suites to be loaded & run on a SPOT.
The SPOTWorld application is now called Solarium.
Demos are now included as part of the SDK: <sdk>/Demos
Three new demos have been added: DatabaseDemo, HTTPDemo and SendDataDemo.
New SPOT-Utilities directory containing utility applications to calibrate the accelerometer, sniff packets and test the eDemo sensors.
The Tutorial now includes information about programming Sun SPOTs using the emulator.
New persistent system properties to specify default radio channel, pan id and transmit power.
Several new ant commands.
SPOT host applications should no longer use the SPOT class; use RadioFactory instead.
Bugs in the eDemo board UART code have been fixed and the UART API changed.
Many SPOT library jar files were renamed or moved.
Almost 200 bugs fixed.

Notes

The organization of the SPOT's flash memory has changed. As a result upgrading a SPOT to Blue will delete any user set properties. Also trying to downgrade a SPOT from Blue back to Purple will hang---the SPOT will continually reboot itself. To recover use the command "ant sysadmin" and type "resetconfigpage" when you see the prompt "BL>", followed by typing "quit" at the next prompt. Then redo the "ant upgrade" command and it should work properly.
Note: towards the end of the upgrade you may see the message "sorry your firmware is too old for java based updates". This is due to a bug in the Purple Power Controller firmware updater. You can ignore this warning message as the Purple version of the SPOT SDK will work with the Blue version of the Power Controller firmware.
The major change from Purple is support for multiple application suites to be loaded & run on a SPOT. One can now deploy several applications to a SPOT without disturbing already running applications. See "ant help" for details.
New persistent system properties to specify default radio channel, pan id and transmit power:
- radio.channel
- radio.pan.id
- radio.transmit.power
The "ant set-radio-properties" command will store these properties to a SPOT or basestation and they will be used whenever the SPOT or basestation is started up. For a host application if any of these properties are specified in your .sunspot.properties file, the project's build.properties file or on the command line, they will be used to set the radio on the basestation. Use "ant delete-radio-properties" to have a SPOT go back to the standard radio defaults.
The old ant properties remote.channel & remote.pan.id, plus the old manifest properties DefaultChannelNumber, DefaultPanId & DefaultTransmitPower, will all still work for now, though they will be overruled by the radio.* properties if they are set.
Also the ant property "multi.process.basestation.sharing" has been replaced with the shorter property "basestation.shared".
The SPOT class has been deprecated for host applications. The few methods from the Spot class that are needed by host applications can now be accessed as static methods of the class RadioFactory. SPOT-based applications can also call these RadioFactory methods in order to use the same code on both SPOT and host platforms. The most commonly used of these methods are getRadioPolicyManager() used to access the IRadioPolicyManager and isRunningOnHost() used to determine where the application is running.
For now a stub Spot class is available in spotlib_host.jar, but it will be removed in a future release. Here is a list of the methods that matter:
- IRadioPolicyManager getRadioPolicyManager()
- I802_15_4_MAC[] getI802_15_4_MACs()
- void setProperty(()
- void setPersistentProperty()
- boolean isMasterIsolate()
- boolean isRunningOnHost()
Changes to the EDemoBoard API to access the UART on the sensor board.
- Deprecated UARTAvailable() and replaced it with new method availableUART().
- Deprecated receiveUART() and replaced it with new method readUART().
  readUART() will block until a character becomes available.
- Added new method readUART(long timeout) that will throw a com.sun.spot.peripheral.TimeoutException if it times out.
- Added new method int readUART(byte[] b, int off, int len) that will read multiple bytes from the UART.
  It blocks until at least one character becomes available.
- Deprecated sendUART(byte val) and replaced it with new method writeUART(byte val).
- Added new methods writeUART(String msg), writeUART(byte[] msg) and writeUART(byte[] msg, int off, int len) to make it easier and more efficient to write messages.
- Can now specify the parity as odd, even or none; and the number of databits as 5, 6, 7, or 8 bits.
The preferred way to use any SPOT stream-based IO is via the Generic Connection Framework (GCF). The current changes do not change anything for code accessing the UART via GCF (except adding the new ability to set the parity or number of databits).
For the most part the SPOT library APIs have not changed except as mentioned above, so most of your SPOT applications should compile without needing any changes. However, a number of library jar files have been renamed or moved. This should not affect anyone who uses the ant scripts to build & deploy SPOT apps, but it may cause people using an IDE like NetBeans or Eclipse to not find various library packages. A list of jar files in the SDK in the Reference section at the end of the SPOT Developer's Guide.
Jar files in the SDK fall into three categories:
- Those that do not contain java classes, such as source jars.
- Those that are private to the SDK and contain classes. These jars reside in the bin directory.
- Those that are useful to SPOT developers and contain classes. These jars reside in the lib directory. A naming convention is applied to these to indicate their purpose as follows:
  - name_device.jar: containing code that can only be executed on the Sun SPOT
  - name_host.jar: containing code that can only be executed on the host computer
  - name_common.jar: containing code that can be executed either on the Sun SPOT or on the host computer.

For NetBeans users this information is specified for each project in the project.xml file in the nbproject folder. We are now using a much better way to specify the classpath using the same properties that are used when building a project with ant. In your project's project.xml file please change:

old: (located near the top)

  <properties/>

new: (for SPOT apps)

  <properties>
    <property-file>${user.home}/.sunspot.properties</property-file>
    <property-file>build.properties</property-file>
    <property-file>${sunspot.home}/default.properties</property-file>
  </properties>

or (for SPOT host apps)

  <properties>
    <property-file>${user.home}/.sunspot.properties</property-file>
    <property-file>build.properties</property-file>
    <property-file>${sunspot.home}/default.properties</property-file>
    <property-file>${netbeans.user}/build.properties</property-file>
  </properties>

and

old: (located near the bottom)

  <classpath mode="compile">xxx/SunSPOT/sdk/lib/spotlib_device.jar:/Users/xxx/SunSPOT/sdk/lib/spotlib_common.jar:/Users/xxx/SunSPOT/sdk/lib/multihoplib.jar:xxx/SunSPOT/sdk/lib/transducerlib_rt.jar</classpath>
  <classpath mode="boot">/Users/xxx/SunSPOT/sdk/lib/squawk_rt.jar</classpath>

new: (for SPOT apps)

  <classpath mode="boot">${sunspot.bootclasspath}</classpath>
  <classpath mode="compile">${sunspot.classpath}</classpath>
  <built-to>build</built-to> 
  <source-level>1.4</source-level>

or (for SPOT host apps)

  <classpath mode="compile">${hostagent.compile.classpath}:${libs.absolutelayout.classpath}:${libs.swing-layout.classpath}</classpath>
  <built-to>build</built-to>
  <source-level>1.5</source-level>

Known issues

Changing the clock speed to save power during shallow sleep causes the ARM to crash (bug 1386). Because of this the setShallowSleepClockMode() method in the AT91_PowerManager class has been disabled.

Changes since V4.0 Blue Beta1 (blue-080724)

Note: Bugs numbered 1231 or higher can be found at: https://squawk.dev.java.net/issues/query.cgi

1392	IDE cannot disconnect from a debugging session & sometimes...	FIXED
1395	Export com.sun.cldc.i18n.StreamReader and StreamWriter	FIXED
1396	Give isolates sensible names	FIXED

Changes since purple-071018

24	Update license/copyright in demos and sample code	FIXED
205	Improve thread scheduling performance	DUPLICATE
310	Switch to slow clock when shallow sleeping to save power	FIXED
328	OTA command monitor can hang when flashing an application...	FIXED
447	Developers guide should explain how to code libraries for...	FIXED
511	Improvements to sdk build script	FIXED
573	host-run finding of basestation unreliable	FIXED
580	Incomprehensible error thrown in SPOT client	FIXED
585	multiple application slots	FIXED
590	trying to find a route can fail if radio is off	FIXED
601	ANT_HOME and JAVA_HOME not needed?	FIXED
612	Take steps to minimize suite size	FIXED
621	Need through hole pad for Vext	FIXED
622	Swap pins on ARM9 for timestamp of packets	FIXED
643	SpotSelector should be better integrated with spotclient	FIXED
647	Use more recent gcc for ARM	FIXED
665	Tagging process for sdk releases isn't flexible enough	FIXED
679	Name label does not properly recenter after a name change	FIXED
690	SPOTWorld should start up or continue to run even with no...	FIXED
694	java.util.Vector improperly synchronized	FIXED
704	bootloader should identify the spots	FIXED
708	Radio Stack Test timeouts in continuous integration (2)	FIXED
799	Dummy application can deep sleep and so fail to work OTA	FIXED
818	final long field in class with GlobalStaticFields causes ...	FIXED
835	Space in Release Notes causes file not to load	FIXED
836	Ensure resource management framework supports isolate hib...	FIXED
839	Bugzilla does not have a category for bugs against bugzilla	FIXED
862	The demo app "PowerReport" call to IPowerController.getSt...	FIXED
876	SDK tests dir contents inconsistent and incomplete	FIXED
878	Management of host-SPOT distinction is clunky	FIXED
882	Add temperature sensor	FIXED
883	can't build squawk for SPOT	FIXED
911	Ensure that suitable tool chains to build SDK are available	FIXED
912	Ensure that SDK can be built-for-testing on any supported...	FIXED
913	The SDK "buildmaster" should be able to use any supported...	FIXED
922	Document how the bootloader boots the SPOT and starts the VM	FIXED
924	spot.external..part.id should be set by the base library	FIXED
937	Need a documented API that can be used by ant extensions	FIXED
949	Inconsistent use of CRC checking in bootloader/admin	FIXED
977	Shared base-station should report its channel and pan-Id	FIXED
992	Need non-multihop basestation tests	FIXED
999	Error on java.lang.System.out property breaks	FIXED
1012	Why does Flashtest test #24 take so long?	FIXED
1022	Need API to get default SPI DMA buffer size	FIXED
1028	Host apps (inc. SPOT World) can't tell whether there is a...	FIXED
1033	"Port in use" during bootloader upgrade	FIXED
1034	Need property to select VM executable file name	FIXED
1035	Error if "VM" returns	FIXED
1043	MMU init should be done in VM startup	FIXED
1047	Need an ant script to build the SPOT-specific Squawk Buil...	FIXED
1055	Flash sectors previously used for library are unused	FIXED
1056	minimize what gets printed during suite creation	FIXED
1058	Changes to PCTRL API	FIXED
1061	SPOT Socket Proxy generates "attempt to open connection t...	FIXED
1063	ExternalBoard.newBoardDeviceSPI has wrong return type	FIXED
1064	Add option to "ant upgrade" to skip firmware upgrades	FIXED
1069	spotfinder not detecting ports	FIXED
1072	Emulator doesn't work for standard Windows install	FIXED
1075	Demos button disabled, but tooltip message says "Download...	FIXED
1076	Sun SPOT Purple Beta CD: Installation fails on Apple PPC ...	FIXED
1078	including too many SPOT-only classes in hostagent classpa...	FIXED
1080	The definition of the C compiler flags is dispersed	FIXED
1081	Better Split-VM support - ENABLE_DYNAMIC_CLASSLOADING	FIXED
1082	ant scripts should suppport netinfo	FIXED
1083	UARTAvailable() is broken	FIXED
1085	Could not launch "SPOTManager" from NetBean Sun SPOT Info...	FIXED
1086	Source files have CP1252 encoding	FIXED
1087	Could not launch the SPOTManger from a "link" at the end ...	FIXED
1089	Debugger proxy doesn't handle dynamically loaded classes ...	FIXED
1090	spotfinder needs to be updated for Mac OS X Leopard	FIXED
1092	RadioPolicyManager javadoc should explain limits on power...	FIXED
1093	Spotfinder scripts fails for some linux flavours	FIXED
1094	Continuous integration output not complete.	FIXED
1095	VM.getTimeMillis() is too costly	FIXED
1096	Radio enables fifop interrupt when rx is off	FIXED
1098	Corrupt/bad external board EEPROM hangs system	FIXED
1099	FAT should be written incrementally	FIXED
1100	sdk creator doesnt always copy squawk executable	FIXED
1101	Javadoc should explain that rx must be on when sending	FIXED
1102	The FCC compliance application needs updating to provide ...	FIXED
1103	FIQInterruptDaemon doesn't respond to external power event	FIXED
1104	CPU stats arent accurate	FIXED
1108	Need to document "resetlibrary" function	FIXED
1109	FlashFile.getVirtualAddress throws exception	FIXED
1111	Improvements to source file specification when compiling	FIXED
1112	The build.properties file in the spottests.jar is wrong	FIXED
1113	Flash write performance could be improved by stream writes	FIXED
1114	The getfat command doesn't always display the latest FAT	FIXED
1116	SDK build process needs to build two bootstrap suites	FIXED
1117	Isolates that exit aren't GC'd.	FIXED
1119	Can't set startup parameters via bootloader	FIXED
1120	Hello response fails if the remote SPOT does not have a p...	FIXED
1122	SDCardLib fails on deep sleep	FIXED
1125	VM.setSystemThreadPriority rejects MIN_PRIORITY	FIXED
1126	System.getProperty("line.separator") isn't defined on SPOTs.	FIXED
1128	SDK doc folder contains doc sources	FIXED
1129	Deploying application suites via USART fails	DUPLICATE
1130	radiostream javadoc should note closed connection may not...	FIXED
1131	USB data doesn't arrive	FIXED
1132	CrcTest mock tests fail on Linux	FIXED
1134	ant parameter names are inconsistent	DUPLICATE
1135	undeploy can be used to remove the master app isolate	FIXED
1136	LEDs get left on	FIXED
1138	Recovery procedure doesnt work reliably	FIXED
1141	Spurious character on end of pctrl version string	FIXED
1142	ant blink doesnt work with locally connected SPOTs	FIXED
1143	System.currentTimeMillis doesnt work in the emulator	FIXED
1144	Spotclient doesn't handle spaces in arguments properly	FIXED
1147	All suite uris and suite management should be consistent	FIXED
1148	Unit test error in TestUsbPowerDaemon	FIXED
1149	SpotStateChecker can leave serial port open	FIXED
1150	Javadoc doesn't build correctly	FIXED
1152	SPOT handles deep sleep poorly when there's external power	FIXED
1153	SockeProxy fail to connect to port 1467247	FIXED
1156	Remove support for old-style suite creation	FIXED
1157	Enable romizer to be called multiple times...	FIXED
1158	Build system copies build.override into Squawk checkout	FIXED
1159	Null Pointer Exception in SpotProxyUi	FIXED
1161	debugger proxy kills spotworld	FIXED
1162	tests/Base.class somehow gets in suite used by emulator	FIXED
1164	sdk jar files needs to include a new file	FIXED
1165	Wake up from deep sleep using external input	FIXED
1169	Flash library fails with "unlikely checked byte array siz...	FIXED
1170	Firmware updater apps aren't cleaned up after the upgrade...	FIXED
1171	There's no way to retrieve the startup midlet number	FIXED
1172	Remove support for "base SDK" creation	FIXED
1173	Need a SPOT Client command to get startup settings	FIXED
1174	Clients of Spotclient have no generic execute interface a...	FIXED
1175	High-current pins don't reset	FIXED
1176	Characters can be lost when USB port is closed	FIXED
1177	Spot World launch classpath incorrect	FIXED
1181	ant flashlibrary deploy fails	FIXED
1183	Going to sleep and waking up take too long	FIXED
1184	SDK build needs to support multiple repositories	FIXED
1185	Corrupt persistent properties cause SPOT to fail	FIXED
1187	temp folder checked in to svn	FIXED
1188	"blue" javadoc should have correct colour and text in its...	FIXED
1189	"ant deploy run" runs spotfinder twice	FIXED
1195	InterIsolateServer doesn't have named threads	FIXED
1197	OTA prevents deep sleep	DUPLICATE
1203	Outdated constants in IPowerController	FIXED
1204	routing manager prevents deep sleep	FIXED
1205	Rename and reorganise jars in SDK	FIXED
1206	Coulomb count doesn't match with current measurement	FIXED
1209	Recovery process may not work with latest Spotclient	FIXED
1210	small phoneme-ing cleanups	FIXED
1231	uart send breaks at low baud rate	FIXED
1232	Thread safety of EDemoBoard.receiveUART()	FIXED
1244	trying to suspend OTACommandServer starts it up	DUPLICATE
1260	OTA Command Server needs to implement IService interface	FIXED
1262	Integrate spotworld extensions to spot client	FIXED
1271	Deep sleep duration can be calculated incorrectly	FIXED
1277	Would be useful to have system properties for PanID, Channel	DUPLICATE
1285	Rearrange usage of small flash sectors	FIXED
1290	Allow setting of radio power on the command line.	DUPLICATE
1298	names of source jars need to be updated	FIXED
1308	Need range-checked access to raw memory...	FIXED
1314	Debugger mishandles two-word local variable display	FIXED
1316	Cry Wolf! Debugger code calls VM.print when not an emergency	FIXED
1328	cannot load chained suites on desktop	FIXED
1329	available() method doesn't work on http connection streams	FIXED
1331	no way to enumerate Isolate properties	FIXED
1341	Need ability to dump heap usage statistics	FIXED
1342	easily specifying default radio channel/panId/power for SPOT	FIXED
1344	Shallow sleep with slower clock causes crash	LATER
1345	Implement dead string elimination	FIXED
1357	Redeploying child suites doesn't work immediately	FIXED
1358	stack traces sometimes display internal error message	FIXED
1359	Demos should be part of installed SDK	FIXED
1360	Once debugger proxy has started, it's hard to get it to stop	FIXED
1361	Memory leak in interisolate server	FIXED
1367	InterIsolateServer doesnt clean up more than one WorkerThrea	FIXED
1368	Emulator should be able to deploy using ant	FIXED
1370	SPOT restarts unexpectedly	FIXED
1372	Need more math...	FIXED
1373	why do i need to force System.gc()?	FIXED
1375	LEDColor.equals() method takes wrong argument type	FIXED
1376	redo how radio properties get set	FIXED
1377	Wrong value for MAX_32_BIT_UNSIGNED_INT	FIXED
1379	problems with security javadoc	FIXED
1383	When is an object NOT an object - Squawk Primitives too dang	FIXED
1387	Allocate all free RAM to Squawk	FIXED
1389	Trap handler should display resgisters and stack on aborts.	FIXED
1391	(Don't Fear) The Reaper	FIXED

Full change history