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