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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x00 lolen Minimum payload length
2 0x01 class Message class:System
3 0x03 method Message ID

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x06 lolen Minimum payload length
2 0x01 class Message class:System
3 0x03 method Message ID
4-9 bd_addr address Bluetooth public address in little endian format

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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0f method Message ID
4 uint8 reset Reset counters if parameter value is nonzero

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x0a lolen Minimum payload length
2 0x01 class Message class:System
3 0x0f method Message ID
4-5 uint16 result Result code
  • 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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0b method Message ID
4 uint8 length Length of random data. Maximum length is 16 bytes.

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x03 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0b method Message ID
4-5 uint16 result Result code
  • 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.

NOTE:Software timer is also halted. Hardware interrupts are the only way to wake up from energy mode 2 when system is halted.

Command

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0c method Message ID
4 uint8 halt Values:
  • 1: halt
  • 0: resume

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0c method Message ID
4-5 uint16 result Result code
  • 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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x00 lolen Minimum payload length
2 0x01 class Message class:System
3 0x00 method Message ID

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x00 method Message ID
4-5 uint16 result Result code
  • 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_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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x01 lolen Minimum payload length
2 0x01 class Message class:System
3 0x01 method Message ID
4 uint8 dfu Boot mode:
  • 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

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

system_set_bt_address

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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x06 lolen Minimum payload length
2 0x01 class Message class:System
3 0x04 method Message ID
4-9 bd_addr address Bluetooth public address in little endian format

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x04 method Message ID
4-5 uint16 result Result code
  • 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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0d method Message ID
4 uint8 type Device name to set. Values:
  • 0: OTA device name
5 uint8array name Device name

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0d method Message ID
4-5 uint16 result Result code
  • 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_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

Byte Type Name Description
0 0x20 hilen Message type: Command
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0a method Message ID
4-5 int16 power TX power in 0.1dBm steps, for example the value of 10 is 1dBm and 55 is 5.5dBm

Response

Byte Type Name Description
0 0x20 hilen Message type: Response
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x0a method Message ID
4-5 int16 set_power The selected maximum power level

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

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x12 lolen Minimum payload length
2 0x01 class Message class:System
3 0x00 method Message ID
4-5 uint16 major Major release version
6-7 uint16 minor Minor release version
8-9 uint16 patch Patch release number
10-11 uint16 build Build number
12-15 uint32 bootloader Bootloader version
16-17 uint16 hw Hardware type
18-21 uint32 hash Version hash

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

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x04 lolen Minimum payload length
2 0x01 class Message class:System
3 0x03 method Message ID
4-7 uint32 extsignals Bitmask of external signals received since last 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

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x00 lolen Minimum payload length
2 0x01 class Message class:System
3 0x04 method Message ID

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

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x02 lolen Minimum payload length
2 0x01 class Message class:System
3 0x05 method Message ID
4-5 uint16 status Result code
  • 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

Byte Type Name Description
0 0xa0 hilen Message type: Event
1 0x03 lolen Minimum payload length
2 0x01 class Message class:System
3 0x06 method Message ID
4-5 uint16 reason Standard code of the error just happened.
6 uint8array data Data related to the error, this field can be empty.

API

/* event id*/
gecko_evt_system_error_id

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