-
Version: v1.0
-
Version Date: 2023-06-13
-
Prepared By: Medical Devices Working Group
Version History
|
Version Number |
Date |
Comments |
|---|---|---|
|
v1.0 |
2023-06-13 |
Adopted by the Bluetooth SIG Board of Directors. |
Acknowledgments
|
Name |
Company |
|---|---|
|
Erik Moll |
Koninklijke Philips N.V. |
|
Brian Reinhold |
Lamprey Networks |
Use of this specification is your acknowledgement that you agree to and will comply with the following notices and disclaimers. You are advised to seek appropriate legal, engineering, and other professional advice regarding the use, interpretation, and effect of this specification.
Use of Bluetooth specifications by members of Bluetooth SIG is governed by the membership and other related agreements between Bluetooth SIG and its members, including those agreements posted on Bluetooth SIG’s website located at www.bluetooth.com. Any use of this specification by a member that is not in compliance with the applicable membership and other related agreements is prohibited and, among other things, may result in (i) termination of the applicable agreements and (ii) liability for infringement of the intellectual property rights of Bluetooth SIG and its members. This specification may provide options, because, for example, some products do not implement every portion of the specification. All content within the specification, including notes, appendices, figures, tables, message sequence charts, examples, sample data, and each option identified is intended to be within the bounds of the Scope as defined in the Bluetooth Patent/Copyright License Agreement (“PCLA”). Also, the identification of options for implementing a portion of the specification is intended to provide design flexibility without establishing, for purposes of the PCLA, that any of these options is a “technically reasonable non-infringing alternative.”
Use of this specification by anyone who is not a member of Bluetooth SIG is prohibited and is an infringement of the intellectual property rights of Bluetooth SIG and its members. The furnishing of this specification does not grant any license to any intellectual property of Bluetooth SIG or its members. THIS SPECIFICATION IS PROVIDED “AS IS” AND BLUETOOTH SIG, ITS MEMBERS AND THEIR AFFILIATES MAKE NO REPRESENTATIONS OR WARRANTIES AND DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING ANY WARRANTIES OF MERCHANTABILITY, TITLE, NON-INFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR THAT THE CONTENT OF THIS SPECIFICATION IS FREE OF ERRORS. For the avoidance of doubt, Bluetooth SIG has not made any search or investigation as to third parties that may claim rights in or to any specifications or any intellectual property that may be required to implement any specifications and it disclaims any obligation or duty to do so.
TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, BLUETOOTH SIG, ITS MEMBERS AND THEIR AFFILIATES DISCLAIM ALL LIABILITY ARISING OUT OF OR RELATING TO USE OF THIS SPECIFICATION AND ANY INFORMATION CONTAINED IN THIS SPECIFICATION, INCLUDING LOST REVENUE, PROFITS, DATA OR PROGRAMS, OR BUSINESS INTERRUPTION, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, AND EVEN IF BLUETOOTH SIG, ITS MEMBERS OR THEIR AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF THE DAMAGES.
Products equipped with Bluetooth wireless technology ("Bluetooth Products") and their combination, operation, use, implementation, and distribution may be subject to regulatory controls under the laws and regulations of numerous countries that regulate products that use wireless non-licensed spectrum. Examples include airline regulations, telecommunications regulations, technology transfer controls, and health and safety regulations. You are solely responsible for complying with all applicable laws and regulations and for obtaining any and all required authorizations, permits, or licenses in connection with your use of this specification and development, manufacture, and distribution of Bluetooth Products. Nothing in this specification provides any information or assistance in connection with complying with applicable laws or regulations or obtaining required authorizations, permits, or licenses.
Bluetooth SIG is not required to adopt any specification or portion thereof. If this specification is not the final version adopted by Bluetooth SIG’s Board of Directors, it may not be adopted. Any specification adopted by Bluetooth SIG’s Board of Directors may be withdrawn, replaced, or modified at any time. Bluetooth SIG reserves the right to change or alter final specifications in accordance with its membership and operating agreements.
Copyright © 2022–2023. All copyrights in the Bluetooth Specifications themselves are owned by Apple Inc., Ericsson AB, Intel Corporation, Lenovo (Singapore) Pte. Ltd., Microsoft Corporation, Nokia Corporation, and Toshiba Corporation. The Bluetooth word mark and logos are owned by Bluetooth SIG, Inc. Other third-party brands and names are the property of their respective owners.
1. Introduction
The Elapsed Time Service (ETS) specification defines a GATT service that can be used by personal health devices and other devices that need to keep track of time. The purpose of ETS is to be usable beyond the healthcare domain and to provide:
-
A simple time format of a device clock by using a time value that is a counter of time units.
-
Time stamps that are understandable stand-alone by having sufficient metadata.
ETS includes one characteristic that reports the current time, status, and capability of the server’s clock. The Current Elapsed Time characteristic supports reading, indicating, and writing (optionally when the server allows a client to set the clock). The client can use a write action to set the current time of the sensor.
The time format can be used for time stamps and comes with sufficient metadata on the status of the clock to be fully understood by clients without needing further information from the server.
1.1. Language
1.1.1. Language conventions
In the development of a specification, the Bluetooth SIG has established the following conventions for use of the terms “shall”, “shall not”, “should”, “should not”, “may”, “must”, and “can”. In this Bluetooth specification, the terms in Table 1.1 have the specific meanings given in that table, irrespective of other meanings that exist.
|
Term |
Definition |
|---|---|
|
shall |
—used to express what is required by the specification and is to be implemented exactly as written without deviation |
|
shall not |
—used to express what is forbidden by the specification |
|
should |
—used to express what is recommended by the specification without forbidding anything |
|
should not |
—used to indicate that something is discouraged but not forbidden by the specification |
|
may |
—used to indicate something that is permissible within the limits of the specification |
|
must |
—used to indicate either:
|
|
can |
—used to express a statement of possibility or capability |
1.1.1.1. Implementation alternatives
When specification content indicates that there are multiple alternatives to satisfy specification requirements, if one alternative is explained or illustrated in an example it is not intended to limit other alternatives that the specification requirements permit.
1.1.1.2. Discrepancies
It is the goal of Bluetooth SIG that specifications are clear, unambiguous, and do not contain discrepancies. However, members can report any perceived discrepancy by filing an erratum and can request a test case waiver as appropriate.
1.1.2. Reserved for Future Use
Where a field in a packet, Protocol Data Unit (PDU), or other data structure is described as "Reserved for Future Use" (irrespective of whether in uppercase or lowercase), the device creating the structure shall set its value to zero unless otherwise specified. Any device receiving or interpreting the structure shall ignore that field; in particular, it shall not reject the structure because of the value of the field.
Where a field, parameter, or other variable object can take a range of values, and some values are described as "Reserved for Future Use," a device sending the object shall not set the object to those values. A device receiving an object with such a value should reject it, and any data structure containing it, as being erroneous; however, this does not apply in a context where the object is described as being ignored or it is specified to ignore unrecognized values.
When a field value is a bit field, unassigned bits can be marked as Reserved for Future Use and shall be set to 0. Implementations that receive a message that contains a Reserved for Future Use bit that is set to 1 shall process the message as if that bit was set to 0, except where specified otherwise.
The acronym RFU is equivalent to Reserved for Future Use.
1.1.3. Prohibited
When a field value is an enumeration, unassigned values can be marked as “Prohibited.” These values shall never be used by an implementation, and any message received that includes a Prohibited value shall be ignored and shall not be processed and shall not be responded to.
Where a field, parameter, or other variable object can take a range of values, and some values are described as “Prohibited,” devices shall not set the object to any of those Prohibited values. A device receiving an object with such a value should reject it, and any data structure containing it, as being erroneous.
“Prohibited” is never abbreviated.
1.2. Table requirements
Requirements in tables in this document are defined as "Mandatory" (M), "Optional" (O), "Excluded" (X), “Not Applicable” (N/A), or "Conditional" (C.n). Conditional statements (C.n) are listed directly below the table in which they appear.
1.3. Conformance
Each capability of this specification shall be supported in the specified manner. This specification may provide options for design flexibility, because, for example, some products do not implement every portion of the specification. For each implementation option that is supported, it shall be supported as specified.
1.4. Byte transmission order
All characteristics used with this service shall be transmitted with the least significant octet (LSO) first (i.e., little endian). Where the format is described in tables in this document, the LSO is the first octet in the topmost field of the table; the most significant octet (MSO) is the last octet in the bottommost field of the table. Where characteristics are defined in the GATT Specification Supplement (GSS), see Section 2.2 in GSS [3].
2. Service
2.1. Service dependencies
ETS does not depend on other services.
2.2. Bluetooth Core Specification release compatibility
This specification is compatible with Bluetooth Core Specification v4.2 or later [1] that includes the Generic Attribute Profile (GATT).
2.3. Transport dependencies
There are no transport-related dependencies.
2.4. Attribute Protocol Application error codes
This service references Common Profile and Service Error Codes that are defined in Part B, Section 1 of the Core Specification Supplement (CSS) [2]. This service also defines Attribute Protocol Application error codes. Table 2.1: lists the set of error codes used in this service.
|
Name |
Error Code |
Description |
|---|---|---|
|
Time Source Quality Too Low |
0x80 |
Application error code |
|
Incorrect Time Format |
0x81 |
Application error code |
|
Out of Range |
0xFF |
Common profile error code defined in CSS [2] |
2.5. GATT sub-procedure requirements
Requirements in this section represent a minimum set of requirements for a server. Other GATT sub-procedures may be used if supported by both the client and the server.
Table 2.2: summarizes additional GATT sub-procedure requirements beyond those required by all GATT servers.
|
GATT sub-procedure |
Requirements |
|---|---|
|
Characteristic Value Indication |
M |
|
Read Characteristic Descriptors |
M |
|
Write Characteristic Descriptors |
M |
|
Write Characteristic Value |
C.1 |
- C.1:
-
Mandatory if the Current Elapsed Time characteristic can be written.
2.6. Declaration
The service universally unique identifier (UUID) shall be set to «Elapsed Time Service» as defined in [4].
ETS should be instantiated as a «Primary Service».
ETS should be instantiated only once in a device.
2.7. Behavior
ETS contains one characteristic that can be used to keep track of the current time of a server. The client can read the Current Elapsed Time characteristic to obtain the server’s current time. Indications of this characteristic are used by the server to inform clients of changes to the current time of the server.
A client can also write to the Current Elapsed Time characteristic to set the time on the server, when supported by the server.
3. Service characteristics
This section defines the characteristic and descriptor requirements. Where a characteristic can be indicated or notified, a Client Characteristic Configuration descriptor must be included in that characteristic as required by [1].
|
Characteristic Name |
Requirement |
Mandatory Properties |
Optional Properties |
Security Permissions |
|---|---|---|---|---|
|
Current Elapsed Time (see Section 3.1) |
M |
Read, Indicate |
Write |
none |
3.1. Current Elapsed Time
The Current Elapsed Time characteristic informs clients of the current time and the capabilities of an Elapsed Time Server’s clock. A client can update the current time of the server by writing to the Current Elapsed Time characteristic.
3.1.1. Characteristic format
The format of the Current Elapsed Time characteristic is shown in Table 3.2: .
|
Field |
Requirement |
Data Type |
Size (in octets) |
Description |
|---|---|---|---|---|
|
Elapsed Time |
M |
struct |
9 |
The field contains the current time of the server (see Section 3.1.1.1). |
|
Clock Status |
C.1 |
struct |
1 |
The status of the server’s clock (see Section 3.1.1.2). |
|
Clock Capabilities |
C.1 |
struct |
1 |
The server’s clock capabilities (see Section 3.1.1.3). |
- C.1:
-
Mandatory when the characteristic is read or indicated by the server, otherwise Excluded when written by a client.
3.1.1.1. Elapsed Time
When the Current Elapsed Time characteristic is read, the Elapsed Time field reports the server’s current time. When written, the Elapsed Time field contains the time to be set as the current time on the server. The format of the Elapsed Time field is defined in GSS [3]. Some examples of Elapsed Time values are given in Appendix A.
3.1.1.2. Clock Status
Table 3.3: defines the Clock Status field.
|
Bit # |
Clock Status flag |
Description |
|---|---|---|
|
0 |
Clock needs to be set |
Indicates that the server wants the clock to be set. This does not require the Current Elapsed Time to be writable by the client. The clock can, for example, only be set via the user interface (UI) of the server or by a specific other client. |
|
1-7 |
Clock Status flags - RFU |
Reserved for Future Use |
3.1.1.3. Clock Capabilities
Table 3.4: defines the Clock Capabilities field.
|
Bit # |
Clock Capabilities flag |
Description |
|---|---|---|
|
0 |
Clock applies DST rules |
Clock autonomously updates DST offset |
|
1 |
Clock manages TZ changes |
Clock autonomously updates TZ offset |
|
2-7 |
Clock Capabilities flags - RFU |
Reserved for Future Use |
3.1.2. Characteristic behavior
3.1.2.1. Reading time
A client can understand the server’s time and clock capabilities by reading the Current Elapsed Time characteristic. The flags in the Elapsed Time field tell the client which type of time and which resolution the server supports. The following types of time are supported in various resolutions:
-
Coordinated Universal Time (UTC) time, with or without TZ/DST offset
-
Local time, with or without TZ/DST offset
-
Tick counter
The type of time a server supports, the TZ/DST offset support, and the time resolution are static.
The starting point for the Elapsed Time field for UTC or local time is 2000-01-01 00:00:00 as defined in GSS. For a tick counter, the starting point is implementation-dependent.
When reading the Current Elapsed Time characteristic, the Time Stamp Is From The Current Timeline flag in the Elapsed Time field is set to a value of 1. When using the Elapsed Time value as a time stamp to record an event, the Time Stamp Is From The Current Timeline flag may be set to a value of 0 when there has been a discontinuity in the timeline of the clock since the time was recorded. Examples of discontinuities in the timeline include a reset of the clock by a battery fault or a user setting the clock from the user interface (UI) of a device. In such situations, there is no relation between the current time as reported by the clock and the recorded Time value.
3.1.2.2. Reporting time changes
When the ETS server reconnects to a bonded client and when the current time has changed other than by natural progression, the ETS server shall send an indication of the Current Elapsed Time characteristic to the bonded client to facilitate a proper understanding of the server’s clock.
When the ETS server is connected to a client and the current time changes other than by natural progression, the ETS server shall send an indication of the Current Elapsed Time characteristic to the client. When the server changes its time after a write by a client to the Current Elapsed Time characteristic, the server shall send an indication of the Current Elapsed Time characteristic to other connected clients. It is an implementation choice to send an indication to the client that performed the write or not.
The ETS server only sends indications of the Current Elapsed Time characteristic to a client when the client has enabled the Current Elapsed Time characteristic for indications.
3.1.2.3. Setting the time
If the Current Elapsed Time characteristic is writable, a client can set the time by writing to the Current Elapsed Time characteristic.
The server shall respond with an Attribute Protocol (ATT) Application Error code of Incorrect Time Format when the flags in the Flags field in the Elapsed Time field do not match the features as supported by the server as described in Section 3.1.2.1.
The server shall ignore the value of the Time Stamp Is From The Current Timeline flag when the time is set by a client. See GSS [3] for the definition of the flags of the Current Elapsed Time characteristic.
When writing the time, the server may respond with an Attribute Protocol Application Error under specific conditions as defined in Table 3.5: .
|
Error Code Name |
Error Code |
Condition |
|---|---|---|
|
Time Source Quality Too Low |
0x80 |
The time sync source used when setting the clock is of too low quality as judged by the server. For example, the server may consider a mobile network time source as lower quality than a Global Positioning System (GPS) time source. The conditions under which this error code is sent are implementation-specific. |
|
Incorrect Time Format |
0x81 |
The flags set in the value written to the Current Elapsed Time characteristic do not match what the server supports. |
|
Out of Range |
0xFF |
The server judges the value as being out of range (e.g., when the value is from before the server production date). The conditions under which this error code is sent are implementation-specific. |
4. SDP interoperability
If this service is exposed over BR/EDR, then it shall have the following SDP record:
|
Item |
Definition |
Type |
Value |
Status |
|---|---|---|---|---|
|
Service Class ID List |
- |
- |
- |
M |
|
Service Class #0 |
- |
UUID |
«Elapsed Time Service» |
M |
|
Protocol Descriptor List |
- |
Data Element Sequence |
- |
M |
|
Protocol #0 |
- |
UUID |
«L2CAP» |
M |
|
Parameter #0 for Protocol #0 |
PSM |
uint16 |
PSM = «ATT» |
M |
|
Protocol #1 |
- |
UUID |
«ATT» |
M |
|
BrowseGroupList |
- |
- |
«PublicBrowseRoot»* |
M |
* «PublicBrowseRoot» shall be present; however, other browse UUIDs may also be included in the list.
5. Acronyms and abbreviations
|
Acronym/Abbreviation |
Meaning |
|---|---|
|
ATT |
Attribute Protocol |
|
BR/EDR |
Basic Rate/Enhanced Data Rate |
|
CSS |
Core Specification Supplement |
|
DST |
Daylight Saving Time |
|
ETS |
Elapsed Time Service |
|
GATT |
Generic Attribute Profile |
|
GPS |
Global Positioning System |
|
GSS |
GATT Specification Supplement |
|
L2CAP |
Logical Link Control and Adaptation Protocol |
|
LSO |
least significant octet |
|
MSO |
most significant octet |
|
PSM |
Protocol/Service Multiplexer |
|
RFU |
Reserved for Future Use |
|
TZ |
Time Zone |
|
UI |
user interface |
|
UTC |
Coordinated Universal Time |
|
UUID |
universally unique identifier |
6. References
Bibliography
[1] Bluetooth Core Specification, Version 4.2 or later
[2] Core Specification Supplement (CSS), v10 or later
[3] GATT Specification Supplement (GSS), v10 or later
[4] Bluetooth Assigned Numbers, https://www.bluetooth.com/specifications/assigned-numbers/
Appendix A. Elapsed Time examples
The sections below give a few examples of Elapsed Time characteristic values.
A.1. Example 1: UTC time without TZ/DST offset in seconds
|
Field |
Data Type |
Size (in octets) |
Example |
Value (hex) |
Little endian – transmission order |
|---|---|---|---|---|---|
|
Flags |
struct |
1 |
Bit 0: Time is a tick counter: 0 Bit 1: Time is UTC: 1 Bit 2-3: Time resolution: 1 second - 00 Bit 4: TZ/DST offset is used: 0 Bit 5: Time stamp is from the current timeline: 1 Bit 6-7: RFU - 00 0b0010 0010 |
22 |
22 |
|
Time Value |
uint48 |
6 |
2021-11-20 11:50:10 |
00 00 29 2B 9D 72 |
72 9D 2B 29 00 00 |
|
Time Sync Source Type |
enumeration |
1 |
Cellular network |
06 |
06 |
|
TZ/DST Offset |
int8 |
1 |
Not used |
00 |
00 |
A.2. Example 2: UTC time with TZ/DST offset in milliseconds
|
Field |
Data Type |
Size (in octets) |
Example |
Value (hex) |
Little endian – transmission order |
|---|---|---|---|---|---|
|
Flags |
struct |
1 |
Bit 0: Time is a tick counter: 0 Bit 1: Time is UTC: 1 Bit 2-3: Time resolution: 1 millisecond - 10 Bit 4: TZ/DST offset is used: 1 Bit 5: Time stamp is from the current timeline: 1 Bit 6-7: RFU - 00 0b0011 1010 |
3A |
3A |
|
Time Value |
uint48 |
6 |
2021-11-22 11:56:00.567 690897360567 |
00 A0 DC B1 16 B7 |
B7 16 B1 DC A0 00 |
|
Time Sync Source Type |
enumeration |
1 |
GPS |
02 |
02 |
|
TZ/DST Offset |
int8 |
1 |
Not used |
00 |
00 |
A.3. Example 3: Local time
|
Field |
Data Type |
Size (in octets) |
Example |
Value (hex) |
Little endian – transmission order |
|---|---|---|---|---|---|
|
Flags |
struct |
1 |
Bit 0: Time is a tick counter: 0 Bit 1: Time is UTC: 0 Bit 2-3: Time resolution: 1 second - 00 Bit 4: TZ/DST offset is used: 0 Bit 5: Time stamp is from the current timeline: 1 Bit 6-7: RFU - 00 0b0010 0000 |
20 |
20 |
|
Time Value |
uint48 |
6 |
2021-11-20 11:50:10 |
00 00 29 2B 9D 72 |
72 9D 2B 29 00 00 |
|
Time Sync Source Type |
enumeration |
1 |
Manual |
04 |
04 |
|
TZ/DST Offset |
int8 |
1 |
Not used |
00 |
00 |
A.4. Example 4: Tick counter
|
Field |
Data Type |
Size (in octets) |
Example |
Value (hex) |
Little endian – transmission order |
|---|---|---|---|---|---|
|
Flags |
struct |
1 |
Bit 0: Time is a tick counter: 1 Bit 1: Time is UTC: 0 Bit 2-3: Time resolution: 100 microseconds - 11 Bit 4: TZ/DST offset is used: 0 Bit 5: Time stamp is from the current timeline: 1 Bit 6-7: RFU - 00 0b0010 1101 |
2D |
2D |
|
Time Value |
uint48 |
6 |
2^32 4294967296 |
00 01 00 00 00 00 |
00 00 00 00 01 00 |
|
Time Sync Source Type |
enumeration |
1 |
Other / not used |
00 |
00 |
|
TZ/DST Offset |
int8 |
1 |
Not used |
00 |
00 |