ble_gatt.h File Reference

Bluetooth ATT protocol codec + GATT characteristic bridge (PROTOCORE_ENABLE_BLE_GATT). More...

#include "protocore_config.h"

Go to the source code of this file.

Classes
struct	AttPdu
	A parsed ATT PDU (value points into the input). More...
struct	GattChar
	One GATT characteristic for the northbound bridge. More...
struct	BleGattNs
	Dispatch table. Addressed by offset, so the layout is asserted below. More...

Macros
#define	ATT_OP_ERROR_RSP   0x01
	ATT opcodes (subset).
#define	ATT_OP_READ_REQ   0x0A
	[op][handle:2]
#define	ATT_OP_READ_RSP   0x0B
	[op][value...]
#define	ATT_OP_WRITE_REQ   0x12
	[op][handle:2][value...]
#define	ATT_OP_WRITE_RSP   0x13
	[op]
#define	ATT_OP_HANDLE_VALUE_NTF   0x1B
	[op][handle:2][value...]
#define	GATT_PROP_READ   0x02
	GATT characteristic property bits (declaration properties byte).
#define	GATT_PROP_WRITE_NR   0x04
	write without response.
#define	GATT_PROP_WRITE   0x08
#define	GATT_PROP_NOTIFY   0x10
#define	GATT_PROP_INDICATE   0x20

Functions
	PROTOCORE_NS_LAYOUT (BleGattNs, att_read_req, att_read_rsp, att_write_req, att_notify, att_error_rsp, att_parse, char_json)
size_t	protocore_ble_gatt_att_read_req (uint8_t *work, uint16_t handle, uint8_t *out, size_t cap)
	Build a Read Request: [0x0A][handle:2 LE]. 3, or 0 on overflow.
size_t	protocore_ble_gatt_att_read_rsp (uint8_t *work, const uint8_t *val, size_t vlen, uint8_t *out, size_t cap)
	Build a Read Response: [0x0B][value...]. 1+vlen, or 0 on overflow.
size_t	protocore_ble_gatt_att_write_req (uint8_t *work, uint16_t handle, const uint8_t *val, size_t vlen, uint8_t *out, size_t cap)
	Build a Write Request: [0x12][handle:2 LE][value...]. 3+vlen, or 0 .
size_t	protocore_ble_gatt_att_notify (uint8_t *work, uint16_t handle, const uint8_t *val, size_t vlen, uint8_t *out, size_t cap)
	Build a Handle Value Notification: [0x1B][handle:2 LE][value...]. .
size_t	protocore_ble_gatt_att_error_rsp (uint8_t *work, uint8_t req_op, uint16_t handle, uint8_t error, uint8_t *out, size_t cap)
	Build an Error Response: [0x01][req-op][handle:2 LE][error]. 5, or .
proto_bool	protocore_ble_gatt_att_parse (uint8_t *work, const uint8_t *pdu, size_t len, AttPdu *out)
	Parse an ATT PDU into out. true if len >= 1 and the fixed fields fit.
size_t	protocore_ble_gatt_char_json (uint8_t *work, const GattChar *chars, size_t n, char *out, size_t cap)
	Serialize a characteristic table as .

Variables
PROTOCORE_NS BleGattNs BleGatt	PROTOCORE_UNUSED
	Module namespace.

Detailed Description

Bluetooth ATT protocol codec + GATT characteristic bridge (PROTOCORE_ENABLE_BLE_GATT).

The ESP32's BLE radio is on-chip, but bridging GATT to the web still needs the wire protocol under GATT - the Attribute Protocol (ATT, Bluetooth Core Vol 3 Part F): the read / write / notify / error PDUs a central and peripheral exchange, each a 1-byte opcode followed by a little-endian attribute handle and value. This is that codec (build + parse the common ATT PDUs) plus a small characteristic table serializer that exposes discovered / offered GATT characteristics as JSON for the web stack.

Pure, zero heap, no stdlib, host-testable. The BLE stack (NimBLE / Bluedroid) owns the radio; this owns the ATT bytes and the northbound JSON.

work is bytes the CALLER holds. This module reads none of them: it carries nothing between calls, so there is no state to keep and nothing to wipe. The parameter is there so a caller drives every namespace the same way.

Definition in file ble_gatt.h.

Macro Definition Documentation

ATT_OP_ERROR_RSP

#define ATT_OP_ERROR_RSP   0x01

ATT opcodes (subset).

[op][req-op][handle:2][error]

Definition at line 35 of file ble_gatt.h.

ATT_OP_READ_REQ

#define ATT_OP_READ_REQ   0x0A

[op][handle:2]

Definition at line 36 of file ble_gatt.h.

ATT_OP_READ_RSP

#define ATT_OP_READ_RSP   0x0B

[op][value...]

Definition at line 37 of file ble_gatt.h.

ATT_OP_WRITE_REQ

#define ATT_OP_WRITE_REQ   0x12

[op][handle:2][value...]

Definition at line 38 of file ble_gatt.h.

ATT_OP_WRITE_RSP

#define ATT_OP_WRITE_RSP   0x13

[op]

Definition at line 39 of file ble_gatt.h.

ATT_OP_HANDLE_VALUE_NTF

#define ATT_OP_HANDLE_VALUE_NTF   0x1B

[op][handle:2][value...]

Definition at line 40 of file ble_gatt.h.

GATT_PROP_READ

#define GATT_PROP_READ   0x02

GATT characteristic property bits (declaration properties byte).

Definition at line 43 of file ble_gatt.h.

GATT_PROP_WRITE_NR

#define GATT_PROP_WRITE_NR   0x04

write without response.

Definition at line 44 of file ble_gatt.h.

GATT_PROP_WRITE

#define GATT_PROP_WRITE   0x08

Definition at line 45 of file ble_gatt.h.

GATT_PROP_NOTIFY

#define GATT_PROP_NOTIFY   0x10

Definition at line 46 of file ble_gatt.h.

GATT_PROP_INDICATE

#define GATT_PROP_INDICATE   0x20

Definition at line 47 of file ble_gatt.h.

Function Documentation

PROTOCORE_NS_LAYOUT()

PROTOCORE_NS_LAYOUT	(	BleGattNs	,
		att_read_req	,
		att_read_rsp	,
		att_write_req	,
		att_notify	,
		att_error_rsp	,
		att_parse	,
		char_json
	)

protocore_ble_gatt_att_read_req()

size_t protocore_ble_gatt_att_read_req	(	uint8_t *	work,
		uint16_t	handle,
		uint8_t *	out,
		size_t	cap
	)

Build a Read Request: [0x0A][handle:2 LE]. 3, or 0 on overflow.

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
handle	Handle
out	Out
cap	Cap

Returns

The size_t.

protocore_ble_gatt_att_read_rsp()

size_t protocore_ble_gatt_att_read_rsp	(	uint8_t *	work,
		const uint8_t *	val,
		size_t	vlen,
		uint8_t *	out,
		size_t	cap
	)

Build a Read Response: [0x0B][value...]. 1+vlen, or 0 on overflow.

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
val	Val
vlen	Vlen
out	Out
cap	Cap

Returns

The size_t.

protocore_ble_gatt_att_write_req()

size_t protocore_ble_gatt_att_write_req	(	uint8_t *	work,
		uint16_t	handle,
		const uint8_t *	val,
		size_t	vlen,
		uint8_t *	out,
		size_t	cap
	)

Build a Write Request: [0x12][handle:2 LE][value...]. 3+vlen, or 0 .

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
handle	Handle
val	Val
vlen	Vlen
out	Out
cap	Cap

Returns

The size_t.

protocore_ble_gatt_att_notify()

size_t protocore_ble_gatt_att_notify	(	uint8_t *	work,
		uint16_t	handle,
		const uint8_t *	val,
		size_t	vlen,
		uint8_t *	out,
		size_t	cap
	)

Build a Handle Value Notification: [0x1B][handle:2 LE][value...]. .

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
handle	Handle
val	Val
vlen	Vlen
out	Out
cap	Cap

Returns

The size_t.

protocore_ble_gatt_att_error_rsp()

size_t protocore_ble_gatt_att_error_rsp	(	uint8_t *	work,
		uint8_t	req_op,
		uint16_t	handle,
		uint8_t	error,
		uint8_t *	out,
		size_t	cap
	)

Build an Error Response: [0x01][req-op][handle:2 LE][error]. 5, or .

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
req_op	Req op
handle	Handle
error	Error
out	Out
cap	Cap

Returns

The size_t.

protocore_ble_gatt_att_parse()

proto_bool protocore_ble_gatt_att_parse	(	uint8_t *	work,
		const uint8_t *	pdu,
		size_t	len,
		AttPdu *	out
	)

Parse an ATT PDU into out. true if len >= 1 and the fixed fields fit.

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
pdu	Pdu
len	Len
out	Out

Returns

PROTO_TRUE on success.

protocore_ble_gatt_char_json()

size_t protocore_ble_gatt_char_json	(	uint8_t *	work,
		const GattChar *	chars,
		size_t	n,
		char *	out,
		size_t	cap
	)

Serialize a characteristic table as .

Parameters

work	PROTOCORE_BLE_GATT_BORROW bytes the caller took. Not held past the call.
chars	Chars
n	N
out	Out
cap	Cap

Returns

The size_t.

Variable Documentation

PROTOCORE_UNUSED

PROTOCORE_NS BleGattNs BleGatt PROTOCORE_UNUSED

Initial value:

= {.att_read_req = protocore_ble_gatt_att_read_req,
                                                   .att_read_rsp = protocore_ble_gatt_att_read_rsp,
                                                   .att_write_req = protocore_ble_gatt_att_write_req,
                                                   .att_notify = protocore_ble_gatt_att_notify,
                                                   .att_error_rsp = protocore_ble_gatt_att_error_rsp,
                                                   .att_parse = protocore_ble_gatt_att_parse,
                                                   .char_json = protocore_ble_gatt_char_json}

Module namespace.

Definition at line 158 of file ble_gatt.h.