BGAPI Functions#

sl_bgapi_obtain_message_buffer#

sl_status_t sl_bgapi_obtain_message_buffer (size_t max_payload_size, void ** buffer)

Obtain a buffer that can be used to execute BGAPI or user commands.

This function is provided as a convenience for NCP/CPC components that need to handle BGAPI or user commands and responses in their binary format. If the user of sl_bgapi_execute_binary_command already has memory available for the command and response buffer (such as the memory allocated for UART RX/TX buffers), the user is encouraged to use the already existing memory when executing sl_bgapi_execute_binary_command.

If the user needs to allocate dedicated memory for any reason, using this function for the allocation may reduce the overall memory usage depending on the application configuration. If the configuration allows safe sharing of a message buffer (this is the case in a single-threaded baremetal application), the function returns the shared message buffer instead of making a separate allocation. When an RTOS is used, the function allocates a dedicated buffer for the caller.

Callers that use this function must call sl_bgapi_release_message_buffer to release the message buffer when it is no longer needed.

Returns

• SL_STATUS_OK if the buffer was obtained, otherwise an error code

sl_bgapi_release_message_buffer#

void sl_bgapi_release_message_buffer (void * buffer)

Release a buffer that was obtained with sl_bgapi_obtain_message_buffer.

sl_bgapi_execute_binary_command#

sl_status_t sl_bgapi_execute_binary_command (const void * command_buf, size_t command_buf_size, void * response_buf, size_t response_buf_size)

Execute a BGAPI command in binary format.

This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format. This function automatically performs any locking or inter-process communication required to execute the command. The function returns when the command has been executed.

If the caller does not need the command buffer after executing the command, it is acceptable to point the response buffer response_buf to the same memory location as the command buffer command_buf. In this case the response overwrites the command buffer. Provided that the response buffer is large enough, this function guarantees that the response buffer is always filled with a valid response message. If command execution fails, the response buffer is filled with a generic error response.

Returns

• SL_STATUS_OK if the command was executed, otherwise an error code. Note that SL_STATUS_OK does not mean that the command was successful, only that it was executed.

sl_bgapi_lock#

SL_BGAPI_DEPRECATED sl_status_t sl_bgapi_lock (void )

Lock the BGAPI for exclusive access.

Deprecated and replaced by sl_bgapi_execute_binary_command. The replacement provides a more flexible and efficient way to execute BGAPI commands in their binary format. The new function automatically performs any locking that's needed and enables re-using the command buffer memory for the response.

NOTE: This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format in an application that uses an RTOS. Normal application code that issues BGAPI commands by calling API functions defined by protocol stacks must never call this function directly.

See the documentation of sl_bgapi_handle_command for the full sequence that must be followed when processing commands in their binary format.

Returns

• SL_STATUS_OK if the lock has been obtained, otherwise an error code

sl_bgapi_unlock#

SL_BGAPI_DEPRECATED void sl_bgapi_unlock (void )

Release the lock obtained by sl_bgapi_lock.

Deprecated and replaced by sl_bgapi_execute_binary_command. The replacement provides a more flexible and efficient way to execute BGAPI commands in their binary format. The new function automatically performs any locking that's needed and enables re-using the command buffer memory for the response.

NOTE: This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format in an application that uses an RTOS. Normal application code that issues BGAPI commands by calling API functions defined by protocol stacks must never call this function directly.

See the documentation of sl_bgapi_handle_command for the full sequence that must be followed when processing commands in their binary format.

sl_bgapi_handle_command#

SL_BGAPI_DEPRECATED void sl_bgapi_handle_command (uint32_t hdr, const void * data)

Handle a BGAPI command in binary format.

Deprecated and replaced by sl_bgapi_execute_binary_command. The replacement provides a more flexible and efficient way to execute BGAPI commands in their binary format. The new function automatically performs any locking that's needed and enables re-using the command buffer memory for the response.

NOTE: This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format. Normal application code that issues BGAPI commands by calling API functions defined by protocol stacks must never call this function directly.

If the application uses an RTOS, the caller must protect the BGAPI handling by obtaining the BGAPI lock with sl_bgapi_lock, handle the command with sl_bgapi_handle_command, read the response from the buffer returned by sl_bgapi_get_command_response, and then release the lock with sl_bgapi_unlock. Here's an example of the full sequence that's required:

// Lock BGAPI for exclusive access
sl_status_t status = sl_bgapi_lock();
if (status != SL_STATUS_OK) {
  // Locking will only fail if there are fatal unrecoverable errors with the
  // RTOS primitives, so caller may choose to just assert in case of errors.
}

// Process the command
sl_bgapi_handle_command(hdr, data);

// Read the response
void *rsp = sl_bgapi_get_command_response();
uint32_t rsp_header = *((uint32_t *)rsp);
size_t rsp_len = SL_BGAPI_MSG_LEN(rsp_header) + SL_BGAPI_MSG_HEADER_LEN;
// Send the `rsp_len` bytes of response starting from `rsp`

// Finally unlock the BGAPI to allow other commands to proceed
sl_bgapi_unlock();

Empty stub implementations are provided for sl_bgapi_lock and sl_bgapi_unlock, so the same sequence can be used for all NCP/CPC implementations even if an RTOS is not present.

sl_bgapi_get_command_response#

SL_BGAPI_DEPRECATED void * sl_bgapi_get_command_response (void )

Get the response of a handled BGAPI command.

Deprecated and replaced by sl_bgapi_execute_binary_command. The replacement provides a more flexible and efficient way to execute BGAPI commands in their binary format. The new function automatically performs any locking that's needed and enables re-using the command buffer memory for the response.

NOTE: This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format. Normal application code that issues BGAPI commands by calling API functions defined by protocol stacks must never call this function directly.

See the documentation of sl_bgapi_handle_command for the full sequence that must be followed when processing commands in their binary format.

Returns

• Pointer to the BGAPI response structure that was filled when the command was executed in sl_bgapi_handle_command.

sl_bgapi_set_error_response#

void sl_bgapi_set_error_response (uint32_t command_hdr, uint16_t result, void * response, size_t response_buf_size)

Set a generic error response to the specified buffer.

NOTE: This function is provided for NCP/CPC components that need to handle BGAPI commands and responses in their binary format. Normal application code that issues BGAPI commands by calling API functions defined by protocol stacks must never call this function directly.

This function is available for NCP components that have detected fatal errors in command processing (for example have failed to receive a complete command message from the NCP host) and need to generate an error response without going through the normal BGAPI command processing.