BLE S110 GATTS Functions

nRF5 SDK v9.0.0
nRF51 SDK v9.0.0

Table of Contents

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


service_add_packet.png
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


service_add_resp_packet.png
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


ble_gatts_include_add_packet.png
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


service_add_resp_packet.png
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


gatts_characteristic_add.png
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


gatts_characteristic_add_char_metadata.png
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


gatts_characteristic_add_char_metadata_prop.png
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


gatts_characteristic_add_char_metadata_ext_prop.png
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


gatts_characteristic_add_char_metadata_pres_format.png
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


gatts_characteristic_add_char_metadata_desc_metadata.png
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


gatts_characteristic_add_char_attr.png
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


gatts_characteristic_add_char_attr_uuid.png
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


gatts_characteristic_add_char_attr_metadata.png
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


gatts_characteristic_add_response_packet.png
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


gatts_descriptor_add.png
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


gatts_descriptor_add_response_packet.png
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


value_set_packet_s120.png
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


value_set_resp_packet_s120.png
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


gatts_value_get_packet.png
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


gatts_value_get_response_packet.png
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


hvx_packet.png
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


hvx_resp_packet.png
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


gatts_service_changed.png
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


default_response_packet_generic.png
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::params
gatts_rw_authorize_reply_packet.png
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


gatts_read_authorize_reply_params.png
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


gatts_write_authorize_reply_params.png
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


default_response_packet_generic.png
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


sys_attr_set_packet_s120.png
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


default_response_packet_generic.png
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


sys_attr_get_packet_s120.png
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 S110 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


sys_attr_get_resp_packet.png
Figure 2: Packet format for sd_ble_gatts_sys_attr_get function response.



Please send us your feedback about the documentation! For technical questions, visit the Nordic Developer Zone .