Skip to main content

interface.openudp(callback, localPort)

Attempt to create a UDP socket for sending and receiving data via the local network

Availability

Device (from impOS™ 42)

Parameters

Name Type Description
callback Function An optional function to be called when data is received via UDP
localPort Integer An optional UDP port number

Returns

A UDPSocket instance

Description

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 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;
            }
    }
}

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 still open
    if (udpsocket.isopen()) {
        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) {
        // 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;