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

enum class	OpcodeType : uint8_t { UNDEFINED = 0 , REQUEST = 1 , RESPONSE = 2 , NOTIFICATION = 3 , INDICATION = 4 }

enum class	ReqRespType : bool { REQUEST = true , RESPONSE = false }

Public Member Functions
	AttPDUMsg (AttPDUMsg &&o) noexcept=default

	AttPDUMsg (const AttPDUMsg &o)=default

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

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

virtual	~AttPDUMsg () noexcept=default

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

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

virtual std::string	getName () const noexcept

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

constexpr Opcode	getOpcode () 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 Opcode	getOpMethod () const noexcept
	ATT PDU Format Vol 3, Part F 3.3.1. More...

constexpr_cxx20 jau::nsize_t	getPDUMinSize () const noexcept
	Returns this PDU's minimum size, i.e. 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	getPDUValueSize () const noexcept
	Returns the net octet size of this PDU's attributes value, i.e. More...

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

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

virtual std::string	toString () const noexcept

Static Public Member Functions
static constexpr OpcodeType	get_type (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...

static constexpr bool	is_request (const ReqRespType rhs) noexcept

static constexpr uint8_t	number (const Opcode rhs) noexcept

Public Attributes
jau::POctets	pdu
	actual received PDU More...

const uint64_t	ts_creation
	creation timestamp in milliseconds More...

Protected Member Functions
virtual std::string	baseString () const noexcept

void	check_range ()

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

void	checkOpcode (const Opcode expected) const

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 Specification

BT Core Spec v5.2: Vol 3, Part F ATT: 3.2.8 Exchanging MTU size
BT Core Spec v5.2: Vol 3, Part F ATT: 3.2.9 Long attribute values
BT Core Spec v5.2: Vol 3, Part G GATT: 5.2.1 ATT_MTU

resulting in a ATT_MTU range of

ATT_MTU minimum is 23 bytes (Vol 3, Part G: 5.2.1)
ATT_MTU is negotiated, maximum is 512 bytes (Vol 3, Part F: 3.2.8-9)
ATT Value sent: [1 .. ATT_MTU-1] (Vol 3, Part F: 3.2.8-9)

BT Core Spec v5.2: Vol 3, Part F ATT: 3.3.1 Attribute PDU Format

{ 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.

direct_bt::L2CAP_CID::ATT

@ ATT

Examples: dbt_repeater00.cpp.

Definition at line 347 of file ATTPDUTypes.hpp.

Member Enumeration Documentation

◆ Opcode

enum class 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 351 of file ATTPDUTypes.hpp.

◆ ReqRespType

enum class direct_bt::AttPDUMsg::ReqRespType : bool

strong

Enumerator
REQUEST
RESPONSE

Definition at line 399 of file ATTPDUTypes.hpp.

◆ OpcodeType

enum class direct_bt::AttPDUMsg::OpcodeType : uint8_t

strong

Enumerator
UNDEFINED
REQUEST
RESPONSE
NOTIFICATION
INDICATION

Definition at line 407 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 544 of file ATTPDUTypes.hpp.

◆ AttPDUMsg() [2/4]

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

inline

Persistent memory, w/ ownership .

Definition at line 550 of file ATTPDUTypes.hpp.

◆ AttPDUMsg() [3/4]

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

default

◆ AttPDUMsg() [4/4]

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

defaultnoexcept

◆ ~AttPDUMsg()

virtual direct_bt::AttPDUMsg::~AttPDUMsg ( )

virtualdefaultnoexcept

Member Function Documentation

◆ number()

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

inlinestaticconstexprnoexcept

Definition at line 394 of file ATTPDUTypes.hpp.

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:

◆ is_request()

static constexpr bool direct_bt::AttPDUMsg::is_request ( const ReqRespType rhs )

inlinestaticconstexprnoexcept

Definition at line 403 of file ATTPDUTypes.hpp.

◆ get_type()

static constexpr OpcodeType direct_bt::AttPDUMsg::get_type ( const Opcode rhs )

inlinestaticconstexprnoexcept

Definition at line 415 of file ATTPDUTypes.hpp.

◆ check_range()

void direct_bt::AttPDUMsg::check_range ( )

inlineprotected

Definition at line 497 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ checkOpcode() [1/2]

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

inlineprotected

Definition at line 501 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ checkOpcode() [2/2]

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

inlineprotected

Definition at line 509 of file ATTPDUTypes.hpp.

◆ baseString()

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

inlineprotectedvirtualnoexcept

Definition at line 519 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ valueString()

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

inlineprotectedvirtualnoexcept

Reimplemented in direct_bt::AttErrorRsp, direct_bt::AttExchangeMTU, direct_bt::AttReadReq, direct_bt::AttReadBlobReq, direct_bt::AttReadNRsp, direct_bt::AttWriteReq, direct_bt::AttWriteCmd, direct_bt::AttPrepWrite, direct_bt::AttHandleValueRcv, direct_bt::AttElementList, direct_bt::AttReadByNTypeReq, direct_bt::AttFindInfoReq, direct_bt::AttFindByTypeValueReq, and direct_bt::AttFindByTypeValueRsp.

Definition at line 523 of file ATTPDUTypes.hpp.

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 119 of file ATTPDUTypes.cpp.

◆ operator=() [1/2]

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

deletenoexcept

◆ operator=() [2/2]

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

deletenoexcept

◆ getOpcode()

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

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 565 of file ATTPDUTypes.hpp.

Here is the caller 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 568 of file ATTPDUTypes.hpp.

◆ getOpCommandFlag()

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

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 571 of file ATTPDUTypes.hpp.

◆ getOpAuthSigFlag()

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

inlineconstexprnoexcept

ATT PDU Format Vol 3, Part F 3.3.1.

Definition at line 574 of file ATTPDUTypes.hpp.

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 585 of file ATTPDUTypes.hpp.

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 603 of file ATTPDUTypes.hpp.

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::AttPDUUndefined, direct_bt::AttErrorRsp, direct_bt::AttExchangeMTU, direct_bt::AttReadReq, direct_bt::AttReadBlobReq, direct_bt::AttReadNRsp, direct_bt::AttWriteReq, direct_bt::AttWriteRsp, direct_bt::AttWriteCmd, direct_bt::AttPrepWrite, direct_bt::AttExeWriteReq, direct_bt::AttExeWriteRsp, direct_bt::AttHandleValueRcv, direct_bt::AttHandleValueCfm, direct_bt::AttReadByNTypeReq, direct_bt::AttReadByTypeRsp, direct_bt::AttReadByGroupTypeRsp, direct_bt::AttFindInfoReq, direct_bt::AttFindInfoRsp, direct_bt::AttFindByTypeValueReq, and direct_bt::AttFindByTypeValueRsp.

Definition at line 625 of file ATTPDUTypes.hpp.

Here is the caller 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 634 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 net octet size of this PDU's attributes value, i.e.

pdu.size - getAuthSigSize() - value-offset or
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 655 of file ATTPDUTypes.hpp.

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's attribute value.

 ATT_MTU - getAuthSigSize() - value-offset

Definition at line 663 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ getName()

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

inlinevirtualnoexcept

Reimplemented in direct_bt::AttPDUUndefined, direct_bt::AttErrorRsp, direct_bt::AttExchangeMTU, direct_bt::AttReadReq, direct_bt::AttReadBlobReq, direct_bt::AttReadNRsp, direct_bt::AttWriteReq, direct_bt::AttWriteRsp, direct_bt::AttWriteCmd, direct_bt::AttPrepWrite, direct_bt::AttExeWriteReq, direct_bt::AttExeWriteRsp, direct_bt::AttHandleValueRcv, direct_bt::AttHandleValueCfm, direct_bt::AttElementList, direct_bt::AttReadByNTypeReq, direct_bt::AttReadByTypeRsp, direct_bt::AttReadByGroupTypeRsp, direct_bt::AttFindInfoReq, direct_bt::AttFindInfoRsp, direct_bt::AttFindByTypeValueReq, and direct_bt::AttFindByTypeValueRsp.

Definition at line 667 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

◆ toString()

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

inlinevirtualnoexcept

Examples: dbt_repeater00.cpp.

Definition at line 671 of file ATTPDUTypes.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ pdu

jau::POctets direct_bt::AttPDUMsg::pdu

actual received PDU

Definition at line 530 of file ATTPDUTypes.hpp.

◆ ts_creation

const uint64_t direct_bt::AttPDUMsg::ts_creation

creation timestamp in milliseconds

Definition at line 533 of file ATTPDUTypes.hpp.

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

api/direct_bt/ATTPDUTypes.hpp
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

BT Core Spec v5.2: Vol 3, Part F ATT: 3.3.1 Attribute PDU Format

Member Enumeration Documentation

◆ Opcode

◆ ReqRespType

◆ OpcodeType

Constructor & Destructor Documentation

◆ AttPDUMsg() [1/4]

◆ AttPDUMsg() [2/4]

◆ AttPDUMsg() [3/4]

◆ AttPDUMsg() [4/4]

◆ ~AttPDUMsg()

Member Function Documentation

◆ number()

◆ getOpcodeString()

◆ is_request()

◆ get_type()

◆ check_range()

◆ checkOpcode() [1/2]

◆ checkOpcode() [2/2]

◆ baseString()

◆ valueString()

◆ getSpecialized()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ getOpcode()

◆ getOpMethod()

◆ getOpCommandFlag()

◆ getOpAuthSigFlag()

◆ getAuthSigSize()

◆ getPDUParamSize()

◆ getPDUValueOffset()

◆ getPDUMinSize()

◆ getPDUValueSize()

◆ getMaxPDUValueSize()

◆ getName()

◆ toString()

Member Data Documentation

◆ pdu

◆ ts_creation