udp¶

Publish and receive data using UDP sockets.

This module provides an interface for publishing data over UDP sockets. The main objects responsible for transmitting data over UDP sockets are:

Connection

RawBroadcaster

RawListener

Data are transmitted using IPv6 multicasts. Note that this module inherits the advantages and disadvantages of UDP. That is; UDP allows connectionless, low-latency broadcasts with no guarantee of delivery, ordering, or duplicate protection.

Example usage:

import os
import time
from mcl.network.udp import Connection
from mcl.network.udp import RawListener
from mcl.network.udp import RawBroadcaster

# Create UDP connection.
connection = Connection('ff15::c73d:cf41:ea8e:b0a0')

# Create raw listener and broadcaster from IPv6 connection.
listener = RawListener(connection)
broadcaster = RawBroadcaster(connection)

# Print received data to screen.
listener.subscribe(lambda d: os.sys.stdout.write(d['payload']))

# Broadcast data.
broadcaster.publish('hello world')
time.sleep(0.1)

# Close connections.
listener.close()
broadcaster.close()

Note

To use IPv6 multicast, a connected network interface must exist on the system. If no interface is available, linux systems can be configured to work offline with the following:

sudo modprobe dummy
sudo ip -6 addr add fd34::1/64 dev dummy0

Note

It is advised to increase the UDP kernel buffer size:

http://lcm.googlecode.com/svn/www/reference/lcm/multicast.html

In linux, a temporary method (does not persist across reboots) of increasing the UDP kernel buffer size to 2MB can be achieved by issuing:

sudo sysctl -w net.core.rmem_max=2097152
sudo sysctl -w net.core.rmem_default=2097152

A permanent solution is to add the following lines to /etc/sysctl.conf:

net.core.rmem_max=2097152
net.core.rmem_default=2097152

Warning

A bug introduced into the linux kernel prevents IPv6 multicast packets from reaching the destination sockets under certain conditions. This is believed to affect linux kernels 3.13 to 3.15. The regression was fixed and should not be present in recent kernels.

Classes

class Connection(url, port=26000)[source]¶

Object for encapsulating UDP connection parameters.

Parameters:	url (str) – IPv6 address of connection. port (int) – Port to use (between 1024 and 65535).

url¶

str

IPv6 address of connection.

port¶

int

Port used in connection.

Raises:	`TypeError` – If `url` is not a string or `port` is not an integer between 1024 and 65536.

classmethod from_dict(dictionary)¶

Make a new Connection object from a dictionary

If optional attributes are not specified, their default values are used.

port

itemgetter(item, ...) –> itemgetter object

Return a callable object that fetches the given item(s) from its operand. After f = itemgetter(2), the call f(r) returns r[2]. After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

to_dict(t)¶: Return a new dict which maps field names to their values

url

itemgetter(item, ...) –> itemgetter object

Return a callable object that fetches the given item(s) from its operand. After f = itemgetter(2), the call f(r) returns r[2]. After g = itemgetter(2, 5, 3), the call g(r) returns (r[2], r[5], r[3])

class RawBroadcaster(connection, topic=None)[source]¶

Send data over the network using a UDP socket.

The RawBroadcaster object allows data to be published over a UDP socket. The object marshalls broadcasts and ensures large items will be fragmented into smaller sub-packets which obey the network maximum transmission unit (MTU) constraints.

Parameters:	connection (`Connection`) – Connection object. topic (str) – Default topic associated with the IPv6 interface.

connection¶

Connection

Connection object.

topic¶

str

Default topic associated with the IPv6 interface.

is_open¶

bool

Return whether the UDP socket is open.

Raises:	`TypeError` – If any of the inputs are ill-specified.

close()[source]¶

Close connection to UDP broadcast interface.

Returns:	Returns `True` if the socket was closed. If the socket was already closed, the request is ignored and the method returns `False`.
Return type:	`bool`

publish(data, topic=None)[source]¶

Send data over UDP interface.

Large data is fragmented into smaller MTU sized packets. The protocol used during publishing is documented in RawBroadcaster.

Parameters:	data (obj) – Serialisable object to broadcast over UDP. topic (str) – Topic associated with published data. This option will temporarily override the topic specified during instantiation.

class RawListener(connection, topics=None)[source]¶

Receive data from the network using a UDP socket.

The RawListener object subscribes to a UDP socket and issues publish events when UDP data are received. Network data are made available to other objects by issuing callbacks in the following format:

{'topic': str(),
 'payload': obj()}

where:

<topic> is a string containing the topic associated with the received data.

<payload> is the received (serialisable) data.

The RawListener marshalls broadcasts and ensures multiple, fragmented packets will be recomposed into a single packet before issuing a publish event.

Note

RawListener does not interpret the received data in anyway. Code receiving the data must be aware of how to handle it. A method for simplifying data handling is to pair a specific data type with a unique network address. By adopting this paradigm, handling the data is trivial if the network address is known.

Parameters:	connection (`Connection`) – Connection object. topics (str or list) – Topics associated with the `RawListener` interface.

connection¶

Connection

Connection object.

topics¶

str or list

Topics associated with the RawListener interface.

is_open¶

bool

Return whether the UDP socket is open.

close()[source]¶

Close connection to UDP receive interface.

Returns:	Returns `True` if the socket was closed. If the socket was already closed, the request is ignored and the method returns `False`.
Return type:	`bool`