Time Client

The Time Client model provides time sources for and configures Time Server models.

Unlike the Time Server model, the Time Client only creates a single model instance in the mesh composition data. The Time Client can send messages to both the Time Server and the Time Setup Server, as long as it has the right application keys.

Extended models

None.

Persistent storage

None.

Shell commands

The Bluetooth mesh shell subsystem provides a set of commands to interact with the Time Client model instantiated on a device.

To make these commands available, enable the following Kconfig options:

mdl_time instance get-all

Print all instances of the Time Client model on the device.

mdl_time instance set <elem_idx>

Select the Time Client model instantiated on the specified element ID. This instance will be used in message sending. If no model instance is selected, the first model instance found on the device will be used by default.

  • elem_idx - Element index where the model instance is found.

mdl_time time-get

Get the current Time Status of a Time Server.

mdl_time time-set <sec> <subsec> <uncertainty> <tai_utc_delta> <time_zone_offset> <is_authority>

Set the Time Status of a Time Server and wait for a response.

  • sec - The current TAI time in seconds.

  • subsec - The sub-seconds time in units of 1/256th second.

  • uncertainty - Accumulated uncertainty of the mesh Timestamp in milliseconds.

  • tai_utc_delta - Current TAI-UTC Delta (leap seconds).

  • time_zone_offset - Current zone offset in 15-minute increments.

  • is_authority - Reliable TAI source flag.

mdl_time zone-get

Get the Time Zone status of a Time Server.

mdl_time zone-set <new_offset> <timestamp>

Schedule a Time Zone change for the Time Server and wait for a response.

  • new_offset - New zone offset in 15-minute increments.

  • timestamp - TAI update point for Time Zone Offset.

mdl_time tai-utc-delta-get

Get the UTC Delta status of a Time Server.

mdl_time tai-utc-delta-set <delta_new> <timestamp>

Schedule a UTC Delta change for the Timer Server and wait for a response.

  • delta_new - New TAI-UTC Delta (leap seconds).

  • timestamp - TAI update point for TAI-UTC Delta.

mdl_time role-get

Get the Time Role state of a Time Server.

mdl_time role-set <role>

Set the Time Role state of a Time Server and wait for a response.

  • role - Time Role to set. Allowed values:

    • 0 - The element does not participate in propagation of time information.

    • 1 - The element publishes Time Status messages but does not process received Time Status messages.

    • 2 - The element both publishes and processes received Time Status messages.

    • 3 - The element does not publish but processes received Time Status messages.

API documentation

Header file: include/bluetooth/mesh/time_cli.h
Source file: subsys/bluetooth/mesh/time_cli.c
group bt_mesh_time_cli

API for the Time Client model.

Defines

BT_MESH_TIME_CLI_INIT(_handlers)

Initialization parameters for a Time Client model instance.

See also

bt_mesh_time_cli_handlers

Parameters

  • _handlers – [in] Optional message handler structure.

BT_MESH_MODEL_TIME_CLI(_cli)

Time Client model composition data entry.

Parameters

Functions

int bt_mesh_time_cli_time_get(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_time_status *rsp)

Get the current Time Status of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • rsp – [out] Status response buffer, returning the Server’s current time Status, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_time_set(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_status *set, struct bt_mesh_time_status *rsp)

Set the Time Status of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • set – [in] Time Status parameter to set.

  • rsp – [out] Status response buffer, returning the Server’s current time Status, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_zone_get(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_time_zone_status *rsp)

Get the Time Zone status of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • rsp – [out] Status response buffer, returning the Server’s current Time Zone Offset new state, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_zone_set(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_zone_change *set, struct bt_mesh_time_zone_status *rsp)

Schedule a Time Zone change for the Time Server.

Used to set the point in TAI a Time Server is to update its Time Zone Offset, and what this new offset should be

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • set – [in] Time Zone Change parameters to set.

  • rsp – [out] Status response buffer, returning the Server’s current time Status, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_tai_utc_delta_get(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_time_tai_utc_delta_status *rsp)

Get the UTC Delta status of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • rsp – [out] Status response buffer, returning the Server’s TAI-UTC Delta new state, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_tai_utc_delta_set(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_tai_utc_change *set, struct bt_mesh_time_tai_utc_delta_status *rsp)

Schedule a UTC Delta change for the Timer Server.

Used to set the point in TAI a Time Server is to update its TAI-UTC Delta, and what this new offset should be

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • set – [in] TAI-UTC Delta Change parameters to set.

  • rsp – [out] Status response buffer, returning the Server’s current time Status, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_role_get(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, uint8_t *rsp)

Get the Time Role state of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • rsp – [out] Status response buffer, returning the Server’s current Time Role state, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

int bt_mesh_time_cli_role_set(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const uint8_t *set, uint8_t *rsp)

Set the Time Role state of a Time Server.

Parameters

  • cli – [in] Client model to send on.

  • ctx – [in] Message context, or NULL to use the configured publish parameters.

  • set – [in] Time Role to set.

  • rsp – [out] Status response buffer, returning the Server’s current time Status, or NULL to keep from blocking.

Return values

  • 0 – Successfully sent the message and populated the rsp buffer.

  • -EALREADY – A blocking request is already in progress.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

  • -ETIMEDOUT – The request timed out without a response.

struct bt_mesh_time_cli_handlers
#include <time_cli.h>

Time Client handler functions.

Public Members

void (*const time_status)(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_status *status)

Time status message handler.

Called when the client receives a Time Status message, either as a result of calling bt_mesh_time_cli_time_get, bt_mesh_time_cli_time_set, or as an unsolicited message.

Note

This handler is optional.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the incoming message.

Param status

[in] Time Status contained in the message.

void (*const time_zone_status)(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_zone_status *status)

Time Zone status message handler.

Called when the client receives a Time Zone Status message, either as a result of calling bt_mesh_time_cli_zone_get, bt_mesh_time_cli_zone_set, or as an unsolicited message.

Note

This handler is optional.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the incoming message.

Param status

[in] Time Zone Status contained in the message.

void (*const tai_utc_delta_status)(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_time_tai_utc_delta_status *status)

TAI-UTC Delta status message handler.

Called when the client receives a TAI-UTC Delta Status message, either as a result of calling bt_mesh_time_cli_tai_utc_delta_get, bt_mesh_time_cli_tai_utc_delta_set, or as an unsolicited message.

Note

This handler is optional.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the incoming message.

Param status

[in] TAI-UTC Delta Status contained in the message.

void (*const time_role_status)(struct bt_mesh_time_cli *cli, struct bt_mesh_msg_ctx *ctx, enum bt_mesh_time_role time_role)

Time Role status message handler.

Called when the client receives a Time Role Status message, either as a result of calling bt_mesh_time_cli_role_get, bt_mesh_time_cli_role_set, or as an unsolicited message.

Note

This handler is optional.

Param cli

[in] Client that received the status message.

Param ctx

[in] Context of the incoming message.

Param time_role

[in] Time Role of the server.

struct bt_mesh_time_cli
#include <time_cli.h>

Time Client instance. Should be initialized with BT_MESH_TIME_CLI_INIT.

Public Members

struct bt_mesh_model *model

Model entry.

struct bt_mesh_model_pub pub

Publish parameters.

struct bt_mesh_msg_ack_ctx ack_ctx

Acknowledged message tracking.

const struct bt_mesh_time_cli_handlers *handlers

Collection of handler callbacks.

Note

Must point to memory that remains valid.