* [PATCH] doc: Add mangement API for service information feature
@ 2015-03-12 19:42 Marcel Holtmann
2015-03-12 21:22 ` Luiz Augusto von Dentz
2015-03-12 22:11 ` Arman Uguray
0 siblings, 2 replies; 3+ messages in thread
From: Marcel Holtmann @ 2015-03-12 19:42 UTC (permalink / raw)
To: linux-bluetooth
---
doc/mgmt-api.txt | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 137 insertions(+)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index d4df8d94208d..af85b3c10ce1 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -2390,6 +2390,114 @@ Read Extended Controller Index List Command
a Command Status event on failure.
+Add Service Information Command
+===============================
+
+ Command Code: 0x003d
+ Controller Index: <controller id>
+ Command Parameters: UUID (16 Octets)
+ Type (1 Octet)
+ Timeout (2 Octets)
+ Data_Len (1 Octet)
+ Data (0-255 Octets)
+ Return Parameters: UUID (16 Octets)
+
+ This command is used to add service information for Bluetooth
+ Low Energy controllers. These information are used when the
+ controller has to advertise its services.
+
+ The Type parameter defines the actions associcated with the
+ provided UUID. The following values are defined:
+
+ 0 Service UUID (opportunistic)
+ 1 Service UUID (required)
+ 2 Service data information
+ 3 Service solicitation using general discoverable mode
+ 4 Service solicitation using limited discoverable mode
+
+ Every UUID can only be provided once and can only be associated
+ with one of these types. It is possible to change the current
+ type, but it means that it will no longer advertised using the
+ previous configured type.
+
+ The Service UUID (type 0 and 1) are advertised using the standard
+ Service UUID advertising data type. The difference is that type 1
+ UUID are mandatory to include and the command will fail in case
+ there is no space in the advertising data. The type 0 will add
+ the UUID and add the UUID if there is space. It is preferred to
+ use type 0 over type 1 to provide the Bluetooth core with maximum
+ flexibility to choose which UUIDs to include.
+
+ The Service data information will include the data information
+ instead of the Service UUID. Since both types include the UUID,
+ it makes no sense to be duplicated. However Service data information
+ is treated the same as type 1 and mandatory. If it does not fit,
+ then the command will return an error.
+
+ For type 0, 1 and 2 the Set Advertising command has to be used
+ to enable advertising in the first place. Adding the Service UUID
+ or Service data will not enable advertising.
+
+ The Service solicitation however will actually enable advertising
+ in general or limited discoverable mode. This means that adding
+ a UUID with type 3 or 4 will cause the Bluetooth core to advertise.
+
+ In case the controller is not configured as connectable, then
+ using type 3 or 4 will return an error. In that sense it behaves
+ similar to Set Discoverable mode. For the Service solicitation,
+ the Timeout parameter can be used to limit the transaction. The
+ Bluetooth core will disable advertising and discoverable mode
+ automatically then.
+
+ The Timeout parameter can also be used for type 0, 1 and 2 in
+ case advertising of a certain UUID should be limited to a certain
+ amount of time. The Timeout paramter value is specified in seconds
+ and a value of 0 disables the timeout handling.
+
+ UUID values configured will stay around when the controller gets
+ powered down and will be automatically programmed back into the
+ controller once it gets powered on. However for UUID values with
+ a timeout, the powering down of the controller result in the
+ timeout triggering and the UUID being removed. The same applies
+ for type 3 and 4 when connectable setting is turned off.
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ This command generates a Command Complete event on success
+ or failure.
+
+ Possible errors: Failed
+ Not Supported
+ Invalid Parameters
+ Invalid Index
+
+
+Remove Service Information Command
+==================================
+
+ Command Code: 0x003e
+ Controller Index: <controller id>
+ Command Parameters: UUID (16 Octets)
+ Return Parameters: UUID (16 Octets)
+
+ This command is used to remove service information from a Bluetooth
+ Low Energy controller previously added by using the Add Service
+ Information command.
+
+ When the UUID parameter is an empty UUID (16 x 0x00), then all
+ previously loaded UUIDs will be removed.
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ This command generates a Command Complete event on success or
+ a Command Status event on failure.
+
+ Possible errors: Invalid Parameters
+ Invalid Index
+
+
Command Complete Event
======================
@@ -3164,3 +3272,32 @@ Extended Index Removed Event
This event will only be used after Read Extended Controller Index
List has been used at least once. If it has not been used, then
Index Removed and Unconfigured Index Removed are send instead.
+
+
+Service Information Added Event
+===============================
+
+ Event Code: 0x0022
+ Controller Index: <controller id>
+ Event Parameters: UUID (16 Octets)
+ Type (1 Octet)
+
+ This event indicates that service information have been added
+ using the Add Service Information command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
+
+
+Service Information Removed Event
+=================================
+
+ Event Code: 0x0023
+ Controller Index: <controller id>
+ Event Parameters: UUID (16 Octets)
+
+ This event indicates that service information have been removed
+ using the Remove Service Information command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
--
2.1.0
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] doc: Add mangement API for service information feature
2015-03-12 19:42 [PATCH] doc: Add mangement API for service information feature Marcel Holtmann
@ 2015-03-12 21:22 ` Luiz Augusto von Dentz
2015-03-12 22:11 ` Arman Uguray
1 sibling, 0 replies; 3+ messages in thread
From: Luiz Augusto von Dentz @ 2015-03-12 21:22 UTC (permalink / raw)
To: Marcel Holtmann; +Cc: linux-bluetooth
Hi Marcel,
On Thu, Mar 12, 2015 at 9:42 PM, Marcel Holtmann <marcel@holtmann.org> wrote:
> ---
> doc/mgmt-api.txt | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 137 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index d4df8d94208d..af85b3c10ce1 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -2390,6 +2390,114 @@ Read Extended Controller Index List Command
> a Command Status event on failure.
>
>
> +Add Service Information Command
> +===============================
> +
> + Command Code: 0x003d
> + Controller Index: <controller id>
> + Command Parameters: UUID (16 Octets)
> + Type (1 Octet)
> + Timeout (2 Octets)
> + Data_Len (1 Octet)
> + Data (0-255 Octets)
> + Return Parameters: UUID (16 Octets)
> +
> + This command is used to add service information for Bluetooth
> + Low Energy controllers. These information are used when the
> + controller has to advertise its services.
> +
> + The Type parameter defines the actions associcated with the
> + provided UUID. The following values are defined:
> +
> + 0 Service UUID (opportunistic)
> + 1 Service UUID (required)
> + 2 Service data information
> + 3 Service solicitation using general discoverable mode
> + 4 Service solicitation using limited discoverable mode
Are you intentionally leaving it out the connectable (peripheral) vs
non-connectable (broadcaster) types, at D-Bus level we were planning
to tight them with advertising data so the kernel could decide what
address to use base on the type e.g. broadcaster we could just use
different addresses for each advertisement if privacy is enabled.
> + Every UUID can only be provided once and can only be associated
> + with one of these types. It is possible to change the current
> + type, but it means that it will no longer advertised using the
> + previous configured type.
> +
> + The Service UUID (type 0 and 1) are advertised using the standard
> + Service UUID advertising data type. The difference is that type 1
> + UUID are mandatory to include and the command will fail in case
> + there is no space in the advertising data. The type 0 will add
> + the UUID and add the UUID if there is space. It is preferred to
> + use type 0 over type 1 to provide the Bluetooth core with maximum
> + flexibility to choose which UUIDs to include.
> +
> + The Service data information will include the data information
> + instead of the Service UUID. Since both types include the UUID,
> + it makes no sense to be duplicated. However Service data information
> + is treated the same as type 1 and mandatory. If it does not fit,
> + then the command will return an error.
> +
> + For type 0, 1 and 2 the Set Advertising command has to be used
> + to enable advertising in the first place. Adding the Service UUID
> + or Service data will not enable advertising.
> +
> + The Service solicitation however will actually enable advertising
> + in general or limited discoverable mode. This means that adding
> + a UUID with type 3 or 4 will cause the Bluetooth core to advertise.
> +
> + In case the controller is not configured as connectable, then
> + using type 3 or 4 will return an error. In that sense it behaves
> + similar to Set Discoverable mode. For the Service solicitation,
> + the Timeout parameter can be used to limit the transaction. The
> + Bluetooth core will disable advertising and discoverable mode
> + automatically then.
> +
> + The Timeout parameter can also be used for type 0, 1 and 2 in
> + case advertising of a certain UUID should be limited to a certain
> + amount of time. The Timeout paramter value is specified in seconds
> + and a value of 0 disables the timeout handling.
> +
> + UUID values configured will stay around when the controller gets
> + powered down and will be automatically programmed back into the
> + controller once it gets powered on. However for UUID values with
> + a timeout, the powering down of the controller result in the
> + timeout triggering and the UUID being removed. The same applies
> + for type 3 and 4 when connectable setting is turned off.
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Failed
> + Not Supported
> + Invalid Parameters
> + Invalid Index
> +
> +
> +Remove Service Information Command
> +==================================
> +
> + Command Code: 0x003e
> + Controller Index: <controller id>
> + Command Parameters: UUID (16 Octets)
> + Return Parameters: UUID (16 Octets)
> +
> + This command is used to remove service information from a Bluetooth
> + Low Energy controller previously added by using the Add Service
> + Information command.
> +
> + When the UUID parameter is an empty UUID (16 x 0x00), then all
> + previously loaded UUIDs will be removed.
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Invalid Parameters
> + Invalid Index
> +
> +
> Command Complete Event
> ======================
>
> @@ -3164,3 +3272,32 @@ Extended Index Removed Event
> This event will only be used after Read Extended Controller Index
> List has been used at least once. If it has not been used, then
> Index Removed and Unconfigured Index Removed are send instead.
> +
> +
> +Service Information Added Event
> +===============================
> +
> + Event Code: 0x0022
> + Controller Index: <controller id>
> + Event Parameters: UUID (16 Octets)
> + Type (1 Octet)
> +
> + This event indicates that service information have been added
> + using the Add Service Information command.
> +
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> +
> +
> +Service Information Removed Event
> +=================================
> +
> + Event Code: 0x0023
> + Controller Index: <controller id>
> + Event Parameters: UUID (16 Octets)
> +
> + This event indicates that service information have been removed
> + using the Remove Service Information command.
> +
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> --
> 2.1.0
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Luiz Augusto von Dentz
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] doc: Add mangement API for service information feature
2015-03-12 19:42 [PATCH] doc: Add mangement API for service information feature Marcel Holtmann
2015-03-12 21:22 ` Luiz Augusto von Dentz
@ 2015-03-12 22:11 ` Arman Uguray
1 sibling, 0 replies; 3+ messages in thread
From: Arman Uguray @ 2015-03-12 22:11 UTC (permalink / raw)
To: Marcel Holtmann; +Cc: BlueZ development
Hi Marcel,
> On Thu, Mar 12, 2015 at 12:42 PM, Marcel Holtmann <marcel@holtmann.org> wrote:
> ---
> doc/mgmt-api.txt | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 137 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index d4df8d94208d..af85b3c10ce1 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -2390,6 +2390,114 @@ Read Extended Controller Index List Command
> a Command Status event on failure.
>
>
> +Add Service Information Command
> +===============================
> +
> + Command Code: 0x003d
> + Controller Index: <controller id>
> + Command Parameters: UUID (16 Octets)
> + Type (1 Octet)
> + Timeout (2 Octets)
> + Data_Len (1 Octet)
> + Data (0-255 Octets)
> + Return Parameters: UUID (16 Octets)
> +
> + This command is used to add service information for Bluetooth
> + Low Energy controllers. These information are used when the
> + controller has to advertise its services.
nit: "...This information is used for the controller to advertise..."
> +
> + The Type parameter defines the actions associcated with the
nit: s/associcated/associated/
> + provided UUID. The following values are defined:
> +
> + 0 Service UUID (opportunistic)
> + 1 Service UUID (required)
> + 2 Service data information
> + 3 Service solicitation using general discoverable mode
> + 4 Service solicitation using limited discoverable mode
> +
> + Every UUID can only be provided once and can only be associated
> + with one of these types. It is possible to change the current
> + type, but it means that it will no longer advertised using the
nit: s/no longer advertised/no longer be advertised/
> + previous configured type.
> +
> + The Service UUID (type 0 and 1) are advertised using the standard
> + Service UUID advertising data type. The difference is that type 1
> + UUID are mandatory to include and the command will fail in case
> + there is no space in the advertising data. The type 0 will add
> + the UUID and add the UUID if there is space. It is preferred to
> + use type 0 over type 1 to provide the Bluetooth core with maximum
> + flexibility to choose which UUIDs to include.
> +
> + The Service data information will include the data information
> + instead of the Service UUID. Since both types include the UUID,
> + it makes no sense to be duplicated. However Service data information
> + is treated the same as type 1 and mandatory. If it does not fit,
> + then the command will return an error.
> +
> + For type 0, 1 and 2 the Set Advertising command has to be used
> + to enable advertising in the first place. Adding the Service UUID
> + or Service data will not enable advertising.
> +
> + The Service solicitation however will actually enable advertising
> + in general or limited discoverable mode. This means that adding
> + a UUID with type 3 or 4 will cause the Bluetooth core to advertise.
> +
> + In case the controller is not configured as connectable, then
> + using type 3 or 4 will return an error. In that sense it behaves
> + similar to Set Discoverable mode. For the Service solicitation,
> + the Timeout parameter can be used to limit the transaction. The
> + Bluetooth core will disable advertising and discoverable mode
> + automatically then.
> +
> + The Timeout parameter can also be used for type 0, 1 and 2 in
> + case advertising of a certain UUID should be limited to a certain
> + amount of time. The Timeout paramter value is specified in seconds
> + and a value of 0 disables the timeout handling.
> +
> + UUID values configured will stay around when the controller gets
> + powered down and will be automatically programmed back into the
> + controller once it gets powered on. However for UUID values with
> + a timeout, the powering down of the controller result in the
> + timeout triggering and the UUID being removed. The same applies
> + for type 3 and 4 when connectable setting is turned off.
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + This command generates a Command Complete event on success
> + or failure.
> +
> + Possible errors: Failed
> + Not Supported
> + Invalid Parameters
> + Invalid Index
> +
> +
> +Remove Service Information Command
> +==================================
> +
> + Command Code: 0x003e
> + Controller Index: <controller id>
> + Command Parameters: UUID (16 Octets)
> + Return Parameters: UUID (16 Octets)
> +
> + This command is used to remove service information from a Bluetooth
> + Low Energy controller previously added by using the Add Service
> + Information command.
> +
> + When the UUID parameter is an empty UUID (16 x 0x00), then all
> + previously loaded UUIDs will be removed.
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + This command generates a Command Complete event on success or
> + a Command Status event on failure.
> +
> + Possible errors: Invalid Parameters
> + Invalid Index
> +
> +
> Command Complete Event
> ======================
>
> @@ -3164,3 +3272,32 @@ Extended Index Removed Event
> This event will only be used after Read Extended Controller Index
> List has been used at least once. If it has not been used, then
> Index Removed and Unconfigured Index Removed are send instead.
> +
> +
> +Service Information Added Event
> +===============================
> +
> + Event Code: 0x0022
> + Controller Index: <controller id>
> + Event Parameters: UUID (16 Octets)
> + Type (1 Octet)
> +
> + This event indicates that service information have been added
nit: s/have been/has been/
> + using the Add Service Information command.
> +
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> +
> +
> +Service Information Removed Event
> +=================================
> +
> + Event Code: 0x0023
> + Controller Index: <controller id>
> + Event Parameters: UUID (16 Octets)
> +
> + This event indicates that service information have been removed
> + using the Remove Service Information command.
> +
nit: s/have been/has been/
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> --
> 2.1.0
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-bluetooth" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at http://vger.kernel.org/majordomo-info.html
Thanks,
Arman
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2015-03-12 22:11 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2015-03-12 19:42 [PATCH] doc: Add mangement API for service information feature Marcel Holtmann
2015-03-12 21:22 ` Luiz Augusto von Dentz
2015-03-12 22:11 ` Arman Uguray
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.