README-P2P revision 7a5e50a0554bee77a9da492ea3d86f46147f1671
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>] [ht40] [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>] [ht40] 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 and joining-a-group related 195operation. This operations unauthorizes the specific peer device (if any 196had been authorized to start group formation), stops P2P find (if in 197progress), stops pending operations for join-a-group, and removes the 198P2P group interface (if one was used) that is in the WPS provisioning 199step. If the WPS provisioning step has been completed, the group is not 200terminated. 201 202Service Discovery 203 204p2p_serv_disc_req 205 206Schedule a P2P service discovery request. The parameters for this 207command are the device address of the peer device (or 00:00:00:00:00:00 208for wildcard query that is sent to every discovered P2P peer that 209supports service discovery) and P2P Service Query TLV(s) as hexdump. For 210example, 211 212p2p_serv_disc_req 00:00:00:00:00:00 02000001 213 214schedules a request for listing all available services of all service 215discovery protocols and requests this to be sent to all discovered 216peers (note: this can result in long response frames). The pending 217requests are sent during device discovery (see p2p_find). 218 219Only a single pending wildcard query is supported, but there can be 220multiple pending peer device specific queries (each will be sent in 221sequence whenever the peer is found). 222 223This command returns an identifier for the pending query (e.g., 224"1f77628") that can be used to cancel the request. Directed requests 225will be automatically removed when the specified peer has replied to 226it. 227 228Service Query TLV has following format: 229Length (2 octets, little endian) - length of following data 230Service Protocol Type (1 octet) - see the table below 231Service Transaction ID (1 octet) - nonzero identifier for the TLV 232Query Data (Length - 2 octets of data) - service protocol specific data 233 234Service Protocol Types: 2350 = All service protocols 2361 = Bonjour 2372 = UPnP 2383 = WS-Discovery 2394 = Wi-Fi Display 240 241For UPnP, an alternative command format can be used to specify a 242single query TLV (i.e., a service discovery for a specific UPnP 243service): 244 245p2p_serv_disc_req 00:00:00:00:00:00 upnp <version hex> <ST: from M-SEARCH> 246 247For example: 248 249p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 250 251Additional examples for queries: 252 253# list of all Bonjour services 254p2p_serv_disc_req 00:00:00:00:00:00 02000101 255 256# list of all UPnP services 257p2p_serv_disc_req 00:00:00:00:00:00 02000201 258 259# list of all WS-Discovery services 260p2p_serv_disc_req 00:00:00:00:00:00 02000301 261 262# list of all Bonjour and UPnP services 263p2p_serv_disc_req 00:00:00:00:00:00 0200010102000202 264 265# Apple File Sharing over TCP 266p2p_serv_disc_req 00:00:00:00:00:00 130001010b5f6166706f766572746370c00c000c01 267 268# Bonjour SSTH (supported service type hash) 269p2p_serv_disc_req 00:00:00:00:00:00 05000101000000 270 271# UPnP examples 272p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 ssdp:all 273p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 upnp:rootdevice 274p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:service:ContentDirectory:2 275p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 uuid:6859dede-8574-59ab-9332-123456789012 276p2p_serv_disc_req 00:00:00:00:00:00 upnp 10 urn:schemas-upnp-org:device:InternetGatewayDevice:1 277 278# Wi-Fi Display examples 279# format: wifi-display <list of roles> <list of subelements> 280p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source] 2,3,4,5 281p2p_serv_disc_req 02:01:02:03:04:05 wifi-display [pri-sink] 3 282p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [sec-source] 2 283p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source+sink] 2,3,4,5 284p2p_serv_disc_req 00:00:00:00:00:00 wifi-display [source][pri-sink] 2,3,4,5 285 286p2p_serv_disc_cancel_req <query identifier> 287 288Cancel a pending P2P service discovery request. This command takes a 289single parameter: identifier for the pending query (the value returned 290by p2p_serv_disc_req, e.g., "p2p_serv_disc_cancel_req 1f77628". 291 292p2p_serv_disc_resp 293 294Reply to a service discovery query. This command takes following 295parameters: frequency in MHz, destination address, dialog token, 296response TLV(s). The first three parameters are copied from the 297request event. For example, "p2p_serv_disc_resp 2437 02:40:61:c2:f3:b7 2981 0300000101". This command is used only if external program is used 299to process the request (see p2p_serv_disc_external). 300 301p2p_service_update 302 303Indicate that local services have changed. This is used to increment 304the P2P service indicator value so that peers know when previously 305cached information may have changed. This is only needed when external 306service discovery processing is enabled since the commands to 307pre-configure services for internal processing will increment the 308indicator automatically. 309 310p2p_serv_disc_external <0|1> 311 312Configure external processing of P2P service requests: 0 (default) = 313no external processing of requests (i.e., internal code will process 314each request based on pre-configured services), 1 = external 315processing of requests (external program is responsible for replying 316to service discovery requests with p2p_serv_disc_resp). Please note 317that there is quite strict limit on how quickly the response needs to 318be transmitted, so use of the internal processing is strongly 319recommended. 320 321p2p_service_add bonjour <query hexdump> <RDATA hexdump> 322 323Add a local Bonjour service for internal SD query processing. 324 325Examples: 326 327# AFP Over TCP (PTR) 328p2p_service_add bonjour 0b5f6166706f766572746370c00c000c01 074578616d706c65c027 329# AFP Over TCP (TXT) (RDATA=null) 330p2p_service_add bonjour 076578616d706c650b5f6166706f766572746370c00c001001 00 331 332# IP Printing over TCP (PTR) (RDATA=MyPrinter._ipp._tcp.local.) 333p2p_service_add bonjour 045f697070c00c000c01 094d795072696e746572c027 334# IP Printing over TCP (TXT) (RDATA=txtvers=1,pdl=application/postscript) 335p2p_service_add bonjour 096d797072696e746572045f697070c00c001001 09747874766572733d311a70646c3d6170706c69636174696f6e2f706f7374736372797074 336 337# Supported Service Type Hash (SSTH) 338p2p_service_add bonjour 000000 <32-byte bitfield as hexdump> 339(note: see P2P spec Annex E.4 for information on how to construct the bitfield) 340 341p2p_service_del bonjour <query hexdump> 342 343Remove a local Bonjour service from internal SD query processing. 344 345p2p_service_add upnp <version hex> <service> 346 347Add a local UPnP service for internal SD query processing. 348 349Examples: 350 351p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::upnp:rootdevice 352p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::upnp:rootdevice 353p2p_service_add upnp 10 uuid:1122de4e-8574-59ab-9322-333456789044::urn:schemas-upnp-org:service:ContentDirectory:2 354p2p_service_add upnp 10 uuid:5566d33e-9774-09ab-4822-333456785632::urn:schemas-upnp-org:service:ContentDirectory:2 355p2p_service_add upnp 10 uuid:6859dede-8574-59ab-9332-123456789012::urn:schemas-upnp-org:device:InternetGatewayDevice:1 356 357p2p_service_del upnp <version hex> <service> 358 359Remove a local UPnP service from internal SD query processing. 360 361p2p_service_flush 362 363Remove all local services from internal SD query processing. 364 365Invitation 366 367p2p_invite [persistent=<network id>|group=<group ifname>] [peer=address] 368 [go_dev_addr=address] [freq=<freq in MHz>] [ht40] [pref=<MHz>] 369 370Invite a peer to join a group (e.g., group=wlan1) or to reinvoke a 371persistent group (e.g., persistent=4). If the peer device is the GO of 372the persistent group, the peer parameter is not needed. Otherwise it is 373used to specify which device to invite. go_dev_addr parameter can be 374used to override the GO device address for Invitation Request should 375it be not known for some reason (this should not be needed in most 376cases). When reinvoking a persistent group, the GO device can specify 377the frequency for the group with the freq parameter. When reinvoking a 378persistent group, the P2P client device can use freq parameter to force 379a specific operating channel (or invitation failure if GO rejects that) 380or pref parameter to request a specific channel (while allowing GO to 381select to use another channel, if needed). 382 383Group Operations 384 385(These are used on the group interface.) 386 387wps_pin <any|address> <PIN> 388 389Start WPS PIN method. This allows a single WPS Enrollee to connect to 390the AP/GO. This is used on the GO when a P2P client joins an existing 391group. The second parameter is the address of the Enrollee or a string 392"any" to allow any station to use the entered PIN (which will restrict 393the PIN for one-time-use). PIN is the Enrollee PIN read either from a 394label or display on the P2P Client/WPS Enrollee. 395 396wps_pbc 397 398Start WPS PBC method (i.e., push the button). This allows a single WPS 399Enrollee to connect to the AP/GO. This is used on the GO when a P2P 400client joins an existing group. 401 402p2p_get_passphrase 403 404Get the passphrase for a group (only available when acting as a GO). 405 406p2p_presence_req [<duration> <interval>] [<duration> <interval>] 407 408Send a P2P Presence Request to the GO (this is only available when 409acting as a P2P client). If no duration/interval pairs are given, the 410request indicates that this client has no special needs for GO 411presence. the first parameter pair gives the preferred duration and 412interval values in microseconds. If the second pair is included, that 413indicates which value would be acceptable. 414 415Parameters 416 417p2p_ext_listen [<period> <interval>] 418 419Configure Extended Listen Timing. If the parameters are omitted, this 420feature is disabled. If the parameters are included, Listen State will 421be entered every interval msec for at least period msec. Both values 422have acceptable range of 1-65535 (with interval obviously having to be 423larger than or equal to duration). If the P2P module is not idle at 424the time the Extended Listen Timing timeout occurs, the Listen State 425operation will be skipped. 426 427The configured values will also be advertised to other P2P Devices. The 428received values are available in the p2p_peer command output: 429 430ext_listen_period=100 ext_listen_interval=5000 431 432p2p_set <field> <value> 433 434Change dynamic P2P parameters 435 436p2p_set discoverability <0/1> 437 438Disable/enable advertisement of client discoverability. This is 439enabled by default and this parameter is mainly used to allow testing 440of device discoverability. 441 442p2p_set managed <0/1> 443 444Disable/enable managed P2P Device operations. This is disabled by 445default. 446 447p2p_set listen_channel <1/6/11> 448 449Set P2P Listen channel. This is mainly meant for testing purposes and 450changing the Listen channel during normal operations can result in 451protocol failures. 452 453p2p_set ssid_postfix <postfix> 454 455Set postfix string to be added to the automatically generated P2P SSID 456(DIRECT-<two random characters>). For example, postfix of "-testing" 457could result in the SSID becoming DIRECT-ab-testing. 458 459set <field> <value> 460 461Set global configuration parameters which may also affect P2P 462operations. The format on these parameters is same as is used in 463wpa_supplicant.conf. Only the parameters listen here should be 464changed. Modifying other parameters may result in incorrect behavior 465since not all existing users of the parameters are updated. 466 467set uuid <UUID> 468 469Set WPS UUID (by default, this is generated based on the MAC address). 470 471set device_name <device name> 472 473Set WPS Device Name (also included in some P2P messages). 474 475set manufacturer <manufacturer> 476 477Set WPS Manufacturer. 478 479set model_name <model name> 480 481Set WPS Model Name. 482 483set model_number <model number> 484 485Set WPS Model Number. 486 487set serial_number <serial number> 488 489Set WPS Serial Number. 490 491set device_type <device type> 492 493Set WPS Device Type. 494 495set os_version <OS version> 496 497Set WPS OS Version. 498 499set config_methods <config methods> 500 501Set WPS Configuration Methods. 502 503set sec_device_type <device type> 504 505Add a new Secondary Device Type. 506 507set p2p_go_intent <GO intent> 508 509Set the default P2P GO Intent. Note: This value can be overridden in 510p2p_connect command and as such, there should be no need to change the 511default value here during normal operations. 512 513set p2p_ssid_postfix <P2P SSID postfix> 514 515Set P2P SSID postfix. 516 517set persistent_reconnect <0/1> 518 519Disable/enabled persistent reconnect for reinvocation of persistent 520groups. If enabled, invitations to reinvoke a persistent group will be 521accepted without separate authorization (e.g., user interaction). 522 523set country <two character country code> 524 525Set country code (this is included in some P2P messages). 526 527Status 528 529p2p_peers [discovered] 530 531List P2P Device Addresses of all the P2P peers we know. The optional 532"discovered" parameter filters out the peers that we have not fully 533discovered, i.e., which we have only seen in a received Probe Request 534frame. 535 536p2p_peer <P2P Device Address> 537 538Fetch information about a known P2P peer. 539 540Group Status 541 542(These are used on the group interface.) 543 544status 545 546Show status information (connection state, role, use encryption 547parameters, IP address, etc.). 548 549sta 550 551Show information about an associated station (when acting in AP/GO role). 552 553all_sta 554 555Lists the currently associated stations. 556 557Configuration data 558 559list_networks 560 561Lists the configured networks, including stored information for 562persistent groups. The identifier in this list is used with 563p2p_group_add and p2p_invite to indicate which persistent group is to 564be reinvoked. 565 566remove_network <network id> 567 568Remove a network entry from configuration. 569 570 571wpa_cli action script 572--------------------- 573 574See examples/p2p-action.sh 575 576TODO: describe DHCP/DNS setup 577TODO: cross-connection 578