Skip to content

Commit 44bc7e7

Browse files
trond-snekvikjoerchan
trond-snekvik
authored and
joerchan
committed
Bluetooth: Mesh: Generic Property models
Adds the Generic Property Client and the Generic Property Server models. Also adds the Mesh Properties header, restructuring the Bluetooth Mesh Profile documentation page to keep models as a subpage next to properties. Signed-off-by: Trond Einar Snekvik <[email protected]>
1 parent 2d2a2d1 commit 44bc7e7

File tree

14 files changed

+2060
-24
lines changed

14 files changed

+2060
-24
lines changed

‎include/bluetooth/mesh.rst‎

Lines changed: 8 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,17 @@
11
.. _bt_mesh:
22

3-
Bluetooth Mesh Models
4-
######################
3+
Bluetooth Mesh Profile
4+
#######################
55

6-
Nordic Semiconductor provides a variety of model implementations from the Mesh
7-
Model Specification.
6+
The nRF Connect SDK has experimental support for the Bluetooth Mesh
7+
Specification through the Zephyr :ref:`zephyr:bluetooth_mesh` implementation.
88

9-
Here you can find documentation for these model implementations, including API
10-
documentation.
9+
Nordic Semiconductor additionally provides some modules to aid in the
10+
development of Bluetooth Mesh-based applications:
1111

1212
.. toctree::
1313
:maxdepth: 1
14-
:caption: Model implementations:
15-
:glob:
1614

17-
../../include/bluetooth/mesh/*
15+
mesh/models.rst
16+
mesh/properties.rst
1817

19-
20-
Common model types
21-
===================
22-
23-
Models in the Bluetooth Mesh Model Specification share some common types, that
24-
are collected in a single header file.
25-
26-
API documentation
27-
******************
28-
29-
| Header file: :file:`include/bluetooth/mesh/model_types.h`
30-
31-
.. doxygengroup:: bt_mesh_model_types
32-
:project: nrf
33-
:members:

‎include/bluetooth/mesh/gen_prop.h‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
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_prop Generic Property models
10+
* @{
11+
* @brief API for the Generic Property models.
12+
*/
13+
14+
#ifndef BT_MESH_GEN_PROP_H__
15+
#define BT_MESH_GEN_PROP_H__
16+
17+
#include <bluetooth/mesh.h>
18+
#include <bluetooth/mesh/properties.h>
19+
20+
#ifdef __cplusplus
21+
extern "C" {
22+
#endif
23+
24+
/** @cond INTERNAL_HIDDEN */
25+
#define BT_MESH_PROP_OP_MFR_PROPS_GET BT_MESH_MODEL_OP_2(0x82, 0x2A)
26+
#define BT_MESH_PROP_OP_MFR_PROPS_STATUS BT_MESH_MODEL_OP_1(0x43)
27+
#define BT_MESH_PROP_OP_MFR_PROP_GET BT_MESH_MODEL_OP_2(0x82, 0x2B)
28+
#define BT_MESH_PROP_OP_MFR_PROP_SET BT_MESH_MODEL_OP_1(0x44)
29+
#define BT_MESH_PROP_OP_MFR_PROP_SET_UNACK BT_MESH_MODEL_OP_1(0x45)
30+
#define BT_MESH_PROP_OP_MFR_PROP_STATUS BT_MESH_MODEL_OP_1(0x46)
31+
#define BT_MESH_PROP_OP_ADMIN_PROPS_GET BT_MESH_MODEL_OP_2(0x82, 0x2C)
32+
#define BT_MESH_PROP_OP_ADMIN_PROPS_STATUS BT_MESH_MODEL_OP_1(0x47)
33+
#define BT_MESH_PROP_OP_ADMIN_PROP_GET BT_MESH_MODEL_OP_2(0x82, 0x2D)
34+
#define BT_MESH_PROP_OP_ADMIN_PROP_SET BT_MESH_MODEL_OP_1(0x48)
35+
#define BT_MESH_PROP_OP_ADMIN_PROP_SET_UNACK BT_MESH_MODEL_OP_1(0x49)
36+
#define BT_MESH_PROP_OP_ADMIN_PROP_STATUS BT_MESH_MODEL_OP_1(0x4A)
37+
#define BT_MESH_PROP_OP_USER_PROPS_GET BT_MESH_MODEL_OP_2(0x82, 0x2E)
38+
#define BT_MESH_PROP_OP_USER_PROPS_STATUS BT_MESH_MODEL_OP_1(0x4B)
39+
#define BT_MESH_PROP_OP_USER_PROP_GET BT_MESH_MODEL_OP_2(0x82, 0x2F)
40+
#define BT_MESH_PROP_OP_USER_PROP_SET BT_MESH_MODEL_OP_1(0x4C)
41+
#define BT_MESH_PROP_OP_USER_PROP_SET_UNACK BT_MESH_MODEL_OP_1(0x4D)
42+
#define BT_MESH_PROP_OP_USER_PROP_STATUS BT_MESH_MODEL_OP_1(0x4E)
43+
#define BT_MESH_PROP_OP_CLIENT_PROPS_GET BT_MESH_MODEL_OP_1(0x4F)
44+
#define BT_MESH_PROP_OP_CLIENT_PROPS_STATUS BT_MESH_MODEL_OP_1(0x50)
45+
46+
#define BT_MESH_PROP_MSG_LEN_PROPS_GET 0
47+
#define BT_MESH_PROP_MSG_MINLEN_PROPS_STATUS 0
48+
#define BT_MESH_PROP_MSG_MAXLEN_PROPS_STATUS (2 * CONFIG_BT_MESH_PROP_MAXCOUNT)
49+
#define BT_MESH_PROP_MSG_LEN_PROP_GET 2
50+
#define BT_MESH_PROP_MSG_MINLEN_PROP_STATUS 3
51+
#define BT_MESH_PROP_MSG_MAXLEN_PROP_STATUS (3 + CONFIG_BT_MESH_PROP_MAXSIZE)
52+
#define BT_MESH_PROP_MSG_LEN_MFR_PROP_SET 3
53+
#define BT_MESH_PROP_MSG_MINLEN_ADMIN_PROP_SET 3
54+
#define BT_MESH_PROP_MSG_MAXLEN_ADMIN_PROP_SET (3 + CONFIG_BT_MESH_PROP_MAXSIZE)
55+
#define BT_MESH_PROP_MSG_MINLEN_USER_PROP_SET 2
56+
#define BT_MESH_PROP_MSG_MAXLEN_USER_PROP_SET (2 + CONFIG_BT_MESH_PROP_MAXSIZE)
57+
/** @endcond */
58+
59+
/** Access flags for properties */
60+
enum bt_mesh_prop_access {
61+
/** Access to the property is prohibited. */
62+
BT_MESH_PROP_ACCESS_PROHIBITED = 0,
63+
/** Property may be read. */
64+
BT_MESH_PROP_ACCESS_READ = BIT(0),
65+
/** Property may be written. */
66+
BT_MESH_PROP_ACCESS_WRITE = BIT(1),
67+
/** Property may be read or written. */
68+
BT_MESH_PROP_ACCESS_READ_WRITE =
69+
(BT_MESH_PROP_ACCESS_READ | BT_MESH_PROP_ACCESS_WRITE),
70+
};
71+
72+
/** Property Server kinds. */
73+
enum bt_mesh_prop_srv_kind {
74+
/** Manufacturer property server. */
75+
BT_MESH_PROP_SRV_KIND_MFR,
76+
/** Admin property server. */
77+
BT_MESH_PROP_SRV_KIND_ADMIN,
78+
/** User property server. */
79+
BT_MESH_PROP_SRV_KIND_USER,
80+
/** Client property server. */
81+
BT_MESH_PROP_SRV_KIND_CLIENT,
82+
};
83+
84+
/** Property representation. */
85+
struct bt_mesh_prop {
86+
/** Property ID. @sa bt_mesh_property_ids. */
87+
u16_t id;
88+
/** User access flags for the property. */
89+
enum bt_mesh_prop_access user_access;
90+
};
91+
92+
/** Property value representation. */
93+
struct bt_mesh_prop_val {
94+
struct bt_mesh_prop meta; /**< Metadata for this property. */
95+
size_t size; /**< Size of the property value. */
96+
u8_t *value; /**< Property value. */
97+
};
98+
99+
#ifdef __cplusplus
100+
}
101+
#endif
102+
103+
#endif /* BT_MESH_GEN_PROP_H__ */
104+
105+
/** @} */

‎include/bluetooth/mesh/gen_prop.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.. _bt_mesh_prop_readme:
2+
3+
Generic Property models
4+
#######################
5+
6+
The Generic Property models allow remote access to the Device Properties of a
7+
mesh node. Read more about device properties in
8+
:ref:`bt_mesh_properties_readme`.
9+
10+
There Generic Property models fall into two categories:
11+
12+
- :ref:`bt_mesh_prop_srv_readme`
13+
- :ref:`bt_mesh_prop_cli_readme`
14+
15+
Configuration
16+
==============
17+
18+
There are two configuration parameters associated with the Generic Property
19+
models:
20+
21+
- :option:`CONFIG_BT_MESH_PROP_MAXSIZE`: The largest available property value.
22+
- :option:`CONFIG_BT_MESH_PROP_MAXCOUNT`: The largest number of properties
23+
available on a single Generic Property Server.
24+
25+
.. _bt_mesh_prop_srv_readme:
26+
27+
Generic Property Servers
28+
========================
29+
30+
A Generic Property Server holds a list of Device Properties.
31+
There are four different property servers:
32+
33+
- **Generic Manufacturer Property Server**: Provides access to Manufacturer
34+
properties, which are read-only properties set by the device manufacturer.
35+
- **Generic Admin Property Server**: Provides access to Admin properties, which
36+
can be read and written to.
37+
- **Generic User Property Server**: Provides access to both Admin and
38+
Manufacturer properties on its element, but only if the Property owner allows
39+
it.
40+
- **Generic Client Property Server**: Provides a list of all properties
41+
supported by the Generic Property Client on the same element. The Client
42+
Property Server does not actually own any properties, and does not need the
43+
user to provide access to any property values.
44+
45+
Typically, only the administrator of the mesh network should have access to the
46+
Admin or Manufacturer servers, all other mesh nodes should operate on the User
47+
server. The Manufacturer and Admin servers may change the User property access
48+
rights for each individual Property it owns at runtime.
49+
50+
The Manufacturer and Admin Servers must provide a list of all Properties they
51+
own in the initialization of the model. Access to the property values should be
52+
provided through the server getter (:cpp:member:`bt_mesh_prop_srv::get`) and
53+
setter (:cpp:member:`bt_mesh_prop_srv::set`) callbacks.
54+
55+
The User Property server does not own any properties, but relies on Admin and
56+
Manufacturer servers on the same element to provide access to theirs. An
57+
element with a User Property Server and no Admin or Manufacturer Servers is
58+
useless.
59+
60+
The model keeps the user access field of each Admin and Manufacturer property
61+
in persistent storage. The property values themselves have to be stored by the
62+
application.
63+
64+
The set of Property IDs and their order cannot be changed.
65+
66+
States
67+
*******
68+
69+
**Device Properties**: :cpp:type:`bt_mesh_prop`
70+
71+
A single server may own several Device Properties, which are accessed by their
72+
Property ID. Each Property holds a value and a user access parameter, which
73+
controls the Property's availability to a Generic User Property Server on the
74+
same element.
75+
76+
The Device properties have slightly different access restrictions depending on
77+
the type of server that owns them:
78+
79+
- **Manufacturer Property**: The value can only be read.
80+
- **Admin Property**: The value can be read and written.
81+
- **Client Property**: Has no associated value, and is only a listing of the
82+
property IDs supported by the accompanying Generic Property Client.
83+
84+
Extended models
85+
****************
86+
87+
The Generic Admin Property Server and Generic Manufacturer Property Server both
88+
extend the Generic User Property Server. As a consequence, a single element can
89+
only hold one Generic Manufacturer or Generic Admin Property Server.
90+
91+
Persistent storage
92+
*******************
93+
94+
The Generic Manufacturer Property Server and Generic Admin Property Server
95+
models will store changes to the user access rights of their properties.
96+
Any permanent changes to the property values themselves should be stored
97+
manually by the application.
98+
99+
API documentation
100+
******************
101+
102+
| Header file: :file:`include/bluetooth/mesh/gen_prop_srv.h`
103+
| Source file: :file:`subsys/bluetooth/mesh/gen_prop_srv.c`
104+
105+
.. doxygengroup:: bt_mesh_prop_srv
106+
:project: nrf
107+
:members:
108+
109+
----
110+
111+
.. _bt_mesh_prop_cli_readme:
112+
113+
Generic Property Client
114+
=======================
115+
116+
The Generic Property Client model can access properties from a Property Server
117+
remotely. The Property Client can talk directly to all types of Property
118+
Servers, but only if it shares an application key with the target server.
119+
120+
Generally, the Property Client should only target User Property Servers, unless
121+
it is part of some network administrator node that is responsible for
122+
configuring the other mesh nodes.
123+
124+
To ease configuration, the Property Client can be paired with a Client Property
125+
Server that lists which properties this Client will request.
126+
127+
Extended models
128+
****************
129+
130+
None.
131+
132+
API documentation
133+
******************
134+
135+
| Header file: :file:`include/bluetooth/mesh/gen_prop_cli.h`
136+
| Source file: :file:`subsys/bluetooth/mesh/gen_prop_cli.c`
137+
138+
.. doxygengroup:: bt_mesh_prop_cli
139+
:project: nrf
140+
:members:
141+
142+
----
143+
144+
Common types
145+
=============
146+
147+
| Header file: :file:`include/bluetooth/mesh/gen_prop.h`
148+
149+
.. doxygenfile:: gen_prop.h
150+
:project: nrf

0 commit comments

Comments
 (0)