README.md
1# UDP Multicast Example
2
3This example shows how to use the IPV4 & IPV6 UDP multicast features via the BSD-style sockets interface.
4
5## Behaviour
6
7The behaviour of the example is:
8
9* Listens to specified multicast addresses (one IPV4 and/or one IPV6).
10* Print any UDP packets received as ASCII text.
11* If no packets are received it will periodicially (after 2.5 seconds) send its own plaintext packet(s) to the multicast address(es).
12
13## Configuration
14
15Open the project configuration menu (`idf.py menuconfig`).
16
17Configure Wi-Fi or Ethernet under "Example Connection Configuration" menu. See "Establishing Wi-Fi or Ethernet Connection" section in [examples/protocols/README.md](../../README.md) for more details.
18
19The "Example Configuration" menu allows you to configure the details of the example:
20
21* IP Mode: IPV4 & IPV6 dual, IPV4 only, or IPv6 only.
22* Multicast addresses for IPV4 and/or IPV6.
23* Enable multicast socket loopback (ie should the socket receive its own multicast transmissions.)
24* Change the interface to add the multicast group on (default interface, or WiFi STA interface.) Both methods are valid.
25
26## Implementation Details
27
28In IPV4 & IPV6 dual mode, an IPV6 socket is created and the "dual mode" options described in [RFC4038](https://tools.ietf.org/html/rfc4038) are used to bind it to the default address for both IPV4 & IPV6 and join both the configured IPV4 & IPV6 multicast groups. Otherwise, a single socket of the appropriate type is created.
29
30The socket is always bound to the default address, so it will also receive unicast packets. If you only want to receive multicast packets for a particular address, `bind()` to that multicast address instead.
31
32## Host Tools
33
34There are many host-side tools which can be used to interact with the UDP multicast example. One command line tool is [socat](http://www.dest-unreach.org/socat/) which can send and receive many kinds of packets.
35
36### Send IPV4 multicast via socat
37
38```
39echo "Hi there, IPv4!" | socat STDIO UDP4-DATAGRAM:232.10.11.12:3333,ip-multicast-if=(host_ip_addr)
40```
41
42Replace `232.10.11.12:3333` with the IPV4 multicast address and port, and `(host_ip_addr)` with the host's IP address (used to find the interface to send the multicast packet on.)
43
44### Receive IPV4 multicast via socat
45
46```
47socat STDIO UDP4-RECVFROM:3333,ip-add-membership=232.10.11.12:(host_ip_addr)
48```
49
50Replace `:3333` and `232.10.11.12` with the port and IPV4 multicast address, respectively. Replace `(host_ip_addr)` with the host IP address, used to find the interface to listen on.
51
52(The `,ip-add-membership=...` clause may not be necessary, depending on your network configuration.)
53
54### Send IPV6 multicast via socat
55
56```
57echo "Hi there, IPV6!" | socat STDIO UDP6-DATAGRAM:[ff02::fc]:3333
58```
59
60Replace `[ff02::fc]:3333` with the IPV6 multicast address and port, respectively.
61
62### Receive IPV6 multicast via socat
63
64At time of writing this is not possible without patching socat. Use a different tool or programming language to receive IPV6 multicast packets.
65
66## About Examples
67
68See the README.md file in the upper level 'examples' directory for general information about examples.
69
70
