Skip to main content

imp Module NVRAM Image Guide

How To Modify Your Product’s WiFi Chip Configuration

imps incorporating Cypress/Broadcom WiFi cores (currently imp001 through imp005) initialize those cores at start-up using a configuration file called the ‘NVRAM image’. These imps include a default NVRAM image, but for production imp modules (imp003, imp004m and imp005), this can be overridden by the customer during product manufacture.

Note Generally, there is no need for you to override the default settings, which have been chosen by Electric Imp to cater for the vast majority of customers’ wireless products.

To replace an imp’s configuration file, the device under test (DUT) flow within your factory firmware will need to call the factory only imp API method imp.setnvramimage() (it cannot be called in application firmware). This method has a single parameter which takes as its argument a string comprising a hash of your new NVRAM image.

Currently, the settings applied via imp.setnvramimage() take effect when the imp next attempts to connect to the impCloud™. For the imp005 only, the settings applied via imp.setnvramimage() will only take effect after an imp restart, eg. by calling imp.reset() or physically power-cycling the device. Other imps will continue to enable the new settings on the next connection attempt.

Your custom image must be complete as it will wholly overwrite the default image. This is the case even if you only need to change a few settings — in this case you need to ensure your image contains all of the default settings you are not changing. To request a template NVRAM image, please visit Electric Imp Support.

NVRAM Image Settings

This document provides guidance on which settings within the NVRAM image you should consider changing and how those settings are formatted. The NVRAM image’s settings each fall into one of three broad types:

  • Settings which should not be changed by the customer
  • Settings which depend upon your product’s antenna tuning
  • Settings used to indicate to impOS how the WiFi core has been configured for clocking

In this document we consider only the latter. For assistance with settings not detailed below, please visit Electric Imp Support.

NVRAM Image Format

The NVRAM image consists of a list of key-value pairs. The pairs comprise Ascii text, in the format key=value (no space either side of the equals sign), and are separated by NUL bytes, not CR or LF. You must use the following representation to indicate NUL: \0. The list is terminated by an empty entry, ie. by two consecutive NULs. Each key should appear only once.

Imp-specific NVRAM Image Settings


Configuring WiFi power-save clock

The WiFi chip in the imp004m accepts an optional 32kHz clock input, pin LPO_IN, which is used to implement WiFi power-save mode.

Note This signal is routed internally in other imps; it is made external (and optional) on the imp004m only.

There are three hardware options for generating the 32kHz clock signal — which one you have used should be indicated using the the NVRAM image’s boardflags3 setting, as follows:

  • boardflags3=0x04000000 — No 32kHz clock at all (WiFi power-save not available)
  • boardflags3=0x00000000 — 32kHz from imp004m pin E (ie. pin E looped-back to LPO_IN)
  • boardflags3=0x08000000 — 32kHz supplied in some other way (external clock)

The imp004m default NVRAM image specifies no 32kHz clock.

If your product uses an external clock, it needs to be active whenever WiFi is on. This can be detected, if necessary, using the imp004m’s PSU_ENABLE output pin.

Looping-back pin E requires that your product’s hardware design incorporate the optional 32kHz crystal on pins OSC32_IN and OSC32_OUT. Please see the imp004m datasheet for details.

Note that no harm will be done if the clock signal is active while WiFi is off; the only mandatory action is the clock must be active when WiFi is on. If the imp is told to expect a clock signal but isn’t getting one, then no specific error will be generated, but packet loss in power-save mode will be severe.

It is possible to use an imp004m PWM pin to generate the 32kHz clock as required, but this currently requires a special ‘quirk’; please visit Electric Imp Support to request further information about this.


Configuring WiFi bands

The WiFi chip in the imp005 supports both 2.4GHz and 5GHz WiFi operation. Sometimes this is not desirable, for instance when the module is to be used with an antenna that is only certified in one of the two bands. There are NVRAM entries for enabling or disabling the bands independently:

  • aa2g=1 — 2.4GHz band enabled
  • aa2g=0 — 2.4GHz band disabled
  • aa5g=1 — 5GHz band enabled
  • aa5g=0 — 5GHz band disabled

The imp005 default NVRAM image enables both bands. If either the aa2g or the aa5g entries is not included in the NVRAM image, it is equivalent to disabling the band (ie. setting the key to zero).

For the imp005 only, the settings applied via imp.setnvramimage() will take effect after an imp restart, eg. by calling imp.reset() or physically power-cycling the device.