Skip to main content

spiflash.setspeed(speed)

Sets the speed of SPI flash accesses on certain devices

Availability

Device
imp003 and imp004m only

Parameters

Name Type Description
speed Float or integer The requested SPI flash speed in Hertz

Returns

Integer — the actual speed of the SPI flash in Hertz

Description

This method allows developers of imp003- or imp004m-based devices to set the speed of the SPI flash chip connected to the module. The requested speed is passed into the method’s only parameter, speed, and the method returns the speed applied, ie. rounded down to the nearest valid speed. The speed will not be applied until your code subsequently calls spiflash.enable().

Current supported speeds are:

Module Available Speeds (Hz) Default
imp003 4,500,000
9,000,000
18,000,000
4,500,000
imp004m 3,000,000
6,000,000
12,000,000
3,000,000

Note The speeds taken and returned by setspeed() are in Hertz.

Attempts to set the speed below the minimum or above the maximum listed above for your chosen module will cause an exception to be thrown. The maximum speed that can be achieved among those available will depend on which SPI flash chip you have fitted to your connected product and the layout of your board.

It is essential that you carefully determine a safe speed before writing the SPI flash in software. If the speed is set too high, it may cause the imp to reboot on connection to the server or to damage the SPI flash chip during subsequent write operations. Determine a safe speed by trying various speeds and checking its effect on your device, ideally on a scope. Reading at too high a speed is safe, in that the worst that can happen is that the device’s imp will crash and restart; set a lower speed in your Squirrel code. However, writing at too high a speed is dangerous because it may cause the WiFi firmware to be overwritten, which will render the imp permanently inoperable.

The safest approach is to raise the read speed to your determined safe speed immediately prior to SPI flash read operations and lower the speed to the default immediately prior to any write operations.

Increasing the speed of SPI flash reads has another benefit: it causes the WiFi firmware to load more quickly. This decreases the time it takes to establish a WiFi connection on a warm boot by up to ~200ms. In turn, this allows applications which need to tightly control their network access — for example, applications on battery powered devices — to reduce the time during which they maintain a network connection. To benefit this way, the call to setspeed() should be made early in your Squirrel code before any calls which contact the server and cause a WiFi connection, such as server.log().

Bear in mind, that because this setting is applied via Squirrel, it will not affect devices that are starting cold, because they connect before Squirrel is loaded and run (in order to receive updated Squirrel if it is available).

Note Calls to spiflash.setspeed() are not applied if specified after the first call to spiflash.enable(). For example, the first time the following code is called, the Spiflash speed will be set to requiredSpeed (assuming it is a valid request) but if called again, the speed will not be changed:

hardware.spiflash.enable();
local actualSpeed = hardware.spiflash.setspeed(requiredSpeed);

Workaround Place the spiflash.enable() call after spiflash.setspeed().

Module-specific Information

This method is only available on the imp003 and imp004m; an exception will be thrown if it is called on any other imp.

Known Issue

The value passed into spiflash.setspeed() will survive a Squirrel reload (eg. after waking from deep sleep), so that the speed set on the first call to spiflash.enable() (made in the the first Squirrel run after a cold boot, ie. a power cycle) will be retained if the application attempts to alter the speed following a warm boot (ie. a Squirrel restart).