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.

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#

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

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

Command#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x02

lolen

Minimum payload length

2

0x01

class

Message class:System

3

0x0e

method

Message ID

4

uint8

key

Key to configure:

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

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x01

class

Message class:System

3

0x0e

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

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#

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#

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

Byte

Type

Name

Description

0

0x20

hilen

Message type: Command

1

0x07

lolen

Minimum payload length

2

0x01

class

Message class:System

3

0x13

method

Message ID

4-9

bd_addr

address

Bluetooth identity address in little endian

format

10

uint8

type

Address type

  • 0: Public device address

  • 1: Static random address

Response#

Byte

Type

Name

Description

0

0x20

hilen

Message type: Response

1

0x02

lolen

Minimum payload length

2

0x01

class

Message class:System

3

0x13

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

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  
}