System
System.
Modules | |
sl_bt_evt_system_boot | |
Indicates that the device has started and the radio is ready. | |
sl_bt_evt_system_error | |
Indicates that an error has occurred. | |
sl_bt_evt_system_hardware_error | |
Indicates that a hardware-related error has occurred. | |
sl_bt_evt_system_external_signal | |
Indicates that the external signals have been received. | |
sl_bt_evt_system_awake | |
Indicates that the device is awake and no longer in sleep mode. | |
sl_bt_evt_system_soft_timer | |
Indicates that a soft timer has lapsed. | |
Enumerations | |
enum | sl_bt_system_boot_mode_t { sl_bt_system_boot_mode_normal = 0x0, sl_bt_system_boot_mode_uart_dfu = 0x1, sl_bt_system_boot_mode_ota_dfu = 0x2 } |
System boot mode. | |
enum | sl_bt_system_linklayer_config_key_t { sl_bt_system_linklayer_config_key_halt = 0x1, sl_bt_system_linklayer_config_key_priority_range = 0x2, sl_bt_system_linklayer_config_key_scan_channels = 0x3, sl_bt_system_linklayer_config_key_set_flags = 0x4, sl_bt_system_linklayer_config_key_clr_flags = 0x5, sl_bt_system_linklayer_config_key_set_afh_interval = 0x7, sl_bt_system_linklayer_config_key_set_priority_table = 0x9, sl_bt_system_linklayer_config_key_power_control_golden_range = 0xa } |
Link Layer Configuration Keys. | |
Functions | |
sl_status_t | sl_bt_system_hello () |
sl_status_t | sl_bt_system_start_bluetooth () |
sl_status_t | sl_bt_system_stop_bluetooth () |
sl_status_t | sl_bt_system_get_version (uint16_t *major, uint16_t *minor, uint16_t *patch, uint16_t *build, uint32_t *bootloader, uint32_t *hash) |
void | sl_bt_system_reset (uint8_t dfu) |
sl_status_t | sl_bt_system_halt (uint8_t halt) |
sl_status_t | sl_bt_system_linklayer_configure (uint8_t key, size_t data_len, const uint8_t *data) |
SL_BGAPI_DEPRECATED sl_status_t | sl_bt_system_set_max_tx_power (int16_t power, int16_t *set_power) |
sl_status_t | sl_bt_system_set_tx_power (int16_t min_power, int16_t max_power, int16_t *set_min, int16_t *set_max) |
sl_status_t | sl_bt_system_get_tx_power_setting (int16_t *support_min, int16_t *support_max, int16_t *set_min, int16_t *set_max, int16_t *rf_path_gain) |
sl_status_t | sl_bt_system_set_identity_address (bd_addr address, uint8_t type) |
sl_status_t | sl_bt_system_get_identity_address (bd_addr *address, uint8_t *type) |
sl_status_t | sl_bt_system_get_random_data (uint8_t length, size_t max_data_size, size_t *data_len, uint8_t *data) |
sl_status_t | sl_bt_system_data_buffer_write (size_t data_len, const uint8_t *data) |
sl_status_t | sl_bt_system_data_buffer_clear () |
sl_status_t | sl_bt_system_get_counters (uint8_t reset, uint16_t *tx_packets, uint16_t *rx_packets, uint16_t *crc_errors, uint16_t *failures) |
sl_status_t | sl_bt_system_set_soft_timer (uint32_t time, uint8_t handle, uint8_t single_shot) |
sl_status_t | sl_bt_system_set_lazy_soft_timer (uint32_t time, uint32_t slack, uint8_t handle, uint8_t single_shot) |
Detailed Description
System.
Commands and events in this class can be used to access and query the local device.
Enumeration Type Documentation
◆ sl_bt_system_boot_mode_t
◆ sl_bt_system_linklayer_config_key_t
Link Layer Configuration Keys.
Function Documentation
◆ sl_bt_system_hello()
sl_status_t sl_bt_system_hello | ( |
| ) |
Verify whether the communication between the host and the device is functional.
NOTE: This command is available even if the Bluetooth stack has not been started. See sl_bt_system_start_bluetooth for description of how the Bluetooth stack is started.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_start_bluetooth()
sl_status_t sl_bt_system_start_bluetooth | ( |
| ) |
If the Bluetooth on-demand start component is not included in the application build, the Bluetooth stack is automatically started at UC initialization time. In this configuration the on-demand start command is not available and the command returns the error SL_STATUS_NOT_AVAILABLE.
When the Bluetooth on-demand start component is included in the application build, this command is used by the application to request starting the Bluetooth stack when the application needs it. If the command returns a success result, the stack starts to asynchronously allocate the resources and configure the Bluetooth stack based on the configuration passed at UC initialization time.
Successful start of the stack is indicated by the sl_bt_evt_system_boot event. The configured classes and Bluetooth stack features are available after the application has received the sl_bt_evt_system_boot event. If starting the Bluetooth stack fails, the error is indicated to the application with the sl_bt_evt_system_error event.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_stop_bluetooth()
sl_status_t sl_bt_system_stop_bluetooth | ( |
| ) |
If the Bluetooth on-demand start component is not included in the application build, the Bluetooth stack is automatically started at UC initialization time and never stopped. In this configuration the stop command is not available and the command returns the error SL_STATUS_NOT_AVAILABLE.
When the Bluetooth on-demand start component is included in the application build, this command is used by the application to stop the Bluetooth stack when the application no longer needs it. This command gracefully restores Bluetooth to an idle state by disconnecting any active connections and stopping any on-going advertising and scanning. Any resources that were allocated when the stack was started are freed when the stack is stopped. After this command the BGAPI classes other than System become unavailable. The application can use the command sl_bt_system_start_bluetooth in order to continue using Bluetooth later.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_get_version()
sl_status_t sl_bt_system_get_version | ( | uint16_t * | major, |
uint16_t * | minor, |
||
uint16_t * | patch, |
||
uint16_t * | build, |
||
uint32_t * | bootloader, |
||
uint32_t * | hash |
||
) |
Get the firmware version information.
NOTE: This command is available even if the Bluetooth stack has not been started. See sl_bt_system_start_bluetooth for description of how the Bluetooth stack is started.
- Parameters
-
[out] major
Major release version [out] minor
Minor release version [out] patch
Patch release number [out] build
Build number [out] bootloader
Bootloader version [out] hash
Version hash
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_reset()
void sl_bt_system_reset | ( | uint8_t | dfu | ) |
Reset the system. The command does not have a response but it triggers one of the boot events (normal reset or boot to DFU mode) depending on the selected boot mode.
NOTE: This command is available even if the Bluetooth stack has not been started. See sl_bt_system_start_bluetooth for description of how the Bluetooth stack is started.
- Parameters
-
[in] dfu
Enum sl_bt_system_boot_mode_t. Boot mode. Values: - sl_bt_system_boot_mode_normal (0x0): Boot to normal mode
- sl_bt_system_boot_mode_uart_dfu (0x1): Boot to UART DFU mode
- sl_bt_system_boot_mode_ota_dfu (0x2): Boot to OTA DFU mode
Events
- sl_bt_evt_system_boot - Sent after the device has booted in normal mode.
- sl_bt_evt_dfu_boot - Sent after the device has booted in UART DFU mode.
◆ sl_bt_system_halt()
sl_status_t sl_bt_system_halt | ( | uint8_t | halt | ) |
Force radio to idle state and allow device to sleep. Advertising, scanning, connections, and software timers are halted by this command. Halted operations resume after calling this command with parameter 0. Connections stay alive if the system is resumed before connection supervision timeout.
Use this command only for a short time period (a few seconds at maximum). Although it halts Bluetooth activity, all tasks and operations still exist inside the stack with their own concepts of time. Halting the system for a long time period may have negative consequences on stack's internal states.
NOTE: The software timer is also halted. Hardware interrupts are the only way to wake up from energy mode 2 when the system is halted.
- Parameters
-
[in] halt
Values: - 1: halt
- 0: resume
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_linklayer_configure()
sl_status_t sl_bt_system_linklayer_configure | ( | uint8_t | key, |
size_t | data_len, |
||
const uint8_t * | data |
||
) |
Send configuration data to the link layer. This command fine tunes low-level Bluetooth operations.
- Parameters
-
[in] key
Enum sl_bt_system_linklayer_config_key_t. Key to configure. Values: - sl_bt_system_linklayer_config_key_halt (0x1): Same as system_halt command, value-0 Stop Radio 1- Start Radio
- sl_bt_system_linklayer_config_key_priority_range (0x2): Sets the RAIL priority_mapping offset field of the link layer priority configuration structure to the first byte of the value field.
- sl_bt_system_linklayer_config_key_scan_channels (0x3): Sets channels to scan on. The first byte of the value is the channel map. 0x1 = Channel 37, 0x2 = Channel 38, 0x4 = Channel 39
- sl_bt_system_linklayer_config_key_set_flags (0x4): Sets the link layer configuration flags. The value is a little endian 32-bit integer. Flag Values:
- 0x00000001 - Disable Feature Exchange when slave
- 0x00000002 - Disable Feature Exchange when master
- sl_bt_system_linklayer_config_key_clr_flags (0x5): The value is flags to clear. Flags are the same as in SET_FLAGS command.
- sl_bt_system_linklayer_config_key_set_afh_interval (0x7): Set afh_scan_interval field of Link Layer priority configuration structure.
- sl_bt_system_linklayer_config_key_set_priority_table (0x9): The value contains a priority table to be copied over the existing table. If the value is smaller than the full table, only those values are updated. See sl_bt_bluetooth_ll_priorities struct for the definition of a priority table.
- sl_bt_system_linklayer_config_key_power_control_golden_range (0xa): Power control golden range configuration. The first byte of the value is the lower boundary and the second byte is the upper boundary. Values are in dBm.
[in] data_len
Array length [in] data
Configuration data. Length and contents of the data field depend on the key value used.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_set_max_tx_power()
SL_BGAPI_DEPRECATED sl_status_t sl_bt_system_set_max_tx_power | ( | int16_t | power, |
int16_t * | set_power |
||
) |
Deprecated and replaced by sl_bt_system_set_tx_power.
Set the global maximum radiated TX power for Bluetooth. This returns the selected power level that is radiated from the antenna at TX. The transmitter power at antenna pin will apply the RF TX path gain to match this setting. RF TX path gain can be set in the Bluetooth configuration. If the GATT server contains a TX power service, the TX Power Level attribute will be updated with the selected maximum power level.
The selected power level may be less than the specified value if the device does not meet the power requirements. For Bluetooth connections, the maximum TX power is limited to 10 dBm if Adaptive Frequency Hopping (AFH) is not enabled.
The maximum TX power level can also be configured in the Bluetooth configuration and passed into the Bluetooth stack initialization. By default, the global maximum TX power is 8 dBm.
NOTE: Do not use this command while advertising or scanning. Furthermore, the stack does not allow setting TX powers during connections.
- Parameters
-
[in] power
The maximum radiated TX power in 0.1 dBm steps. For example, value 10 means 1 dBm. [out] set_power
Selected maximum radiated TX power
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_set_tx_power()
sl_status_t sl_bt_system_set_tx_power | ( | int16_t | min_power, |
int16_t | max_power, |
||
int16_t * | set_min, |
||
int16_t * | set_max |
||
) |
Set the global minimum and maximum radiated TX power levels for Bluetooth. This returns selected power levels that are radiated from the antenna at TX. The transmitter power at antenna pin will apply the RF TX path gain to match this setting. RF TX path gain can be set in the Bluetooth configuration. If the GATT server contains a TX power service, the TX Power Level attribute will be updated with the selected maximum power level.
A selected power level may be different than the requested value if the device cannot meet the requirement. For Bluetooth connections, the maximum radiated TX power is limited to 10 dBm if Adaptive Frequency Hopping (AFH) is not enabled.
The minimum TX power setting is used by LE power control. It has no effect in Bluetooth stack if the LE power control feature is not enabled. However, the application may still use this setting for other purposes, e.g., setting the minimum TX power for DTM transmitter test.
The minimum and maximum radiated TX power levels can also be configured in the Bluetooth configuration and passed into the Bluetooth stack initialization. By default, the minimum radiated TX power level is configured to -3 dBm and the maximum radiated TX power level to 8 dBm.
NOTE: Do not use this command while advertising or scanning. Furthermore, the stack does not allow setting TX powers during connections.
- Parameters
-
[in] min_power
Minimum radiated TX power. Unit: 0.1 dBm. For example, the value 10 means 1 dBm. [in] max_power
Maximum radiated TX power. Unit: 0.1 dBm. For example, the value 10 means 1 dBm. [out] set_min
The selected minimum radiated TX power. Unit: 0.1 dBm [out] set_max
The selected maximum radiated TX power. Unit: 0.1 dBm
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_get_tx_power_setting()
sl_status_t sl_bt_system_get_tx_power_setting | ( | int16_t * | support_min, |
int16_t * | support_max, |
||
int16_t * | set_min, |
||
int16_t * | set_max, |
||
int16_t * | rf_path_gain |
||
) |
Get TX power settings including the minimum and maximum radiated TX power levels the device supports, the minimum and maximum radiated TX power levels currently set in the stack, and the TX RF path gain configuration.
- Parameters
-
[out] support_min
The minimum radiated TX power the device supports. Unit: 0.1 dBm [out] support_max
The maximum radiated TX power the device supports. Unit: 0.1 dBm [out] set_min
The minimum radiated TX power currently set in stack. Unit: 0.1 dBm [out] set_max
The maximum radiated TX power currently set in stack. Unit: 0.1 dBm [out] rf_path_gain
TX RF path gain. Unit: 0.1 dBm
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_set_identity_address()
sl_status_t sl_bt_system_set_identity_address | ( | bd_addr | address, |
uint8_t | type |
||
) |
Set the device's Bluetooth identity address. The address can be a public device address or a static device address. A valid address set with this command will be written into persistent storage using NVM keys. The stack returns an error if the static device address does not conform to the Bluetooth specification.
The new address will be effective in the next system reboot. The stack will use the address in the NVM keys when present. Otherwise, it uses the default Bluetooth public device address which is programmed at production.
The stack treats 00:00:00:00:00:00 and ff:ff:ff:ff:ff:ff as invalid addresses. Therefore, passing one of them into this command will cause the stack to delete the NVM keys and use the default address in the next system reboot.
Note: Because the NVM keys are located in flash and flash wearing can occur, avoid calling this command regularly.
- Parameters
-
[in] address
Bluetooth identity address in little endian format [in] type
Address type - 0: Public device address
- 1: Static device address
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_get_identity_address()
sl_status_t sl_bt_system_get_identity_address | ( | bd_addr * | address, |
uint8_t * | type |
||
) |
Read the Bluetooth identity address used by the device, which can be a public or random static device address.
- Parameters
-
[out] address
Bluetooth public address in little endian format [out] type
Address type - 0: Public device address
- 1: Static random address
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_get_random_data()
sl_status_t sl_bt_system_get_random_data | ( | uint8_t | length, |
size_t | max_data_size, |
||
size_t * | data_len, |
||
uint8_t * | data |
||
) |
Get random data up to 16 bytes.
- Parameters
-
[in] length
Length of random data. THe maximum length is 16 bytes. [in] max_data_size
Size of output buffer passed in data
[out] data_len
On return, set to the length of output data written to data
[out] data
Random data
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_data_buffer_write()
sl_status_t sl_bt_system_data_buffer_write | ( | size_t | data_len, |
const uint8_t * | data |
||
) |
Write data into the system data buffer. Data will be appended to the end of existing data.
- Parameters
-
[in] data_len
Array length [in] data
Data to write
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_data_buffer_clear()
sl_status_t sl_bt_system_data_buffer_clear | ( |
| ) |
Remove all data from the system data buffer.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_get_counters()
sl_status_t sl_bt_system_get_counters | ( | uint8_t | reset, |
uint16_t * | tx_packets, |
||
uint16_t * | rx_packets, |
||
uint16_t * | crc_errors, |
||
uint16_t * | failures |
||
) |
Get packet and error counters. Passing a non-zero value also resets counters.
- Parameters
-
[in] reset
Reset counters if the parameter value is not zero. [out] tx_packets
The number of successfully transmitted packets [out] rx_packets
The number of successfully received packets [out] crc_errors
The number of received packets with CRC errors [out] failures
The number of radio failures, such as aborted TX/RX packets, scheduling failures, and so on.
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
◆ sl_bt_system_set_soft_timer()
sl_status_t sl_bt_system_set_soft_timer | ( | uint32_t | time, |
uint8_t | handle, |
||
uint8_t | single_shot |
||
) |
Start a software timer. Multiple concurrent timers can be running simultaneously. 256 unique timer handles (IDs) are available. The maximum number of concurrent timers is configurable at device initialization. Up to 16 concurrent timers can be configured. The default configuration is 4. As the RAM for storing timer data is pre-allocated at initialization, an application should not configure the amount more than it needs for minimizing RAM usage.
- Parameters
-
[in] time
Frequency interval of events, which indicates how often to send events in hardware clock ticks (1 second is equal to 32768 ticks).
The smallest supported interval value is 328, which is around 10 milliseconds. Any parameters between 0 and 328 will be rounded up to 328. The maximum value is 2147483647, which corresponds to about 18.2 hours.
If
time
is 0, removes the scheduled timer with the same handle.[in] handle
Timer handle to use, which is returned in timeout event [in] single_shot
Timer mode. Values: - 0: false (timer is repeating)
- 1: true (timer runs only once)
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
Events
- sl_bt_evt_system_soft_timer - Sent after this timer has lapsed.
◆ sl_bt_system_set_lazy_soft_timer()
sl_status_t sl_bt_system_set_lazy_soft_timer | ( | uint32_t | time, |
uint32_t | slack, |
||
uint8_t | handle, |
||
uint8_t | single_shot |
||
) |
Start a software timer with slack. The slack parameter allows the stack to optimize wakeups and save power. The timer event is triggered between time and time + slack
. See also description of sl_bt_system_set_soft_timer command.
- Parameters
-
[in] time
An interval between how often to send events in hardware clock ticks (1 second is equal to 32768 ticks).
The smallest interval value supported is 328, which is around 10 milliseconds. Any parameters between 0 and 328 will be rounded up to 328. The maximum value is 2147483647, which corresponds to about 18.2 hours.
If
time
is 0, removes the scheduled timer with the same handle.[in] slack
Slack time in hardware clock ticks [in] handle
Timer handle to use, which is returned in timeout event [in] single_shot
Timer mode. Values: - 0: false (timer is repeating)
- 1: true (timer runs only once)
- Returns
- SL_STATUS_OK if successful. Error code otherwise.
Events
- sl_bt_evt_system_soft_timer - Sent after this timer has lapsed.