Generic Location Server

The Generic Location Server provides location information about the device. The location data is split up into the following separate states: Global and Local.

  • Global Location represents the device location in the world.

  • Local Location represents the device location relative to a local coordinate system, for instance inside a building.

The Generic Location Server adds the following model instances in the composition data:

  • The Generic Location Server

  • The Generic Location Setup Server

These model instances share the states of the Generic Location Server, but accept different messages. This allows for a fine-grained control of the access rights for the location states, as the two model instances can be bound to different application keys:

  • The Generic Location Server allows observation of the location states, as it only exposes get-messages for the location states. This is typically the user-facing model instance, as the device location should not normally be configurable by the users.

  • The Generic Location Setup Server allows configuration of the location states by exposing set-messages for the location states. This model instance can be used to configure the location information of the device, for instance during deployment.

If the device is capable of determining its own location information, the Generic Location Setup Server is redundant, and can be deactivated by removing all its bindings to application keys.

Note

The Generic Location Server does not store any of its states persistently. If the Generic Location Server is to get its location configured during setup, this must be stored by the application.

States

The Generic Location Server model contains the following states:

Global Location: bt_mesh_loc_global

The Global Location state is a composite state representing a global location as a WGS84 coordinate point.

  • The latitude and longitude (in degrees) are represented as a double, and are each encoded as a signed 32-bit integer.

  • The altitude is represented as a signed 16-bit integer, measured in meters.

The memory for the Global Location state is owned by the application, and should be exposed to the model through the callbacks in a bt_mesh_loc_srv_handlers structure.

Local Location: bt_mesh_loc_local

The Local Location state represents the device’s location within a locally defined coordinate system, like the interior of a building. The state contains the following parameters:

  • Three-dimensional device location measured in decimeters

  • Floor number

  • Parameters to determine the precision of the location parameters

The memory for the Local Location state is owned by the user, and should be exposed to the model through the callbacks in a bt_mesh_loc_srv_handlers structure.

Extended models

None.

Persistent storage

None.

API documentation

Header file: include/bluetooth/mesh/gen_loc_srv.h
Source file: subsys/bluetooth/mesh/gen_loc_srv.c
group bt_mesh_loc_srv

API for the Generic Location Server model.

Defines

BT_MESH_LOC_SRV_INIT(_handlers)

Init parameters for a Generic Location Server model instance.

Parameters:

  • _handlers – [in] Handler function structure.

BT_MESH_MODEL_LOC_SRV(_srv)

Generic Location Server model composition data entry.

Parameters:

Functions

int bt_mesh_loc_srv_global_pub(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_global *global)

Publish the Global Location state.

Asynchronously publishes a Global Location status message with the configured publish parameters.

Note

This API is only used for publishing unprompted status messages. Response messages for get and set messages are handled internally.

Note

The server will only publish one state at the time. Calling this function will terminate any publishing of the Local Location state.

Parameters:

  • srv – [in] Server instance to publish on.

  • ctx – [in] Message context to send with, or NULL to send with the default publish parameters.

  • global – [in] Current global location.

Return values:

  • 0 – Successfully published a Global Location status message.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

int bt_mesh_loc_srv_local_pub(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_local *local)

Publish the Local Location state.

Asynchronously publishes a Local Location status message with the configured publish parameters.

Note

This API is only used for publishing unprompted status messages. Response messages for get and set messages are handled internally.

Note

The server will only publish one state at the time. Calling this function will terminate any publishing of the Global Location state.

Parameters:

  • srv – [in] Server instance to publish on.

  • ctx – [in] Message context to send with, or NULL to send with the default publish parameters.

  • local – [in] Current local location.

Return values:

  • 0 – Successfully published a Local Location status message.

  • -EADDRNOTAVAIL – A message context was not provided and publishing is not configured.

  • -EAGAIN – The device has not been provisioned.

struct bt_mesh_loc_srv_handlers
#include <gen_loc_srv.h>

Location Server handler functions.

Public Members

void (*const global_get)(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_global *rsp)

Get the Global Location state.

Note

This handler is mandatory.

Param srv:

[in] Server to get the Global Location state of.

Param ctx:

[in] Context of the get message that triggered the query, or NULL if it was not triggered by a message.

Param rsp:

[out] Global Location state to fill.

void (*const global_set)(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_global *loc)

Set the Global Location state.

Any changes to the new loc parameter will be taken into account before a response is sent to the client.

Note

This handler is mandatory.

Param srv:

[in] Server to set the Global Location state of.

Param ctx:

[in] Context of the set message that triggered the change, or NULL if it was not triggered by a message.

Param loc:

[inout] New Global Location state.

void (*const local_get)(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_local *rsp)

Get the Local Location state.

Note

This handler is mandatory.

Param srv:

[in] Server to get the Local Location state of.

Param ctx:

[in] Context of the get message that triggered the query, or NULL if it was not triggered by a message.

Param rsp:

[out] Local Location state to fill.

void (*const local_set)(struct bt_mesh_loc_srv *srv, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_local *loc)

Set the Local Location state.

Any changes to the new loc parameter will be taken into account before a response is sent to the client.

Note

This handler is mandatory.

Param srv:

[in] Server to set the Local Location state of.

Param ctx:

[in] Context of the set message that triggered the change, or NULL if it was not triggered by a message.

Param loc:

[inout] New Local Location state.

struct bt_mesh_loc_srv
#include <gen_loc_srv.h>

Generic Location Server instance. Should primarily be initialized with the BT_MESH_LOC_SRV_INIT macro.

Public Members

const struct bt_mesh_model *model

Pointer to the model instance.

struct bt_mesh_model_pub pub

Publish parameters for this model instance.

uint8_t is_global_available

Global location is available for publishing.

uint8_t is_local_available

Local location is available for publishing.

uint8_t was_last_local

The last published location over periodic publication.

struct bt_mesh_loc_srv.[anonymous] pub_state

Location publishing state.

const struct bt_mesh_loc_srv_handlers *const handlers

Pointer to a handler structure.