System (system)

Commands and events in this class can be used to access and query the local device.

system commands

system_data_buffer_clear

Remove all data from the system data buffer.

C API

/* Function */
struct gecko_msg_system_data_buffer_clear_rsp_t *gecko_cmd_system_data_buffer_clear();

/* Response id */
gecko_rsp_system_data_buffer_clear_id

/* Response structure */
struct gecko_msg_system_data_buffer_clear_rsp_t
{
  uint16 result;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_data_buffer_write

Write data into the system data buffer. Data will be appended to the end of existing data.

C API

/* Function */
struct gecko_msg_system_data_buffer_write_rsp_t *gecko_cmd_system_data_buffer_write(uint8 data_len, const uint8 *data_data);

/* Response id */
gecko_rsp_system_data_buffer_write_id

/* Response structure */
struct gecko_msg_system_data_buffer_write_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 data_len Array length.
uint8array data_data Data to write

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_get_bt_address

Read the Bluetooth public address used by the device.

C API

/* Function */
struct gecko_msg_system_get_bt_address_rsp_t *gecko_cmd_system_get_bt_address();

/* Response id */
gecko_rsp_system_get_bt_address_id

/* Response structure */
struct gecko_msg_system_get_bt_address_rsp_t
{
  bd_addr address;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address Bluetooth public address in little endian format

system_get_counters

Get packet and error counters. Passing a non-zero value also resets counters.

C API

/* Function */
struct gecko_msg_system_get_counters_rsp_t *gecko_cmd_system_get_counters(uint8 reset);

/* Response id */
gecko_rsp_system_get_counters_id

/* Response structure */
struct gecko_msg_system_get_counters_rsp_t
{
  uint16 result;
  uint16 tx_packets;
  uint16 rx_packets;
  uint16 crc_errors;
  uint16 failures;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 reset Reset counters if the parameter value is not zero.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint16 tx_packets The number of successfully transmitted packets
uint16 rx_packets The number of successfully received packets
uint16 crc_errors The number of received packets with CRC errors
uint16 failures The number of radio failures, such as aborted TX/RX packets, scheduling failures, and so on.

system_get_random_data

Get random data up to 16 bytes.

C API

/* Function */
struct gecko_msg_system_get_random_data_rsp_t *gecko_cmd_system_get_random_data(uint8 length);

/* Response id */
gecko_rsp_system_get_random_data_id

/* Response structure */
struct gecko_msg_system_get_random_data_rsp_t
{
  uint16 result;
  uint8array data;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 length Length of random data. Maximum length is 16 bytes.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint8array data Random data

system_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 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.

C API

/* Function */
struct gecko_msg_system_halt_rsp_t *gecko_cmd_system_halt(uint8 halt);

/* Response id */
gecko_rsp_system_halt_id

/* Response structure */
struct gecko_msg_system_halt_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 halt Values:
  • 1: halt
  • 0: resume

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_hello

Verify whether the communication between the host and the device is functional.

C API

/* Function */
struct gecko_msg_system_hello_rsp_t *gecko_cmd_system_hello();

/* Response id */
gecko_rsp_system_hello_id

/* Response structure */
struct gecko_msg_system_hello_rsp_t
{
  uint16 result;
}

Command does not have parameters (for BGAPI headers refer to link)

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_linklayer_configure

Send configuration data to the link layer. This command fine tunes low-level Bluetooth operations.

C API

/* Function */
struct gecko_msg_system_linklayer_configure_rsp_t *gecko_cmd_system_linklayer_configure(uint8 key, uint8 data_len, const uint8 *data_data);

/* Response id */
gecko_rsp_system_linklayer_configure_id

/* Response structure */
struct gecko_msg_system_linklayer_configure_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 key Key to configure
uint8 data_len Array length.
uint8array data_data Configuration data. Length and contents of the data field depend on the key value used.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_reset

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.

C API

/* Function */
void *gecko_cmd_system_reset(uint8 dfu);

/* Command does not have response */

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 dfu Boot mode:
  • 0: Normal reset
  • 1: Boot to UART DFU mode
  • 2: Boot to OTA DFU mode

Command does not have response (for BGAPI headers refer to link)

Events generated

Event Description
system_boot Sent after the device has booted in normal mode.
dfu_boot Sent after the device has booted in UART DFU mode.

system_set_bt_address

Deprecated and replaced by system_set_identity_address command.

Set the Bluetooth public address used by the device. A valid address set with this command overrides the default Bluetooth public address programmed at production and is effective in the next system reboot. The stack treats 00:00:00:00:00:00 and ff:ff:ff:ff:ff:ff as invalid addresses. As a result, passing one of them into this command will cause the stack to use the default address in the next system reboot.

C API

/* Function */
struct gecko_msg_system_set_bt_address_rsp_t *gecko_cmd_system_set_bt_address(bd_addr address);

/* Response id */
gecko_rsp_system_set_bt_address_id

/* Response structure */
struct gecko_msg_system_set_bt_address_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address Bluetooth public address in little endian format

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_set_device_name

Set the device name which will be used in application mode or during the OTA update. The name will be stored in the persistent store. If the OTA device name is also set in the stack configuration, the name stored in the persistent store is overwritten by the name in the stack configuration during the device boot.

C API

/* Function */
struct gecko_msg_system_set_device_name_rsp_t *gecko_cmd_system_set_device_name(uint8 type, uint8 name_len, const uint8 *name_data);

/* Response id */
gecko_rsp_system_set_device_name_id

/* Response structure */
struct gecko_msg_system_set_device_name_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
uint8 type Device name to set. Values:
  • 0: OTA device name
uint8 name_len Array length.
uint8array name_data Device name

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_set_identity_address

Set the device's Bluetooth identity address. The address can be a public device address or a random static device address. A valid address set with this command will be written into persistent storage using PS keys. The stack checks whether a random static address conforms to the Bluetooth specification. If it does not, it returns an error.

The new address will be effective in the next system reboot. The stack will use the address in the PS 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 PS keys and use the default address in the next system reboot.

Note: Because the PS keys are located in flash and flash wearing can occur, avoid calling this command regularly.

C API

/* Function */
struct gecko_msg_system_set_identity_address_rsp_t *gecko_cmd_system_set_identity_address(bd_addr address, uint8 type);

/* Response id */
gecko_rsp_system_set_identity_address_id

/* Response structure */
struct gecko_msg_system_set_identity_address_rsp_t
{
  uint16 result;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
bd_addr address Bluetooth identity address in little endian format
uint8 type Address type
  • 0: Public device address
  • 1: Static random address

Response Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 result Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_set_tx_power

Set the global maximum TX power for Bluetooth. The returned value is the selected maximum output power level after applying the RF path compensation. If the GATT server contains a TX power service, the TX Power Level attribute will be updated accordingly.

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.

By default, the global maximum TX power value is 8 dBm.

NOTE: Do not use this command while advertising, scanning, or during connection.

C API

/* Function */
struct gecko_msg_system_set_tx_power_rsp_t *gecko_cmd_system_set_tx_power(int16 power);

/* Response id */
gecko_rsp_system_set_tx_power_id

/* Response structure */
struct gecko_msg_system_set_tx_power_rsp_t
{
  int16 set_power;
}

Command Parameters (for BGAPI headers refer to link)

Type Name Description
int16 power TX power in 0.1 dBm steps. For example, the value of 10 is 1 dBm and 55 is 5.5 dBm.

Response Parameters (for BGAPI headers refer to link)

Type Name Description
int16 set_power The selected maximum power level

system events

system_boot

Indicates that the device has started and the radio is ready. This event carries the firmware build number and other software and hardware identification codes.

C API

/* event id*/
gecko_evt_system_boot_id

/* event structure*/
struct gecko_msg_system_boot_evt_t
{
  uint16 major;
  uint16 minor;
  uint16 patch;
  uint16 build;
  uint32 bootloader;
  uint16 hw;
  uint32 hash;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 major Major release version
uint16 minor Minor release version
uint16 patch Patch release number
uint16 build Build number
uint32 bootloader Bootloader version
uint16 hw Hardware type
uint32 hash Version hash

system_external_signal

Indicates that the external signals have been received. External signals are generated from the native application.

C API

/* event id*/
gecko_evt_system_external_signal_id

/* event structure*/
struct gecko_msg_system_external_signal_evt_t
{
  uint32 extsignals;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint32 extsignals Bitmask of external signals received since last event.

system_awake

Indicates that the device is awake and no longer in sleep mode.

NOTE: Stack does not generate this event by itself because sleep and wakeup are managed by applications. If this event is needed, call function gecko_send_system_awake(), which signals the stack to send this event.

C API

/* event id*/
gecko_evt_system_awake_id

/* event structure*/
struct gecko_msg_system_awake_evt_t
{
}

Event does not have parameters (for BGAPI headers refer to link)

system_hardware_error

Indicates that a hardware-related error has occurred.

C API

/* event id*/
gecko_evt_system_hardware_error_id

/* event structure*/
struct gecko_msg_system_hardware_error_evt_t
{
  uint16 status;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 status Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes

system_error

Indicates that an error has occurred. See error codes table for more information.

C API

/* event id*/
gecko_evt_system_error_id

/* event structure*/
struct gecko_msg_system_error_evt_t
{
  uint16 reason;
  uint8array data;
}

Event Parameters (for BGAPI headers refer to link)

Type Name Description
uint16 reason Result code
  • 0: success
  • Non-zero: an error has occurred
For other values see Error codes
uint8array data Data related to the error; this field can be empty.

system enumerations

system_linklayer_config_key

These Keys are used to configure Link Layer Operation

Enumerations

Value Name Description
1 system_linklayer_config_key_halt Same as system_halt command, value-0 Stop Radio 1- Start Radio
2 system_linklayer_config_key_priority_range Sets the RAIL priority_mapping offset field of the link layer priority configuration structure to the first byte of the value field.
3 system_linklayer_config_key_scan_channels Sets channels to scan on. The first byte of the value is the channel map. 0x1 = Channel 37, 0x2 = Channel 38, 0x4 = Channel 39
4 system_linklayer_config_key_set_flags 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
5 system_linklayer_config_key_clr_flags Value is flags to clear. Flags are the same as in SET_FLAGS command.
7 system_linklayer_config_key_set_afh_interval Set afh_scan_interval field of Link Layer priority configuration structure.
9 system_linklayer_config_key_set_priority_table Value contains priority table to be copied over the existing table. If value is smaller than full table then only those values are updated. see gecko_bluetooth_ll_priorities struct for the definition of priority table.