Send data to the local network via UDP
Device (from impOS™ 42)
Destination IPv4 address
Destination port number
|data||String or blob||
The data to be sent
Integer — 0 on success or a Send Error Code on failure
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.
"18.104.22.168", 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.
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().
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.
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.
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)|