0xA2 - sd_ble_gatts_characteristic_add

Function packet format

Frame format encoding of the sd_ble_gatts_characteristic_add packet.

Operation Code = 0xA2 (162) for sd_ble_gatts_characteristic_add, see BLE_GATTS_SVCS.

The parameters provided as input to sd_ble_gatts_characteristic_add are encoded in the following order:

- 1 byte:		Operation Code, Value = 0xA2 (162)
- 2 bytes:		Service Handle
- 1 byte:		Metadata Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 11..539 bytes:	ble_gatts_char_md_t	Conditional: Characteristic Metadata
- 1 byte:		Characteristic Attribute Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 9..527 bytes:	ble_gatts_attr_t	Conditional: Characteristic Attribute
- 1 byte:		Handles Present
		0x00 Field not present
		0x01 Field present on Application Chip

Figure 1: Packet format for sd_ble_gatts_characteristic_add function.

Encoding of Characteristic Metadata

- 1 byte:	ble_gatt_char_props_t	Characteristic Properties
- 1 byte:	ble_gatt_char_ext_props_t	Characteristic Extended Properties
- 2 bytes:		ble_gatts_char_md_t::char_user_desc_max_size
- 2 bytes:		ble_gatts_char_md_t::char_user_desc_size
- 1 byte:		User Descriptor present
- 0..512 bytes:		User Descriptor
- 1 byte:		Presentation Format Structure present
- 7 bytes:		ble_gatts_char_pf_t Presentation Format Structure
- 1 byte:		Attribute Metadata User Description Descriptor present
- 3 byte:		ble_gatts_attr_md_t Attribute Metadata User Description Descriptor
- 1 byte:		Attribute metadata for the Client Characteristic Configuration Descriptor present
- 3 bytes:		Attribute metadata for the Client Characteristic Configuration Descriptor
- 1 byte:		Attribute metadata for the Server Characteristic Configuration Descriptor present
- 3 bytes:		Attribute metadata for the Server Characteristic Configuration Descriptor

Figure 2: Encoding of Characteristic Metadata.

Encoding of Characteristic Metadata Property field

- 1 byte:	ble_gatt_char_props_t	Characteristic properties
	- bit 0:	ble_gatt_char_props_t::broadcast
	- bit 1:	ble_gatt_char_props_t::read
	- bit 2:	ble_gatt_char_props_t::write_wo_resp
	- bit 3:	ble_gatt_char_props_t::write
	- bit 4:	ble_gatt_char_props_t::notify
	- bit 5:	ble_gatt_char_props_t::indicate
	- bit 6:	ble_gatt_char_props_t::auth_signed_wr
	- bit 7:	Not used

Figure 3: Encoding of Property field inside Characteristic Metadata.

Encoding of Characteristic Metadata Extended Property field

- 1 byte:	ble_gatt_char_ext_props_t	Characteristic Extended Properties
	- bit 0:	ble_gatt_char_ext_props_t::reliable_wr
	- bit 1:	ble_gatt_char_ext_props_t::wr_aux
	- bit 2..7:	Not used

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

Encoding of Characteristic Metadata Presentation Format field.

- 7 bytes:	ble_gatts_char_pf_t	Presentation Format
- 1 byte:		Format
- 1 bytes:		Exponent
- 2 bytes:		Unit
- 1 byte:		Namespace
- 2 bytes:		Description

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:

- 1 byte:	ble_gatts_attr_md_t::read_perm	Read Permission
	- bit 0..3:	sm
	- bit 4..7:	lv
- 1 byte:	ble_gatts_attr_md_t::write_perm	Write Permission
	- bit 0..3:	sm
	- bit 4..7:	lv
- 1 byte:	ble_gatts_attr_md_t	Length Location and Authorization
	- bit 0:	vlen
	- bit 1-2:	vloc
	- bit 3:	rd_auth
	- bit 4:	wr_auth

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

Encoding of Characteristic Attributes

- 1 byte:		UUID Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 3 bytes:	ble_uuid_t	Conditional: UUID
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 1 byte:		Attribute Metadata Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 3 bytes:	ble_gatts_attr_md_t	Conditional: Attribute Metadata
- 2 bytes:		Value length
- 2 bytes:		Value offset
- 2 bytes:		Maximum value length
- 1 byte:		Attribute Data Present
		0x00 Field not present
		0x01 Field present and follows immediately in the packet
- 0..512 bytes:	ble_gatts_attr_md_t	Conditional: Attribute Data

Figure 7: Encoding of Characteristic Attributes.

Encoding of Characteristic Attributes UUID field.

- 2 bytes:	ble_uuid_t::uuid	UUID Value
- 1 byte:	ble_uuid_t::type	UUID Type, see Types of UUID

Figure 8: Encoding of UUID field inside Characteristic Attributes.

Encoding of Characteristic Attributes Metadata field.

- 1 byte:	ble_gatts_attr_md_t::read_perm	Read Permission
	- bit 0..3:	sm
	- bit 4..7:	lv
- 1 byte:	ble_gatts_attr_md_t::write_perm	Write Permission
	- bit 0..3:	sm
	- bit 4..7:	lv
- 1 byte:	ble_gatts_attr_md_t	Length Location and Authorization
	- bit 0:	vlen
	- bit 1-2:	vloc
	- bit 3:	rd_auth
	- bit 4:	wr_auth

Figure 9: Encoding of Metadata field inside Characteristic Attributes.

Response packet format

In case of an error, the following data is encoded:

- 1 byte:		Operation Code, Value = 0xA2 (162)
- 1 byte:		nRF Error Code

Figure 2: Packet format for sd_ble_gatts_characteristic_add error response.

In case of a successful command, i.e. 'nRF Error Code' = NRF_SUCCESS , the following data is encoded:

- 1 byte:		Operation Code, Value = 0xA2 (162)
- 4 bytes:		nRF Success
- 4 bytes:		Length
- 2 bytes:		Value Handle
- 2 bytes:		User Desc Handle
- 2 bytes:		CCCD Handle
- 2 bytes:		SCCD Handle

Figure 3: Response Packet format for sd_ble_gatts_characteristic_add function.