| Message ID | 20200916162155.Bluez.10.If15d3d09724ded2bcc7240d29f6888f2ad12e723@changeid (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Bluetooth: Add new MGMT interface for advertising add | expand |
Hi Daniel, On Wed, Sep 16, 2020 at 4:26 PM Daniel Winkler <danielwinkler@google.com> wrote: > > This patch adds the following to mgmt-api: > - Add Extended Advertising Parameters Command > - Add Extended Advertising Data Command > - Read Controller Capabilities Command > - Advertisement Tx Power Selected Event > > Reviewed-by: Sonny Sasaka <sonnysasaka@chromium.org> > --- > > doc/mgmt-api.txt | 243 +++++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 243 insertions(+) > > diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt > index ca0d38469..6e8914611 100644 > --- a/doc/mgmt-api.txt > +++ b/doc/mgmt-api.txt > @@ -3574,6 +3574,235 @@ Remove Advertisement Monitor Command > Busy > > > +Add Extended Advertising Parameters Command > +======================= > + > + Command Code: 0x0054 > + Controller Index: <controller id> > + Command Parameters: Instance (1 Octet) > + Flags (4 Octets) > + Params (2 Octets) > + Duration (2 Octets) > + Timeout (2 Octets) > + MinInterval (4 Octets) > + MaxInterval (4 Octets) > + TxPower (1 Octet) > + Return Parameters: Instance (1 Octet) > + There seems to be an extra empty like here. > + This command is used to configure the parameters for Bluetooth Low > + Energy advertising instance. This command is expected to be followed > + by an Add Extended Advertising Data command to complete and enable > + the advertising instance. > + > + Added advertising information with this command will not be visible > + immediately if advertising is enabled via the Set Advertising > + command. The usage of the Set Advertising command takes precedence > + over this command. Instance information is stored and will be > + advertised once advertising via Set Advertising has been disabled. > + > + The Instance identifier is a value between 1 and the number of > + supported instances. The value 0 is reserved. > + > + With the Flags value the type of advertising is controlled and > + the following flags are defined: > + > + 0 Switch into Connectable mode > + 1 Advertise as Discoverable > + 2 Advertise as Limited Discoverable > + 3 Add Flags field to Adv_Data > + 4 Add TX Power field to Adv_Data > + 5 Add Appearance field to Scan_Rsp > + 6 Add Local Name in Scan_Rsp > + 7 Secondary Channel with LE 1M > + 8 Secondary Channel with LE 2M > + 9 Secondary Channel with LE Coded > + > + When the connectable flag is set, then the controller will use > + undirected connectable advertising. The value of the connectable > + setting can be overwritten this way. This is useful to switch a > + controller into connectable mode only for LE operation. This is > + similar to the mode 0x02 from the Set Advertising command. > + > + When the connectable flag is not set, then the controller will > + use advertising based on the connectable setting. When using > + non-connectable or scannable advertising, the controller will > + be programmed with a non-resolvable random address. When the > + system is connectable, then the identity address or resolvable > + private address will be used. > + > + Using the connectable flag is useful for peripheral mode support > + where BR/EDR (and/or LE) is controlled by Add Device. This allows > + making the peripheral connectable without having to interfere > + with the global connectable setting. > + > + Secondary channel flags can be used to advertise in secondary > + channel with the corresponding PHYs. These flag bits are mutually > + exclusive and setting multiple will result in Invalid Parameter > + error. Choosing either LE 1M or LE 2M will result in using > + extended advertising on the primary channel with LE 1M and the > + respectively LE 1M or LE 2M on the secondary channel. Choosing > + LE Coded will result in using extended advertising on the primary > + and secondary channels with LE Coded. Choosing none of these flags > + will result in legacy advertising. > + > + To allow future parameters to be optionally extended in this structure, > + the Params member is used to specify which of the structure fields were > + purposefully set by the caller. Unspecified parameters will be given > + sensible defaults by the kernel before the advertisement is registered. > + The Params bit field uses the following bit to parameter relationship: > + > + 0 The Duration parameter should be used > + 1 The Timeout parameter should be used > + 2 The Interval parameters should be used > + 3 The Tx Power parameter should be used > + > + The Duration parameter configures the length of an Instance. The > + value is in seconds. The default is 2 seconds. > + > + If only one advertising Instance has been added, then the Duration > + value will be ignored. It only applies for the case where multiple > + Instances are configured. In that case every Instance will be > + available for the Duration time and after that it switches to > + the next one. This is a simple round-robin based approach. > + > + The Timeout parameter configures the life-time of an Instance. In > + case the value 0 is used it indicates no expiration time. If a > + timeout value is provided, then the advertising Instance will be > + automatically removed when the timeout passes. The value for the > + timeout is in seconds. Powering down a controller will invalidate > + all advertising Instances and it is not possible to add a new > + Instance with a timeout when the controller is powered down. > + > + When a Timeout is provided, then the Duration subtracts from > + the actual Timeout value of that Instance. For example an Instance > + with Timeout of 5 and Duration of 2 will be scheduled exactly 3 > + times, twice with 2 seconds and once with one second. Other > + Instances have no influence on the Timeout. > + > + MinInterval and MaxInterval define the minimum and maximum advertising > + intervals, with units as number of .625ms advertising slots. The Max > + interval is expected to be greater than or equal to the Min interval, > + and both must have values in the range [0x000020, 0xFFFFFF]. If either > + condition is not met, the registration will fail. > + > + The provided Tx Power parameter will only be used if the controller > + supports it, which can be determined by the presence of the > + CanSetTxPower member of the Read Advertising Features command. > + > + The acceptable range for requested Tx Power is defined in the spec > + (Version 5.2 | Vol 4, Part E, page 2585) to be [-127, +20] dBm, and the > + controller will select a power value up to the requested one. The > + transmission power selected by the controller is not guaranteed > + to match the requested one, but the caller can determine the power > + chosen by the controller by listening for the Tx Power Selected MGMT > + event that follows this command. If the requested Tx Power is outside > + the valid range, the registration will fail. > + > + Re-adding an already existing instance (i.e. issuing the Add Extended > + Advertising Parameters command with an Instance identifier of an > + existing instance) will update that instance's configuration. > + > + An instance being added or changed while another instance is > + being advertised will not be visible immediately but only when > + the new/changed instance is being scheduled by the round robin > + advertising algorithm. > + > + Changes to an instance that is currently being advertised will > + cancel that instance and switch to the next instance. The changes > + will be visible the next time the instance is scheduled for > + advertising. In case a single instance is active, this means > + that changes will be visible right away. > + > + LE must already be enabled, and the controller must be powered, > + otherwise a "rejected" status will be returned. > + > + This command generates a Command Complete event on success or a > + Command Status event on failure. > + > + Possible errors: Failed > + Rejected > + Not Supported > + Invalid Parameters > + Busy > + > + > +Add Extended Advertising Data Command > +======================= > + > + Command Code: 0x0055 > + Controller Index: <controller id> > + Command Parameters: Instance (1 Octet) > + Advertising Data Length (1 Octet) > + Scan Response Length (1 Octet) > + Advertising Data (0-255 Octets) > + Scan Response (0-255 Octets) > + Return Parameters: Instance (1 Octet) > + > + The Add Extended Advertising Data command is used to update the > + advertising data of an existing advertising instance known to the > + kernel. It is expected to be called after an Add Extended Advertising > + Parameters command, as part of the advertisement registration > + process. > + > + If extended advertising is available, this call will initiate HCI > + commands to set the instance's advertising data, set scan response > + data, and then enable the instance. If extended advertising is > + unavailable, the advertising instance structure maintained in kernel > + will have its advertising data and scan response updated, and the > + instance will either be scheduled immediately or left in the queue > + for later advertisement as part of round-robin advertisement rotation > + in software. > + > + If Scan_Rsp_Len is zero and the flags defined in Add Extended > + Advertising Parameters command do not have connectable flag set and > + the global connectable setting is off, then non-connectable > + advertising is used. If Scan_Rsp_Len is larger than zero and > + connectable flag is not set and the global advertising is off, > + then scannable advertising is used. This small difference is > + supported to provide less air traffic for devices implementing > + broadcaster role. > + > + If the Instance provided does not match a known instance, or if the > + provided advertising data or scan response are in an unrecognized > + format, an "Invalid Parameters" status will be returned. > + > + If a "Set LE" or Advertising command is still in progress, a "Busy" > + status will be returned. > + > + If the controller is not powered, a "rejected" status will be returned. > + > + This command generates a Command Complete event on success or a > + Command Status event on failure. > + > + Possible errors: Failed > + Rejected > + Invalid Parameters > + Busy > + > + > +Read Controller Capabilities Command > +==================================== > + > + Command Code: 0x0056 > + Controller Index: <controller id> > + Command Parameters: > + Return Parameters: Parameter1 { > + Capability_Tag (2 Octet) > + Value_Length (1 Octet) > + Value (0-255 Octets) > + } > + Parameter2 { } > + ... > + > + This command is used to read a list of controller capabilities. > + > + Currently defined Capability_Tag values are: > + > + 0x0000 Minimum Supported LE Tx Power (dBm) > + 0x0001 Maximum Supported LE Tx Power (dBm) > + > + > Command Complete Event > ====================== > > @@ -4577,3 +4806,17 @@ Advertisement Monitor Removed Event > > The event will only be sent to management sockets other than the > one through which the command was sent. > + > + > +Advertisement Tx Power Selected Event > +=================================== > + > + Event Code: 0x002f > + Controller Index: <controller id> > + Event Parameters: Instance (1 Octet) > + TxPower (1 Octet) > + > + This event indicates that the controller selected a transmission > + power for an advertising instance. The event is emitted on platforms > + that support extended advertising after an Add Extended Advertising > + Parameters command is submitted. > \ No newline at end of file > -- > 2.28.0.618.gf4bc123cb7-goog I see you had the documentation at the end, this should probably go in the beginning so we can agree on the API first.
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt index ca0d38469..6e8914611 100644 --- a/doc/mgmt-api.txt +++ b/doc/mgmt-api.txt @@ -3574,6 +3574,235 @@ Remove Advertisement Monitor Command Busy +Add Extended Advertising Parameters Command +======================= + + Command Code: 0x0054 + Controller Index: <controller id> + Command Parameters: Instance (1 Octet) + Flags (4 Octets) + Params (2 Octets) + Duration (2 Octets) + Timeout (2 Octets) + MinInterval (4 Octets) + MaxInterval (4 Octets) + TxPower (1 Octet) + Return Parameters: Instance (1 Octet) + + + This command is used to configure the parameters for Bluetooth Low + Energy advertising instance. This command is expected to be followed + by an Add Extended Advertising Data command to complete and enable + the advertising instance. + + Added advertising information with this command will not be visible + immediately if advertising is enabled via the Set Advertising + command. The usage of the Set Advertising command takes precedence + over this command. Instance information is stored and will be + advertised once advertising via Set Advertising has been disabled. + + The Instance identifier is a value between 1 and the number of + supported instances. The value 0 is reserved. + + With the Flags value the type of advertising is controlled and + the following flags are defined: + + 0 Switch into Connectable mode + 1 Advertise as Discoverable + 2 Advertise as Limited Discoverable + 3 Add Flags field to Adv_Data + 4 Add TX Power field to Adv_Data + 5 Add Appearance field to Scan_Rsp + 6 Add Local Name in Scan_Rsp + 7 Secondary Channel with LE 1M + 8 Secondary Channel with LE 2M + 9 Secondary Channel with LE Coded + + When the connectable flag is set, then the controller will use + undirected connectable advertising. The value of the connectable + setting can be overwritten this way. This is useful to switch a + controller into connectable mode only for LE operation. This is + similar to the mode 0x02 from the Set Advertising command. + + When the connectable flag is not set, then the controller will + use advertising based on the connectable setting. When using + non-connectable or scannable advertising, the controller will + be programmed with a non-resolvable random address. When the + system is connectable, then the identity address or resolvable + private address will be used. + + Using the connectable flag is useful for peripheral mode support + where BR/EDR (and/or LE) is controlled by Add Device. This allows + making the peripheral connectable without having to interfere + with the global connectable setting. + + Secondary channel flags can be used to advertise in secondary + channel with the corresponding PHYs. These flag bits are mutually + exclusive and setting multiple will result in Invalid Parameter + error. Choosing either LE 1M or LE 2M will result in using + extended advertising on the primary channel with LE 1M and the + respectively LE 1M or LE 2M on the secondary channel. Choosing + LE Coded will result in using extended advertising on the primary + and secondary channels with LE Coded. Choosing none of these flags + will result in legacy advertising. + + To allow future parameters to be optionally extended in this structure, + the Params member is used to specify which of the structure fields were + purposefully set by the caller. Unspecified parameters will be given + sensible defaults by the kernel before the advertisement is registered. + The Params bit field uses the following bit to parameter relationship: + + 0 The Duration parameter should be used + 1 The Timeout parameter should be used + 2 The Interval parameters should be used + 3 The Tx Power parameter should be used + + The Duration parameter configures the length of an Instance. The + value is in seconds. The default is 2 seconds. + + If only one advertising Instance has been added, then the Duration + value will be ignored. It only applies for the case where multiple + Instances are configured. In that case every Instance will be + available for the Duration time and after that it switches to + the next one. This is a simple round-robin based approach. + + The Timeout parameter configures the life-time of an Instance. In + case the value 0 is used it indicates no expiration time. If a + timeout value is provided, then the advertising Instance will be + automatically removed when the timeout passes. The value for the + timeout is in seconds. Powering down a controller will invalidate + all advertising Instances and it is not possible to add a new + Instance with a timeout when the controller is powered down. + + When a Timeout is provided, then the Duration subtracts from + the actual Timeout value of that Instance. For example an Instance + with Timeout of 5 and Duration of 2 will be scheduled exactly 3 + times, twice with 2 seconds and once with one second. Other + Instances have no influence on the Timeout. + + MinInterval and MaxInterval define the minimum and maximum advertising + intervals, with units as number of .625ms advertising slots. The Max + interval is expected to be greater than or equal to the Min interval, + and both must have values in the range [0x000020, 0xFFFFFF]. If either + condition is not met, the registration will fail. + + The provided Tx Power parameter will only be used if the controller + supports it, which can be determined by the presence of the + CanSetTxPower member of the Read Advertising Features command. + + The acceptable range for requested Tx Power is defined in the spec + (Version 5.2 | Vol 4, Part E, page 2585) to be [-127, +20] dBm, and the + controller will select a power value up to the requested one. The + transmission power selected by the controller is not guaranteed + to match the requested one, but the caller can determine the power + chosen by the controller by listening for the Tx Power Selected MGMT + event that follows this command. If the requested Tx Power is outside + the valid range, the registration will fail. + + Re-adding an already existing instance (i.e. issuing the Add Extended + Advertising Parameters command with an Instance identifier of an + existing instance) will update that instance's configuration. + + An instance being added or changed while another instance is + being advertised will not be visible immediately but only when + the new/changed instance is being scheduled by the round robin + advertising algorithm. + + Changes to an instance that is currently being advertised will + cancel that instance and switch to the next instance. The changes + will be visible the next time the instance is scheduled for + advertising. In case a single instance is active, this means + that changes will be visible right away. + + LE must already be enabled, and the controller must be powered, + otherwise a "rejected" status will be returned. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Failed + Rejected + Not Supported + Invalid Parameters + Busy + + +Add Extended Advertising Data Command +======================= + + Command Code: 0x0055 + Controller Index: <controller id> + Command Parameters: Instance (1 Octet) + Advertising Data Length (1 Octet) + Scan Response Length (1 Octet) + Advertising Data (0-255 Octets) + Scan Response (0-255 Octets) + Return Parameters: Instance (1 Octet) + + The Add Extended Advertising Data command is used to update the + advertising data of an existing advertising instance known to the + kernel. It is expected to be called after an Add Extended Advertising + Parameters command, as part of the advertisement registration + process. + + If extended advertising is available, this call will initiate HCI + commands to set the instance's advertising data, set scan response + data, and then enable the instance. If extended advertising is + unavailable, the advertising instance structure maintained in kernel + will have its advertising data and scan response updated, and the + instance will either be scheduled immediately or left in the queue + for later advertisement as part of round-robin advertisement rotation + in software. + + If Scan_Rsp_Len is zero and the flags defined in Add Extended + Advertising Parameters command do not have connectable flag set and + the global connectable setting is off, then non-connectable + advertising is used. If Scan_Rsp_Len is larger than zero and + connectable flag is not set and the global advertising is off, + then scannable advertising is used. This small difference is + supported to provide less air traffic for devices implementing + broadcaster role. + + If the Instance provided does not match a known instance, or if the + provided advertising data or scan response are in an unrecognized + format, an "Invalid Parameters" status will be returned. + + If a "Set LE" or Advertising command is still in progress, a "Busy" + status will be returned. + + If the controller is not powered, a "rejected" status will be returned. + + This command generates a Command Complete event on success or a + Command Status event on failure. + + Possible errors: Failed + Rejected + Invalid Parameters + Busy + + +Read Controller Capabilities Command +==================================== + + Command Code: 0x0056 + Controller Index: <controller id> + Command Parameters: + Return Parameters: Parameter1 { + Capability_Tag (2 Octet) + Value_Length (1 Octet) + Value (0-255 Octets) + } + Parameter2 { } + ... + + This command is used to read a list of controller capabilities. + + Currently defined Capability_Tag values are: + + 0x0000 Minimum Supported LE Tx Power (dBm) + 0x0001 Maximum Supported LE Tx Power (dBm) + + Command Complete Event ====================== @@ -4577,3 +4806,17 @@ Advertisement Monitor Removed Event The event will only be sent to management sockets other than the one through which the command was sent. + + +Advertisement Tx Power Selected Event +=================================== + + Event Code: 0x002f + Controller Index: <controller id> + Event Parameters: Instance (1 Octet) + TxPower (1 Octet) + + This event indicates that the controller selected a transmission + power for an advertising instance. The event is emitted on platforms + that support extended advertising after an Add Extended Advertising + Parameters command is submitted. \ No newline at end of file
This patch adds the following to mgmt-api: - Add Extended Advertising Parameters Command - Add Extended Advertising Data Command - Read Controller Capabilities Command - Advertisement Tx Power Selected Event Reviewed-by: Sonny Sasaka <sonnysasaka@chromium.org> --- doc/mgmt-api.txt | 243 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+)