Skip to content

UDP

Reserved UDP ports

UDP ports from 6960 to 6970 are reserved for internal Mira communications.

Ports from 49152 to 65535 are used when no port has been specified for a connection.

Packet fragmentation

MiraMesh uses 6lowpan to fragment packets that are larger than what can be sent on the physical radio link. Packets that are too large to fit in a single radio packet will be fragmented into two or more fragments depending on how large the UDP packet is. When a packet is fragmented the probability of delivery of the packet will be lowered as it is split in multiple parts. To avoid packet fragmentation, the user can limit the size of the packets to be sent. The following two sections describe some limits and calculations on how to make sure that UDP packets does not get fragmented.

General

UDP packets that are smaller or equal to 160 bytes will never get fragmented if they are sent upstream i.e from a node in the network to the root. Packets going downstream, i.e from root to nodes in the network or node to node in the network, requires extra routing information and that size varies depending on how many nodes it needs to traverse before it reaches its destination. For UDP packets going downstream and have 10 hops to its destination can have a maximum datagram size of 64 bytes, larger UDP packets will get fragmented.

Advanced downstream packet size calculation

The size (in bytes) of the extra routing information required when sending downstream can be calculated as follows: 24 + nodes_to_traverse * 8 To calculate the maximum datagram length when sending downstream, this formula can be used: 168 - 24 - nodes_to_traverse * 8 = number_of_bytes_for_datagram

Note

When calculating the maximum size, the nodes_to_traverse parameter is hard to estimate since the network is self-organizing and self-healing and the depth of the network can change at anytime. A good rule of thumb is to assume a max value of 10 for nodes_to_traverse.

Types

mira_net_udp_connection_t

typedef struct mira_net_udp_connection_t mira_net_udp_connection_t;

mira_net_udp_callback_t

typedef void(* mira_net_udp_callback_t) (mira_net_udp_connection_t *connection, const void *data, uint16_t data_len, const mira_net_udp_callback_metadata_t *metadata, void *storage);

mira_net_udp_icmp6_callback_t

typedef void(* mira_net_udp_icmp6_callback_t) (mira_net_udp_connection_t *connection, const void *data, uint16_t data_len, const mira_net_udp_icmp6_callback_metadata_t *metadata, void *storage);

Structs

mira_net_udp_callback_metadata_t

Name Type Description
source_address const mira_net_address_t *
destination_address const mira_net_address_t *
source_port uint16_t
destination_port uint16_t

mira_net_udp_icmp6_callback_metadata_t

Name Type Description
icmp6 mira_net_icmp6_callback_metadata_t
udp_source_address const mira_net_address_t *
source_port uint16_t
udp_destination_address const mira_net_address_t *
destination_port uint16_t

Functions

mira_net_udp_listen

mira_net_udp_connection_t * mira_net_udp_listen(uint16_t port, mira_net_udp_callback_t callback, void *storage);

Listen the specified UDP port.

Note

Cannot be called before mira_net_init.

Parameters

Name Description
port The port number, zero means the system will allocate it.
callback Callback function with data.
storage Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

A UDP connection on the specified port or NULL if it fails.

mira_net_udp_listen_address

mira_net_udp_connection_t * mira_net_udp_listen_address(const mira_net_address_t *address, uint16_t port, mira_net_udp_callback_t callback, void *storage);

Listen to the specified UDP port and address.

Please see mira_net_udp_multicast_group_join() for more info about handling multicast groups.

Note

Can not be called before mira_net_init. No verification is made of the address.

Parameters

Name Description
address The link-local multicast IP address to listen to, NULL means all IP addresses.
port The port number, zero means the system will allocate it.
callback Callback function with data.
storage Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

A UDP connection on the specified port or NULL if it fails.

mira_net_udp_connect

mira_net_udp_connection_t * mira_net_udp_connect(const mira_net_address_t *address, uint16_t port, mira_net_udp_callback_t callback, void *storage);

Connect via UDP to the specified IP address and port.

When address is NULL, the socket will not bind to a specific remote address and mira_net_udp_send_to has to be used to send messages.

Note

Can not be called before mira_net_init.

Parameters

Name Description
address The IP address to connect to.
port The remote port number to connect to. Discarded if address is NULL.
callback UDP callback function.
storage Storage pointer that is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

The UDP Connection or NULL if it fails.

mira_net_udp_bind

mira_net_udp_connection_t * mira_net_udp_bind(const mira_net_address_t *remote_address, uint16_t remote_port, uint16_t local_port, mira_net_udp_callback_t callback, void *storage);

Bind a socket and sets up a connection.

When remote_address is NULL, the socket does not have a remote address and mira_net_udp_send_to has to be used when sending messages.

If local_port is 0, a random number within the 49152 to 65535 range will be used.

Note

Can not be called before mira_net_init.

Parameters

Name Description
remote_address IP address to bind to.
remote_port The remote port to connect to. Discarded if address is NULL.
local_port The local port to bind the connection to.
callback UDP callback function.
storage Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

The UDP Connection or NULL if it fails.

mira_net_udp_bind_address

mira_net_udp_connection_t * mira_net_udp_bind_address(const mira_net_address_t *remote_address, const mira_net_address_t *local_address, uint16_t remote_port, uint16_t local_port, mira_net_udp_callback_t callback, void *storage);

Binds a socket to a local address and/or sets up a connection.

When remote_address is NULL, the socket does not have a remote address and mira_net_udp_send_to has to be used when sending messages.

When local_address is NULL, the socket listens to all available addresses. Please see mira_net_udp_multicast_group_join() for more info about multicast groups.

If local_port is 0, a random number within the 49152 to 65535 range will be used.

Note

Can not be called before mira_net_init. No verification is made of local_address.

Parameters

Name Description
remote_address IP address to bind to.
local_address IP link-local multicast IP address to listen to.
remote_port The remote port to connect to.
local_port The local port to bind the connection to.
callback UDP callback function.
storage Storage pointer which is used to store optional information to be used by the callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

The UDP Connection or NULL if it fails.

mira_net_udp_close

mira_status_t mira_net_udp_close(mira_net_udp_connection_t *mira_udp_connection);

Close the specified connection.

Parameters

Name Description
mira_udp_connection The UDP connection to close.

Return value

Name Description
MIRA_SUCCESS UDP connection successfully closed.
MIRA_NET_ERROR_INVALID_SOCKET Connection is not open.
MIRA_ERROR_INVALID_VALUE Invalid input value.

mira_net_udp_multicast_group_join

mira_status_t mira_net_udp_multicast_group_join(mira_net_udp_connection_t *mira_udp_connection, const mira_net_address_t *multicast_address);

Join a multicast group.

Add a socket to a multicast group.

To be able to receive packets to a multicast address, the address must be joined (with this call) and the socket must also listen to all addresses or to the multicast address (using mira_net_udp_listen_address or mira_net_udp_bind_address).

The node leaves the group when all sockets have left the group. Sockets leave the group when mira_net_udp_multicast_group_leave() is called and when they are closed.

To control latency and current consumption, the address needs to follow a certain the format: ff02::3fRR:XXXX, where RR is the rate, from 0-31, same as for mira_net_init(). XXXX is an any number.

Lower value of rate decreases latency and increases throughput, to the cost of current consumption.

Only one multicast group is allowed per socket.

Note

The address must be a link-local multicast address to bind to, no verification is done of it.

Parameters

Name Description
mira_udp_connection The UDP connection to use for multicast address.
multicast_address The address of the multicast group to join.

Return value

Name Description
MIRA_SUCCESS Successfully joined multicast group.
MIRA_ERROR_INVALID_VALUE Arguments null or address not ff02::3fRR:XXXX.
MIRA_ERROR_NO_MEMORY No space for additional multicast addresses in socket.

mira_net_udp_multicast_group_leave

mira_status_t mira_net_udp_multicast_group_leave(mira_net_udp_connection_t *mira_udp_connection, const mira_net_address_t *multicast_address);

Leave a multicast group.

Leave a group that previously was joined using mira_net_udp_multicast_group_join. Sockets will also leave the group when they are closed.

Parameters

Name Description
mira_udp_connection The UDP connection to close.
multicast_address The address of the multicast group to leave.

Return value

Name Description
MIRA_SUCCESS Successfully left multicast group.
MIRA_NET_ERROR_NO_ADDRESS_SET Socket is not bound to address.
MIRA_ERROR_INVALID_VALUE Invalid argument.

mira_net_udp_send

mira_status_t mira_net_udp_send(mira_net_udp_connection_t *mira_udp_connection, const void *data, uint16_t data_len);

Sends a data string over a specified UDP connection.

The connection must be created with a remote address and port to use this method. To specify the remote address and port when sending, use the mira_net_udp_send_to() method.

Note

When sending to link-local multicast addresses, expect lower delivery rates due to lack of retransmissions. Also when packet is fragmented, the delivery rates will reduced further. Recommended maximum packet size to avoid fragmentation is 160 bytes.

Parameters

Name Description
mira_udp_connection The UDP connection to use for the transmission.
data The data to be sent.
data_len The length, in bytes, of the data to be sent. At most 800 should be used.

Return value

Name Description
MIRA_SUCCESS UDP packet successfully sent.
MIRA_NET_ERROR_SEND_FAILED Sending UDP packet failed.

mira_net_udp_send_to

mira_status_t mira_net_udp_send_to(mira_net_udp_connection_t *mira_udp_connection, const mira_net_address_t *address, uint16_t port, const void *data, uint16_t data_len);

Sends a data string via UDP to a specified IP address.

To reply to a received message, use mira_net_udp_send_to() with addess and port set to the values from metadata->source_address and metadata->source_port from the receive callback.

Note

When sending to link-local multicast addresses, expect lower delivery rates due to lack of retransmissions. Also when packet is fragmented, the delivery rates will reduced further. Recommended maximum packet size to avoid fragmentation is 160 bytes.

Parameters

Name Description
mira_udp_connection The UDP connection to use for the transmission.
address The IP address to send to, i.e. the receiver.
port The UDP port to send to.
data Data to send as vector.
data_len The length of the data vector to send. At most 800 should be used.

Return value

Name Description
MIRA_SUCCESS UDP packet successfully sent.
MIRA_NET_ERROR_SEND_FAILED Sending UDP packet failed.

mira_net_udp_icmp6_register_callback

mira_status_t mira_net_udp_icmp6_register_callback(mira_net_udp_connection_t *mira_udp_connection, mira_net_udp_icmp6_callback_t callback, void *storage);

Register a callback for incoming ICMP packets generated as result of packets from the UDP connection.

For example, this callback is called for ICMP packets of type destination host unreachable as result of UDP packets on this connection.

Note

A generic ICMP callback that is invoked at the reception of any ICMP message can be registered using mira_net_icmp6_register_callback.

Parameters

Name Description
mira_udp_connection The UDP connection to which the callback has to be registered.
callback The UDP-ICMP callback function.
storage Storage pointer which is used to store optional information to be used by the UDP-ICMP callback function. E.g. it could be used as an identifier or to pass on a configuration struct.

Return value

Name Description
MIRA_SUCCESS UDP-ICMP callback successfully registered.
MIRA_ERROR_INVALID_VALUE UDP connectection is invalid.
MIRA_ERROR_RESOURCE_NOT_AVAILABLE Failed to register callback.

mira_net_udp_icmp6_deregister_callback

mira_status_t mira_net_udp_icmp6_deregister_callback(mira_net_udp_connection_t *mira_udp_connection);

Deregister the ICMP callback for this UDP connection.

Parameters

Name Description
mira_udp_connection The UDP connection for which the ICMP callback has to be deregistered.

Return value

Name Description
MIRA_SUCCESS UDP-ICMP callback successfully deregistered.
MIRA_ERROR_INVALID_VALUE UDP connectection is invalid.
Back to top