Generic Default Transition Time Server

The DTT Server provides a common way to specify the state transition time for other models on any element. If a DTT Server is not present on the model’s element, use the DTT Server model instance that is present on the element with the largest address that is smaller than the address of the given element. This way, if other generic models on any element receive state change commands without transition parameters, they will use the default transition time specified by the DTT Server model. The DTT Server can then define a consistent transition time for all states on their elements, without depending on client configurations.

Configuration

The following configuration parameters are associated with the Generic DTT Server model:

States

The Generic Level Server model contains the following state:

Generic Default Transition Time: int32_t

This state can have the following values:

  • 0 to perform the state change instantly or when no transition is planned

  • Positive number of milliseconds that defines the transition time

  • SYS_FOREVER_MS if the transition time is undefined

On the air, the transition time is encoded into a single byte, and loses some of its granularity:

  • Step count: 6 bits (range 0x00 to 0x3e)

  • Step resolution: 2 bits

    • Step 0: 100-millisecond resolution

    • Step 1: 1-second resolution

    • Step 2: 10-second resolution

    • Step 3: 10-minute resolution

The state is encoded with the highest resolution available, and rounded to the nearest representation. Values lower than 100 milliseconds and higher than 0 are encoded as 100 milliseconds. Values higher than the max value of 620 minutes are encoded as “undefined”.

The DTT Server holds the memory for this state itself, and optionally notifies the user of any changes through bt_mesh_dtt_srv.update_handler. If your application changes the transition time manually, the change must be published using bt_mesh_dtt_srv_pub().

Extended models

None.

Persistent storage

The Generic Default Transition Time is stored persistently if CONFIG_BT_MESH_DTT_SRV_PERSISTENT is enabled.

API documentation

Header file: include/bluetooth/mesh/gen_dtt_srv.h
Source file: subsys/bluetooth/mesh/gen_dtt_srv.c
group bt_mesh_dtt_srv

API for the Generic Default Transition Time (DTT) Server model.

model

Defines

BT_MESH_DTT_SRV_INIT(_update)

Initialization parameters for Generic Default Transition Time Server.

Parameters:

  • _update – [in] Update handler called on every change to the transition time in this server.

BT_MESH_MODEL_DTT_SRV(_srv)

Generic Default Transition Time Server model composition data entry.

Parameters:

Functions

void bt_mesh_dtt_srv_set(struct bt_mesh_dtt_srv *srv, uint32_t transition_time)

Set the Default Transition Time of the DTT server.

If an update handler is set, it’ll be called with the updated transition time. If publication is configured, the change will cause the server to publish.

Parameters:

  • srv – [in] Server to set the DTT of.

  • transition_time – [in] New Default Transition Time, in milliseconds.

int bt_mesh_dtt_srv_pub(struct bt_mesh_dtt_srv *srv, struct bt_mesh_msg_ctx *ctx)

Publish the current transition time.

Parameters:

  • srv – [in] Server instance to publish with.

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

Return values:

  • 0 – Successfully published the current transition time.

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

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_dtt_srv *bt_mesh_dtt_srv_get(const struct bt_mesh_elem *elem)

Find the Generic DTT server over multiple elements.

If the DTT Server is not present on the given element of the model, then the try to find the DTT Server model instance that is present on the element with the largest address that is smaller than the address of the given element.

Parameters:

  • elem – [in] Element to start search of the DTT server in.

Returns:

A pointer to the DTT server instance, or NULL if no instance is found.

static inline bool bt_mesh_dtt_srv_transition_get(struct bt_mesh_model *model, struct bt_mesh_model_transition *transition)

Get the default transition parameters for the given model.

Parameters:

  • model – [in] Model to get the DTT for.

  • transition – [out] Transition buffer.

Returns:

Whether the transition was set.

struct bt_mesh_dtt_srv
#include <gen_dtt_srv.h>

Generic Default Transition Time server instance.

Public Members

uint32_t transition_time

Current transition time in milliseconds

void (*const update)(struct bt_mesh_dtt_srv *srv, struct bt_mesh_msg_ctx *ctx, uint32_t old_transition_time, uint32_t new_transition_time)

Update handler for the transition time state.

Called every time the transition time is updated.

Param srv:

[in] Server instance that was updated.

Param ctx:

[in] Context of the set message that caused the update, or NULL if the update was not a result of a set message.

Param old_transition_time:

[in] The transition time prior to the update, in milliseconds.

Param new_transition_time:

[in] The new transition time after the update, in milliseconds.

struct bt_mesh_model *model

Composition data Model entry pointer.

struct bt_mesh_model_pub pub

Model publish parameters.