BGAPI Functions#

sl_bgapi_lock#

sl_status_t sl_bgapi_lock (void )

Lock the BGAPI for exclusive access.

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#

void sl_bgapi_unlock (void )

Release the lock obtained by sl_bgapi_lock.

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#

void sl_bgapi_handle_command (uint32_t hdr, const void * data)

Handle a BGAPI command in binary format.

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#

void * sl_bgapi_get_command_response (void )

Get the response of a handled BGAPI command.

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.