Skip to main content

How To Connect To Devices On A Local Network (Pre-Release Documentation)

Inside impOS’ New LAN Functionality

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.


From release 42, impOS™ is able to make and maintain connections to other devices that are part of the local area network to which the imp is connected. These are links established at the LAN level — there is no longer any need to communicate with local devices via the Internet and the imp’s agent, as was the case with earlier versions of impOS (though you may continue to do so if you prefer).

This functionality is intentionally limited, to ensure that imp security is not compromised. Current restrictions include:

  • Only the UDP (User Datagram Protocol) is supported.
  • Connections must be made to local/private IPv4 addresses only — the only route to the Internet for application data remains the imp’s agent.
  • Any interface opened for local communications will only have access to the local subnet (ie. traffic will not be able to cross routers).

Within these restrictions, however, your application has considerable scope to connect to devices on the local network and exchange data with them.

Note The local networking functionality described in this document makes use of impOS 42’s new network interface management system, in particular its standard Network Interface Identifiers (NIIs), which can be used to prepare specified imp network interfaces for local area networking. Please see the separate document, ‘imp Network Interface Management’, for more information on NIIs and a detailed description of impOS 42’s network interface management system.

Preparing A Network Interface For A Local Connection

To initiate a local network connection, your code calls the new imp API method imp.net.open() and passes in a standard NII, such as "ethernet", "eth0", "wifi" or "wl0i", which tells impOS which specific interface you wish to use for the connection. This call powers up (if necessary) and readies the named interface for use, provided it is available. If the specified interface is not available (you might have disabled it using impOS 42’s new network interface management system, eg. via imp.net.setserverinterfaces()) then imp.net.open() will throw an exception.

If the chosen interface is available to be used, imp.net.open() immediately returns a reference to an object that represents it. When imp.net.open() returns, the interface may not yet be connected, so you should use a callback function (registered with imp.net.open()) to discover when the chosen interface is connected so that you can use it to make a local network connection (see below).

The connection-state notification callback passed into imp.net.open() via its second parameter is a function which has one parameters of its own: state, an integer connection status code. The possible values which may be passed into state are listed below:

impOS Constant Value Network Interface State
imp.net.UNKNOWN -1 Idle/unknown
imp.net.STARTING 0 Starting
imp.net.CONNECTED 1 Connected
imp.net.WIFI_SCANNING 100 WiFi scanning
imp.net.WIFI_JOINING 101 WiFi joining
imp.net.WIFI_WPSING 102 WiFi WPS in progress
imp.net.WIFI_LINK_UP 103 WiFi link up
imp.net.WIFI_DHCPING 104 WiFi getting IP address via DHCP
imp.net.WIFI_STOPPED 105 WiFi stopped
imp.net.WIFI_STOPPED_UNHAPPY 106 WiFi sub-system unhappy
imp.net.ETHERNET_LINK_UP 200 Ethernet link up
imp.net.ETHERNET_DHCPING 201 Ethernet getting IP address via DHCP
imp.net.ETHERNET_STOPPED 202 Ethernet stopped
imp.net.ETHERNET_STOPPED_UNHAPPY 203 Ethernet sub-system unhappy
imp.net.ETHERNET_STOPPED_NO_LINK 204 Ethernet stopped: No link
imp.net.CELLULAR_PINGING 300 Cellular contacting modem
imp.net.CELLULAR_WAITING_FOR_SIM 301 Cellular waiting for SIM
imp.net.CELLULAR_PPP_CONNECTING 302 Cellular connecting via PPP
imp.net.CELLULAR_REGISTERING 303 Cellular registering with network
imp.net.CELLULAR_REGISTRATION_DENIED 304 Cellular network registration request denied
imp.net.CELLULAR_STOPPED 305 Cellular stopped
imp.net.CELLULAR_STOPPED_UNHAPPY 306 Cellular modem unhappy

Electric Imp reserves the right to alter the value of these constants in future impOS releases.

Making A Local Connection

You use the interface object returned by imp.net.open() to open a local network connection once the callback function registered with imp.net.open() indicates that the interface is connected (see above). You can also use the interface.getstate() method to check whether the interface is connected; it returns the same integer passed into the imp.net.open() callback and is the only way to acquire connection state information if you’re not using a callback. imp.net.open() does not block, but returns immediately.

impOS currently supports only UDP communication on local connections. UDP sockets are initiated by calling the new imp API method openudp() on an interface object returned by imp.net.open(). If you wish, you can pass a function into interface.openudp() which will be called when data is received via the UDP socket. This callback has the following parameters of its own:

  • fromAddress — A string representation of the IPv4 address from which the data has been received, eg. "192.168.0.1".
  • fromPort — The remote port through which the received data was sent. This is an integer.
  • toAddress — A string representation of the IPv4 address for which the data is intended, eg. "192.168.0.2".
  • toPort — The remote port through which the received data was received. This is an integer.
  • data — A blob containing the received data payload.

When calling interface.openudp(), you can also set the local port number to which UDP traffic will be bound. You pass this value as an integer into interface.openudp()’s second parameter. You must bind the network interface to a port, either manually here or when you send data by call the send() method on the object returned by interface.openudp(). If you don’t specify a port number, impOS will set one for you when you call send() — it will be returned to you via the data received callback’s port parameter.

interface.openudp() returns an object representing the UDP socket created by impOS. This object can now be used to send data out. This, and the other methods discussed above, are demonstrated in the following simple example:

local udpsocket;
local interface;
local ucastIP;
local bcastIP;

function dataReceived(fromAddress, fromPort, toAddress, toPort, data) {
    // Check that we are the destination (unicast or broadcast)
    if (toAddress == ucastIP || toAddress == bcastIP) {
        // Log the receipt of data
        server.log("Received " + data.len() + "bytes from " + format("%s:%d", fromAddress, fromPort));

        // Echo it back
        local udpsocket.send(fromAddress, fromPort, data);
        if (result != 0) server.error("Could not send the data (code: " + result + ")");
    }
}

function interfaceHandler(state) {
    if (state == imp.net.CONNECTED && udpsocket == null) {
        // We're connected, so initiate UDP
        udpsocket = interface.openudp(dataReceived, 1234);
    }

    if (state == imp.net.ETHERNET_STOPPED ||
        state == imp.net.ETHERNET_STOPPED_UNHAPPY ||
        state == imp.net.ETHERNET_STOPPED_NO_LINK ) {
        server.error("Ethernet error - closing UDP");
        if (udpsocket != null) {
            udpsocket.close();
            udpsocket = null;
        }
    }
}

// Set up a UDP echo server
// Get an interface object
interface = imp.net.open({"interface":"eth0"}, interfaceHandler);

// Get the imp's IP and the network broadcast IP
local i = imp.net.info();
ucastIP = i.ipv4.address;
bcastIP = i.ipv4.broadcast;

The first call, to imp.net.open(), instantiates an interface object representing the host imp’s primary Ethernet interface. The call also takes an optional reference an interface state-change notification callback; here we provide the function interfaceHandler() for this purpose.

The callback checks the value passed into its state parameter to see if the interface is connected, ie. that it’s ready for local networking. If it is, the code calls the target interface object’s openudp() method to open a UDP connection on port 2001 (the second argument). The interface object is referenced by the variable interface. We also provide a reference to the data-received callback function, dataReceived(), which will handle data received via UDP. The openudp() method returns a udpsocket object which we retain as udpsocket and make use of in dataReceived().

In addition to data, dataReceived() also receives the IPv4 address of the source and the port number; it logs this information. But it only does so if the IP address of the datagram’s destination is the imp’s own, or is a broadcast packet (ie. intended for all devices on the network). If the packet is relevant to this imp, it uses the udpsocket.send() method to transmit the received data back to the source.

Sending Data

As the above example shows, the send() method, called on a udpsocket object returned by interface.openudp(), has three parameters. These match those of the data-received callback that you register with interface.openudp():

  • address — A string representation of the IPv4 address to which the data will be sent.
  • port — The remote port number to which the data will be sent. This is passed as an integer.
  • data — A string or blob containing the data to be sent.

The supplied address must be formatted correctly as a dotted quad string and it must not be an Internet routable address. In other words, it must only be a local/private in the ranges 192.168.0.0—192.168.255.255, 10.0.0.0—10.255.255.255, or 172.16.0.0—172.31.255.255). Incorrectly formatted addresses and/or address outside of these ranges will trigger a runtime error and the UDP socket will be closed.

From impOS 41.12, udpsocket.send() will return an integer value which represents the status of the operation. Successful transmissions are signalled by the value 0 — all other values represent a non-throwing error. Possible error values are listed below.

Error Code Constant Value Description
SEND_ERROR_NOT_CONNECTED 1 Could not connect to the destination machine
SEND_ERROR_WOULDBLOCK 4 The transmission was rate-limited (see above)

Data Transmission Limitations

Outgoing UDP packets are rate limited, to protect the local network and impOS connectivity. You can send up to 100 packets simultaneously in burst mode, or 25 packets a second continuously. In other words, an initial allowance of 100 packets is replenished back up to 100 at a rate of 25 per second.

Broadcasting Data

To send data to all UDP devices on the network via the set port, transmit to the network’s broadcast address. Data sent to other IP address will be sent specifically to the device with that address.

Note You may choose to determine the broadcast address of the local network. If you use the standard proxy for this value, 255.255.255.255, impOS will emit this value unchanged, leaving it to the router to convert to the correct address for the local network.

Receiving Data

As shown in the example above, UDP data is passed to the application via the data-received callback function that you register when calling interface.openudp(). This callback’s third parameter receives the incoming data as its argument.

The function receives the address and port from which the datagram was sent. It also receives the destination address and port, allowing your code to determine whether it is the intended recipient. This will be the case if the destination address is either that of the code’s host imp, or destination address is the network’s broadcast address. Both of these addresses can be gathered using imp.net.info() as the example above shows.

If you did not provide a data-received callback via interface.openudp(), or you wish to switch to an alternative callback at any time, you can register a data-received callback by calling udpsocket.onreceive() method.

Note If you register a new callback immediately after sending data (using udpsocket.send()) then there is a small window during which packets could be dropped. For this reason, you should either call udpsocket.onreceive() before calling udpsocket.send(), or specify the receive callback and local port number in interface.openudp().

Disconnections And Offline Operation

It’s important to understand that an imp’s local network connections are entirely separate from its connection to the server (ie. to its agent in the impCloud and thus the wider Internet), even if both operate across the same network interface.

Your application can be notified of unplanned server connection losses by registering a callback function using the imp API method server.onunexpecteddisconnect(). UDP connection losses will be reported via the callback you register with imp.net.open(). These two callbacks are entirely separate, and they will only be called at the same time if, for example, the local network goes down, breaking an imp’s connections to other devices and to the server.

It is entirely possible that though the local network continues to function, that network’s Internet link has been lost. In this case, your application can continue communicating with other local devices while it attempts to reconnect to the server, perhaps using a different network interface.

Equally, you can call server.disconnect() to break the server connection manually and be sure that though the imp is offline — ie. not connected to the impCloud — it will still be connected to other, nearby devices via the local network and UDP.

Communication With Devices

This mechanism provides a means for an imp to interact with multiple devices that are using the same local network that as is the imp, using UDP. Your code will still need to encode/decode the data passing between connected devices and perform device discovery, eg. by sending a broadcast UDP packet.

Example

The following example might be run on an imp-based sensor hub. At start-up it sets up UDP communications and sends a broadcast to all the devices on the local WiFi network. Only our application’s sensor nodes should respond; when they do, the code retains their IP addresses for future use.

Every 60 seconds, the hub sends a data-request packet to each known sensor node; the responses, when received, are transferred to the agent, perhaps for relaying to a cloud-hosted data analysis platform. The results are made available via the log and on a web UI served by the hub’s agent.

The hub code will run on any imp-based breakout board. The sensor-node code is intended to be run on impExplorer™ Kits.

Note UDP makes no guarantees about the order in which packets will be received — or even whether they will be received at all. As such, you should expect to see some devices log Bad Sequence Number errors when, for example, a data packet was sent by a node but not received by the hub; in this case, when the hub next requests a reading, the sequence number it sends will be lower than the node expects, and the request will be ignored. Subsequent requests from the hub will be correctly sequenced, however.

Hub Agent Code

Hub Device Code

Node Device Code

Note There is no Node Agent Code in this example.