Set impOS’ network connection failover sequence for multi-interface devices
Device (from impOS™ 42)
|identifiers||Array of Network Interface Identifier strings||
A failover sequence of network interfaces
Important Please see the Known Issue before making use of this method.
This method is used to override the default sequence of network interfaces that impOS™ will iterate over as it attempts to connect to a server in the Electric Imp impCloud™. If impOS fails to connect using the current network interface, it will move on to the next interface in sequence. If it has tried all of the interfaces in the specified sequence, it will proceed to the default sequence: Ethernet, WiFi and, finally, cellular. imps which lack any of these interfaces will not include the unavailable interfaces in their default sequences.
You provide your own sequence by passing in an array of Network Interface Identifiers, including interface classes —
"cell" — and/or instances —
For example, if you are making a vehicle-mounted product and it is intended to offload collected data when it can connect to a WiFi network at the depot, but use cellular when mobile, then the call might look something like this:
In this case, impOS will first attempt to connect to the server through any available WiFi interface. If that fails, however, impOS will attempt to connect via any available cellular interface. To ensure that the imp connects to WiFi when it can, your code may need to manually disconnect after any cellular connection is made.
Note impOS reserves the right to connect to the impCloud temporarily via any interface if it needs to do so to complete an upgrade or Squirrel reload. Your application will not be notified if this occurs. Once the operation has completed, impOS will continue to use the interfaces you have specified.
If you omit an interface from the list, this does not mean that the omitted network interface is disabled in any way — it is simply not used as a failover and may continue to draw power.
If you include identifiers for interfaces that a given imp lacks —
cell on a WiFi-only imp, for instance — those identifiers will be ignored. An exception will be thrown if none of the identified interfaces are available on the imp, even if they are only type identifiers, eg.
imp.net.setserverinterfaces(["ethernet", "cell"]) on a WiFi-only imp.
The new sequence will overwrite any previously specified interface sequence and will take effect on the next attempt to connect to the server (eg. after a server.disconnect() followed by a server.connect() or server.connectwith(). The sequence is written to non-volatile memory and will persist even after a cold boot and after Squirrel changes such as a change of Device Group.
To clear a current sequence and revert to the default, call imp.net.setserverinterfaces() with an empty array as its argument:
// Go back to default interface list imp.net.setserverinterfaces();
You can apply a new list at any time, but unless you manually disconnect and reconnect, the current interface will not change until there is an unexpected disconnection, ie. when impOS next connects automatically or your application connects manually. However impOS reconnects, it will start working with the first item on the new list (ie. applying a new list sets the index to zero).
imp.clearconfiguration(CONFIG_ALL) in your code will also clear any list of preferred network interfaces you may have applied using imp.net.setserverinterfaces().
Currently, imp.net.setserverinterfaces() accepts an unlimited number of interface identifiers, including multiple uses of the same identifier. However, if you include any identifier more than once, impOS may spend an excessive amount of time iterating through the listed interfaces after a cold boot. This can impact applications making use of a rescue pin.
We recommend listing each interface once only. If you are including a given interface multiple times — for example, to favour Ethernet connections over WiFi ones — you should instead control interface selection manually using server.connectwith().
A subsequent impOS 42 update will limit the number of identifiers that imp.net.setserverinterfaces() will accept to 12. It will also remove duplicates from the supplied list before the list is persisted. Removed items will not be present if you later read back the list with imp.net.getserverinterfaces().
Additionally, identifiers referencing specific interface instances — ie. those returned via imp.net.info() interface.name values — will be replaced by the relevant interface class. For example, the sequence
"wl0", "wl1", "cell" will be persisted as
"wifi", "cell" (after the two
"wifi" entries have been de-duped). Again, if you later read back the list with imp.net.getserverinterfaces(), you will receive the sequence