Skip to content

Commit 403f69f

Browse files
trond-snekvikjoerchan
trond-snekvik
authored and
joerchan
committed
Bluetooth: Mesh: Generic DTT models
Adds the Generic Default Transition Time Client and Generic Default Transition Time Server models. Signed-off-by: Trond Einar Snekvik <[email protected]>
1 parent 6c5f2ea commit 403f69f

File tree

9 files changed

+699
-1
lines changed

9 files changed

+699
-1
lines changed

‎include/bluetooth/mesh/gen_dtt.h‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
/*
2+
* Copyright (c) 2019 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-BSD-5-Clause-Nordic
5+
*/
6+
7+
/**
8+
* @file
9+
* @defgroup bt_mesh_dtt Generic Default Transition Time models
10+
* @{
11+
* @brief API for the Generic Default Transition Time models.
12+
*/
13+
14+
#ifndef BT_MESH_GEN_DTT_H__
15+
#define BT_MESH_GEN_DTT_H__
16+
17+
#include <bluetooth/mesh.h>
18+
19+
#ifdef __cplusplus
20+
extern "C" {
21+
#endif
22+
23+
/** @cond INTERNAL_HIDDEN */
24+
#define BT_MESH_DTT_OP_GET BT_MESH_MODEL_OP_2(0x82, 0x0D)
25+
#define BT_MESH_DTT_OP_SET BT_MESH_MODEL_OP_2(0x82, 0x0E)
26+
#define BT_MESH_DTT_OP_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x0F)
27+
#define BT_MESH_DTT_OP_STATUS BT_MESH_MODEL_OP_2(0x82, 0x10)
28+
29+
#define BT_MESH_DTT_MSG_LEN_GET 0
30+
#define BT_MESH_DTT_MSG_LEN_SET 1
31+
#define BT_MESH_DTT_MSG_LEN_STATUS 1
32+
/** @endcond */
33+
34+
#ifdef __cplusplus
35+
}
36+
#endif
37+
38+
#endif /* BT_MESH_GEN_DTT_H__ */
39+
40+
/** @} */

‎include/bluetooth/mesh/gen_dtt.rst‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _bt_mesh_dtt_readme:
2+
3+
Generic Default Transition Time models
4+
######################################
5+
6+
The Generic Default Transition Time (DTT) models are used to control the
7+
transition of any other states on the same element as a DTT Server.
8+
The DTT Client can remotely control the default transition time state
9+
of a server.
10+
11+
There are two Default Transition Time models:
12+
13+
- :ref:`bt_mesh_dtt_srv_readme`
14+
- :ref:`bt_mesh_dtt_cli_readme`
15+
16+
.. _bt_mesh_dtt_srv_readme:
17+
18+
Generic Default Transition Time Server
19+
======================================
20+
21+
The DTT Server provides a common way to specify the state transition time for
22+
other models on the same element. If other generic models on the same element
23+
receive state change commands without transition parameters, they will use the
24+
default transition time specified by the DTT Server model. This way, the DTT
25+
Server can define a consistent transition time for all states on their
26+
elements, without depending on client configurations.
27+
28+
Configuration
29+
**************
30+
31+
The Generic DTT Server has one associated configuration option:
32+
33+
- :option:`CONFIG_BT_MESH_DTT_SRV_PERSISTENT`: Control whether changes to the
34+
Generic Default Transition Time are stored persistently. Note that this
35+
option is only available if :option:`CONFIG_BT_SETTINGS` is enabled.
36+
37+
States
38+
*******
39+
40+
**Generic Default Transition Time**: ``s32_t``
41+
42+
The Default Transition Time can either be 0, a positive number of milliseconds,
43+
or ``K_FOREVER`` if the transition is undefined. On the air, the transition
44+
time is encoded into a single byte, and loses some of its granularity:
45+
46+
- Step count: 6 bits (0-0x3e)
47+
- Step resolution: 2 bits
48+
- Step 0: 100 millisecond resolution
49+
- Step 1: 1 second resolution
50+
- Step 2: 10 second resolution
51+
- Step 3: 10 minutes resolution
52+
53+
The state is encoded with the highest resolution available, and rounded to the
54+
nearest representation. Values lower than 100 milliseconds, but higher than 0
55+
are encoded as 100 milliseconds. Values higher than the max value of 620
56+
minutes are encoded as "undefined".
57+
58+
The DTT Server holds the memory for this state itself, and optionally
59+
notifies the user of any changes through
60+
:cpp:member:`bt_mesh_dtt_srv::update_handler`. If the user changes the
61+
transition time manually, the change should be published using
62+
:cpp:func:`bt_mesh_dtt_srv_pub`.
63+
64+
Extended models
65+
****************
66+
67+
None.
68+
69+
Persistent storage
70+
*******************
71+
72+
The Generic Default Transition Time is stored persistently if
73+
:option:`CONFIG_BT_MESH_DTT_SRV_PERSISTENT` is enabled.
74+
75+
76+
API documentation
77+
******************
78+
79+
| Header file: :file:`include/bluetooth/mesh/gen_dtt_srv.h`
80+
| Source file: :file:`subsys/bluetooth/mesh/gen_dtt_srv.c`
81+
82+
.. doxygengroup:: bt_mesh_dtt_srv
83+
:project: nrf
84+
:members:
85+
86+
----
87+
88+
.. _bt_mesh_dtt_cli_readme:
89+
90+
Generic Default Transition Time Client
91+
======================================
92+
93+
The DTT Client remotely controls the transition time state of a DTT Server.
94+
This can be used to set up the server's default transition time behavior
95+
when changing states in other models on the same element.
96+
97+
Extended models
98+
****************
99+
100+
None.
101+
102+
Persistent storage
103+
*******************
104+
105+
None.
106+
107+
API documentation
108+
******************
109+
110+
| Header file: :file:`include/bluetooth/mesh/gen_dtt_cli.h`
111+
| Source file: :file:`subsys/bluetooth/mesh/gen_dtt_cli.c`
112+
113+
.. doxygengroup:: bt_mesh_dtt_cli
114+
:project: nrf
115+
:members:

‎include/bluetooth/mesh/gen_dtt_cli.h‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
/*
2+
* Copyright (c) 2019 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-BSD-5-Clause-Nordic
5+
*/
6+
7+
/**
8+
*
9+
* @file
10+
* @defgroup bt_mesh_dtt_cli Generic Default Transition Time Client API
11+
* @{
12+
* @brief API for the Generic Default Transition Time (DTT) Client.
13+
*/
14+
15+
#ifndef BT_MESH_GEN_DTT_CLI_H__
16+
#define BT_MESH_GEN_DTT_CLI_H__
17+
18+
#include <bluetooth/mesh/gen_dtt.h>
19+
#include <bluetooth/mesh/model_types.h>
20+
21+
#ifdef __cplusplus
22+
extern "C" {
23+
#endif
24+
25+
struct bt_mesh_dtt_cli;
26+
27+
/** @def BT_MESH_DTT_CLI_INIT
28+
*
29+
* @brief Initialization parameters for the @ref bt_mesh_dtt_cli.
30+
*
31+
* @param[in] _status_handler Optional status message handler.
32+
* @sa bt_mesh_dtt_cli::status_handler
33+
*/
34+
#define BT_MESH_DTT_CLI_INIT(_status_handler) \
35+
{ \
36+
.pub = { .msg = NET_BUF_SIMPLE(BT_MESH_MODEL_BUF_LEN( \
37+
BT_MESH_DTT_OP_SET, \
38+
BT_MESH_DTT_MSG_LEN_SET)) }, \
39+
.status_handler = _status_handler, \
40+
}
41+
42+
/** @def BT_MESH_MODEL_DTT_CLI
43+
*
44+
* @brief Generic DTT Client model composition data entry.
45+
*
46+
* @param[in] _cli Pointer to a @ref bt_mesh_dtt_cli instance.
47+
*/
48+
#define BT_MESH_MODEL_DTT_CLI(_cli) \
49+
BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI, \
50+
_bt_mesh_dtt_cli_op, &(_cli)->pub, \
51+
BT_MESH_MODEL_USER_DATA(struct bt_mesh_dtt_cli, \
52+
_cli), \
53+
&_bt_mesh_dtt_cli_cb)
54+
55+
/**
56+
* Generic DTT client structure.
57+
*
58+
* Should be initialized using the @ref BT_MESH_DTT_CLI_INIT macro.
59+
*/
60+
struct bt_mesh_dtt_cli {
61+
/** @brief Default Transition Time status message handler.
62+
*
63+
* @param[in] cli Client that received the message.
64+
* @param[in] ctx Message context.
65+
* @param[in] transition_time Transition time presented in the message.
66+
*/
67+
void (*const status_handler)(struct bt_mesh_dtt_cli *cli,
68+
struct bt_mesh_msg_ctx *ctx,
69+
s32_t transition_time);
70+
71+
/** Response context for tracking acknowledged messages. */
72+
struct bt_mesh_model_ack_ctx ack_ctx;
73+
/** Model publish parameters. */
74+
struct bt_mesh_model_pub pub;
75+
/** Composition data model entry pointer. */
76+
struct bt_mesh_model *model;
77+
};
78+
79+
/** @brief Get the Default Transition Time of the server.
80+
*
81+
* This call is blocking if the @p rsp_transition_time buffer is non-NULL.
82+
* Otherwise, this function will not request a response from the server, and
83+
* return immediately.
84+
*
85+
* @param[in] cli Client making the request.
86+
* @param[in] ctx Message context to use for sending, or NULL to publish with
87+
* the configured parameters.
88+
* @param[out] rsp_transition_time Pointer to a response buffer. Cannot be
89+
* NULL. Note that the response is a signed value, that can be K_FOREVER if the
90+
* current state is unknown or too large to represent.
91+
*
92+
* @retval 0 Successfully retrieved the status of the bound srv.
93+
* @retval -EALREADY A blocking operation is already in progress in this model.
94+
* @retval -EAGAIN The request timed out.
95+
*/
96+
int bt_mesh_dtt_get(struct bt_mesh_dtt_cli *cli, struct bt_mesh_msg_ctx *ctx,
97+
s32_t *rsp_transition_time);
98+
99+
/** @brief Set the Default Transition Time of the server.
100+
*
101+
* This call is blocking if the @p rsp_transition_time buffer is non-NULL.
102+
* Otherwise, this function will not request a response from the server, and
103+
* return immediately.
104+
*
105+
* @param[in] cli Client model to send on.
106+
* @param[in] ctx Message context to use for sending, or NULL to publish with
107+
* the configured parameters.
108+
* @param[in] transition_time Transition time to set (in milliseconds). Must be
109+
* less than @ref BT_MESH_MODEL_TRANSITION_TIME_MAX_MS.
110+
* @param[out] rsp_transition_time Response buffer, or NULL to send an
111+
* unacknowledged message. Note that the response is a signed value, that can
112+
* be K_FOREVER if the current state is unknown or too large to represent.
113+
*
114+
* @retval 0 Successfully sent the message. If the message is acknowledged,
115+
* the response buffer has been set according to the srv's response.
116+
* @retval -EINVAL The given transition time is invalid.
117+
* @retval -EALREADY A blocking operation is already in progress in this model.
118+
* @retval -EAGAIN The request timed out.
119+
*/
120+
int bt_mesh_dtt_set(struct bt_mesh_dtt_cli *cli, struct bt_mesh_msg_ctx *ctx,
121+
u32_t transition_time, s32_t *rsp_transition_time);
122+
123+
/** @cond INTERNAL_HIDDEN */
124+
extern const struct bt_mesh_model_op _bt_mesh_dtt_cli_op[];
125+
extern const struct bt_mesh_model_cb _bt_mesh_dtt_cli_cb;
126+
/** @endcond */
127+
128+
#ifdef __cplusplus
129+
}
130+
#endif
131+
132+
#endif /* BT_MESH_GEN_DTT_CLI_H__ */
133+
134+
/** @} */

0 commit comments

Comments
 (0)