Skip to main content

udpsocket.send(address, port, data)

Send data to the local network via UDP

Availability

Device (from impOS™ 42)

Parameters

Name Type Description
address String Destination IPv4 address
port Integer Destination port number
data String or blob The data to be sent

Returns

Integer — 0 on success or a Send Error Code on failure

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 sends the provided data via the target UDP socket to the specified address through the indicated port.

The destination address is provided as a dotted quad IPv4 address string, eg. "192.160.0.1", and the destination port is provided as an integer. impOS™ checks that the port number is within a valid range (between 0 and the value of the constant MAX_IP_PORT, and not 67 [DHCP] or 68 [BOOTP]), and that the address has been formatted correctly and is not Internet routable (ie. local/private only: 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). If the settings fail these checks, or the udpsocket object on which send() is called is closed, an exception will be thrown.

You should note that even if the address and port pass impOS’ checks, that does not mean that the destination is able or willing to receive the data.

If the data is not provided as a string or a blob, or is bigger than the constant MAX_SIZE in bytes, a runtime error will be thrown and the data will not be sent (and the socket, if not yet bound to a port, will remain unbound). Attempting to send data through a closed socket will also generate a runtime error.

Local Port Number

If you did not set a local port number when you created the udpsocket object (with interface.openudp()), a local port number will be set for you when data is first sent through the socket.You will not be able to determine a impOS-assigned local port number; if this is important to you, please ensure you provide a local port number when you call interface.openudp().

Rate Limits

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.

Maximum Data Length

Some imps have a relatively small MTU (576 bytes for imps 001-004m, 1460 bytes for imp005), but all support IP fragmentation. Datagrams larger than the MTU will be fragmented if they are outgoing, and simply dropped when incoming. Users should note that a fragmented UDP datagram will be lost if any of its fragments are lost. For maximum reliability, datagrams should be smaller than the MTU.

Send Error Codes

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)