Skip to content

Commit 512bcdc

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

File tree

9 files changed

+844
-0
lines changed

9 files changed

+844
-0
lines changed

‎include/bluetooth/mesh/gen_ponoff.h‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
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_ponoff Generic Power OnOff Models
9+
* @{
10+
* @brief API for the Generic Power OnOff models.
11+
*/
12+
13+
#ifndef BT_MESH_GEN_PONOFF_H__
14+
#define BT_MESH_GEN_PONOFF_H__
15+
16+
#include <bluetooth/mesh.h>
17+
18+
#ifdef __cplusplus
19+
extern "C" {
20+
#endif
21+
22+
/** @cond INTERNAL_HIDDEN */
23+
#define BT_MESH_PONOFF_OP_GET BT_MESH_MODEL_OP_2(0x82, 0x11)
24+
#define BT_MESH_PONOFF_OP_STATUS BT_MESH_MODEL_OP_2(0x82, 0x12)
25+
#define BT_MESH_PONOFF_OP_SET BT_MESH_MODEL_OP_2(0x82, 0x13)
26+
#define BT_MESH_PONOFF_OP_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x14)
27+
28+
#define BT_MESH_PONOFF_MSG_LEN_GET 0
29+
#define BT_MESH_PONOFF_MSG_LEN_STATUS 1
30+
#define BT_MESH_PONOFF_MSG_LEN_SET 1
31+
/** @endcond */
32+
33+
/** Generic Power OnOff On Power Up state values. */
34+
enum bt_mesh_on_power_up {
35+
/** On power up, set state to off. */
36+
BT_MESH_ON_POWER_UP_OFF,
37+
/** On power up, set state to on. */
38+
BT_MESH_ON_POWER_UP_ON,
39+
/** On power up, Restore the previous state value. */
40+
BT_MESH_ON_POWER_UP_RESTORE,
41+
/** Invalid power up state. */
42+
BT_MESH_ON_POWER_UP_INVALID,
43+
};
44+
45+
#ifdef __cplusplus
46+
}
47+
#endif
48+
49+
#endif /* BT_MESH_GEN_PONOFF_H__ */
50+
51+
/** @} */

‎include/bluetooth/mesh/gen_ponoff.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
.. _bt_mesh_ponoff_readme:
2+
3+
Generic Power OnOff models
4+
##########################
5+
6+
The Generic Power OnOff models allow remote control of the power up behavior
7+
on a mesh device.
8+
9+
There are two Generic Power OnOff models:
10+
11+
- :ref:`bt_mesh_ponoff_srv_readme`
12+
- :ref:`bt_mesh_ponoff_cli_readme`
13+
14+
.. _bt_mesh_ponoff_srv_readme:
15+
16+
Generic Power OnOff Server
17+
==========================
18+
19+
The Generic Power OnOff server controls the power up behavior of other models
20+
on its element. The Generic Power OnOff server depends on the
21+
:option:`CONFIG_BT_SETTINGS` to be enabled to work properly. Unless
22+
:option:`CONFIG_BT_SETTINGS` is explicitly disabled, including the Generic
23+
Power OnOff Server will enable :option:`CONFIG_BT_SETTINGS`.
24+
25+
Generic Power OnOff Server adds two model instances in the composition data:
26+
27+
- The Generic Power OnOff Server
28+
- The Generic Power OnOff Setup Server
29+
30+
The two model instances share the states of the Generic Power OnOff Server,
31+
but accept different messages. This allows fine-grained control of the access
32+
rights for the Generic Power OnOff state, as the two model instances can be
33+
bound to different application keys.
34+
35+
The Generic Power OnOff Server only provides read access to the Generic
36+
On Power Up state.
37+
38+
The Generic Power OnOff Setup Server provides write access to the Generic
39+
On Power Up state, allowing configurator devices to change the power up
40+
behavior of the element.
41+
42+
States
43+
*******
44+
45+
**Generic On Power Up**: :cpp:type:`bt_mesh_on_power_up`.
46+
47+
The Generic On Power Up state controls the initial value of the extended
48+
Generic OnOff state when the device powers up:
49+
50+
- On Power Up is
51+
:cpp:enumerator:`BT_MESH_ON_POWER_UP_OFF <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_OFF>`:
52+
The OnOff state is initialized to Off.
53+
- On Power Up is
54+
:cpp:enumerator:`BT_MESH_ON_POWER_UP_ON <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_ON>`:
55+
The OnOff state is initialized to On. If any other states are bound to the On
56+
Power Up state, they are initialized to their default values.
57+
- On Power Up is
58+
:cpp:enumerator:`BT_MESH_ON_POWER_UP_RESTORE <bt_mesh_ponoff::BT_MESH_ON_POWER_UP_RESTORE>`:
59+
The OnOff state is initialized to its last known value. If any other states
60+
are bound to the On Power Up state, they are initialized to their default
61+
values.
62+
63+
The memory for the Generic On Power Up state is contained in the model
64+
structure, and state changes can be observed with the
65+
:cpp:member:`bt_mesh_ponoff_srv::update` callback.
66+
67+
Extended models
68+
****************
69+
70+
The Generic Power OnOff Server extends the following models:
71+
72+
- :ref:`bt_mesh_onoff_srv_readme`
73+
- :ref:`bt_mesh_dtt_srv_readme`
74+
75+
The On Power Up state is bound to the Generic OnOff state of the extended
76+
Generic OnOff model through its power up behavior. No other state bindings
77+
are present, and the callbacks for both the Generic OnOff server and the
78+
Generic DTT server are forwarded to the application as they are.
79+
80+
Persistent storage
81+
*******************
82+
83+
The Generic On Power Up state is stored persistently, along with the current
84+
Generic OnOff state of the extended :ref:`bt_mesh_onoff_srv_readme`.
85+
86+
API documentation
87+
******************
88+
89+
| Header file: :file:`include/bluetooth/mesh/gen_ponoff_srv.h`
90+
| Source file: :file:`subsys/bluetooth/mesh/gen_ponoff_srv.c`
91+
92+
.. doxygengroup:: bt_mesh_ponoff_srv
93+
:project: nrf
94+
:members:
95+
96+
----
97+
98+
.. _bt_mesh_ponoff_cli_readme:
99+
100+
Generic Power OnOff Client
101+
==========================
102+
103+
The Generic Power OnOff Client model remotely controls the state of a Generic
104+
Power OnOff Server model.
105+
106+
Contrary to the Generic Power OnOff Server, the Generic Power OnOff Client only
107+
adds one model instance to the composition data. The Generic Power OnOff Client
108+
may send messages to both the Generic Power OnOff Server and the Generic Power
109+
OnOff Setup server, as long as it has the right application keys.
110+
111+
Extended models
112+
****************
113+
114+
None.
115+
116+
Persistent storage
117+
*******************
118+
119+
None.
120+
121+
API documentation
122+
******************
123+
124+
| Header file: :file:`include/bluetooth/mesh/gen_ponoff_cli.h`
125+
| Source file: :file:`subsys/bluetooth/mesh/gen_ponoff_cli.c`
126+
127+
.. doxygengroup:: bt_mesh_ponoff_cli
128+
:project: nrf
129+
:members:
130+
131+
----
132+
133+
Common types
134+
=============
135+
136+
| Header file: :file:`include/bluetooth/mesh/gen_ponoff.h`
137+
138+
.. doxygengroup:: bt_mesh_ponoff
139+
:project: nrf
140+
:members:

‎include/bluetooth/mesh/gen_ponoff_cli.h‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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_ponoff_cli Generic Power OnOff Client
10+
* @{
11+
* @brief API for the Generic Power OnOff Client.
12+
*/
13+
#ifndef BT_MESH_GEN_PONOFF_CLI_H__
14+
#define BT_MESH_GEN_PONOFF_CLI_H__
15+
16+
#include <bluetooth/mesh/gen_ponoff.h>
17+
#include <bluetooth/mesh/model_types.h>
18+
19+
#ifdef __cplusplus
20+
extern "C" {
21+
#endif
22+
23+
struct bt_mesh_ponoff_cli;
24+
25+
/** @def BT_MESH_PONOFF_CLI_INIT
26+
*
27+
* @brief Initialization parameters for @ref bt_mesh_ponoff_cli.
28+
*
29+
* @param[in] _power_onoff_status_handler OnPowerUp status handler.
30+
*/
31+
#define BT_MESH_PONOFF_CLI_INIT(_power_onoff_status_handler) \
32+
{ \
33+
.status_handler = _power_onoff_status_handler, \
34+
.pub = { .msg = NET_BUF_SIMPLE(BT_MESH_MODEL_BUF_LEN( \
35+
BT_MESH_PONOFF_OP_SET, \
36+
BT_MESH_PONOFF_MSG_LEN_SET)) }, \
37+
}
38+
39+
/** @def BT_MESH_MODEL_PONOFF_CLI
40+
*
41+
* @brief Generic Power OnOff Client model composition data entry.
42+
*
43+
* @param[in] _cli Pointer to a @ref bt_mesh_ponoff_cli instance.
44+
*/
45+
#define BT_MESH_MODEL_PONOFF_CLI(_cli) \
46+
BT_MESH_MODEL_CB(BT_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI, \
47+
_bt_mesh_ponoff_cli_op, &(_cli)->pub, \
48+
BT_MESH_MODEL_USER_DATA( \
49+
struct bt_mesh_ponoff_cli, _cli), \
50+
&_bt_mesh_ponoff_cli_cb)
51+
52+
/**
53+
* Generic Power OnOff client instance.
54+
*
55+
* Should be initialized with @ref BT_MESH_PONOFF_CLI_INIT.
56+
*/
57+
struct bt_mesh_ponoff_cli {
58+
/** Model entry pointer. */
59+
struct bt_mesh_model *model;
60+
/** Publish parameters. */
61+
struct bt_mesh_model_pub pub;
62+
/** Response context for tracking acknowledged messages. */
63+
struct bt_mesh_model_ack_ctx ack_ctx;
64+
65+
/** @brief OnPowerUp status message handler.
66+
*
67+
* @param[in] cli Client that received the status message.
68+
* @param[in] ctx Message context the message was received with.
69+
* @param[in] on_power_up The OnPowerUp state presented in the message.
70+
*/
71+
void (*const status_handler)(struct bt_mesh_ponoff_cli *cli,
72+
struct bt_mesh_msg_ctx *ctx,
73+
enum bt_mesh_on_power_up on_power_up);
74+
};
75+
76+
/** @brief Get the OnPowerUp state of a server.
77+
*
78+
* This call is blocking if the @p rsp buffer is non-NULL. Otherwise, this
79+
* function will return, and the response will be passed to the
80+
* @ref bt_mesh_ponoff_cli::status_handler callback.
81+
*
82+
* @param[in] cli Power OnOff client to send the message on.
83+
* @param[in] ctx Context of the message, or NULL to send on the configured
84+
* publish parameters.
85+
* @param[out] rsp Response buffer to put the received response in, or NULL to
86+
* process the response in the status handler callback.
87+
*
88+
* @retval 0 Successfully sent a get message. If a response buffer is
89+
* provided, it has been populated.
90+
* @retval -EALREADY A blocking request is already in progress.
91+
* @retval -EADDRNOTAVAIL A message context was not provided and publishing is
92+
* not configured.
93+
* @retval -EAGAIN The device has not been provisioned.
94+
* @retval -ETIMEDOUT The request timed out without a response.
95+
*/
96+
int bt_mesh_ponoff_cli_on_power_up_get(struct bt_mesh_ponoff_cli *cli,
97+
struct bt_mesh_msg_ctx *ctx,
98+
enum bt_mesh_on_power_up *rsp);
99+
100+
/** @brief Set the OnPowerUp state of a server.
101+
*
102+
* @param[in] cli Power OnOff client to send the message on.
103+
* @param[in] ctx Context of the message, or NULL to send with the configured
104+
* publish parameters.
105+
* @param[in] on_power_up New OnPowerUp state of the server.
106+
* @param[out] rsp Response buffer to put the received response in, or NULL to
107+
* send an unacknowledged message.
108+
*
109+
* @retval 0 Successfully sent a set message. If a response buffer is
110+
* provided, it has been populated.
111+
* @retval -EALREADY A blocking request is already in progress.
112+
* @retval -EADDRNOTAVAIL A message context was not provided and publishing is
113+
* not configured.
114+
* @retval -EAGAIN The device has not been provisioned.
115+
* @retval -ETIMEDOUT The request timed out without a response.
116+
*/
117+
int bt_mesh_ponoff_cli_on_power_up_set(struct bt_mesh_ponoff_cli *cli,
118+
struct bt_mesh_msg_ctx *ctx,
119+
enum bt_mesh_on_power_up on_power_up,
120+
enum bt_mesh_on_power_up *rsp);
121+
122+
/** @cond INTERNAL_HIDDEN */
123+
extern const struct bt_mesh_model_op _bt_mesh_ponoff_cli_op[];
124+
extern const struct bt_mesh_model_cb _bt_mesh_ponoff_cli_cb;
125+
/** @endcond */
126+
127+
#ifdef __cplusplus
128+
}
129+
#endif
130+
131+
#endif /* BT_MESH_GEN_PONOFF_CLI_H__ */
132+
133+
/** @} */

0 commit comments

Comments
 (0)