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
This is draft documentation which covers impOS™ functionality that, though currently in internal development, has been made available to a number of customers for testing purposes only. Both the functionality described here and the documentation itself are subject to change, including breaking changes, and may differ significantly from their final release versions.
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. These include:
"cell"— General identifiers indicating the type of interface. For imps with, for example, a single Ethernet port,
"ethernet"will reference that port. If you are working with an imp with multiple Ethernet ports under impOS control, then
"ethernet"will reference the first of these ports.
"wl2", etc. — Specific WiFi interfaces, as many as there are WiFi interfaces under impOS control. If there is only one such interface available, then
"wifi"will both identify that interface.
"eth2", etc. — Specific Ethernet interfaces, as many as there are Ethernet interfaces under impOS control. If there is only one such interface available, then
"ethernet"will both identify that interface.
"cell2", etc. — Specific cellular interfaces, as many as there are cellular interfaces under impOS control. If there is only one such interface available, then
"cell"will both identify that interface.
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.
Alternatively if you have a product with WiFi, cellular and two Ethernet ports, you might prefer that traffic to go via one of the Ethernet connections. However, there may be locations that cannot be wired, so WiFi or cellular can then be used instead. The call might look like this:
imp.net.setserverinterfaces(["eth0", "wifi", "cell"]);
The imp will first attempt server connection through the
eth0 interface, then through any WiFi interface and then through any cellular interface. The absence of
eth1 from this list means that the imp will never attempt to connect to the server through
eth1, even if all of the other interfaces can’t be used to make a connection.
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 unavailable interfaces, what action impOS will take depends on which identifiers you have included. For example, type indicators —
cell on a WiFi-only imp, for instance — will be ignored, but identifiers indicating specific interfaces —
wl0 on an Ethernet-only imp, say — will cause an exception to be thrown. An exception will also 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.
You may include the same identifier more than once, to indicate, for example:
imp.net.setserverinterfaces(["wifi", "ethernet", "wifi"]) will cause WiFi to be tried twice as often as Ethernet.
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).
From impOS 42, including
imp.clearconfiguration(CONFIG_ALL) in your code will also clear any list of preferred network interfaces you may have applied using imp.net.setserverinterfaces().