Generic Location Client

Extended models
Persistent storage
Shell commands
API documentation

The Generic Location Client model can get and set the state of a Generic Location Server model remotely.

Unlike the Generic Location Server model, the Generic Location Client only creates a single model instance in the mesh composition data. The Generic Location Client may send messages to both the Generic Location Server and the Generic Location Setup Server, as long as it has the right application keys.

Extended models 

None.

Persistent storage 

None.

Shell commands 

The Bluetooth mesh shell subsystem provides a set of commands to interact with the Generic Location Client model instantiated on a device.

To make these commands available, enable the following Kconfig options:

mdl_loc instance get-all

Print all instances of the Generic Location Client model on the device.

mdl_loc instance set <elem_idx>

Select the Generic Location Client model instantiated on the specified element ID. This instance will be used in message sending. If no model instance is selected, the first model instance found on the device will be used by default.

elem_idx - Element index where the model instance is found.

mdl_loc global-get

Get the current global location value of the Generic Location state.

mdl_loc global-set <latitude> <longitude> <altitude>

Set the global location value of the Generic Location state and wait for a response.

latitude - Global WGS84 North coordinate in degrees.
longitude - Global WGS84 East coordinate in degrees.
altitude - Global altitude above the WGS84 datum in meters.

mdl_loc global-set-unack <latitude> <longitude> <altitude>

Set the global location value of the Generic Location state without requesting a response.

latitude - Global WGS84 North coordinate in degrees.
longitude - Global WGS84 East coordinate in degrees.
altitude - Global altitude above the WGS84 datum in meters.

mdl_loc local-get

Get the current local location value of the Generic Location state.

mdl_loc local-set <north> <east> <altitude> <floor> [time_delta [precision_mm [is_mobile]]]

Set the local location value of the Generic Location state and wait for a response.

north - Local north position in decimeters.
east - Local east position in decimeters.
altitude - Local altitude in decimeters.
floor - Floor number.
time_delta - If present, defines the time since the previous position update in milliseconds.
precision_mm - If present, defines the precision of the location in millimeters.
is_mobile - If present, defines whether the device is movable.

mdl_loc local-set-unack <north> <east> <altitude> <floor> [time_delta [precision_mm [is_mobile]]]

Set the local location value of the Generic Location state without requesting a response.

north - Local north position in decimeters.
east - Local east position in decimeters.
altitude - Local altitude in decimeters.
floor - Floor number.
time_delta - If present, defines the time since the previous position update in milliseconds.
precision_mm - If present, defines the precision of the location in millimeters.
is_mobile - If present, defines whether the device is movable.

API documentation 

Header file: include/bluetooth/mesh/gen_loc_cli.h

Source file: subsys/bluetooth/mesh/gen_loc_cli.c

group bt_mesh_loc_cli

API for the Generic Location Client model.

Defines

BT_MESH_LOC_CLI_INIT(_handlers)

Initialization parameters for a Generic Location Client model instance.

Parameters

_handlers – [in] Pointer to a bt_mesh_loc_cli_handlers instance.

BT_MESH_MODEL_LOC_CLI(_cli)

Generic Location Client model composition data entry.

Parameters

_cli – [in] Pointer to a Generic Location Client model instance.

Functions

int bt_mesh_loc_cli_global_get(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_global *rsp)

Get the global location of the bound srv.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_loc_cli_handlers::global_status callback.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
rsp – [out] Global Location response buffer, or NULL to keep from blocking.

Return values

0 – Successfully sent the message and populated the rsp buffer.
-EALREADY – A blocking request is already in progress.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.
-ETIMEDOUT – The request timed out without a response.

int bt_mesh_loc_cli_global_set(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_global *loc, struct bt_mesh_loc_global *rsp)

Set the Global Location in the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_loc_cli_handlers::global_status callback.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
loc – [in] New Global Location value to set.
rsp – [out] Response status buffer, or NULL to keep from blocking.

Return values

0 – Successfully sent the message and populated the rsp buffer.
-EALREADY – A blocking request is already in progress.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.
-ETIMEDOUT – The request timed out without a response.

int bt_mesh_loc_cli_global_set_unack(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_global *loc)

Set the Global Location in the server without requesting a response.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
loc – [in] New Global Location value to set.

Return values

0 – Successfully sent the message.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.

int bt_mesh_loc_cli_local_get(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, struct bt_mesh_loc_local *rsp)

Get the local location of the bound srv.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_loc_cli_handlers::local_status callback.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
rsp – [out] Local Location response buffer, or NULL to keep from blocking.

Return values

0 – Successfully sent the message and populated the rsp buffer.
-EALREADY – A blocking request is already in progress.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.
-ETIMEDOUT – The request timed out without a response.

int bt_mesh_loc_cli_local_set(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_local *loc, struct bt_mesh_loc_local *rsp)

Set the Local Location in the server.

This call is blocking if the rsp buffer is non-NULL. Otherwise, this function will return, and the response will be passed to the bt_mesh_loc_cli_handlers::local_status callback.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
loc – [in] New Local Location value to set.
rsp – [out] Response status buffer, or NULL to keep from blocking.

Return values

0 – Successfully sent the message and populated the rsp buffer.
-EALREADY – A blocking request is already in progress.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.
-ETIMEDOUT – The request timed out without a response.

int bt_mesh_loc_cli_local_set_unack(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_local *loc)

Set the Local Location in the server without requesting a response.

Parameters

cli – [in] Client model to send on.
ctx – [in] Message context, or NULL to use the configured publish parameters.
loc – [in] New Local Location value to set.

Return values

0 – Successfully sent the message.
-EADDRNOTAVAIL – A message context was not provided and publishing is not configured.
-EAGAIN – The device has not been provisioned.

struct bt_mesh_loc_cli_handlers

#include <gen_loc_cli.h>

Location handler functions

Public Members

void (*const global_status)(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_global *status)

Global Location status message handler.

Param cli: [in] Client that received the status message.
Param ctx: [in] Context of the incoming message.
Param status: [in] Global Location parameters of the Generic Location Server that published the message.

void (*const local_status)(struct bt_mesh_loc_cli *cli, struct bt_mesh_msg_ctx *ctx, const struct bt_mesh_loc_local *status)

Local Location status message handler.

Param cli: [in] Client that received the status message.
Param ctx: [in] Context of the incoming message.
Param status: [in] Local Location parameters of the Generic Location Server that published the message.

struct bt_mesh_loc_cli

#include <gen_loc_cli.h>

Generic Location Client structure.

Should be initialized with the BT_MESH_LOC_CLI_INIT macro.

Public Members

const struct bt_mesh_loc_cli_handlers *const handlers: Handler function structure

struct bt_mesh_msg_ack_ctx ack_ctx: Response context for tracking acknowledged messages.

struct bt_mesh_model_pub pub: Publish parameters.

struct bt_mesh_model *model: Composition data model entry pointer.

Generic Location Client

Extended models

Persistent storage

Shell commands

API documentation

Extended models 

Persistent storage 

Shell commands 

API documentation 