examples/minimal-mdns/README.md

   1 ## Example server
   2
   3 The file `server.cpp` contains an example of a mdns server that can listen on
   4 both IPv4 and IPv6 interfaces or mDNS queries.
   5
   6 To run, you can use:
   7
   8 ```sh
   9 ./out/minimal_mdns/minimal-mdns-server -4
  10 ```
  11
  12 which will listen on both IPv4 and IPv6 addresses, on port 5353.
  13
  14 See
  15
  16 ```sh
  17 ./out/minimal_mdns/minimal-mdns-server --help
  18 ```
  19
  20 for supported options.
  21
  22 The server will print out any queries as well as any advertisements it sees on
  23 the network while running.
  24
  25 ## Example client
  26
  27 The file `client.cpp` contains an example of a mdns client. By default it
  28 queries for **\_services.\_dns-sd.\_udp.local** (DNS-SD list services) and uses
  29 unicast queries.
  30
  31 Example run:
  32
  33 ```sh
  34 ./out/minimal_mdns/minimal-mdns-client -4
  35 ```
  36
  37 which is likely to list a lot of answers.
  38
  39 You can customize the queries run:
  40
  41 ```sh
  42 /out/minimal_mdns/minimal-mdns-client -4 -q chip-mdns-demo._chip._tcp.local
  43 ```
  44
  45 see
  46
  47 ```sh
  48 ./out/minimal_mdns/minimal-mdns-client --help
  49 ```
  50
  51 for full command line details.
  52
  53 ## Example advertiser
  54
  55 This example uses the chip built-in advertiser, implemented in the file
  56 `advertiser.cpp`.
  57
  58 Example runs:
  59
  60 ```sh
  61 ./out/minimal_mdns/mdns-advertiser -4 -m operational
  62 ```
  63
  64 ```sh
  65 ./out/minimal_mdns/mdns-advertiser -4 -m commisioning --vendor-id 123 --product-id 456
  66 ```
  67
  68 see
  69
  70 ```sh
  71 ./out/minimal_mdns/mdns-advertiser --help
  72 ```
  73
  74 for full command line details.
  75
  76 ## Testing with dns-sd
  77
  78 If you have a mac computer (or are able to install dns-sd via opkg), here are
  79 some helpful examples on usage. More details are available in the CHIP spec on
  80 discovery.
  81
  82 ### Advertising to test client listings
  83
  84 #### Simulated uncommisioned node
  85
  86 ```sh
  87 dns-sd -R DD200C20D25AE5F7 _chipc._udp,S052,L0840,V123 . 11111 D=0840 VP=123+456
  88 ```
  89
  90 Will create the following records
  91
  92 ```
  93 _chipc._udp.local.                   PTR   DD200C20D25AE5F7._chipc._udp.local.
  94 S052._sub._chipc._udp.local.         PTR   DD200C20D25AE5F7._chipc._udp.local.
  95 L0840._sub._chipc._udp.local.        PTR   DD200C20D25AE5F7._chipc._udp.local.
  96 V123._sub._chipc._udp.local.         PTR   DD200C20D25AE5F7._chipc._udp.local.
  97 DD200C20D25AE5F7._chipc._udp.local.  TXT   "D=0840" "VP=123+456"
  98 DD200C20D25AE5F7._chipc._udp.local.  SRV   0 0 11111 B75AFB458ECD.local.
  99 B75AFB458ECD.local.                  AAAA  ba2a:b311:742e:b44c:f515:576f:9783:3f30
 100 ```
 101
 102 #### Simulated commisioning node
 103
 104 ```sh
 105 dns-sd -R DD200C20D25AE5F7 _chipd._udp,S052,L0840,V123 . 11111 D=0840 VP=123+456 PH=3
 106 ```
 107
 108 Will create the following records:
 109
 110 ```
 111 _chipd._udp.local.              PTR   DD200C20D25AE5F7._chipd._udp.local.
 112 S052._sub._chipd._udp.local.    PTR   DD200C20D25AE5F7._chipd._udp.local.
 113 V123._sub._chipd._udp.local.    PTR   DD200C20D25AE5F7._chipd._udp.local.
 114 D0840._sub._chipd._udp.local.   PTR   DD200C20D25AE5F7._chipd._udp.local.
 115 DD200C20D25AE5F7._chipd._udp.local.  TXT   "D=0840" "VP=123+456" "PH=3"
 116 DD200C20D25AE5F7._chipd._udp.local.  SRV   0 0 11111 B75AFB458ECD.local.
 117 B75AFB458ECD.local.             AAAA  ba2a:b311:742e:b44c:f515:576f:9783:3f30
 118 ```
 119
 120 #### Simulated commisioned node
 121
 122 ```sh
 123 dns-sd -R 2906C908D115D362-8FC7772401CD0696 _chip._tcp . 22222
 124 ```
 125
 126 ### Discovery commands
 127
 128 Nodes:
 129
 130 ```sh
 131 dns-sd -B _chipc._udp          # Nodes awaiting commisioning
 132 dns-sd -B _chipc._udp,S052     # Nodes awaiting commisioning with short discriminator 052
 133 dns-sd -B _chipc._udp,L0840    # Nodes awaiting commisioning with long discriminator 0840
 134 dns-sd -B _chipc._udp,V123     # Nodes awaiting commisioning with vendor id 123
 135
 136 dns-sd -B _chipd._udp          # Commisionable nodes
 137 dns-sd -B _chipd._udp,S052     # Commisionable nodes with short discriminator 052
 138 dns-sd -B _chipd._udp,L0840    # Commisionable nodes with long discriminator 0840
 139 dns-sd -B _chipd._udp,V123     # Commisionable nodes with vendor id 123
 140 ```
 141
 142 IP Address:
 143
 144 ```sh
 145 dns-sd -L 2906C908D115D362-8FC7772401CD0696 _chip._tcp  # find server address
 146 dns-sd -Gv6 B75AFB458ECD.local                          # get IPv6 address
 147 ```