Skip to content

Commit 2d2a2d1

Browse files
trond-snekvikjoerchan
trond-snekvik
authored and
joerchan
committed
Bluetooth: Mesh: Generic Location models
Adds the Generic Location Client and Generic Location Server models. Signed-off-by: Trond Einar Snekvik <[email protected]>
1 parent db1290f commit 2d2a2d1

File tree

10 files changed

+1212
-0
lines changed

10 files changed

+1212
-0
lines changed

‎include/bluetooth/mesh/gen_loc.h‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
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_loc Generic Location models
10+
* @{
11+
* @brief API for the Generic Location models.
12+
*/
13+
14+
#ifndef BT_MESH_GEN_LOC_H__
15+
#define BT_MESH_GEN_LOC_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_LOC_OP_GLOBAL_GET BT_MESH_MODEL_OP_2(0x82, 0x25)
25+
#define BT_MESH_LOC_OP_GLOBAL_STATUS BT_MESH_MODEL_OP_1(0x40)
26+
#define BT_MESH_LOC_OP_GLOBAL_SET BT_MESH_MODEL_OP_1(0x41)
27+
#define BT_MESH_LOC_OP_GLOBAL_SET_UNACK BT_MESH_MODEL_OP_1(0x42)
28+
#define BT_MESH_LOC_OP_LOCAL_GET BT_MESH_MODEL_OP_2(0x82, 0x26)
29+
#define BT_MESH_LOC_OP_LOCAL_STATUS BT_MESH_MODEL_OP_2(0x82, 0x27)
30+
#define BT_MESH_LOC_OP_LOCAL_SET BT_MESH_MODEL_OP_2(0x82, 0x28)
31+
#define BT_MESH_LOC_OP_LOCAL_SET_UNACK BT_MESH_MODEL_OP_2(0x82, 0x29)
32+
33+
#define BT_MESH_LOC_MSG_LEN_GLOBAL_GET 0
34+
#define BT_MESH_LOC_MSG_LEN_GLOBAL_STATUS 10
35+
#define BT_MESH_LOC_MSG_LEN_GLOBAL_SET 10
36+
#define BT_MESH_LOC_MSG_LEN_LOCAL_GET 0
37+
#define BT_MESH_LOC_MSG_LEN_LOCAL_STATUS 9
38+
#define BT_MESH_LOC_MSG_LEN_LOCAL_SET 9
39+
/** @endcond */
40+
41+
/**
42+
* @defgroup bt_mesh_loc_altitude_defines Defines for altitude.
43+
* Boundaries and special values for the altitude.
44+
* @{
45+
*/
46+
/** Highest altitude that can be represented */
47+
#define BT_MESH_LOC_ALTITUDE_MAX 32765
48+
/** Altitude is unknown or not configured. */
49+
#define BT_MESH_LOC_ALTITUDE_UNKNOWN 0x7fff
50+
/** Altitude is out of bounds. */
51+
#define BT_MESH_LOC_ALTITUDE_TOO_LARGE 0x7ffe
52+
/** @} */
53+
54+
/**
55+
* @defgroup bt_mesh_loc_floor_number_defines Defines for floor number.
56+
* Boundaries and special values for the local floor number.
57+
* @{
58+
*/
59+
/** Lowest floor number that can be represented. */
60+
#define BT_MESH_LOC_FLOOR_NUMBER_MIN (-20)
61+
/** Highest floor number that can be represented. */
62+
#define BT_MESH_LOC_FLOOR_NUMBER_MAX 232
63+
/** Ground floor (where the ground floor is referred to as floor 0) */
64+
#define BT_MESH_LOC_FLOOR_NUMBER_GROUND_FLOOR_0 0xfc
65+
/** Ground floor (where the ground floor is referred to as floor 1) */
66+
#define BT_MESH_LOC_FLOOR_NUMBER_GROUND_FLOOR_1 0xfd
67+
/** Unknown or unconfigured floor number. */
68+
#define BT_MESH_LOC_FLOOR_NUMBER_UNKNOWN 0xff
69+
/** @} */
70+
71+
/** Global location parameters. */
72+
struct bt_mesh_loc_global {
73+
/** Global WGS84 North coordinate in degrees. */
74+
double latitude;
75+
/** Global WGS84 East coordinate in degrees. */
76+
double longitude;
77+
/**
78+
* Global altitude above the WGS84 datum in meters.
79+
* @sa bt_mesh_loc_altitude_defines
80+
*/
81+
s16_t altitude;
82+
};
83+
84+
/** Local location parameters. */
85+
struct bt_mesh_loc_local {
86+
/** Local north position in decimeters. */
87+
s16_t north;
88+
/** Local east position in decimeters. */
89+
s16_t east;
90+
/** Local altitude in decimeters. @sa bt_mesh_loc_altitude_defines */
91+
s16_t altitude;
92+
/** Floor number. @sa bt_mesh_loc_floor_number_defines */
93+
s16_t floor_number;
94+
/** Whether the device is movable. */
95+
bool is_mobile;
96+
/** Time since the previous position update, @ref K_FOREVER. */
97+
s32_t time_delta;
98+
/** Precision of the location in millimeters. */
99+
u32_t precision_mm;
100+
};
101+
102+
#ifdef __cplusplus
103+
}
104+
#endif
105+
106+
#endif /* BT_MESH_GEN_LOC_H__ */
107+
108+
/** @} */

‎include/bluetooth/mesh/gen_loc.rst‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
.. _bt_mesh_loc_readme:
2+
3+
Generic Location models
4+
#######################
5+
6+
The Generic Location models allow remote monitoring of the location status of
7+
a mesh device.
8+
9+
There are two Generic Location models:
10+
11+
- :ref:`bt_mesh_loc_srv_readme`
12+
- :ref:`bt_mesh_loc_cli_readme`
13+
14+
.. _bt_mesh_loc_srv_readme:
15+
16+
Generic Location Server
17+
=======================
18+
19+
The Generic Location Server provides location information about the device.
20+
The location data is split up into two separate states: Global and Local.
21+
The Global Location represents the device location in the world, while the
22+
Local Location represents the device location relative to a local coordinate
23+
system, for instance inside a building.
24+
25+
The Generic Location Server adds two model instances in the composition data:
26+
27+
- The Generic Location Server
28+
- The Generic Location Setup Server
29+
30+
The two model instances share the states of the Generic Location Server, but
31+
accept different messages. This allows fine-grained control of the access
32+
rights for the location states, as the two model instances can be bound to
33+
different application keys.
34+
35+
The Generic Location Server allows observation of the location states, as it
36+
only exposes get-messages for the location states. This is typically the
37+
user facing model instance, as the device location shouldn't normally be
38+
configurable by the users.
39+
40+
The Generic Location Setup Server allows configuration of the location states
41+
by exposing set-messages for the location states. This model instance can be
42+
used to configure the location information of the device, for instance during
43+
deployment.
44+
45+
If the device is capable of determining its own location information, the
46+
Generic Location Setup Server is redundant, and can be deactivated by
47+
removing all bindings it has to any application keys.
48+
49+
.. note::
50+
51+
The Generic Location Server does not store any of its states persistently,
52+
so if the Generic Location Server is meant to get its location configured
53+
during setup, this must be stored by the application.
54+
55+
States
56+
*******
57+
58+
**Global Location**: :cpp:type:`bt_mesh_loc_global`
59+
60+
The Global Location state is a composite state representing a global location
61+
as a WGS84 coordinate point. The latitude and longitude (in degrees) are
62+
represented as a ``double``, and are each encoded as a signed 32 bit integer.
63+
The altitude is represented as a signed 16 bit integer, measured in meters.
64+
65+
The memory for the Global Location state is owned by the user, and should be
66+
exposed to the model through the callbacks in a
67+
:cpp:type:`bt_mesh_loc_srv_handlers` structure.
68+
69+
**Local Location**: :cpp:type:`bt_mesh_loc_local`
70+
71+
The Local Location state represents the device's location within a locally
72+
defined coordinate system, like the inside of a building. It contains
73+
parameters for a three dimensional device location measured in decimeters, as
74+
well as a floor number and parameters to determine the precision of the
75+
location parameters.
76+
77+
The memory for the Local Location state is owned by the user, and should be
78+
exposed to the model through the callbacks in a
79+
:cpp:type:`bt_mesh_loc_srv_handlers` structure.
80+
81+
Extended models
82+
****************
83+
84+
None.
85+
86+
Persistent storage
87+
*******************
88+
89+
None.
90+
91+
API documentation
92+
******************
93+
94+
| Header file: :file:`include/bluetooth/mesh/gen_loc_srv.h`
95+
| Source file: :file:`subsys/bluetooth/mesh/gen_loc_srv.c`
96+
97+
.. doxygengroup:: bt_mesh_loc_srv
98+
:project: nrf
99+
:members:
100+
101+
----
102+
103+
.. _bt_mesh_loc_cli_readme:
104+
105+
Generic Location Client
106+
=======================
107+
108+
The Generic Location Client model can get and set the state of a Generic
109+
Location Server model remotely.
110+
111+
Contrary to the Server model, the Client only creates a single model instance
112+
in the mesh composition data. The Generic Location Client may send messages to
113+
both the Generic Location Server and the Generic Location Setup Server, as long
114+
as it has the right application keys.
115+
116+
Extended models
117+
****************
118+
119+
None.
120+
121+
Persistent storage
122+
*******************
123+
124+
None.
125+
126+
API documentation
127+
******************
128+
129+
| Header file: :file:`include/bluetooth/mesh/gen_loc_cli.h`
130+
| Source file: :file:`subsys/bluetooth/mesh/gen_loc_cli.c`
131+
132+
.. doxygengroup:: bt_mesh_loc_cli
133+
:project: nrf
134+
:members:
135+
136+
----
137+
138+
Common types
139+
=============
140+
141+
| Header file: :file:`include/bluetooth/mesh/gen_loc.h`
142+
143+
.. doxygenfile:: gen_loc.h
144+
:project: nrf

0 commit comments

Comments
 (0)