BLE S120 GATTS Functions

Table of Contents

• 0xA0 - sd_ble_gatts_service_add
  • Function packet format
  • Response packet format
• 0xA1 - sd_ble_gatts_include_add
  • Function packet format
  • Response packet format
• 0xA2 - sd_ble_gatts_characteristic_add
  • Function packet format
  • Encoding of Characteristic Metadata
  • Encoding of Characteristic Metadata Property field
  • Encoding of Characteristic Metadata Extended Property field
  • Encoding of Characteristic Metadata Presentation Format field
  • Encoding of User Descriptor, CCCD, and SCCD Descriptor Metadata fields
  • Encoding of Characteristic Attributes
  • Encoding of Characteristic Attributes UUID field
  • Encoding of Characteristic Attributes Metadata field
  • Response packet format
• 0xA3 - sd_ble_gatts_descriptor_add
  • Function packet format
  • Response packet format
• 0xA4 - sd_ble_gatts_value_set
  • Function packet format
  • Response packet format
• 0xA5 - sd_ble_gatts_value_get
  • Function packet format
  • Response packet format
• 0xA6 - sd_ble_gatts_hvx
  • Function packet format
  • Response packet format
• 0xA7 - sd_ble_gatts_service_changed
  • Function packet format
  • Response packet format
• 0xA8 - sd_ble_gatts_rw_authorize_reply
  • Function packet format
  • Response packet format
• 0xA9 - sd_ble_gatts_sys_attr_set
  • Function packet format
  • Response packet format
• 0xAA - sd_ble_gatts_sys_attr_get
  • Function packet format
  • Response packet format

0xA0 - sd_ble_gatts_service_add

Function packet format

Frame format encoding of the sd_ble_gatts_service_add packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA0, see BLE_GATTS_SVCS
1 byte	Service Type	See GATT Server Service Types
1 byte	UUID Present	0x00 - not present, 0x01 - present
3 bytes	UUID	See ble_uuid_t
1 byte	Handle Present	0x00 - not present, 0x01 - present

As can also be seen inside Figure 1, the 3 bytes inside ble_uuid_t are encoded as:

Length	Parameter	Value
2 bytes	UUID	See ble_uuid_t::uuid
1 byte	UUID Type	See ble_uuid_t::type

Figure 1: Packet format for sd_ble_gatts_service_add function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_service_add response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA0, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_service_add
2 bytes	Conditional: Handle Value	See sd_ble_gatts_service_add

Figure 2: Packet format sd_ble_gatts_service_add response packet.

0xA1 - sd_ble_gatts_include_add

Function packet format

Frame format encoding of the sd_ble_gatts_include_add packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA1, see BLE_GATTS_SVCS
2 bytes	Service Handle	See sd_ble_gatts_include_add
2 bytes	Include Service Handle	See sd_ble_gatts_include_add
1 byte	Include Handle Present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gatts_include_add function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_include_add response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA1, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_include_add
2 bytes	Conditional: Handle Value	See sd_ble_gatts_include_add

Figure 2: Packet format sd_ble_gatts_include_add response packet.

0xA2 - sd_ble_gatts_characteristic_add

Function packet format

Frame format encoding of the sd_ble_gatts_characteristic_add packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA2, see BLE_GATTS_SVCS
2 bytes	Service Handle	Service handle
1 byte	Metadata Present	0x00 - not present, 0x01 - present
11..539 bytes	Conditional: Characteristic Metadata	See ble_gatts_char_md_t
1 byte	Characteristic Attribute Present	0x00 - not present, 0x01 - present
9..527 bytes	Conditional: Characteristic Attribute	See ble_gatts_attr_t
1 byte	Handles Present	0x00 - not present, 0x01 - present on Application Chip

Figure 1: Packet format for sd_ble_gatts_characteristic_add function.

Encoding of Characteristic Metadata

Length	Parameter	Value
1 byte	Characteristic Properties	See ble_gatt_char_props_t
1 byte	Characteristic Extended Properties	See ble_gatt_char_ext_props_t
2 bytes	User Descriptor Maximum Size	See ble_gatts_char_md_t::char_user_desc_max_size
2 bytes	User Descriptor Size	See ble_gatts_char_md_t::char_user_desc_size
1 byte	User Descriptor Present	0x00 - not present, 0x01 - present
0..512 bytes	User Descriptor	See ble_gatts_char_md_t::p_char_user_desc
1 byte	Presentation Format Structure Present	0x00 - not present, 0x01 - present
7 bytes	Presentation Format Structure	See ble_gatts_char_pf_t
1 byte	Attribute Metadata User Description Present	0x00 - not present, 0x01 - present
3 bytes	Attribute Metadata User Description	See ble_gatts_attr_md_t
1 byte	Attribute metadata for the Client Characteristic Configuration Present	0x00 - not present, 0x01 - present
3 bytes	Attribute metadata for the Client Characteristic Configuration	See ble_gatts_attr_md_t
1 byte	Attribute metadata for the Server Characteristic Configuration Present	0x00 - not present, 0x01 - present
3 bytes	Attribute metadata for the Server Characteristic Configuration Description	See ble_gatts_attr_md_t

Figure 2: Encoding of Characteristic Metadata.

Encoding of Characteristic Metadata Property field

Length	Parameter	Value
bit 0	broadcast	See ble_gatt_char_props_t::broadcast
bit 1	read	See ble_gatt_char_props_t::read
bit 2	write_wo_resp	See ble_gatt_char_props_t::write_wo_resp
bit 3	write	See ble_gatt_char_props_t::write
bit 4	notify	See ble_gatt_char_props_t::notify
bit 5	indicate	See ble_gatt_char_props_t::indicate
bit 6	auth_signed_wr	See ble_gatt_char_props_t::auth_signed_wr
bit 7	not used	Not used

Figure 3: Encoding of Property field inside Characteristic Metadata.

Encoding of Characteristic Metadata Extended Property field

Length	Parameter	Value
bit 0	reliable_wr	See ble_gatt_char_ext_props_t::reliable_wr
bit 1	wr_aux	See ble_gatt_char_ext_props_t::wr_aux
bit 2..7	not used	Not used

Figure 4: Encoding of Extended Property field inside Characteristic Metadata.

Encoding of Characteristic Metadata Presentation Format field

Length	Parameter	Value
1 byte	format	See ble_gatts_char_pf_t::format
1 byte	exponent	See ble_gatts_char_pf_t::exponent
2 bytes	unit	See ble_gatts_char_pf_t::unit
1 byte	name_space	See ble_gatts_char_pf_t::name_space
2 bytes	desc	See ble_gatts_char_pf_t::desc

Figure 5: Encoding of Presentation Format field inside Characteristic Metadata.

Encoding of User Descriptor, CCCD, and SCCD Descriptor Metadata fields

For User Descriptor, CCCD, and SCCD Descriptor, the Metadata field is encoded in the following order:

Length	Parameter	Value
1 byte	read_perm	See ble_gatts_attr_md_t::read_perm
1 byte	write_perm	See ble_gatts_attr_md_t::write_perm
1 byte	Bit attributes	See ble_gatts_attr_md_t

Read and write permissions are encoded in the following order:

Length	Parameter	Value
bit 0..3	sm	See ble_gap_conn_sec_mode_t::sm
bit 4..7	lv	See ble_gap_conn_sec_mode_t::lv

Bit attributes are encoded in the following order:

Length	Parameter	Value
bit 0	vlen	See ble_gatts_attr_md_t::vlen
bit 1..2	vloc	See ble_gatts_attr_md_t::vloc
bit 3	rd_auth	See ble_gatts_attr_md_t::rd_auth
bit 4	wr_auth	See ble_gatts_attr_md_t::wr_auth
bit 5..7	not used	Not used

Figure 6: Encoding of User Descriptor, CCCD, and SCCD Descriptor Metadata fields inside Characteristic Metadata.

Encoding of Characteristic Attributes

Note that ble_gatts_attr_t::init_len is relocated in the serialized structure in order to have the length field preceeding the data field.

Length	Parameter	Value
1 byte	UUID Present	0x00 - not present, 0x01 - present
3 bytes	Conditional: UUID	See ble_gatts_attr_t::p_uuid
1 byte	Attribute Metadata Present	0x00 - not present, 0x01 - present
3 bytes	Conditional: Attribute Metadata	See ble_gatts_attr_t::p_attr_md
2 bytes	Value offset	See ble_gatts_attr_t::init_offs
2 bytes	Maximum Value Length	See ble_gatts_attr_t::max_len
2 bytes	Value Length	See ble_gatts_attr_t::init_len
1 byte	Attribute Data Present	0x00 - not present, 0x01 - present
n bytes	Attribute Data	See ble_gatts_attr_t::p_value

Figure 7: Encoding of Characteristic Attributes.

Encoding of Characteristic Attributes UUID field

Length	Parameter	Value
2 bytes	UUID	See ble_uuid_t::uuid
1 byte	Type	See ble_uuid_t::type

Figure 8: Encoding of UUID field inside Characteristic Attributes.

Encoding of Characteristic Attributes Metadata field

Length	Parameter	Value
1 byte	read_perm	See ble_gatts_attr_md_t::read_perm
1 byte	write_perm	See ble_gatts_attr_md_t::write_perm
1 byte	Bit attributes	See ble_gatts_attr_md_t

Read and write permissions are encoded in the following order:

Length	Parameter	Value
bit 0..3	sm	See ble_gap_conn_sec_mode_t::sm
bit 4..7	lv	See ble_gap_conn_sec_mode_t::lv

Bit attributes are encoded in the following order:

Length	Parameter	Value
bit 0	vlen	See ble_gatts_attr_md_t::vlen
bit 1..2	vloc	See ble_gatts_attr_md_t::vloc
bit 3	rd_auth	See ble_gatts_attr_md_t::rd_auth
bit 4	wr_auth	See ble_gatts_attr_md_t::wr_auth
bit 5..7	not used	Not used

Figure 9: Encoding of Metadata field inside Characteristic Attributes.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_characteristic_add response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA2, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_characteristic_add
1 byte	Conditional: Handles Present	0x00 - not present, 0x01 - Handles are present in the packet
8 bytes	Conditional: Handles	See ble_gatts_char_handles_t

ble_gatts_char_handles_t is encoded in the following order:

Length	Parameter	Value
2 bytes	Value Handle	See ble_gatts_char_handles_t::value_handle
2 bytes	User Desc Handle	See ble_gatts_char_handles_t::user_desc_handle
2 bytes	CCCD Handle	See ble_gatts_char_handles_t::cccd_handle
2 bytes	SCCD Handle	See ble_gatts_char_handles_t::sccd_handle

Figure 10: Response Packet format for sd_ble_gatts_characteristic_add response.

0xA3 - sd_ble_gatts_descriptor_add

Function packet format

Frame format encoding of the sd_ble_gatts_descriptor_add packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA3, see BLE_GATTS_SVCS
2 bytes	Characteristic Handle	Characteristic handle
1 byte	Characteristic Attribute Present	0x00 - not present, 0x01 - present
11..527 bytes	Conditional: Characteristic Attribute	See ble_gatts_attr_t
1 byte	Handle Present	0x00 - not present, 0x01 - present on application chip

Figure 1: Packet format for sd_ble_gatts_descriptor_add function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_descriptor_add response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA3, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_descriptor_add
2 bytes	Descriptor handle	Descriptor handle

Figure 2: Response Packet format for sd_ble_gatts_descriptor_add response.

0xA4 - sd_ble_gatts_value_set

Function packet format

Frame format encoding of the sd_ble_gatts_value_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA4, see BLE_GATTS_SVCS
2 bytes	Connection Handle	See sd_ble_gatts_value_set
2 bytes	Attribute Handle	See sd_ble_gatts_value_set
1 byte	Attribute Value Present	0x00 - not present, 0x01 - present
2 bytes	Value Length	See sd_ble_gatts_value_set
2 bytes	Offset	See sd_ble_gatts_value_set
1 byte	Value Present	0x00 - not present, 0x01 - present
0...512 bytes	Value	See sd_ble_gatts_value_set

Figure 1: Packet format for sd_ble_gatts_value_set function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_value_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA4, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_value_set
2 bytes	Conditional: Attribute Value	See sd_ble_gatts_value_set

Figure 2: Packet format for sd_ble_gatts_value_set function response.

0xA5 - sd_ble_gatts_value_get

Function packet format

Frame format encoding of the sd_ble_gatts_value_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA5, see BLE_GATTS_SVCS
2 bytes	Connection Handle	See sd_ble_gatts_value_get
2 bytes	Attribute Handle	See sd_ble_gatts_value_get
1 byte	Attribute Value Present	0x00 - not present, 0x01 - present
2 bytes	Conditional: Value Length	See ble_gatts_value_t
2 bytes	Conditional: Offset	See ble_gatts_value_t
1 byte	Conditional: Value Present	0x00 - not present, 0x01 - present

Figure 1: Packet format for sd_ble_gatts_value_get function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_value_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA5, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_value_get
2 bytes	Conditional: Value Length	See ble_gatts_value_t
2 bytes	Conditional: Offset	See ble_gatts_value_t
1 byte	Conditional: Value Present	0x00 - not present, 0x01 - present
0 .. 512 bytes	Conditional: Value	See ble_gatts_value_t

Figure 2: Packet format for sd_ble_gatts_value_get function response.

0xA6 - sd_ble_gatts_hvx

Function packet format

Frame format encoding of the sd_ble_gatts_hvx packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA6, see BLE_GATTS_SVCS
2 bytes	Connection Handle	sd_ble_gatts_hvx
1 byte	HVX Parameters Present	0x00 - not present, 0x01 - present
n bytes	Conditional:HVX Parameters	See sd_ble_gatts_hvx

As shown in Figure 1, the data inside ble_gatts_hvx_params_t is encoded as:

Length	Parameter	Value
2 bytes	handle	See ble_gatts_hvx_params_t::handle
1 byte	type	See ble_gatts_hvx_params_t::type
2 bytes	offset	See ble_gatts_hvx_params_t::offset
1 byte	Length Field Present	0x00 - not present, 0x01 - present
2 bytes	Conditional: Length	See ble_gatts_hvx_params_t::p_len
1 byte	Data Field Present	0x00 - not present, 0x01 - present
n bytes	Conditional: Data	See ble_gatts_hvx_params_t::p_data

Figure 1: Packet format for sd_ble_gatts_hvx function.

Response packet format

If a command was executed successfully, so that 'nRF Error Code' = NRF_SUCCESS, the nRF Error Code is followed by conditional data.

Frame format encoding of the sd_ble_gatts_hvx response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA6, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_hvx
1 byte	Number of Data Written Present	0x00 - not present, 0x01 - present
2 bytes	Conditional: Number of Data written	See sd_ble_gatts_hvx

Figure 2: Packet format sd_ble_gatts_hvx response packet.

0xA7 - sd_ble_gatts_service_changed

Function packet format

Frame format encoding of the sd_ble_gatts_service_changed packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA7, see BLE_GATTS_SVCS
2 bytes	Connection Handle	See sd_ble_gatts_service_changed
2 bytes	Start Handle	See sd_ble_gatts_service_changed
2 bytes	End Handle	See sd_ble_gatts_service_changed

Figure 1: Packet format for sd_ble_gatts_service_changed function.

Response packet format

Frame format encoding of the sd_ble_gatts_service_changed response packet.

Data for the response packet is encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA7, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_service_changed

Figure 2: Response Packet format for sd_ble_gatts_service_changed response.

0xA8 - sd_ble_gatts_rw_authorize_reply

Function packet format

Frame format encoding of the sd_ble_gatts_rw_authorize_reply packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA8, see BLE_GATTS_SVCS
2 bytes	Connection Handle	See sd_ble_gatts_rw_authorize_reply
1 byte	RW Authorize Reply Params Present	0x00 if System Attributes is a NULL pointer, 0x01 otherwise
n bytes	Conditional: RW Authorize Reply Params	See sd_ble_gatts_rw_authorize_reply

ble_gatts_rw_authorize_reply_params_t is encoded in the following order:

Length	Parameter	Value
1 byte	Type	See ble_gatts_rw_authorize_reply_params_t::type
n bytes	Read or Write Params	See ble_gatts_rw_authorize_reply_params_t::read or ble_gatts_rw_authorize_reply_params_t::write

Figure 1: Packet format for sd_ble_gatts_rw_authorize_reply function.

Read parameters (ble_gatts_read_authorize_params_t) are encoded in the following order (also presented in Figure 2):

Length	Parameter	Value
2 bytes	GATT Status	See ble_gatts_read_authorize_params_t::gatt_status
1 byte	Update	See ble_gatts_read_authorize_params_t::update
2 bytes	Offset	See ble_gatts_read_authorize_params_t::offset
2 bytes	Len	See ble_gatts_read_authorize_params_t::len
1 byte	Data Present	0x00 if data is a NULL pointer, 0x01 otherwise
n bytes	Data	See ble_gatts_read_authorize_params_t::p_data

Figure 2: Packet format for ble_gatts_read_authorize_params_t struct.

Write parameters (ble_gatts_write_authorize_params_t) are encoded in the following order (also presented in Figure 3):

Length	Parameter	Value
2 bytes	GATT Status	See GATT Status Codes

Figure 3: Packet format for ble_gatts_write_authorize_params_t struct.

Response packet format

Frame format encoding of the sd_ble_gatts_rw_authorize_reply response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA8, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_rw_authorize_reply

Figure 4: Packet format for sd_ble_gatts_rw_authorize_reply response.

0xA9 - sd_ble_gatts_sys_attr_set

Function packet format

Frame format encoding of the sd_ble_gatts_sys_attr_set packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xA9, see BLE_GATTS_SVCS
2 bytes	Connection Handle	Handle value
1 byte	System Attributes Present	0x00 if System Attributes is a NULL pointer, 0x01 otherwise
2 bytes	Conditional: Length of System Attributes Data	n - number of bytes of System Attributes Data
n bytes	Conditional: System Attributes Data	Data
4 bytes	Flags	Additional optional flags

Figure 1: Packet format for sd_ble_gatts_sys_attr_set function.

Response packet format

Frame format encoding of the sd_ble_gatts_sys_attr_set response packet:

Length	Parameter	Value
1 byte	Operation Code	0xA9, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_sys_attr_set

Figure 2: Packet format for sd_ble_gatts_sys_attr_set response.

0xAA - sd_ble_gatts_sys_attr_get

Function packet format

Frame format encoding of the sd_ble_gatts_sys_attr_get packet.

The parameters are encoded in the following order:

Length	Parameter	Value
1 byte	Operation Code	0xAA, see BLE_GATTS_SVCS
2 bytes	Connection Handle	Handle value
1 byte	System Attribute Length Present	0x00 if is a NULL pointer, 0x01 otherwise
2 bytes	Conditional: System Attribute Length	See sd_ble_gatts_sys_attr_get
1 byte	System Attribute Data Present	0x00 if is a NULL pointer, 0x01 otherwise
4 bytes	Flags	Additional optional flags

Figure 1: Packet format for sys_attr_get_packet function.

Response packet format

If a command was executed successfully, the response packet will encode the return value NRF_SUCCESS. If a valid pointer was provided in the function packet, so that 'System Attribute Present' = 0x01, the System Attributes from the BLE S120 SoftDevice will be encoded, and the length of the data will be encoded in the length field. If a NULL pointer was provided in the function packet, so that 'System Attribute Present' = 0x00 , the length of the System Attribute Data will be encoded, but no data will follow.

Frame format encoding of the sd_ble_gatts_sys_attr_get response packet:

Length	Parameter	Value
1 byte	Operation Code	0xAA, see BLE_GATTS_SVCS
4 bytes	nRF Error Code	See sd_ble_gatts_sys_attr_get
2 bytes	Conditional: System Attribute Length	See sd_ble_gatts_sys_attr_get
1 byte	Conditional: System Attribute Data Present	0x00 if is a NULL pointer, 0x01 otherwise
n bytes	Conditional: System Attribute Data	See sd_ble_gatts_sys_attr_get

Figure 2: Packet format for sd_ble_gatts_sys_attr_get function response.