System (system)#

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

system commands#

system_get_bt_address#

This command can be used to read the Bluetooth public address used by the device.

Command#

Response#

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  
}  

system_get_counters#

Get packet and error counters

Command#

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes
6-7 | uint16 | tx_packets | Number of successfully transmitted packets
8-9 | uint16 | rx_packets | Number of successfully received packets
10-11 | uint16 | crc_errors | Number of received packets with CRC errors
12-13 | uint16 | failures | Number of radio failures like aborted tx/rx packets, scheduling failures, etc

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  
}  

system_get_random_data#

This command can be used to get random data up to 16 bytes.

Command#

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes
6 | uint8array | data | Random data

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  
}  

system_halt#

This command forces radio to idle state and allows device to sleep. Advertising, scanning, connections and software timers are halted by this commands. Halted operations are resumed by calling this command with parameter 0. Connections stay alive if system is resumed before connection supervision timeout.

This command should only be used for a short time period (a few seconds at maximum). It halts Bluetooth activity, but all the tasks and operations are still existing inside 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: Software timer is also halted. Hardware interrupts are the only way to wake up from energy mode 2 when system is halted.

Command#

• 1: halt

• 0: resume

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_hello#

This command does not trigger any event but the response to the command is used to verify that communication between the host and the device is working.

Command#

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_linklayer_configure#

Send configuration data to linklayer. This command is used to fine tune low level Bluetooth operation.

Command#

• 1: HALT, same as system_halt command, value-0 Stop Radio 1- Start Radio

• 2: PRIORITY_RANGE, Sets RAIL priority_mapping offset field of linklayer Priority configuration structure to the first byte of value field.

• 3: SCAN_CHANNELS, Sets channels to scan on. First byte of value is channel map. 0x1 = Channel 37, 0x2 = Channel 38, 0x4 = Channel 39

• 4: SET_FLAGS, Set Link Layer configuration flags. value is little endian 32bit integer. Flag Values:

  • 0x00000001 - Disable Feature Exchange when slave

  • 0x00000002 - Disable Feature Exchange when master

• 5: CLR_FLAGS, value is flags to clear. Flags are same as in SET_FLAGS command.

• 7: SET_AFH_INTERVAL, Set afh_scan_interval field of Link Layer priority configuration structure.

• 0:

5 | uint8array | data | Configuration data. Length and contents of data field depend on the key value used.

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_reset#

This command can be used to reset the system. It 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.

Command#

• 0: Normal reset

• 1: Boot to UART DFU mode

• 2: Boot to OTA DFU mode

Command does not have response#

API#

/* Function */  
void *gecko_cmd_system_reset(uint8 dfu);  
  
/* Command does not have response */  

Events generated#

system_set_bt_address#

Deprecated. Replacement is system_set_identity_address command.

This command can be used to 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 it will be 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. Thus passing one of them into this command will cause the stack to use the default address in the next system reboot.

Command#

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_set_device_name#

This command can be used to set the device name. Currently it is possible to set the name which will be used during the OTA update. The name will be stored in persistent storage. If the OTA device name is also set in gecko configuration, the name stored in persistent storage is overwritten with the name in gecko configuration during device boot.

Command#

• 0: OTA device name

5 | uint8array | name | Device name

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_set_identity_address#

This command can be used to set the device's Bluetooth identity address. The address can be a public device address or static random address. A valid address set with this command overrides the default Bluetooth public address that was programmed at production, and it will be 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. Thus passing one of them into this command will cause the stack to use the default address in next system reboot.

Command#

• 0: Public device address

• 1: Static random address

Response#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

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  
}  

system_set_tx_power#

This command can be used to set the global maximum TX power for Bluetooth. The returned value in the response is the selected maximum output power level after applying RF path compensation. If the GATT server contains a Tx Power service, the Tx Power Level attribute of the service 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 will be limited to 10 dBm if Adaptive Frequency Hopping (AFH) is not enabled.

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

NOTE: This command should not be used while advertising, scanning or during connection.

Command#

Response#

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  
}  

system events#

system_boot#

This event indicates the device has started and the radio is ready. This even carries the firmware build number and other SW and HW identification codes.

Event#

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  
}  

system_external_signal#

This event indicates external signals have been received. External signals are generated from native application.

Event#

API#

/* event id*/  
gecko_evt_system_external_signal_id  
  
/* event structure*/  
struct gecko_msg_system_external_signal_evt_t  
{  
  uint32 extsignals  
}  

system_awake#

This event indicates that the device has woken up from sleep mode.

NOTE: Stack does not generate this event by itself as sleep and wakeup are managed in applications. If this event is needed, the application should call function gecko_send_system_awake() to signal stack to send this event.

Event#

API#

/* event id*/  
gecko_evt_system_awake_id  
  
/* event structure*/  
struct gecko_msg_system_awake_evt_t  
{  
}  

system_hardware_error#

This event indicates that hardware related errors occurred.

Event#

• 0: success

• Non-zero: an error occurred

For other values refer to the Error codes

API#

/* event id*/  
gecko_evt_system_hardware_error_id  
  
/* event structure*/  
struct gecko_msg_system_hardware_error_evt_t  
{  
  uint16 status  
}  

system_error#

This event indicates errors.

Event#

API#

/* event id*/  
gecko_evt_system_error_id  
  
/* event structure*/  
struct gecko_msg_system_error_evt_t  
{  
  uint16 reason,  
  uint8array data  
}