Release 30

Release 30 is a major update to the impOS™;. It addresses a number of reliability and compatibility issues, in particularly around WiFi which also benefits from being brought right up to date with with the latest Broadcom firmware. For example, WiFi module crashes are now managed behind the scenes so they are now invisible to the user, imps are happier connecting to multi-access point networks, and transient captive portal pages — for example, “the Internet is not available” — are now dealt with correctly.

Once again, we’ve made a number of under-the-hood improvements to BlinkUp™ to ensure the process is even more robust on Android-based devices. The technology now supports the widest-ever range of Android phones and tables.

For developers and manufacturers connecting imps to external components, we have considerably enhanced the imp’s support for SPI, I²C and UART buses, and augmented its GPIO options. A number of these changes will make it much easier — and, in some cases, possible — to implement less mainstream buses, such as DMX and RS485.

Release 30 also marks the first version of the imp OS to support the new imp003 (Murata LBWA1ZV1CD) module.

New Features

Wireless and Connectivity

• imp.scanwifinetworks() now works even if WiFi is powered down: WiFi is temporarily re-enabled to allow the scan to take place. It is then turned off again.
• server.connect() now has a default timeout of 60 seconds, so the method’s second parameter, the duration of the timeout period in seconds, is now optional.
• Both server.connect() and server.onunexpecteddisconnect now formally report a broken connection between imp and agent as the constant NOT_CONNECTED if the two can’t contact each other for a reason other than a failure of the imp to access WiFi, to gain an IP address, to contact the Electric Imp Cloud, or to get a nominated server’s IP address.

Hardware IO

• The imp’s spi objects can now be informed that you are not using an SCLK line. This makes possible truly single-wire transmit-only or receive-only connections. Configured spi objects can now be disabled to save power — enabling a peripheral locks an internal clock which can’t then be lowered to reduce power consumption — or to signal that you’re going to change its configuration.
• It is now be easier to debug problematic I²C connections. The imp’s i2c objects now records a code if you encounter an error when using i2c.read() to retrieve data from the bus. If i2c.read() returns null, you can call the new method i2c.readerror(). This returns a constant which indicates the cause of the error. The same, non-zero values are also generated by i2c.write() when it encounters an error writing data to the bus. The I²C buses can now be disabled to save power — enabling a peripheral locks an internal clock which can’t then be lowered to reduce power consumption — or to signal that you are going to change its configuration.
• UART users can now read all the data in the serial bus FIFO buffer rather than reading it byte by byte. This is achieved using the new uart.readblob() and uart.readstring() methods. These methods are complemented by uart.flags() which returns current information about bus events. Reading the flags resets them. The existing uart.configure() method now returns the bus speed in use — the closest speed the hardware can achieve to the one requested. The UART callback function, specified in uart.configure(), can now be set to take an optional parameter: one of the flags of the kind listed by uart.flags() to allow it to be used to respond to specific types of bus event.
• A limitation within the underlying STM32 hardware has been overcome to yield much-improved UART RX flow control. UART now de-asserts RTS when there are 16 or fewer spaces in the RX buffer. This allows successful flow control with devices that don’t stop sending as soon as their CTS line is de-asserted.
• Re-configuring pins on the fly now takes place more smoothly. For instance, configuring a pin to be one of the UART lines and then briefly switching it to a DIGITAL_OUT, will enable the pin as DIGITAL_OUT before UART on that pin is disabled. This prevents any glitches on the line during reconfiguration, and will be welcome to users who need to do configuration switching in order to support certain protocols, such as DMX and RS485.
• Each pin object can now be optionally set to be driven high or low from the moment it is enabled as a DIGITAL_OUT. In previous releases, once the pin had been configured, the pin would always be driven low until explicitly driven high. This remains the default behaviour, but a new, optional parameter in hardware.pin.configure() lets you specify the pin’s start status: hardware.pin1.configure(DIGITAL_OUT, 1) or hardware.pin1.configure(DIGITAL_OUT, 0).
• The optional initial pin state is also applicable if the pin object is configured as DIGITAL_OUT_OD (open drain digital output), allowing the pin to be set to float when it is configured.

Miscellaneous

• An issue causing possible corruption of the imp’s config pages has been addressed.
• The list of possible reasons for an imp being awoken, as relayed by the existing method hardware.wakereason(), has been expanded with three new possible outcomes. Two, WAKEREASON_NEW_FIRMWARE (restarted due to a firmware upgrade) and WAKEREASON_SNOOZE (the imp came out of a snooze-and-retry state, are available on all imps. The third new code, WAKEREASON_HW_RESET, applies only to the imp003 and is signalled when the module’s reset pin is used to trigger a restart.
• If exceptions raised by Squirrel but immediately caught by the device or agent code are logged by that code, then the log entry will be presented with the line number where the exception was raised.
• Device restarts caused by out-of-memory errors are now reported as such.
• Previously, the imp required TCP port 31314 to be open on the user’s router. If the port was closed, the imp could not connect. Now if 31314 is blocked by a firewall, the imp tries to connect on port 993 which is typically left open for email traffic. Note: This capability is not yet enabled on the server-side.

Bug Fixes

In addition to a variety of new features and enhanced or updated functionality, imp OS release 30 addresses a number of bugs.

Wireless and Connectivity

• Routers which return an incorrect IP address or an HTML page with a DNS warning after an upstream disconnection are now managed correctly: the incorrect IP address is no longer cached until the next imp reboot.
• The networking code now correctly schedules its adjustment of the TCP window, preventing unnecessary TCP retries and consequently reduced network performance. imp receive performance is improved on low-latency networks.
• Joining distant WiFi networks, or connecting at low signal strength, is now improved with a longer timeout.
• imps presented with multiple access points all of which they may connect to should now connect more quickly and more reliably.
• Rare crashes experienced when server.flush() has to retransmit the data being flushed have been addressed.
• Various situations where disconnecting from the server then reconnecting can corrupt Squirrel data structures have been dealt with.

Hardware IO

• SPI read operations now simultaneously specified zero-value (0x00) bytes, not random values.
• Configured SPI and I²C buses are now automatically disabled when Squirrel stops.
• The hardware.fixedfrequencydac object no longer has the potential to stop running before the last sample has been processed.
• Calling uart.flush() no longer fails to completely clear the FIFO when the bus is configured to operate at a Baud rate of 2400bps or less.
• A very rare crash associated with uart.flush() in which the operation would never complete has been addressed.
• The pin-triggered pulse generator GPIO option no longer incorrectly uses its previous settings on its first trigger after it has been reconfigured.
• The (unnecessary) use of pull-ups on PWM and PTPG GPIO pins has been disabled.

Squirrel

• Attempts to use the Squirrel keyword base as a variable name are now correctly reported as an error and no longer cause Squirrel to crash.
• A rare bug which prevented fresh Squirrel code being loaded by an IDE-triggered device restart because the on-device Squirrel interpreter was running at a higher priority than the networking code has been addressed.
• Very rare instances in which Squirrel metamethods were called recursively and so caused previous imp OS releases to crash have been blocked in release 30 by preventing metamethods from calling themselves.
• Attempting to dynamically set the properties of a class object is now signalled by a more specific error message.
• Generator functions that are never re-activated with the resume command no longer retain the caller’s variables.
• Incorrect ‘bad parameter’ error reporting by the imp.deepsleepfor() and imp.deepsleepuntil() methods has been fixed.
• server.save() circular data error messages now include a line number.

BlinkUp

• Release 30 now incorporates a ten-second period after BlinkUp in which the imp will attempt to contact the server and download new firmware if it is available. This allows the developer to recover from Squirrel code which immediately wipes the WiFi settings applied by the BlinkUp. Previously, the imp would run cached Squirrel code as soon as BlinkUp was complete.
• When the method imp.enableblinkup() is passed false, BlinkUp is now correctly disabled in all circumstances. Note that BlinkUp is always enabled for the first 60 seconds after a cold boot.
• The imp’s LED now signals the correct color pattern after the imp has been woken up by a wake-up pin pulse, and the imp now correctly times changes from one color pattern to another.
• BlinkUp now constantly refines thresholds during a reception event to deal with phones being moved during the process.
• BlinkUp sync detection has been significantly refined and works better with edge-case phones.

Miscellaneous

• Device restarts caused by out-of-memory errors are now reported as such.
• imps based on STM32 Revision X — all imp002 modules and some imp001 cards — enjoy a more accurate real-time clock than they did with previous releases thanks to more precise calibration. This brings them into line with all other imps.
• The imp003 now wakes more quickly.

imp003/Murata LBWA1ZV1CD Support

A key development incorporated into imp OS release 30 is the addition of support for the new imp003 module, Murata part number LBWA1ZV1CD. The imp003 — you can view more information about this component by taking a look at its datasheet — gives hardware developers a much-expanded array of GPIO options: five separate UART, two I²C and two SPI buses.

To accommodate these options, it has been necessary to adopt an alternative nomenclature for the imp003’s pins; release 30 is the first public version of the imp OS to support this new pin naming scheme, full details of which can be found on the pin mux page. imp001 and imp002 pins will continue to be addressed as they were before.

The imp003 also gives developers the opportunity to use space in the system’s SPI flash storage, which in imp003-based devices is separate from the module itself. Release 30 therefore includes a new API extension to read data from and write data to the SPI storage, and to perform sector-level erasure of the storage as required by NOR flash’s write architecture. These and other methods are made available through a new imp API class, Spiflash, which is instantiated at start-up as the object hardware.spiflash.

The imp003 is designed to be accompanied by between 512KB and 16MB of SPI flash. However much flash is connected to the module, the first 448KB are always reserved for the system, giving each imp003 at least 64KB of flash for the developer to use, typically for information to be accessed by the device software, such as device configuration data.

For manufacturers of imp-based products, the imp003’s WiFi radio can be set at blessing with the regulatory region in which it is going to be sold, in turn specifying the number of of 2.4GHz WiFi channels it can use. This allows manufacturers to develop a single, ‘worldwide’ product and tailor it during production for a given market. The region can’t be changed after the unit has left the factory; this facility is only available to factory firmware. Manufacturers who have worked directly with the WiFi silicon vendor can also install custom WiFi NVRAM settings at blessing time.

New imp API Methods

IO Enhancements

• spi.disable()
• i2c.disable()
• i2c.readerror()

Serial Communications Enhancements

• uart.flags()
• uart.readblob()
• uart.readstring()

Manufacturer Device Configuration Enhancements

• imp.setcountry()
• imp.setnvramimage()
• imp.setenroltokens()

SPI Flash Storage Management

• spiflash.enable()
• spiflash.disable()
• spiflash.read()
• spiflash.readintoblob()
• spiflash.write()
• spiflash.erasesector()
• spiflash.size()
• spiflash.chipid()

Updated imp API Methods

• hardware.wakereason()
• i2c.read()
• i2c.write()
• pin.configure()
• server.connect()
• spi.configure()
• uart.configure()
• uart.flush()

Known Issues

An issue with a third-party library used by impOS causes imp.scanwifinetworks() to leak memory. Repeated use of imp.scanwifinetworks() will drain the imp of available memory even though calls to imp.getmemoryfree() show that there is plenty of memory free for use. When the imp runs out of available RAM, it will reboot and log ‘out of memory’ as its wake reason. The leaked memory can only be made accessible again by forcing the imp to restart: either power-cycling the device physically or by calling imp.deepsleepfor() with 0 as its parameter.

The issue has been fixed and will be implemented in a future release of impOS.

WiFi networks with a 32-character SSID are known to prevent impOS 30 (and earlier) from connecting. A fix for this issue will be implemented in a future impOS release.