Bluetooth Mesh Generic Server Model#
Bluetooth Mesh Generic Server Model.
Generic server model API provides functionality to send and receive messages using Bluetooth SIG server models, including generic server models and lighting server models.
Throughout the API the server model being used is identified by its element address and model ID, while the client model generating requests to the server model is identified by its element address and model ID.
The generic server model API is designed on the premise that the actual state the model represents resides in and is owned by the application, not by the stack.
The model acts as a cache for client queries. In other words, the stack handles state requests from the client automatically. The application does not need to handle those. The cached value is also used for periodic publication.
The flip side of caching is that when the state represented by the model changes in the application, it must update the cached value to the stack by issuing a sl_btmesh_generic_server_update command.
When a client model requests a state change, the stack will generate a sl_btmesh_evt_generic_server_client_request event which the application must process. Then, if the client needs a response the application has to issue a sl_btmesh_generic_server_respond command corresponding to the request. Otherwise, the application only has to update the state with a sl_btmesh_generic_server_update command, which does not result in sending any messages to the network.
Note that, because the Mesh Model specification requires that certain states are bound together and because the stack enforces that, updating one cached state may result in an update of the corresponding bound state, for which the stack generates a sl_btmesh_evt_generic_server_state_changed event. For example, when a dimmable light is switched off, the lightness level bound to the on/off state, is also set to zero because the states are bound.
Data for state change requests and server responses is passed as serialized byte arrays through BGAPI. Bluetooth mesh SDK has functions to convert byte arrays to and from model state structures.
The stack will handle Mesh transaction layer segmentation and reassembly automatically if the messages sent are long enough to require it.
Note on time resolution
Because of message formatting, transition time and remaining time resolution units depend on the requested or reported value. For example, until 6.2 seconds it is 100 ms; until 62 seconds it is 1 s; until 620 seconds it is 10 s; and until 620 minutes it is 10 minutes. The value can't be longer than 620 minutes. Therefore, it is not possible to request a delay of exactly 7500 ms. The resolution unit is 1 s between 6.2 and 62 seconds, so the value is rounded down to 7 s.
Delay resolution is 5 ms and values will be rounded down to the closest 5 ms. The value can't be longer than 1275 ms.
Modules#
sl_btmesh_evt_generic_server_client_request
sl_btmesh_evt_generic_server_state_changed
sl_btmesh_evt_generic_server_state_recall
Functions#
Macros#
Function Documentation#
sl_btmesh_generic_server_respond#
sl_status_t sl_btmesh_generic_server_respond (uint16_t client_address, uint16_t elem_index, uint16_t model_id, uint16_t appkey_index, uint32_t remaining_ms, uint16_t flags, uint8_t type, size_t parameters_len, const uint8_t * parameters)
[in] | client_address | Address of the client model which sent the message |
[in] | elem_index | Server model element index |
[in] | model_id | Server model ID |
[in] | appkey_index | The application key index used |
[in] | remaining_ms | Time (in milliseconds) remaining before transition from current state to target state is complete. Set to zero if no transition is taking place or if the transition time does not apply to the state change. |
[in] | flags | Message flags. Bitmask of the following:
|
[in] | type | Model-specific state type, identifying the kind of state to be updated. See Generic Client Get State Types list for details. |
[in] | parameters_len | Length of data in |
[in] | parameters | Message-specific parameters serialized into a byte array |
Server response to a client request. This command must be used when an application updates the server model state as a response to a sl_btmesh_evt_generic_server_client_request event which required a response.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5902
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_update#
sl_status_t sl_btmesh_generic_server_update (uint16_t elem_index, uint16_t model_id, uint32_t remaining_ms, uint8_t type, size_t parameters_len, const uint8_t * parameters)
[in] | elem_index | Server model element index |
[in] | model_id | Server model ID |
[in] | remaining_ms | Time (in milliseconds) remaining before transition from current state to target state is complete. Set to zero if no transition is taking place or if transition time does not apply to the state change. |
[in] | type | Model-specific state type, identifying the kind of state to be updated. See Generic Client Get State Types list for details. |
[in] | parameters_len | Length of data in |
[in] | parameters | Message-specific parameters, serialized into a byte array |
Server state update. This command must be used when an application updates the server model state as a response to a sl_btmesh_evt_generic_server_client_request event which did not require a response, but also when the application state changes spontaneously or as a result of some external (non-Mesh) event.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5936
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_publish#
sl_status_t sl_btmesh_generic_server_publish (uint16_t elem_index, uint16_t model_id, uint8_t type)
[in] | elem_index | Server model element index |
[in] | model_id | Server model ID |
[in] | type | Model-specific state type, identifying the kind of state used in the published message. See Generic Client Get State Types list for details. |
Publish the server state to the network using the publish parameters configured in the model. The message is constructed using the cached state in the stack.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5958
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init#
sl_status_t sl_btmesh_generic_server_init ()
Initialize generic server models. This command initializes all generic server models on the device. Alternatively, only the necessary server models can be initialized using model-specific initialization commands. Using model-specific initialization can result in a smaller firmware image size for SoC projects.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5974
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_common#
sl_status_t sl_btmesh_generic_server_init_common ()
Initialize the generic server model common functionality. This should be called after all model-specific initialization calls are done, and does not need to be called if sl_btmesh_generic_server_init is used.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5986
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_on_off#
sl_status_t sl_btmesh_generic_server_init_on_off ()
Initialize generic on/off server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
5996
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_level#
sl_status_t sl_btmesh_generic_server_init_level ()
Initialize generic level server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6006
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_default_transition_time#
sl_status_t sl_btmesh_generic_server_init_default_transition_time ()
Initialize generic default transition time server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6016
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_power_on_off#
sl_status_t sl_btmesh_generic_server_init_power_on_off ()
Initialize generic power on/off server models, power on/off setup server models, and all models they extend.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6027
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_power_level#
sl_status_t sl_btmesh_generic_server_init_power_level ()
Initialize generic power level server models, power level setup server models, and all models they extend.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6038
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_battery#
sl_status_t sl_btmesh_generic_server_init_battery ()
Initialize generic battery server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6048
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_location#
sl_status_t sl_btmesh_generic_server_init_location ()
Initialize generic location and generic location setup server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6058
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_property#
sl_status_t sl_btmesh_generic_server_init_property ()
Initialize generic property server models.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6068
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_lightness#
sl_status_t sl_btmesh_generic_server_init_lightness ()
Initialize light lightness server models, light lightness setup server models, and all models they extend.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6079
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_ctl#
sl_status_t sl_btmesh_generic_server_init_ctl ()
Initialize light CTL server models, light CTL temperature server models, light CTL setup server models, and all models they extend.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6090
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_init_hsl#
sl_status_t sl_btmesh_generic_server_init_hsl ()
Initialize light HSL server models, light HSL hue server models, light HSL saturation server models, light HSL setup server models, and all models they extend
Returns
SL_STATUS_OK if successful. Error code otherwise.
6102
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_generic_server_get_cached_state#
sl_status_t sl_btmesh_generic_server_get_cached_state (uint16_t elem_index, uint16_t model_id, uint8_t type, uint32_t * remaining_ms, size_t max_parameters_size, size_t * parameters_len, uint8_t * parameters)
[in] | elem_index | Server model element index |
[in] | model_id | Server model ID |
[in] | type | Model-specific state type, identifying the kind of state reported in the state change event. See Generic Client Get State Types list for details. |
[out] | remaining_ms | Time (in milliseconds) remaining before transition from current state to target state is complete. Ignored if no transition is taking place. |
[in] | max_parameters_size | Size of output buffer passed in |
[out] | parameters_len | On return, set to the length of output data written to |
[out] | parameters | Message-specific parameters, serialized into a byte array |
Get model cached state. This command can be used to get cached model states after scene recall when using compacted recall events. This command supports only those states that would have been reported by sl_btmesh_evt_generic_server_state_recall events.
Returns
SL_STATUS_OK if successful. Error code otherwise.
6128
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
Macro Definition Documentation#
sl_btmesh_cmd_generic_server_respond_id#
#define sl_btmesh_cmd_generic_server_respond_idValue:
0x001f0028
5708
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_update_id#
#define sl_btmesh_cmd_generic_server_update_idValue:
0x011f0028
5709
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_publish_id#
#define sl_btmesh_cmd_generic_server_publish_idValue:
0x021f0028
5710
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_id#
#define sl_btmesh_cmd_generic_server_init_idValue:
0x041f0028
5711
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_common_id#
#define sl_btmesh_cmd_generic_server_init_common_idValue:
0x051f0028
5712
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_on_off_id#
#define sl_btmesh_cmd_generic_server_init_on_off_idValue:
0x061f0028
5713
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_level_id#
#define sl_btmesh_cmd_generic_server_init_level_idValue:
0x071f0028
5714
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_default_transition_time_id#
#define sl_btmesh_cmd_generic_server_init_default_transition_time_idValue:
0x081f0028
5715
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_power_on_off_id#
#define sl_btmesh_cmd_generic_server_init_power_on_off_idValue:
0x091f0028
5716
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_power_level_id#
#define sl_btmesh_cmd_generic_server_init_power_level_idValue:
0x0a1f0028
5717
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_battery_id#
#define sl_btmesh_cmd_generic_server_init_battery_idValue:
0x0b1f0028
5718
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_location_id#
#define sl_btmesh_cmd_generic_server_init_location_idValue:
0x0c1f0028
5719
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_property_id#
#define sl_btmesh_cmd_generic_server_init_property_idValue:
0x0d1f0028
5720
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_lightness_id#
#define sl_btmesh_cmd_generic_server_init_lightness_idValue:
0x0e1f0028
5721
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_ctl_id#
#define sl_btmesh_cmd_generic_server_init_ctl_idValue:
0x0f1f0028
5722
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_init_hsl_id#
#define sl_btmesh_cmd_generic_server_init_hsl_idValue:
0x101f0028
5723
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_cmd_generic_server_get_cached_state_id#
#define sl_btmesh_cmd_generic_server_get_cached_state_idValue:
0x111f0028
5724
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_respond_id#
#define sl_btmesh_rsp_generic_server_respond_idValue:
0x001f0028
5725
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_update_id#
#define sl_btmesh_rsp_generic_server_update_idValue:
0x011f0028
5726
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_publish_id#
#define sl_btmesh_rsp_generic_server_publish_idValue:
0x021f0028
5727
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_id#
#define sl_btmesh_rsp_generic_server_init_idValue:
0x041f0028
5728
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_common_id#
#define sl_btmesh_rsp_generic_server_init_common_idValue:
0x051f0028
5729
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_on_off_id#
#define sl_btmesh_rsp_generic_server_init_on_off_idValue:
0x061f0028
5730
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_level_id#
#define sl_btmesh_rsp_generic_server_init_level_idValue:
0x071f0028
5731
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_default_transition_time_id#
#define sl_btmesh_rsp_generic_server_init_default_transition_time_idValue:
0x081f0028
5732
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_power_on_off_id#
#define sl_btmesh_rsp_generic_server_init_power_on_off_idValue:
0x091f0028
5733
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_power_level_id#
#define sl_btmesh_rsp_generic_server_init_power_level_idValue:
0x0a1f0028
5734
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_battery_id#
#define sl_btmesh_rsp_generic_server_init_battery_idValue:
0x0b1f0028
5735
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_location_id#
#define sl_btmesh_rsp_generic_server_init_location_idValue:
0x0c1f0028
5736
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_property_id#
#define sl_btmesh_rsp_generic_server_init_property_idValue:
0x0d1f0028
5737
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_lightness_id#
#define sl_btmesh_rsp_generic_server_init_lightness_idValue:
0x0e1f0028
5738
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_ctl_id#
#define sl_btmesh_rsp_generic_server_init_ctl_idValue:
0x0f1f0028
5739
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_init_hsl_id#
#define sl_btmesh_rsp_generic_server_init_hsl_idValue:
0x101f0028
5740
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h
sl_btmesh_rsp_generic_server_get_cached_state_id#
#define sl_btmesh_rsp_generic_server_get_cached_state_idValue:
0x111f0028
5741
of file /mnt/raid/workspaces/ws.wDIAeKYhQ/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h