A few additional decisions have been made while implementing the multi-advertising feature where the mgmt api spec was leaving room for interpretation. These changes are being documented in this patch. --- doc/mgmt-api.txt | 66 +++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 54 insertions(+), 12 deletions(-) diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt index 4b97aad..0ac8267 100644 --- a/doc/mgmt-api.txt +++ b/doc/mgmt-api.txt @@ -305,6 +305,14 @@ Set Powered Command switching the controller off will expire this timeout and disable discoverable. + Settings programmed via Set Advertising and Add/Remove + Advertising while the controller was powered off will be activated + when powering the controller on. + + Switching the controller off will permanently cancel and remove + all configured advertising instances, i.e. advertising instances + are not being remembered across power cycles. + This command generates a Command Complete event on success or a Command Status event on failure. @@ -585,6 +593,10 @@ Set Low Energy Command In case the kernel subsystem does not support Low Energy or the controller does not either, the command will fail regardless. + Disabling LE support will permanently disable and remove all + advertising instances configured with the Add Advertising + command. + This command generates a Command Complete event on success or a Command Status event on failure. @@ -1594,6 +1606,10 @@ Set Advertising Command Using this command will temporarily deactive any configuration made by the Add Advertising command. This command takes precedence. + Once a Set Advertising command with value 0x00 is issued any + previously made configurations via Add/Remove Advertising, including + such changes made while Set Advertising was active, will be re- + enabled, though. A pre-requisite is that LE is already enabled, otherwise this command will return a "rejected" response. @@ -2548,9 +2564,11 @@ Add Advertising Command can be used to switch a Bluetooth Low Energy controller into advertising mode. - Added advertising information with this command will be ignored - when using the Set Advertising command to enable advertising. The - usage of Set Advertising command take precedence over this command. + Added advertising information with this command will be ignored as + long as advertising is enabled via the Set Advertising command. The + usage of the Set Advertising command takes precedence over this + command. Instance information is stored, though, 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. @@ -2593,13 +2611,13 @@ Add Advertising Command broadcaster role. The Duration parameter configures the length of an Instance. The - value is in seconds and a value of 0 indicates an automatic choice - for the Duration. 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. + value is in seconds and a value of 0 indicates a default value + (currently 2 seconds) will be chosen for the Duration. 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 @@ -2611,8 +2629,21 @@ Add Advertising Command When a Timeout is provided, then the Duration substracts from the actual Timeout value of that Instance. For example an Instance - with Timeout of 6 and Duration of 2 will be scheduled exactly 3 - times. Other Instances have no influence on the Timeout. + 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. + + Re-adding an already existing instance (i.e. issuing the Add + Advertising 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 be visible right away, i.e. the previous + configuration will be canceled immediately and the new + one activated. A pre-requisite is that LE is already enabled, otherwise this command will return a "rejected" response. @@ -2645,6 +2676,17 @@ Remove Advertising Command When the Instance parameter is zero, then all previously added advertising Instances will be removed. + Removing advertising information with this command will be ignored + as long as advertising is enabled via the Set Advertising command. + The usage of the Set Advertising command takes precedence over this + command. Changes to Instance information are stored, though, and + will be advertised once advertising via Set Advertising has been + disabled. + + Removing an instance while it is being advertised will immediately + cancel the instance, even when it has been advertised less then its + configured Timeout or Duration. + This command can be used when the controller is not powered and all settings will be programmed once powered. -- 1.9.1 -- To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
