Bluetooth Mesh Vendor Model#

Bluetooth Mesh Vendor Model.

Vendor model API provides functionality to send and receive vendor-specific messages.

Throughout the API, the manipulated model is identified by its element address, vendor ID, and model ID.

The API has functions for sending, receiving, and publishing messages. The application has to implement additional complex functionality (state machines or other model-specific logic).

The stack will handle Mesh transaction layer segmentation and reassembly automatically if the messages sent are long enough to require it.

Note that as the application layer overhead for vendor messages is three bytes (vendor ID and opcode) and the access layer MIC is at least four bytes, the longest vendor application payload which can be sent using an unsegmented transport layer PDU is eight bytes. On the other hand, the longest vendor application payload which can be sent using transport layer segmentation is 377 bytes (fragmented into 32 segments).

Modules#

sl_btmesh_evt_vendor_model_receive

sl_btmesh_evt_vendor_model_send_complete

Enumerations#

enum
sl_btmesh_vendor_model_heap_work_buffer = 0x0
}

Key values to identify vendor model configuration options.

Functions#

sl_status_t
sl_btmesh_vendor_model_send(uint16_t destination_address, int8_t va_index, uint16_t appkey_index, uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t nonrelayed, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t *payload)
sl_status_t
sl_btmesh_vendor_model_set_publication(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t *payload)
sl_status_t
sl_btmesh_vendor_model_clear_publication(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
sl_status_t
sl_btmesh_vendor_model_publish(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
sl_status_t
sl_btmesh_vendor_model_init(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t publish, size_t opcodes_len, const uint8_t *opcodes)
sl_status_t
sl_btmesh_vendor_model_deinit(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
sl_status_t
sl_btmesh_vendor_model_send_tracked(uint16_t destination_address, int8_t va_index, uint16_t appkey_index, uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t nonrelayed, uint8_t segment, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t *payload, uint16_t *handle)
sl_status_t
sl_btmesh_vendor_model_set_publication_tracked(uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t segment, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t *payload, uint16_t *handle)
sl_status_t
sl_btmesh_vendor_model_set_option(uint8_t option, uint32_t value)

Enumeration Documentation#

sl_btmesh_vendor_model_options_t#

sl_btmesh_vendor_model_options_t

Key values to identify vendor model configuration options.

Enumerator
sl_btmesh_vendor_model_heap_work_buffer

(0x0) If set to 1, each vendor model allocates a heap work buffer for messages being received. If set to 0, no heap work buffer allocation is made, which saves memory but risks losing messages in a high load environment. Range: 0...1 Default: 1


Definition at line 4167 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

Function Documentation#

sl_btmesh_vendor_model_send#

sl_status_t sl_btmesh_vendor_model_send (uint16_t destination_address, int8_t va_index, uint16_t appkey_index, uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t nonrelayed, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t * payload)
Parameters
[in]destination_address

Destination address of the message. It can be a unicast address, a group address, or a virtual address.

[in]va_index

Index of the destination Label UUID (used only is the destination address is a virtual address)

[in]appkey_index

The application key index used

[in]elem_index

Sending model element index

[in]vendor_id

Vendor ID of the sending model

[in]model_id

Model ID of the sending model

[in]nonrelayed

If the message is a response to a received message, set this parameter according to what was received in the receive event. Otherwise, set to non-zero if the message affects only devices in the immediate radio neighborhood.

[in]opcode

Message opcode

[in]final

Indicates whether this payload chunk is the final one of the message or whether more will follow.

[in]payload_len

Length of data in payload

[in]payload

Payload data (either complete or partial; see final parameter).

Send vendor-specific data.

Note that, because of the bgapi event length restrictions, the message sent may need to be fragmented into several commands. If this is the case, the application must issue the commands in the correct order and mark the command carrying the last message fragment with the final flag set to a non-zero value. The stack will not start sending the message until the complete message is provided by the application. Fragments from multiple messages must not be interleaved.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4303 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_set_publication#

sl_status_t sl_btmesh_vendor_model_set_publication (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t * payload)
Parameters
[in]elem_index

Publishing model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

[in]opcode

Message opcode

[in]final

Indicates whether this payload chunk is the final one of the message or whether more will follow.

[in]payload_len

Length of data in payload

[in]payload

Payload data (either complete or partial; see final parameter).

Set the vendor model publication message.

The model publication message will be sent out when the model publication occurs either periodically (if the model is configured for periodic publishing) or explicitly (see sl_btmesh_vendor_model_publish.

Note that, because of bgapi length requirements, the message may need to be fragmented over multiple commands. If this is the case, the application must issue the commands in the correct order and mark the command carrying the last message fragment with the final flag set to a non-zero value. The stack will not assign the message to the model until the complete message is provided by the application.

To disable publication, the publication message may be erased using the sl_btmesh_vendor_model_clear_publication command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4346 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_clear_publication#

sl_status_t sl_btmesh_vendor_model_clear_publication (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
Parameters
[in]elem_index

Publishing model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

Clear the vendor model publication message.

Clearing the model publication message disables model publishing, which can be re-enabled by defining the publication message using the sl_btmesh_vendor_model_set_publication command.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4369 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_publish#

sl_status_t sl_btmesh_vendor_model_publish (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
Parameters
[in]elem_index

Publishing model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

Publish the vendor model publication message.

Sends the stored publication message to the network using the application key and destination address stored in the model publication parameters.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4387 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_init#

sl_status_t sl_btmesh_vendor_model_init (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t publish, size_t opcodes_len, const uint8_t * opcodes)
Parameters
[in]elem_index

Model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

[in]publish

Indicates if the model is a publish model (non-zero) or not (zero).

[in]opcodes_len

Length of data in opcodes

[in]opcodes

Array of opcodes the model can handle

Initialize the vendor model. This function has to be called before the model can be used. Note that the model can be deinitialized if it is no longer needed. See sl_btmesh_vendor_model_deinit.

Opcodes that the model is able to receive at initialization must be defined. This enables the stack to pass only valid messages up to the model during runtime. Per Mesh specification there are up to 64 opcodes per vendor, ranging from 0 to 63. Specifying opcodes outside of that range will result in an error response. Duplicate opcodes in the array do not result in an error, but will of course be recorded only once.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4415 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_deinit#

sl_status_t sl_btmesh_vendor_model_deinit (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id)
Parameters
[in]elem_index

Model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

Deinitialize the model. After this call, the model cannot be used until it is initialized again. See sl_btmesh_vendor_model_init.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4434 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_send_tracked#

sl_status_t sl_btmesh_vendor_model_send_tracked (uint16_t destination_address, int8_t va_index, uint16_t appkey_index, uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t nonrelayed, uint8_t segment, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t * payload, uint16_t * handle)
Parameters
[in]destination_address

Destination address of the message. It can be a unicast address, a group address, or a virtual address.

[in]va_index

Index of the destination Label UUID (used only is the destination address is a virtual address)

[in]appkey_index

The application key index used

[in]elem_index

Sending model element index

[in]vendor_id

Vendor ID of the sending model

[in]model_id

Model ID of the sending model

[in]nonrelayed

If the message is a response to a received message, set this parameter according to what was received in the receive event. Otherwise, set to non-zero if the message affects only devices in the immediate radio neighborhood.

[in]segment

If nonzero, instruct the stack to use transport layer segmentation, even if the data would be short enough to send as an unsegmented message. If zero, stack selects automatically based on data length whether to use segmentation or not.

[in]opcode

Message opcode

[in]final

Indicates whether this payload chunk is the final one of the message or whether more will follow.

[in]payload_len

Length of data in payload

[in]payload

Payload data (either complete or partial; see final parameter).

[out]handle

Tracking handle for the message sending. Note that a valid handle is returned only when the final payload fragment is received by the stack (as indicated by the final parameter of this message) and the message is accepted for delivery (as indicated by the result code). Otherwise the value of this parameter should be ignored.

Send vendor-specific data with a delivery report.

This command works otherwise as sl_btmesh_vendor_model_send but also provides a tracking handle if there is no immediate local error. Once the message sending completes a sl_btmesh_evt_vendor_model_send_complete event is generated, and the handle received here can be used to correlate the event to the sent message.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4479 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_set_publication_tracked#

sl_status_t sl_btmesh_vendor_model_set_publication_tracked (uint16_t elem_index, uint16_t vendor_id, uint16_t model_id, uint8_t segment, uint8_t opcode, uint8_t final, size_t payload_len, const uint8_t * payload, uint16_t * handle)
Parameters
[in]elem_index

Publishing model element index

[in]vendor_id

Vendor ID of the model

[in]model_id

Model ID of the model

[in]segment

If nonzero, instruct the stack to use transport layer segmentation, even if the data would be short enough to publish as an unsegmented message. If zero, stack selects automatically based on data length whether to use segmentation or not.

[in]opcode

Message opcode

[in]final

Indicates whether this payload chunk is the final one of the message or whether more will follow.

[in]payload_len

Length of data in payload

[in]payload

Payload data (either complete or partial; see final parameter).

[out]handle

Tracking handle for the message publishing. Note that a valid handle is returned only when the final payload fragment is received by the stack (as indicated by the final parameter of this message) and the message is accepted for publication (as indicated by the result code). Otherwise the value of this parameter should be ignored. attempt

Set the vendor model publication message with a delivery report.

This command works otherwise as sl_btmesh_vendor_model_set_publication but also sets up a tracking handle for monitoring message delivery. When the message publishing completes a sl_btmesh_evt_vendor_model_send_complete event is generated, and the handle received here can be used to correlate the event to the sent message.

Note that the same tracking handle will be reported multiple times in case of periodic publication or publication retransmissions.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4528 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_vendor_model_set_option#

sl_status_t sl_btmesh_vendor_model_set_option (uint8_t option, uint32_t value)
Parameters
[in]option

Enum sl_btmesh_vendor_model_options_t. Configuration option.

[in]value

Configuration value

Set global vendor model configuration options.

This command sets global configuration options for all vendor models. Options take effect when models are initialized, so this command should be called before any sl_btmesh_vendor_model_init call.

Returns

  • SL_STATUS_OK if successful. Error code otherwise.


Definition at line 4553 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

Macro Definition Documentation#

sl_btmesh_cmd_vendor_model_send_id#

#define sl_btmesh_cmd_vendor_model_send_id
Value:
0x00190028

Definition at line 4145 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_set_publication_id#

#define sl_btmesh_cmd_vendor_model_set_publication_id
Value:
0x01190028

Definition at line 4146 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_clear_publication_id#

#define sl_btmesh_cmd_vendor_model_clear_publication_id
Value:
0x02190028

Definition at line 4147 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_publish_id#

#define sl_btmesh_cmd_vendor_model_publish_id
Value:
0x03190028

Definition at line 4148 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_init_id#

#define sl_btmesh_cmd_vendor_model_init_id
Value:
0x04190028

Definition at line 4149 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_deinit_id#

#define sl_btmesh_cmd_vendor_model_deinit_id
Value:
0x05190028

Definition at line 4150 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_send_tracked_id#

#define sl_btmesh_cmd_vendor_model_send_tracked_id
Value:
0x06190028

Definition at line 4151 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_set_publication_tracked_id#

#define sl_btmesh_cmd_vendor_model_set_publication_tracked_id
Value:
0x07190028

Definition at line 4152 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_cmd_vendor_model_set_option_id#

#define sl_btmesh_cmd_vendor_model_set_option_id
Value:
0x08190028

Definition at line 4153 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_send_id#

#define sl_btmesh_rsp_vendor_model_send_id
Value:
0x00190028

Definition at line 4154 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_set_publication_id#

#define sl_btmesh_rsp_vendor_model_set_publication_id
Value:
0x01190028

Definition at line 4155 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_clear_publication_id#

#define sl_btmesh_rsp_vendor_model_clear_publication_id
Value:
0x02190028

Definition at line 4156 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_publish_id#

#define sl_btmesh_rsp_vendor_model_publish_id
Value:
0x03190028

Definition at line 4157 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_init_id#

#define sl_btmesh_rsp_vendor_model_init_id
Value:
0x04190028

Definition at line 4158 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_deinit_id#

#define sl_btmesh_rsp_vendor_model_deinit_id
Value:
0x05190028

Definition at line 4159 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_send_tracked_id#

#define sl_btmesh_rsp_vendor_model_send_tracked_id
Value:
0x06190028

Definition at line 4160 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_set_publication_tracked_id#

#define sl_btmesh_rsp_vendor_model_set_publication_tracked_id
Value:
0x07190028

Definition at line 4161 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h

sl_btmesh_rsp_vendor_model_set_option_id#

#define sl_btmesh_rsp_vendor_model_set_option_id
Value:
0x08190028

Definition at line 4162 of file /mnt/raid/workspaces/ws.cynwT2I6w/overlay/gsdk/protocol/bluetooth/build/native/mesh_app/inc/sl_btmesh_api.h