Set impOS’ network connection failover sequence for multi-interface devices
Device
| Name | Type | Description |
|---|---|---|
| identifiers | Array of Network Interface Identifier strings |
A failover sequence of network interfaces
|
Nothing
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, either generic — "wifi", ethernet and/or "cell" — or specific: "wl0", "eth0" and/or "cell0".
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:
imp.net.setserverinterfaces(["wifi", "cell"]);
In this case, impOS will first attempt to connect to the server through the primary WiFi interface. If that fails, however, impOS will attempt to connect via the primary 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.
impOS will remove duplicates from the list you supply, and convert specific NIIs to generic ones, eg. "wl0" will be replaced with "wifi". You should remember this if you read back an applied list with imp.net.getserverinterfaces().
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).
Including imp.clearconfiguration() or imp.clearconfiguration(CONFIG_ALL) in your code will also clear any list of preferred network interfaces you may have applied using imp.net.setserverinterfaces().