Skip to content

Commit 203496c

Browse files
trond-snekvikjoerchan
trond-snekvik
authored and
joerchan
committed
Bluetooth: Mesh: Generic Power Level models
Adds the Generic Power Level Client and generic Power Level Server models. Signed-off-by: Trond Einar Snekvik <[email protected]>
1 parent 512bcdc commit 203496c

File tree

9 files changed

+1668
-0
lines changed

9 files changed

+1668
-0
lines changed

‎include/bluetooth/mesh/gen_plvl.h‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
/*
2+
* Copyright (c) 2019 Nordic Semiconductor ASA
3+
*
4+
* SPDX-License-Identifier: LicenseRef-BSD-5-Clause-Nordic
5+
*/
6+
/**
7+
* @file
8+
* @defgroup bt_mesh_plvl Generic Power Level Models
9+
* @{
10+
* @brief API for the Generic Power Level models.
11+
*/
12+
13+
#ifndef BT_MESH_GEN_PLVL_H__
14+
#define BT_MESH_GEN_PLVL_H__
15+
16+
#include <bluetooth/mesh.h>
17+
#include <bluetooth/mesh/model_types.h>
18+
19+
#ifdef __cplusplus
20+
extern "C" {
21+
#endif
22+
23+
/** @cond INTERNAL_HIDDEN */
24+
#define BT_MESH_PLVL_OP_LEVEL_GET BT_MESH_MODEL_OP_2(0x82, 0x15)
25+
#define BT_MESH_PLVL_OP_LEVEL_SET BT_MESH_MODEL_OP_2(0x82, 0x16)
26+
#define BT_MESH_PLVL_OP_LEVEL_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x17)
27+
#define BT_MESH_PLVL_OP_LEVEL_STATUS BT_MESH_MODEL_OP_2(0x82, 0x18)
28+
#define BT_MESH_PLVL_OP_LAST_GET BT_MESH_MODEL_OP_2(0x82, 0x19)
29+
#define BT_MESH_PLVL_OP_LAST_STATUS BT_MESH_MODEL_OP_2(0x82, 0x1A)
30+
#define BT_MESH_PLVL_OP_DEFAULT_GET BT_MESH_MODEL_OP_2(0x82, 0x1B)
31+
#define BT_MESH_PLVL_OP_DEFAULT_STATUS BT_MESH_MODEL_OP_2(0x82, 0x1C)
32+
#define BT_MESH_PLVL_OP_RANGE_GET BT_MESH_MODEL_OP_2(0x82, 0x1D)
33+
#define BT_MESH_PLVL_OP_RANGE_STATUS BT_MESH_MODEL_OP_2(0x82, 0x1E)
34+
#define BT_MESH_PLVL_OP_DEFAULT_SET BT_MESH_MODEL_OP_2(0x82, 0x1F)
35+
#define BT_MESH_PLVL_OP_DEFAULT_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x20)
36+
#define BT_MESH_PLVL_OP_RANGE_SET BT_MESH_MODEL_OP_2(0x82, 0x21)
37+
#define BT_MESH_PLVL_OP_RANGE_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x22)
38+
39+
#define BT_MESH_PLVL_MSG_LEN_LEVEL_GET 0
40+
#define BT_MESH_PLVL_MSG_MINLEN_LEVEL_SET 3
41+
#define BT_MESH_PLVL_MSG_MAXLEN_LEVEL_SET 5
42+
#define BT_MESH_PLVL_MSG_MINLEN_LEVEL_STATUS 2
43+
#define BT_MESH_PLVL_MSG_MAXLEN_LEVEL_STATUS 5
44+
#define BT_MESH_PLVL_MSG_LEN_LAST_GET 0
45+
#define BT_MESH_PLVL_MSG_LEN_LAST_STATUS 2
46+
#define BT_MESH_PLVL_MSG_LEN_DEFAULT_GET 0
47+
#define BT_MESH_PLVL_MSG_LEN_DEFAULT_STATUS 2
48+
#define BT_MESH_PLVL_MSG_LEN_RANGE_GET 0
49+
#define BT_MESH_PLVL_MSG_LEN_RANGE_STATUS 4
50+
#define BT_MESH_PLVL_MSG_LEN_DEFAULT_SET 2
51+
#define BT_MESH_PLVL_MSG_LEN_RANGE_SET 4
52+
/** @endcond */
53+
54+
/** Power Level set message parameters. */
55+
struct bt_mesh_plvl_set {
56+
/** Power Level. */
57+
u16_t power_lvl;
58+
/**
59+
* Transition time parameters for the state change. Setting the
60+
* transition to NULL makes the server use its default transition time
61+
* parameters.
62+
*/
63+
const struct bt_mesh_model_transition *transition;
64+
};
65+
66+
/** Power Level status message parameters. */
67+
struct bt_mesh_plvl_status {
68+
/** Current Power Level. */
69+
u16_t current;
70+
/** Target Power Level. */
71+
u16_t target;
72+
/**
73+
* Time remaining of the ongoing transition, or @ref K_FOREVER.
74+
* If there's no ongoing transition, @c remaining_time is 0.
75+
*/
76+
s32_t remaining_time;
77+
};
78+
79+
/** Power Level range parameters. */
80+
struct bt_mesh_plvl_range {
81+
u16_t min; /**< Minimum allowed Power Level. */
82+
u16_t max; /**< Maximum allowed Power Level. */
83+
};
84+
85+
/** Power Level range message parameters. */
86+
struct bt_mesh_plvl_range_status {
87+
/** Status of the previous operation. */
88+
enum bt_mesh_model_status status;
89+
/** Current Power Level range. */
90+
struct bt_mesh_plvl_range range;
91+
};
92+
93+
/**
94+
* @brief Convert Power Level to a percent.
95+
*
96+
* @param[in] plvl Raw Power Level.
97+
*
98+
* @return The Power Level in percent.
99+
*/
100+
static inline u8_t bt_mesh_plvl_to_percent(u16_t plvl)
101+
{
102+
return (100UL * plvl) / UINT16_MAX;
103+
}
104+
105+
/**
106+
* @brief Convert percent to raw Power Level.
107+
*
108+
* @param[in] plvl_percent Power Level in percent.
109+
*
110+
* @return The raw Power Level.
111+
*/
112+
static inline u16_t bt_mesh_plvl_from_percent(u8_t plvl_percent)
113+
{
114+
return (UINT16_MAX * plvl_percent) / 100;
115+
}
116+
117+
#ifdef __cplusplus
118+
}
119+
#endif
120+
121+
#endif /* BT_MESH_GEN_PLVL_H__ */
122+
123+
/** @} */

‎include/bluetooth/mesh/gen_plvl.rst‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
.. _bt_mesh_plvl_readme:
2+
3+
Generic Power Level models
4+
##########################
5+
6+
The Generic Power Level models allow remote control of power levels on a
7+
mesh device. Typical applications for the Generic Power Level model are
8+
heaters, fans and dimmer outlets.
9+
10+
There are two Generic Power Level models:
11+
12+
- :ref:`bt_mesh_plvl_srv_readme`
13+
- :ref:`bt_mesh_plvl_cli_readme`
14+
15+
.. _bt_mesh_plvl_srv_readme:
16+
17+
Generic Power Level Server
18+
==========================
19+
20+
The Generic Power Level Server controls the output power level of a peripheral
21+
on the Mesh-enabled device.
22+
23+
Generic Power Level Server adds two model instances in the composition data:
24+
25+
- The Generic Power Level Server
26+
- The Generic Power Level Setup Server
27+
28+
The two model instances share the states of the Generic Power Level Server,
29+
but accept different messages. This allows fine-grained control of the access
30+
rights for the Generic Power Level states, as the two model instances can be
31+
bound to different application keys.
32+
33+
The Generic Power Level Server is the "user facing" model instance in the pair,
34+
and only provides access to the Generic Power Level state, and its last
35+
non-zero value.
36+
37+
The Generic Power Level Setup Server provides access to the two metastates,
38+
Default Power and Power Range, allowing configurator devices to set up the
39+
range and default value for the Generic Power Level state.
40+
41+
States
42+
*******
43+
44+
**Generic Power Level**: ``u16_t``
45+
46+
The Generic Power Level state controls the Power level of an element, and
47+
ranges from 0 to 65535. The Generic Power Level state is bound to the
48+
Generic Level State of the :ref:`bt_mesh_lvl_srv_readme`:
49+
50+
::
51+
52+
Generic Power Level = Generic Level + 32768
53+
54+
The Generic OnOff state of the :ref:`bt_mesh_onoff_srv_readme` (extended
55+
through the :ref:`bt_mesh_ponoff_srv_readme`) is derived from the Power state:
56+
57+
::
58+
59+
Generic OnOff = (Generic Power Level > 0)
60+
61+
Conversely, if the Generic OnOff state is changed to Off, the Generic Power
62+
Level is set to 0. If the Generic OnOff state is changed to On and the Default
63+
Level state is set, the Generic Power level is set to the value of the Default
64+
level state. If the Generic OnOff state is changed to On and the Default Level
65+
state is not set, the Generic Power Level state is set to the last known
66+
non-zero value.
67+
68+
The Power state power up behavior is determined by the On Power Up state of the
69+
extended :ref:`bt_mesh_ponoff_srv_readme`:
70+
71+
- :cpp:enumerator:`BT_MESH_ON_POWER_UP_OFF <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_OFF>`:
72+
The Power level is set to 0 on power up.
73+
- :cpp:enumerator:`BT_MESH_ON_POWER_UP_ON <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_ON>`:
74+
The Power level is set to Default Level on power up, or the last known
75+
non-zero Power level if the Default level is not set.
76+
- :cpp:enumerator:`BT_MESH_ON_POWER_UP_RESTORE <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_RESTORE>`:
77+
The Power level is set to the last known Power level (zero or otherwise).
78+
79+
The user is expected to hold the state memory and provide access to the state
80+
through the :cpp:type:`bt_mesh_plvl_srv_handlers` handler structure.
81+
82+
**Default Power**: ``s16_t``
83+
84+
The Default Power state is a metastate that controls the default non-zero
85+
Generic Power Level. It is used when the Generic Power Level turns on, but its
86+
exact level is not specified.
87+
88+
The memory for the Default Power state is held by the model, and the
89+
application may receive updates on state changes through the
90+
:cpp:member:`bt_mesh_plvl_srv_handlers::default_update` callback.
91+
92+
**Power Range**: :cpp:type:`bt_mesh_plvl_range`
93+
94+
The Power Range state is a metastate that determines the accepted Generic Power
95+
Level range.
96+
97+
If the Generic Power Level is set to a value outside the current Power Range,
98+
the actual Generic Power Level is moved to fit inside the range.
99+
100+
If the Power Level Range changes to exclude the current Generic Power Level,
101+
the Generic Power Level should be changed accordingly. Note that the Generic
102+
Power Level may always be set to zero, even if this is outside the current
103+
Power Range.
104+
105+
The memory for the Power Range state is held by the model, and the
106+
application may receive updates on state changes through the
107+
:cpp:member:`bt_mesh_plvl_srv_handlers::range_update` callback.
108+
109+
Extended models
110+
****************
111+
112+
The Generic Power Level Server extends the following models:
113+
114+
- :ref:`bt_mesh_lvl_srv_readme`
115+
- :ref:`bt_mesh_ponoff_srv_readme`
116+
117+
As the states of both extended models are bound to states in the Generic Power
118+
Level Server, the states of the extended models are not exposed directly to the
119+
application.
120+
121+
Persistent storage
122+
*******************
123+
124+
The Generic Power Level Server stores any changes to the Default Power and
125+
Power Range states, as well as the last known non-zero Generic Power Level and
126+
whether the Generic Power Level is on or off. This information is used to
127+
reestablish the correct Generic Power Level when the device powers up.
128+
129+
API documentation
130+
******************
131+
132+
| Header file: :file:`include/bluetooth/mesh/gen_plvl_srv.h`
133+
| Source file: :file:`subsys/bluetooth/mesh/gen_plvl_srv.c`
134+
135+
.. doxygengroup:: bt_mesh_plvl_srv
136+
:project: nrf
137+
:members:
138+
139+
----
140+
141+
.. _bt_mesh_plvl_cli_readme:
142+
143+
Generic Power Level Client
144+
==========================
145+
146+
The Generic Power Level Client model remotely controls the state of a Generic
147+
Power Level Server model.
148+
149+
Contrary to the Server model, the Client only creates a single model instance
150+
in the mesh composition data. The Generic Power Level Client may send
151+
messages to both the Generic Power Level Server and the Generic Power Level
152+
Setup Server, as long as it has the right application keys.
153+
154+
Extended models
155+
****************
156+
157+
None.
158+
159+
Persistent storage
160+
*******************
161+
162+
None.
163+
164+
API documentation
165+
******************
166+
167+
| Header file: :file:`include/bluetooth/mesh/gen_plvl_cli.h`
168+
| Source file: :file:`subsys/bluetooth/mesh/gen_plvl_cli.c`
169+
170+
.. doxygengroup:: bt_mesh_plvl_cli
171+
:project: nrf
172+
:members:
173+
174+
----
175+
176+
Common types
177+
=============
178+
179+
| Header file: :file:`include/bluetooth/mesh/gen_plvl.h`
180+
181+
.. doxygengroup:: bt_mesh_plvl
182+
:project: nrf
183+
:members:

0 commit comments

Comments
 (0)