Elapsed Time Service (ETS)

Data Structures
struct	bt_ets_elapsed_time
	Elapsed Time data structure as defined in GATT Specification Supplement Section 3.82. More...
struct	bt_ets_cb
	Elapsed Time Service callback structure. More...

Macros
#define	BT_ETS_SUPPORTED_FLAGS_MASK
	Combined supported flags mask based on configuration.
#define	BT_ETS_CLOCK_CAPABILITIES_VALUE
	Clock capabilities (Elapsed Time Service - Section 3.1.1.3).

Enumerations
enum	bt_ets_time_resolution { BT_ETS_RESOLUTION_1_SEC = 0 , BT_ETS_RESOLUTION_100_MS = 1 , BT_ETS_RESOLUTION_1_MS = 2 , BT_ETS_RESOLUTION_100_US = 3 }
	Time resolution values for bits 2-3 of flags field. More...
enum	bt_ets_write_result { BT_ETS_WRITE_SUCCESS = 0 , BT_ETS_WRITE_TIME_SOURCE_TOO_LOW = 1 , BT_ETS_WRITE_OUT_OF_RANGE = 2 , BT_ETS_WRITE_INCORRECT_FORMAT = 3 }
	Write result codes for write_elapsed_time callback. More...

Functions
int	bt_ets_init (const struct bt_ets_cb *cb)
	Initialize Elapsed Time Service.
int	bt_ets_indicate (const struct bt_ets_elapsed_time *elapsed_time, uint8_t clock_status)
	Send indication to subscribed clients.
int	bt_ets_time_to_unix_ms (const struct bt_ets_elapsed_time *et_time, int64_t *unix_ms)
	Decode ETS formatted time into milliseconds since Unix epoch.
int	bt_ets_time_from_unix_ms (struct bt_ets_elapsed_time *et_time, int64_t unix_ms, uint8_t time_src, int8_t tz_dst_offset)
	Encode Unix milliseconds into ETS formatted time.

Elapsed Time Service Flags
Elapsed Time Service flags field bits (GATT Specification Supplement Section 3.82)
#define	BT_ETS_FLAG_TICK_COUNTER   BIT(0)
	Time Value reports a counter (tick counter).
#define	BT_ETS_FLAG_UTC   BIT(1)
	Time is UTC.
#define	BT_ETS_FLAG_RESOLUTION_MASK   (BIT(2) | BIT(3))
	Time resolution mask (bits 2-3).
#define	BT_ETS_FLAG_TZ_DST_USED   BIT(4)
	TZ/DST offset is used.
#define	BT_ETS_FLAG_CURRENT_TIMELINE   BIT(5)
	Time stamp is from current timeline.
#define	BT_ETS_FLAG_RESERVED_MASK   (BIT(6) | BIT(7))
	Reserved bits (6-7).

Time Source Values
Time synchronization source values (GATT Specification Supplement Section 3.243)
#define	BT_ETS_TIME_SOURCE_UNKNOWN   0
	Unknown time source.
#define	BT_ETS_TIME_SOURCE_NTP   1
	Network Time Protocol.
#define	BT_ETS_TIME_SOURCE_GPS   2
	GPS/GNSS.
#define	BT_ETS_TIME_SOURCE_RADIO   3
	Radio Time Signal.
#define	BT_ETS_TIME_SOURCE_MANUAL   4
	Manually set.
#define	BT_ETS_TIME_SOURCE_ATOMIC   5
	Atomic Clock.
#define	BT_ETS_TIME_SOURCE_CELLULAR   6
	Cellular Network.
#define	BT_ETS_TIME_SOURCE_NOT_SYNCHRONIZED   7
	Not synchronized.

Clock Status Flags
Clock Status flags (Elapsed Time Service - Section 3.1.1.2)
#define	BT_ETS_CLOCK_STATUS_NEEDS_SET   BIT(0)
	Clock needs to be set.
#define	BT_ETS_CLOCK_STATUS_RFU_MASK   0xFE
	Clock Status RFU mask (bits 1-7).

Clock Capabilities flags (Elapsed Time Service - Section 3.1.1.3)
#define	BT_ETS_CLOCK_CAP_DST_AUTO   BIT(0)
	Clock autonomously applies DST rules.
#define	BT_ETS_CLOCK_CAP_TZ_AUTO   BIT(1)
	Clock autonomously manages TZ changes.
#define	BT_ETS_CLOCK_CAP_RFU_MASK   0xFC
	Clock Capabilities RFU mask (bits 2-7).

Detailed Description

Macro Definition Documentation

BT_ETS_CLOCK_CAP_DST_AUTO

#define BT_ETS_CLOCK_CAP_DST_AUTO   BIT(0)

#include <zephyr/bluetooth/services/ets.h>

Clock autonomously applies DST rules.

BT_ETS_CLOCK_CAP_RFU_MASK

#define BT_ETS_CLOCK_CAP_RFU_MASK   0xFC

#include <zephyr/bluetooth/services/ets.h>

Clock Capabilities RFU mask (bits 2-7).

BT_ETS_CLOCK_CAP_TZ_AUTO

#define BT_ETS_CLOCK_CAP_TZ_AUTO   BIT(1)

#include <zephyr/bluetooth/services/ets.h>

Clock autonomously manages TZ changes.

BT_ETS_CLOCK_CAPABILITIES_VALUE

#define BT_ETS_CLOCK_CAPABILITIES_VALUE

#include <zephyr/bluetooth/services/ets.h>

Value:

        ((IS_ENABLED(CONFIG_BT_ETS_CLOCK_CAP_DST_AUTO) ? BT_ETS_CLOCK_CAP_DST_AUTO : 0) |          \
         (IS_ENABLED(CONFIG_BT_ETS_CLOCK_CAP_TZ_AUTO) ? BT_ETS_CLOCK_CAP_TZ_AUTO : 0))

Clock capabilities (Elapsed Time Service - Section 3.1.1.3).

BT_ETS_CLOCK_STATUS_NEEDS_SET

#define BT_ETS_CLOCK_STATUS_NEEDS_SET   BIT(0)

#include <zephyr/bluetooth/services/ets.h>

Clock needs to be set.

If 0, clock is set.

BT_ETS_CLOCK_STATUS_RFU_MASK

#define BT_ETS_CLOCK_STATUS_RFU_MASK   0xFE

#include <zephyr/bluetooth/services/ets.h>

Clock Status RFU mask (bits 1-7).

BT_ETS_FLAG_CURRENT_TIMELINE

#define BT_ETS_FLAG_CURRENT_TIMELINE   BIT(5)

#include <zephyr/bluetooth/services/ets.h>

Time stamp is from current timeline.

BT_ETS_FLAG_RESERVED_MASK

#define BT_ETS_FLAG_RESERVED_MASK   (BIT(6) | BIT(7))

#include <zephyr/bluetooth/services/ets.h>

Reserved bits (6-7).

BT_ETS_FLAG_RESOLUTION_MASK

#define BT_ETS_FLAG_RESOLUTION_MASK   (BIT(2) | BIT(3))

#include <zephyr/bluetooth/services/ets.h>

Time resolution mask (bits 2-3).

BT_ETS_FLAG_TICK_COUNTER

#define BT_ETS_FLAG_TICK_COUNTER   BIT(0)

#include <zephyr/bluetooth/services/ets.h>

Time Value reports a counter (tick counter).

If 0, Time Value reports a time of day.

BT_ETS_FLAG_TZ_DST_USED

#define BT_ETS_FLAG_TZ_DST_USED   BIT(4)

#include <zephyr/bluetooth/services/ets.h>

TZ/DST offset is used.

If 0, offset not used. Has no meaning for tick counter.

BT_ETS_FLAG_UTC

#define BT_ETS_FLAG_UTC   BIT(1)

#include <zephyr/bluetooth/services/ets.h>

Time is UTC.

If 0, time is local time. Has no meaning for tick counter.

BT_ETS_SUPPORTED_FLAGS_MASK

#define BT_ETS_SUPPORTED_FLAGS_MASK

#include <zephyr/bluetooth/services/ets.h>

Value:

        ((IS_ENABLED(CONFIG_BT_ETS_SUPPORT_TICK_COUNTER) ? BT_ETS_FLAG_TICK_COUNTER : 0) |         \
         (IS_ENABLED(CONFIG_BT_ETS_SUPPORT_UTC) ? BT_ETS_FLAG_UTC : 0) |                           \
         (IS_ENABLED(CONFIG_BT_ETS_SUPPORT_TZ_DST) ? BT_ETS_FLAG_TZ_DST_USED : 0) |                \
         (IS_ENABLED(CONFIG_BT_ETS_RESOLUTION_1_SEC)    ? 0                                        \
          : IS_ENABLED(CONFIG_BT_ETS_RESOLUTION_100_MS) ? BIT(2)                                   \
          : IS_ENABLED(CONFIG_BT_ETS_RESOLUTION_1_MS)   ? BIT(3)                                   \
          : IS_ENABLED(CONFIG_BT_ETS_RESOLUTION_100_US) ? (BIT(2) | BIT(3))                        \
                                                        : 0) |                                     \
         BT_ETS_FLAG_CURRENT_TIMELINE)

Combined supported flags mask based on configuration.

BT_ETS_TIME_SOURCE_ATOMIC

#define BT_ETS_TIME_SOURCE_ATOMIC   5

#include <zephyr/bluetooth/services/ets.h>

Atomic Clock.

BT_ETS_TIME_SOURCE_CELLULAR

#define BT_ETS_TIME_SOURCE_CELLULAR   6

#include <zephyr/bluetooth/services/ets.h>

Cellular Network.

BT_ETS_TIME_SOURCE_GPS

#define BT_ETS_TIME_SOURCE_GPS   2

#include <zephyr/bluetooth/services/ets.h>

GPS/GNSS.

BT_ETS_TIME_SOURCE_MANUAL

#define BT_ETS_TIME_SOURCE_MANUAL   4

#include <zephyr/bluetooth/services/ets.h>

Manually set.

BT_ETS_TIME_SOURCE_NOT_SYNCHRONIZED

#define BT_ETS_TIME_SOURCE_NOT_SYNCHRONIZED   7

#include <zephyr/bluetooth/services/ets.h>

Not synchronized.

BT_ETS_TIME_SOURCE_NTP

#define BT_ETS_TIME_SOURCE_NTP   1

#include <zephyr/bluetooth/services/ets.h>

Network Time Protocol.

BT_ETS_TIME_SOURCE_RADIO

#define BT_ETS_TIME_SOURCE_RADIO   3

#include <zephyr/bluetooth/services/ets.h>

Radio Time Signal.

BT_ETS_TIME_SOURCE_UNKNOWN

#define BT_ETS_TIME_SOURCE_UNKNOWN   0

#include <zephyr/bluetooth/services/ets.h>

Unknown time source.

Enumeration Type Documentation

bt_ets_time_resolution

enum bt_ets_time_resolution

#include <zephyr/bluetooth/services/ets.h>

Time resolution values for bits 2-3 of flags field.

Enumerator
BT_ETS_RESOLUTION_1_SEC	1 second resolution.
BT_ETS_RESOLUTION_100_MS	100 milliseconds resolution.
BT_ETS_RESOLUTION_1_MS	1 millisecond resolution.
BT_ETS_RESOLUTION_100_US	100 microseconds resolution.

bt_ets_write_result

enum bt_ets_write_result

#include <zephyr/bluetooth/services/ets.h>

Write result codes for write_elapsed_time callback.

These codes indicate the result of a time write operation and map to specific ATT error responses as defined in the ETS specification.

Enumerator
BT_ETS_WRITE_SUCCESS	Write accepted successfully.
BT_ETS_WRITE_TIME_SOURCE_TOO_LOW	Time source quality is too low. Rejects write with ATT error 0x80.
BT_ETS_WRITE_OUT_OF_RANGE	Time value is out of acceptable range. Rejects write with ATT error 0xFF.
BT_ETS_WRITE_INCORRECT_FORMAT	Incorrect time format (flags mismatch). Rejects write with ATT error 0x81.

Function Documentation

bt_ets_indicate()

int bt_ets_indicate	(	const struct bt_ets_elapsed_time *	elapsed_time,
		uint8_t	clock_status )

#include <zephyr/bluetooth/services/ets.h>

Send indication to subscribed clients.

Send indication to all subscribed clients with updated elapsed time. This should be called when the time changes other than by natural progression (e.g., manual adjustment, external time sync, DST change, timezone change).

Parameters

elapsed_time	Elapsed time to indicate.
clock_status	Current clock status flags (BT_ETS_CLOCK_STATUS).

Return values

0	On success.
-ENOTCONN	If no clients are connected or subscribed.
-errno	Other negative errno on failure.

bt_ets_init()

int bt_ets_init

(

const struct bt_ets_cb *

cb

)

#include <zephyr/bluetooth/services/ets.h>

Initialize Elapsed Time Service.

Must be called during initialization. This can be called before or after bt_enable, but before advertising.

Parameters

cb	Callback structure with mandatory callbacks set.

Return values

0	On success.
-EINVAL	If cb is NULL or mandatory callbacks are NULL.

bt_ets_time_from_unix_ms()

int bt_ets_time_from_unix_ms	(	struct bt_ets_elapsed_time *	et_time,
		int64_t	unix_ms,
		uint8_t	time_src,
		int8_t	tz_dst_offset )

#include <zephyr/bluetooth/services/ets.h>

Encode Unix milliseconds into ETS formatted time.

Converts a Unix timestamp (1970-01-01 00:00:00 UTC) to ETS time format. Handles epoch conversion (Unix 1970-01-01 to ETS 2000-01-01), resolution scaling, and timezone conversion based on compile-time configuration.

The unix_ms input is always in UTC. The tz_dst_offset parameter behavior:

• Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_UTC.: Time stays as UTC, no conversion. If

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_TZ_DST. enabled, offset is stored for client use.

• Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_LOCAL_TIME. with

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_TZ_DST.: Offset is applied to convert UTC to local time and stored in output. Formula: Local time = UTC time + TZ/DST Offset × 15 minutes BT_ETS_FLAG_TZ_DST_USED flag is set in output.

  The output et_time flags are set based on compile-time configuration:
• Time mode:

  Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_UTC. or

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_LOCAL_TIME.

• Resolution: CONFIG_BT_ETS_RESOLUTION_* (1_SEC, 100_MS, 1_MS, or 100_US)
• BT_ETS_FLAG_CURRENT_TIMELINE is always set

Note

This function is only available when

Attention

Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_HELPER_API. is enabled. This requires either

Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_UTC. or

Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_TZ_DST. to be enabled.

Parameters

et_time	Pointer to ETS time structure to fill.
unix_ms	Milliseconds since Unix epoch (1970-01-01 00:00:00 UTC) - always UTC.
time_src	Time synchronization source type. (see BT_ETS_TIME_SOURCE)
tz_dst_offset	TZ/DST offset from UTC in 15-minute units (signed). Used for UTC-to-local conversion if in LOCAL_TIME mode.

Return values

0	On success.
-EINVAL	If et_time is NULL or time is before ETS epoch (2000-01-01) after conversion.
-EOVERFLOW	If the time value exceeds 48-bit range after conversion.

bt_ets_time_to_unix_ms()

int bt_ets_time_to_unix_ms	(	const struct bt_ets_elapsed_time *	et_time,
		int64_t *	unix_ms )

#include <zephyr/bluetooth/services/ets.h>

Decode ETS formatted time into milliseconds since Unix epoch.

Converts ETS time format to milliseconds with Unix epoch (1970-01-01 00:00:00 UTC). Handles epoch conversion (ETS uses 2000-01-01 vs Unix 1970-01-01), resolution scaling, and timezone conversion based on the flags field in et_time.

The output unix_ms is always in UTC. Timezone handling based on flags:

• Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_UTC.: Time is already UTC, no conversion needed. If BT_ETS_FLAG_TZ_DST_USED is set, the offset is informational only.

• Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_LOCAL_TIME. with

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_TZ_DST.: If BT_ETS_FLAG_TZ_DST_USED is set in et_time, converts local time to UTC by subtracting the offset: UTC = Local time - TZ/DST Offset × 15 minutes

  Note

  This function is only available when

  Attention

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_HELPER_API. is enabled. This requires either

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_UTC. or

  Available only when the following Kconfig option is enabled: CONFIG_BT_ETS_SUPPORT_TZ_DST. to be enabled (proper UTC conversion needs either UTC mode or timezone offset information).

  Parameters

  et_time	ETS time formatted structure to decode.
  unix_ms	Pointer to store milliseconds since Unix epoch (1970-01-01 00:00:00 UTC).

  Return values

  0	On success.
  -EINVAL	If et_time or unix_ms is NULL.
  -EOVERFLOW	If the converted time value overflows during conversion.