interface.openudp(callback, localPort)

Description

This method establishes a UDP socket through the target network interface object as returned by imp.net.open(), which is used to initialize a named interface.

UDP is not supported on all possible network interfaces. At this time, only WiFi and Ethernet interfaces can be used for UDP; if you attempt to open a UDP socket on a cellular interface, an exception will be thrown. An exception will also be thrown if you attempt to open a UDP socket on any interface that is not powered or is unavailable (eg. through imp.net.setserverinterfaces()). You can use interface.getstate() to determine whether a given interface is powered, available and/or connected.

When the UDP socket has been created, interface.openudp() returns a reference to the imp API udpsocket object which represents it.

The method’s parameters are optional. The first parameter, callback, takes a function which will be called whenever the imp receives data via the UDP socket. For more information, please see udpsocket.onreceive().

The localPort parameter provides a means to bind the UDP to a specific port: pass in an integer indicating the port number. If the port you specify is already in use, out of range (ie. less than 1024 or greater than 65535), or not an integer, an exception will be thrown.

A UDP socket must be bound to a local port if it is to send or receive data. If you create a UDP socket and do not provide a port number through localPort, then a random port (a high-numbered port from the standard IANA ephemeral port range) will be assigned by impOS™ when you first send data through the socket using udpsocket.send().

A socket will not relay received messages to a registered handler until it is assigned a port (by you or impOS).

Examples

Create a send-only UDP socket at port 1234

local udpsocket;
local interface;

function interfaceHandler(state) {
    if (state == imp.net.CONNECTED && udpsocket == null) {
        // We're connected, so initiate UDP
        udpsocket = interface.openudp(null, 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;
            }
    }
}

// Open the interface
interface = imp.net.open({"interface":"eth0"}, interfaceHandler);

// When relay-able data comes in from the agent,
// send it out to the local network via UDP
agent.on("relay.data", function(data) {
    // Check that the UDP socket is open
    if (udpsocket.isopen()) {
        // Send the data
        // NOTE This example assumes the target device's IP
        local result = udpsocket.send("192.168.0.1", 1234, data);
        if (result != 0) server.error("Could not send the data (code: " + result + ")");
    } else {
        server.error("UDP socket on port 1234 is not open for sending");
    }
}

Set up a UDP echo server

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 result = 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) {
        // Get the imp's IP and the network broadcast IP
        local ipData = interface.getiptable();
        ucastIP = ipData.ipv4.address;
        bcastIP = ipData.ipv4.broadcast;

        // 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
// First, open the interface
interface = imp.net.open({"interface":"eth0"}, interfaceHandler);