README-P2P revision 04949598a23f501be6eec21697465fd46a28840a
1wpa_supplicant and Wi-Fi P2P 2============================ 3 4This document describes how the Wi-Fi P2P implementation in 5wpa_supplicant can be configured and how an external component on the 6client (e.g., management GUI) is used to enable WPS enrollment and 7registrar registration. 8 9 10Introduction to Wi-Fi P2P 11------------------------- 12 13TODO 14 15More information about Wi-Fi P2P is available from Wi-Fi Alliance: 16http://www.wi-fi.org/Wi-Fi_Direct.php 17 18 19wpa_supplicant implementation 20----------------------------- 21 22TODO 23 24 25wpa_supplicant configuration 26---------------------------- 27 28Wi-Fi P2P is an optional component that needs to be enabled in the 29wpa_supplicant build configuration (.config). Here is an example 30configuration that includes Wi-Fi P2P support and Linux nl80211 31-based driver interface: 32 33CONFIG_DRIVER_NL80211=y 34CONFIG_CTRL_IFACE=y 35CONFIG_P2P=y 36CONFIG_AP=y 37CONFIG_WPS=y 38 39 40In run-time configuration file (wpa_supplicant.conf), some parameters 41for P2P may be set. In order to make the devices easier to recognize, 42device_name and device_type should be specified. For example, 43something like this should be included: 44 45ctrl_interface=/var/run/wpa_supplicant 46device_name=My P2P Device 47device_type=1-0050F204-1 48 49 50wpa_cli 51------- 52 53Actual Wi-Fi P2P operations are requested during runtime. These can be 54done for example using wpa_cli (which is described below) or a GUI 55like wpa_gui-qt4. 56 57 58wpa_cli starts in interactive mode if no command string is included on 59the command line. By default, it will select the first network interface 60that it can find (and that wpa_supplicant controls). If more than one 61interface is in use, it may be necessary to select one of the explicitly 62by adding -i argument on the command line (e.g., 'wpa_cli -i wlan1'). 63 64Most of the P2P operations are done on the main interface (e.g., the 65interface that is automatically added when the driver is loaded, e.g., 66wlan0). When using a separate virtual interface for group operations 67(e.g., wlan1), the control interface for that group interface may need 68to be used for some operations (mainly WPS activation in GO). This may 69change in the future so that all the needed operations could be done 70over the main control interface. 71 72Device Discovery 73 74p2p_find [timeout in seconds] [type=<social|progressive>] 75 76The default behavior is to run a single full scan in the beginning and 77then scan only social channels. type=social will scan only social 78channels, i.e., it skips the initial full scan. type=progressive is 79like the default behavior, but it will scan through all the channels 80progressively one channel at the time in the Search state rounds. This 81will help in finding new groups or groups missed during the initial 82full scan. 83 84p2p_listen [timeout in seconds] 85 86Start Listen-only state (become discoverable without searching for 87other devices). Optional parameter can be used to specify the duration 88for the Listen operation in seconds. This command may not be of that 89much use during normal operations and is mainly designed for 90testing. It can also be used to keep the device discoverable without 91having to maintain a group. 92 93p2p_stop_find 94 95Stop ongoing P2P device discovery or other operation (connect, listen 96mode). 97 98p2p_flush 99 100Flush P2P peer table and state. 101 102Group Formation 103 104p2p_prov_disc <peer device address> <display|keypad|pbc> [join|auto] 105 106Send P2P provision discovery request to the specified peer. The 107parameters for this command are the P2P device address of the peer and 108the desired configuration method. For example, "p2p_prov_disc 10902:01:02:03:04:05 display" would request the peer to display a PIN for 110us and "p2p_prov_disc 02:01:02:03:04:05 keypad" would request the peer 111to enter a PIN that we display. 112 113The optional "join" parameter can be used to indicate that this command 114is requesting an already running GO to prepare for a new client. This is 115mainly used with "display" to request it to display a PIN. The "auto" 116parameter can be used to request wpa_supplicant to automatically figure 117out whether the peer device is operating as a GO and if so, use 118join-a-group style PD instead of GO Negotiation style PD. 119 120p2p_connect <peer device address> <pbc|pin|PIN#> [display|keypad] 121 [persistent|persistent=<network id>] [join|auth] 122 [go_intent=<0..15>] [freq=<in MHz>] [provdisc] 123 124Start P2P group formation with a discovered P2P peer. This includes 125optional group owner negotiation, group interface setup, provisioning, 126and establishing data connection. 127 128The <pbc|pin|PIN#> parameter specifies the WPS provisioning 129method. "pbc" string starts pushbutton method, "pin" string start PIN 130method using an automatically generated PIN (which will be returned as 131the command return code), PIN# means that a pre-selected PIN can be 132used (e.g., 12345670). [display|keypad] is used with PIN method 133to specify which PIN is used (display=dynamically generated random PIN 134from local display, keypad=PIN entered from peer display). "persistent" 135parameter can be used to request a persistent group to be formed. The 136"persistent=<network id>" alternative can be used to pre-populate 137SSID/passphrase configuration based on a previously used persistent 138group where this device was the GO. The previously used parameters will 139then be used if the local end becomes the GO in GO Negotiation (which 140can be forced with go_intent=15). 141 142"join" indicates that this is a command to join an existing group as a 143client. It skips the GO Negotiation part. This will send a Provision 144Discovery Request message to the target GO before associating for WPS 145provisioning. 146 147"auth" indicates that the WPS parameters are authorized for the peer 148device without actually starting GO Negotiation (i.e., the peer is 149expected to initiate GO Negotiation). This is mainly for testing 150purposes. 151 152"go_intent" can be used to override the default GO Intent for this GO 153Negotiation. 154 155"freq" can be used to set a forced operating channel (e.g., freq=2412 156to select 2.4 GHz channel 1). 157 158"provdisc" can be used to request a Provision Discovery exchange to be 159used prior to starting GO Negotiation as a workaround with some deployed 160P2P implementations that require this to allow the user to accept the 161connection. 162 163p2p_group_add [persistent|persistent=<network id>] [freq=<freq in MHz>] 164 165Set up a P2P group owner manually (i.e., without group owner 166negotiation with a specific peer). This is also known as autonomous 167GO. Optional persistent=<network id> can be used to specify restart of 168a persistent group. Optional freq=<freq in MHz> can be used to force 169the GO to be started on a specific frequency. Special freq=2 or freq=5 170options can be used to request the best 2.4 GHz or 5 GHz band channel 171to be selected automatically. 172 173p2p_reject <peer device address> 174 175Reject connection attempt from a peer (specified with a device 176address). This is a mechanism to reject a pending GO Negotiation with 177a peer and request to automatically block any further connection or 178discovery of the peer. 179 180p2p_group_remove <group interface> 181 182Terminate a P2P group. If a new virtual network interface was used for 183the group, it will also be removed. The network interface name of the 184group interface is used as a parameter for this command. 185 186p2p_cancel 187 188Cancel an ongoing P2P group formation related operation. 189 190Service Discovery 191 192p2p_serv_disc_req 193 194Schedule a P2P service discovery request. The parameters for this 195command are the device address of the peer device (or 00:00:00:00:00:00 196for wildcard query that is sent to every discovered P2P peer that 197supports service discovery) and P2P Service Query TLV(s) as hexdump. For 198example, 199 200p2p_serv_disc_req 00:00:00:00:00:00 02000001 201 202schedules a request for listing all available services of all service 203discovery protocols and requests this to be sent to all discovered 204peers (note: this can result in long response frames). The pending 205requests are sent during device discovery (see p2p_find). 206 207Only a single pending wildcard query is supported, but there can be 208multiple pending peer device specific queries (each will be sent in 209sequence whenever the peer is found). 210 211This command returns an identifier for the pending query (e.g., 212"1f77628") that can be used to cancel the request. Directed requests 213will be automatically removed when the specified peer has replied to 214it. 215 216For UPnP, an alternative command format can be used to specify a 217single query TLV (i.e., a service discovery for a specific UPnP 218service): 219 220p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH> 221 222For example: 223 224p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 225 226Additional examples for queries: 227 228# list of all Bonjour services 229p2p_serv_disc_req 00:00:00:00:00:00 02000101 230 231# list of all UPnP services 232p2p_serv_disc_req 00:00:00:00:00:00 02000201 233 234# list of all WS-Discovery services 235p2p_serv_disc_req 00:00:00:00:00:00 02000301 236 237# list of all Bonjour and UPnP services 238p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202 239 240# Apple File Sharing over TCP 241p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01 242 243# Bonjour SSTH (supported service type hash) 244p2p_serv_disc_req 00:00:00:00:00:00 05000101000000 245 246# UPnP examples 247p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all 248p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice 249p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2 250p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012 251p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 252 253p2p_serv_disc_cancel_req <query identifier> 254 255Cancel a pending P2P service discovery request. This command takes a 256single parameter: identifier for the pending query (the value returned 257by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628". 258 259p2p_serv_disc_resp 260 261Reply to a service discovery query. This command takes following 262parameters: frequency in MHz, destination address, dialog token, 263response TLV(s). The first three parameters are copied from the 264request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7 2651 0300000101". This command is used only if external program is used 266to process the request (see p2p_serv_disc_external). 267 268p2p_service_update 269 270Indicate that local services have changed. This is used to increment 271the P2P service indicator value so that peers know when previously 272cached information may have changed. This is only needed when external 273service discovery processing is enabled since the commands to 274pre-configure services for internal processing will increment the 275indicator automatically. 276 277p2p_serv_disc_external <0|1> 278 279Configure external processing of P2P service requests: 0 (default) = 280no external processing of requests (i.e., internal code will process 281each request based on pre-configured services), 1 = external 282processing of requests (external program is responsible for replying 283to service discovery requests with p2p_serv_disc_resp). Please note 284that there is quite strict limit on how quickly the response needs to 285be transmitted, so use of the internal processing is strongly 286recommended. 287 288p2p_service_add bonjour <query hexdump> <RDATA hexdump> 289 290Add a local Bonjour service for internal SD query processing. 291 292Examples: 293 294# AFP Over TCP (PTR) 295p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027 296# AFP Over TCP (TXT) (RDATA=null) 297p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00 298 299# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.) 300p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027 301# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript) 302p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074 303 304# Supported Service Type Hash (SSTH) 305p2p_service_add bonjour 000000 <32-byte bitfield as hexdump> 306(note: see P2P spec Annex E.4 for information on how to construct the bitfield) 307 308p2p_service_del bonjour <query hexdump> 309 310Remove a local Bonjour service from internal SD query processing. 311 312p2p_service_add upnp <version hex> <service> 313 314Add a local UPnP service for internal SD query processing. 315 316Examples: 317 318p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice 319p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice 320p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2 321p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2 322p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1 323 324p2p_service_del upnp <version hex> <service> 325 326Remove a local UPnP service from internal SD query processing. 327 328p2p_service_flush 329 330Remove all local services from internal SD query processing. 331 332Invitation 333 334p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address] 335 [go_dev_addr=address] 336 337Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a 338persistent group (e.g., persistent=4). If the peer device is the GO of 339the persistent group, the peer parameter is not needed. Otherwise it is 340used to specify which device to invite. go_dev_addr parameter can be 341used to override the GO device address for Invitation Request should 342it be not known for some reason (this should not be needed in most 343cases). 344 345Group Operations 346 347(These are used on the group interface.) 348 349wps_pin <any|address> <PIN> 350 351Start WPS PIN method. This allows a single WPS Enrollee to connect to 352the AP/GO. This is used on the GO when a P2P client joins an existing 353group. The second parameter is the address of the Enrollee or a string 354"any" to allow any station to use the entered PIN (which will restrict 355the PIN for one-time-use). PIN is the Enrollee PIN read either from a 356label or display on the P2P Client/WPS Enrollee. 357 358wps_pbc 359 360Start WPS PBC method (i.e., push the button). This allows a single WPS 361Enrollee to connect to the AP/GO. This is used on the GO when a P2P 362client joins an existing group. 363 364p2p_get_passphrase 365 366Get the passphrase for a group (only available when acting as a GO). 367 368p2p_presence_req [<duration> <interval>] [<duration> <interval>] 369 370Send a P2P Presence Request to the GO (this is only available when 371acting as a P2P client). If no duration/interval pairs are given, the 372request indicates that this client has no special needs for GO 373presence. the first parameter pair gives the preferred duration and 374interval values in microseconds. If the second pair is included, that 375indicates which value would be acceptable. 376 377Parameters 378 379p2p_ext_listen [<period> <interval>] 380 381Configure Extended Listen Timing. If the parameters are omitted, this 382feature is disabled. If the parameters are included, Listen State will 383be entered every interval msec for at least period msec. Both values 384have acceptable range of 1-65535 (with interval obviously having to be 385larger than or equal to duration). If the P2P module is not idle at 386the time the Extended Listen Timing timeout occurs, the Listen State 387operation will be skipped. 388 389The configured values will also be advertised to other P2P Devices. The 390received values are available in the p2p_peer command output: 391 392ext_listen_period=100 ext_listen_interval=5000 393 394p2p_set <field> <value> 395 396Change dynamic P2P parameters 397 398p2p_set discoverability <0/1> 399 400Disable/enable advertisement of client discoverability. This is 401enabled by default and this parameter is mainly used to allow testing 402of device discoverability. 403 404p2p_set managed <0/1> 405 406Disable/enable managed P2P Device operations. This is disabled by 407default. 408 409p2p_set listen_channel <1/6/11> 410 411Set P2P Listen channel. This is mainly meant for testing purposes and 412changing the Listen channel during normal operations can result in 413protocol failures. 414 415p2p_set ssid_postfix <postfix> 416 417Set postfix string to be added to the automatically generated P2P SSID 418(DIRECT-<two random characters>). For example, postfix of "-testing" 419could result in the SSID becoming DIRECT-ab-testing. 420 421set <field> <value> 422 423Set global configuration parameters which may also affect P2P 424operations. The format on these parameters is same as is used in 425wpa_supplicant.conf. Only the parameters listen here should be 426changed. Modifying other parameters may result in incorrect behavior 427since not all existing users of the parameters are updated. 428 429set uuid <UUID> 430 431Set WPS UUID (by default, this is generated based on the MAC address). 432 433set device_name <device name> 434 435Set WPS Device Name (also included in some P2P messages). 436 437set manufacturer <manufacturer> 438 439Set WPS Manufacturer. 440 441set model_name <model name> 442 443Set WPS Model Name. 444 445set model_number <model number> 446 447Set WPS Model Number. 448 449set serial_number <serial number> 450 451Set WPS Serial Number. 452 453set device_type <device type> 454 455Set WPS Device Type. 456 457set os_version <OS version> 458 459Set WPS OS Version. 460 461set config_methods <config methods> 462 463Set WPS Configuration Methods. 464 465set sec_device_type <device type> 466 467Add a new Secondary Device Type. 468 469set p2p_go_intent <GO intent> 470 471Set the default P2P GO Intent. Note: This value can be overridden in 472p2p_connect command and as such, there should be no need to change the 473default value here during normal operations. 474 475set p2p_ssid_postfix <P2P SSID postfix> 476 477Set P2P SSID postfix. 478 479set persistent_reconnect <0/1> 480 481Disable/enabled persistent reconnect for reinvocation of persistent 482groups. If enabled, invitations to reinvoke a persistent group will be 483accepted without separate authorization (e.g., user interaction). 484 485set country <two character country code> 486 487Set country code (this is included in some P2P messages). 488 489Status 490 491p2p_peers [discovered] 492 493List P2P Device Addresses of all the P2P peers we know. The optional 494"discovered" parameter filters out the peers that we have not fully 495discovered, i.e., which we have only seen in a received Probe Request 496frame. 497 498p2p_peer <P2P Device Address> 499 500Fetch information about a known P2P peer. 501 502Group Status 503 504(These are used on the group interface.) 505 506status 507 508Show status information (connection state, role, use encryption 509parameters, IP address, etc.). 510 511sta 512 513Show information about an associated station (when acting in AP/GO role). 514 515all_sta 516 517Lists the currently associated stations. 518 519Configuration data 520 521list_networks 522 523Lists the configured networks, including stored information for 524persistent groups. The identifier in this list is used with 525p2p_group_add and p2p_invite to indicate which persistent group is to 526be reinvoked. 527 528remove_network <network id> 529 530Remove a network entry from configuration. 531 532 533wpa_cli action script 534--------------------- 535 536See examples/p2p-action.sh 537 538TODO: describe DHCP/DNS setup 539TODO: cross-connection 540