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)#

• 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)#

Response Parameters (for BGAPI headers refer to link)#

• 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)#

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)#

Response Parameters (for BGAPI headers refer to link)#

• 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)#

Response Parameters (for BGAPI headers refer to link)#

• 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)#

• 1: halt

• 0: resume

Response Parameters (for BGAPI headers refer to link)#

• 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)#

• 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)#

Response Parameters (for BGAPI headers refer to link)#

• 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)#

• 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)](bgapi-#

headers)

Events generated#

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)#

Response Parameters (for BGAPI headers refer to link)#

• 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 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)#

• 0: OTA device name

uint8 | name_len | Array length.
uint8array | name_data | Device name

Response Parameters (for BGAPI headers refer to link)#

• 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 static device address. A valid address set with this command will be written into persistent storage using PS 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 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)#

• 0: Public device address

• 1: Static device address

Response Parameters (for BGAPI headers refer to link)#

• 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)#

Response Parameters (for BGAPI headers refer to link)#

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)#

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)#

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)](bgapi-#

headers)

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)#

• 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)#

• 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#

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