Handles the Attribute Protocol (ATT) using Protocol Data Unit (PDU) encoded messages over L2CAP channel. More...

#include <ATTPDUTypes.hpp>

Inheritance diagram for direct_bt::AttPDUMsg:

Collaboration diagram for direct_bt::AttPDUMsg:

Public Types
enum	Opcode : uint8_t { Opcode::PDU_UNDEFINED = 0x00, Opcode::METHOD_MASK = 0x3F, Opcode::COMMAND_FLAG = 0x40, Opcode::AUTH_SIGNATURE_FLAG = 0x80, Opcode::ERROR_RSP = 0x01, Opcode::EXCHANGE_MTU_REQ = 0x02, Opcode::EXCHANGE_MTU_RSP = 0x03, Opcode::FIND_INFORMATION_REQ = 0x04, Opcode::FIND_INFORMATION_RSP = 0x05, Opcode::FIND_BY_TYPE_VALUE_REQ = 0x06, Opcode::FIND_BY_TYPE_VALUE_RSP = 0x07, Opcode::READ_BY_TYPE_REQ = 0x08, Opcode::READ_BY_TYPE_RSP = 0x09, Opcode::READ_REQ = 0x0A, Opcode::READ_RSP = 0x0B, Opcode::READ_BLOB_REQ = 0x0C, Opcode::READ_BLOB_RSP = 0x0D, Opcode::READ_MULTIPLE_REQ = 0x0E, Opcode::READ_MULTIPLE_RSP = 0x0F, Opcode::READ_BY_GROUP_TYPE_REQ = 0x10, Opcode::READ_BY_GROUP_TYPE_RSP = 0x11, Opcode::WRITE_REQ = 0x12, Opcode::WRITE_RSP = 0x13, Opcode::WRITE_CMD = WRITE_REQ + COMMAND_FLAG, Opcode::PREPARE_WRITE_REQ = 0x16, Opcode::PREPARE_WRITE_RSP = 0x17, Opcode::EXECUTE_WRITE_REQ = 0x18, Opcode::EXECUTE_WRITE_RSP = 0x19, Opcode::READ_MULTIPLE_VARIABLE_REQ = 0x20, Opcode::READ_MULTIPLE_VARIABLE_RSP = 0x21, Opcode::MULTIPLE_HANDLE_VALUE_NTF = 0x23, Opcode::HANDLE_VALUE_NTF = 0x1B, Opcode::HANDLE_VALUE_IND = 0x1D, Opcode::HANDLE_VALUE_CFM = 0x1E, Opcode::SIGNED_WRITE_CMD = WRITE_REQ + COMMAND_FLAG + AUTH_SIGNATURE_FLAG }
	ATT Opcode Summary Vol 3, Part F 3.4.8. More...

Public Member Functions
	AttPDUMsg (const uint8_t *source, const jau::nsize_t size)
	Persistent memory, w/ ownership . More...

	AttPDUMsg (const Opcode opc, const jau::nsize_t size)
	Persistent memory, w/ ownership . More...

	AttPDUMsg (const AttPDUMsg &o) noexcept=default

	AttPDUMsg (AttPDUMsg &&o) noexcept=default

AttPDUMsg &	operator= (const AttPDUMsg &o) noexcept=delete

AttPDUMsg &	operator= (AttPDUMsg &&o) noexcept=delete

virtual	~AttPDUMsg () noexcept

constexpr Opcode	getOpcode () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr Opcode	getOpMethod () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr bool	getOpCommandFlag () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr bool	getOpAuthSigFlag () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr jau::nsize_t	getAuthSigSize () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr jau::nsize_t	getPDUParamSize () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

virtual constexpr_cxx20 jau::nsize_t	getPDUValueOffset () const noexcept
	Returns the octet offset to the value segment in this PDU including the mandatory opcode, i.e. More...

constexpr_cxx20 jau::nsize_t	getPDUMinSize () const noexcept
	Returns this PDU's minimum size, i.e. More...

constexpr_cxx20 jau::nsize_t	getPDUValueSize () const noexcept
	Returns the octet size of the value attributes in this PDI, i.e. More...

constexpr_cxx20 jau::nsize_t	getMaxPDUValueSize (const jau::nsize_t mtu) const noexcept
	Returns the theoretical maximum value size of a PDU. More...

virtual constexpr_cxx20 std::string	getName () const noexcept

virtual std::string	toString () const noexcept

Static Public Member Functions
static constexpr uint8_t	number (const Opcode rhs) noexcept

static std::string	getOpcodeString (const Opcode opc) noexcept

static std::unique_ptr< const AttPDUMsg >	getSpecialized (const uint8_t *buffer, jau::nsize_t const buffer_size) noexcept
	Return a newly created specialized instance pointer to base class. More...

Public Attributes
POctets	pdu
	actual received PDU More...

const uint64_t	ts_creation
	creation timestamp in milliseconds More...

Protected Member Functions
void	checkOpcode (const Opcode expected) const

void	checkOpcode (const Opcode exp1, const Opcode exp2) const

virtual std::string	baseString () const noexcept

virtual std::string	valueString () const noexcept

Detailed Description

Handles the Attribute Protocol (ATT) using Protocol Data Unit (PDU) encoded messages over L2CAP channel.

Implementation uses persistent memory w/ ownership copying PDU data to allow intermediate pipe processing.

Vol 3, Part F 2 - Protocol Overview pp

One attribute := { UUID type; uint16_t handle; permissions for higher layer; }, where

UUID is an official assigned number,

handle uniquely references an attribute on a server for client R/W access, see Vol 3, Part F 3.4.4 - 3.4.6, also 3.4.7 (notified/indicated), 3.4.3 (discovery) and 3.2.5 (permissions).

Client sends ATT requests to a server, which shall respond to all.

A device can take client and server roles concurrently.

One server per device, ATT handle is unique for all supported bearers. For each client, server has one set of ATTs. The server (and hence device) can support multiple clients.

Services are distinguished by range of handles for each service. Discovery is of these handle ranges is defined by a higher layer spec.

ATT Protocol has notification and indication capabilities for efficient ATT value promotion to client w/o reading them (Vol 3, Part F 3.3).

All ATT Protocol requests sent over an ATT bearer. Multiple ATT bearers can be established between two devices. Each ATT bearer uses a separate L2CAP channel an can have different configurations.

For LE a single ATT bearer using a fixed L2CAP channel is available ASAP after ACL connection is established. Additional ATT bearers can be established using L2CAP (Vol 3, Part F 3.2.11).

Vol 3, Part F 3 - Basics and Types

ATT handle is uint16_t and valid if > 0x0000, max is 0xffff. ATT handle is unique per server.

ATT value (Vol 3, Part F 3.2.4)

ATT value is uint8_t array of fixed or variable length.
ATT values might be too large for a single PDU, hence it must be sent using multiple PDUs.
ATT value encoding is defined by the ATT type (UUID).
ATT value transmission done via request, response, notification or indication
ATT value variable length is implicit by PDU carrying packet (PDU parent), implying:
- One ATT value per ATT request... unless ATT values have fixed length.
- Only one ATT value with variable length in a request...
- L2CAP preserves DGRAM boundaries
Some PDUs include the ATT value length, for which above limitations don't apply.

Maximum length of an attribute value shall be 512 bytes (Vol 3, Part F 3.2.8), spread across multiple PDUs.
BT Core Spec v5.2: Vol 3, Part A: BT Logical Link Control and Adaption Protocol (L2CAP)
BT Core Spec v5.2: Vol 3, Part F Attribute Protocol (ATT)
BT Core Spec v5.2: Vol 3, Part F 3 ATT PDUs (Protocol Data Unit)
BT Core Spec v5.2: Vol 3, Part F 3.3 ATT PDUs
BT Core Spec v5.2: Vol 3, Part F 4 Security Considerations

AttPDUMsg Base Class

Attribute Protocol (ATT)'s Protocol Data Unit (PDU) message Vol 3, Part F 3.3 and Vol 3, Part F 3.4

Little endian, however, ATT value endianess is defined by above layer.

ATT_MTU Vol 3, Part F 3.2.8 Maximum size of any packet sent. Higher layer spec defines the default ATT_MTU value. LE L2CAP GATT ATT_MTU is 23 bytes (Vol 3, Part G 5.2.1).

Maximum length of an attribute value shall be 512 bytes (Vol 3, Part F 3.2.8), spread across multiple PDUs.

ATT PDU Format Vol 3, Part F 3.3.1

{ uint8_t opcode, uint8_t param[0..ATT_MTU-X], uint8_t auth_sig[0||12] }

with

opcode bits{ 0-5 method, 6 command-flag, 7 auth-sig-flag }

and

X = 1 if auth-sig flag of ATT-opcode is 0, or

X = 13 if auth-sig flag of ATT-opcode is 1.

Definition at line 312 of file ATTPDUTypes.hpp.

Member Enumeration Documentation

◆ Opcode

enum direct_bt::AttPDUMsg::Opcode : uint8_t

strong

ATT Opcode Summary Vol 3, Part F 3.4.8.

Enumerator
PDU_UNDEFINED
METHOD_MASK
COMMAND_FLAG
AUTH_SIGNATURE_FLAG
ERROR_RSP
EXCHANGE_MTU_REQ
EXCHANGE_MTU_RSP
FIND_INFORMATION_REQ
FIND_INFORMATION_RSP
FIND_BY_TYPE_VALUE_REQ
FIND_BY_TYPE_VALUE_RSP
READ_BY_TYPE_REQ
READ_BY_TYPE_RSP
READ_REQ
READ_RSP
READ_BLOB_REQ
READ_BLOB_RSP
READ_MULTIPLE_REQ
READ_MULTIPLE_RSP
READ_BY_GROUP_TYPE_REQ
READ_BY_GROUP_TYPE_RSP
WRITE_REQ
WRITE_RSP
WRITE_CMD
PREPARE_WRITE_REQ
PREPARE_WRITE_RSP
EXECUTE_WRITE_REQ
EXECUTE_WRITE_RSP
READ_MULTIPLE_VARIABLE_REQ
READ_MULTIPLE_VARIABLE_RSP
MULTIPLE_HANDLE_VALUE_NTF
HANDLE_VALUE_NTF
HANDLE_VALUE_IND
HANDLE_VALUE_CFM
SIGNED_WRITE_CMD

Definition at line 316 of file ATTPDUTypes.hpp.

Constructor & Destructor Documentation

◆ AttPDUMsg() [1/4]

direct_bt::AttPDUMsg::AttPDUMsg	(	const uint8_t *	source,
		const jau::nsize_t	size
	)

inline

Persistent memory, w/ ownership .

Definition at line 415 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

◆ AttPDUMsg() [2/4]

direct_bt::AttPDUMsg::AttPDUMsg	(	const Opcode	opc,
		const jau::nsize_t	size
	)

inline

Persistent memory, w/ ownership .

Definition at line 422 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

◆ AttPDUMsg() [3/4]

direct_bt::AttPDUMsg::AttPDUMsg ( const AttPDUMsg & o )

defaultnoexcept

◆ AttPDUMsg() [4/4]

direct_bt::AttPDUMsg::AttPDUMsg ( AttPDUMsg && o )

defaultnoexcept

◆ ~AttPDUMsg()

virtual direct_bt::AttPDUMsg::~AttPDUMsg ( )

inlinevirtualnoexcept

Definition at line 434 of file ATTPDUTypes.hpp.

Member Function Documentation

◆ baseString()

virtual std::string direct_bt::AttPDUMsg::baseString ( ) const

inlineprotectedvirtualnoexcept

Definition at line 390 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ checkOpcode() [1/2]

void direct_bt::AttPDUMsg::checkOpcode	(	const Opcode	exp1,
		const Opcode	exp2
	)		const

inlineprotected

Definition at line 380 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

◆ checkOpcode() [2/2]

void direct_bt::AttPDUMsg::checkOpcode ( const Opcode expected ) const

inlineprotected

Definition at line 372 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getAuthSigSize()

constexpr jau::nsize_t direct_bt::AttPDUMsg::getAuthSigSize ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

The ATT Authentication Signature size in octets.

This auth-signature comes at the very last of the PDU.

Definition at line 457 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getMaxPDUValueSize()

constexpr_cxx20 jau::nsize_t direct_bt::AttPDUMsg::getMaxPDUValueSize ( const jau::nsize_t mtu ) const

inlinenoexcept

Returns the theoretical maximum value size of a PDU.

 ATT_MTU - getAuthSigSize() - value-offset

Definition at line 533 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getName()

virtual constexpr_cxx20 std::string direct_bt::AttPDUMsg::getName ( ) const

inlinevirtualnoexcept

Reimplemented in direct_bt::AttFindInfoRsp, direct_bt::AttFindInfoReq, direct_bt::AttReadByGroupTypeRsp, direct_bt::AttReadByTypeRsp, direct_bt::AttReadByNTypeReq, direct_bt::AttElementList, direct_bt::AttHandleValueCfm, direct_bt::AttHandleValueRcv, direct_bt::AttWriteCmd, direct_bt::AttWriteRsp, direct_bt::AttWriteReq, direct_bt::AttReadBlobRsp, direct_bt::AttReadBlobReq, direct_bt::AttReadRsp, direct_bt::AttReadReq, direct_bt::AttExchangeMTU, direct_bt::AttErrorRsp, and direct_bt::AttPDUUndefined.

Definition at line 537 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ getOpAuthSigFlag()

constexpr bool direct_bt::AttPDUMsg::getOpAuthSigFlag ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 446 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getOpcode()

constexpr Opcode direct_bt::AttPDUMsg::getOpcode ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 437 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getOpcodeString()

std::string AttPDUMsg::getOpcodeString ( const Opcode opc )

staticnoexcept

Definition at line 78 of file ATTPDUTypes.cpp.

Here is the caller graph for this function:

◆ getOpCommandFlag()

constexpr bool direct_bt::AttPDUMsg::getOpCommandFlag ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 443 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

◆ getOpMethod()

constexpr Opcode direct_bt::AttPDUMsg::getOpMethod ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 440 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

◆ getPDUMinSize()

constexpr_cxx20 jau::nsize_t direct_bt::AttPDUMsg::getPDUMinSize ( ) const

inlinenoexcept

Returns this PDU's minimum size, i.e.

  opcode + param - value + auth_signature

Value is excluded as it might be flexible.

Definition at line 506 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPDUParamSize()

constexpr jau::nsize_t direct_bt::AttPDUMsg::getPDUParamSize ( ) const

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

The ATT PDU parameter size in octets less opcode (1 byte) and auth-signature (0 or 12 bytes).

  param-size := pdu.size - getAuthSigSize() - 1

<p<blockquote>

Note that the PDU parameter include the PDU value below.

Note that the optional auth-signature is at the end of the PDU.

Definition at line 475 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getPDUValueOffset()

virtual constexpr_cxx20 jau::nsize_t direct_bt::AttPDUMsg::getPDUValueOffset ( ) const

inlinevirtualnoexcept

Returns the octet offset to the value segment in this PDU including the mandatory opcode, i.e.

the number of octets until the first value octet.

Note that the ATT PDU value is part of the PDU param, where it is the last segment.

The value offset is ATT PDU specific and may point to the variable user data post handle etc within the PDU Param block.

Note that the opcode must be included in the implementation, as it may be used to reference the value in the pdu conveniently.

Reimplemented in direct_bt::AttFindInfoRsp, direct_bt::AttFindInfoReq, direct_bt::AttReadByGroupTypeRsp, direct_bt::AttReadByTypeRsp, direct_bt::AttReadByNTypeReq, direct_bt::AttHandleValueCfm, direct_bt::AttHandleValueRcv, direct_bt::AttWriteCmd, direct_bt::AttWriteRsp, direct_bt::AttWriteReq, direct_bt::AttReadBlobRsp, direct_bt::AttReadBlobReq, direct_bt::AttReadRsp, direct_bt::AttReadReq, direct_bt::AttExchangeMTU, direct_bt::AttErrorRsp, and direct_bt::AttPDUUndefined.

Definition at line 497 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ getPDUValueSize()

constexpr_cxx20 jau::nsize_t direct_bt::AttPDUMsg::getPDUValueSize ( ) const

inlinenoexcept

Returns the octet size of the value attributes in this PDI, i.e.

getPDUParamSize() - getPDUValueOffset() + 1.

Note that the opcode size of 1 octet is re-added as included in getPDUValueOffset() for convenience but already taken-off in getPDUParamSize() for spec compliance!

  value-size := param-size - value-offset + 1
  param-size := pdu.size - getAuthSigSize() - 1

  value-size := pdu.size - getAuthSigSize() - 1 - value-offset + 1
  value-size := pdu.size - getAuthSigSize() - value-offset

Definition at line 525 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getSpecialized()

std::unique_ptr< const AttPDUMsg > AttPDUMsg::getSpecialized	(	const uint8_t *	buffer,
		jau::nsize_t const	buffer_size
	)

staticnoexcept

Return a newly created specialized instance pointer to base class.

Returned memory reference is managed by caller (delete etc)

Definition at line 118 of file ATTPDUTypes.cpp.

◆ number()

static constexpr uint8_t direct_bt::AttPDUMsg::number ( const Opcode rhs )

inlinestaticconstexprnoexcept

Definition at line 358 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ operator=() [1/2]

AttPDUMsg& direct_bt::AttPDUMsg::operator= ( AttPDUMsg && o )

deletenoexcept

◆ operator=() [2/2]

AttPDUMsg& direct_bt::AttPDUMsg::operator= ( const AttPDUMsg & o )

deletenoexcept

◆ toString()

virtual std::string direct_bt::AttPDUMsg::toString ( ) const

inlinevirtualnoexcept

Definition at line 541 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ valueString()

virtual std::string direct_bt::AttPDUMsg::valueString ( ) const

inlineprotectedvirtualnoexcept

Reimplemented in direct_bt::AttFindInfoReq, direct_bt::AttReadByNTypeReq, direct_bt::AttElementList, direct_bt::AttHandleValueRcv, direct_bt::AttWriteCmd, direct_bt::AttWriteReq, direct_bt::AttReadBlobRsp, direct_bt::AttReadBlobReq, direct_bt::AttReadRsp, direct_bt::AttReadReq, direct_bt::AttExchangeMTU, and direct_bt::AttErrorRsp.

Definition at line 394 of file ATTPDUTypes.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ pdu

POctets direct_bt::AttPDUMsg::pdu

actual received PDU

Definition at line 401 of file ATTPDUTypes.hpp.

◆ ts_creation

const uint64_t direct_bt::AttPDUMsg::ts_creation

creation timestamp in milliseconds

Definition at line 404 of file ATTPDUTypes.hpp.

The documentation for this class was generated from the following files:

/usr/local/projects/direct_bt/api/direct_bt/ATTPDUTypes.hpp
/usr/local/projects/direct_bt/src/direct_bt/ATTPDUTypes.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Vol 3, Part F 2 - Protocol Overview pp

Vol 3, Part F 3 - Basics and Types

AttPDUMsg Base Class

ATT PDU Format Vol 3, Part F 3.3.1

Member Enumeration Documentation

◆ Opcode

Constructor & Destructor Documentation

◆ AttPDUMsg() [1/4]

◆ AttPDUMsg() [2/4]

◆ AttPDUMsg() [3/4]

◆ AttPDUMsg() [4/4]

◆ ~AttPDUMsg()

Member Function Documentation

◆ baseString()

◆ checkOpcode() [1/2]

◆ checkOpcode() [2/2]

◆ getAuthSigSize()

◆ getMaxPDUValueSize()

◆ getName()

◆ getOpAuthSigFlag()

◆ getOpcode()

◆ getOpcodeString()

◆ getOpCommandFlag()

◆ getOpMethod()

◆ getPDUMinSize()

◆ getPDUParamSize()

◆ getPDUValueOffset()

◆ getPDUValueSize()

◆ getSpecialized()

◆ number()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ toString()

◆ valueString()

Member Data Documentation

◆ pdu

◆ ts_creation