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

Type	Name	Description
bd_addr	address	Bluetooth identity address in little endian format
uint8	type	Address type 0: Public device address 1: Static device 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.