NDEF

The NDEF component provides a utility class for dealing with NFC Data Exchange Format (NDEF) records, which are used by NFC Tags.

API Reference

Header File

components/ndef/include/ndef.hpp

Unions

espp::Ndef::Flags.__unnamed7__

Public Members

struct espp::Ndef::Flags::[anonymous]::[anonymous] [anonymous]

uint8_t raw

Classes

class Ndef

implements serialization & deserialization logic for NFC Data Exchange Format (NDEF) records which can be stored on and transmitted from NFC devices.

NDEF records can be composed the following way:

Bit 7     6       5       4       3       2       1       0
------  ------  ------  ------  ------  ------  ------  ------
[ MB ]  [ ME ]  [ CF ]  [ SR ]  [ IL ]  [        TNF         ]
[                         TYPE LENGTH  (may be 0)            ]
[                       PAYLOAD LENGTH (1B or 4B, see SR)    ]
[                          ID LENGTH   (if IL)               ]
[                         RECORD TYPE  (if TYPE LENGTH > 0)  ]
[                              ID      (if IL)               ]
[                           PAYLOAD    (payload length bytes)]

The first byte (Flags) has these bits:

Bits 0-3: TNF - Type Name Format - describes record type (see TNF class)
Bit 3: IL - ID Length - indicates if the ID Length Field is present or not
Bit 4: SR - Short Record - set to 1 if the payload length field is 1 byte (8 bits / 0-255) or less, otherwise the payload length is 4 bytes
Bit 5: CF - Chunk Flag - indicates if this is the first record chunk or a middle record chunk, set to 0 for the first record of the message and for subsequent records set to 1.
Bit 6: ME - Message End - 1 indicates if this is the last record in the message
Bit 7: MB - Message Begin - 1 indicates if this is the first record in the message

Note

Some information about NDEF can be found:

Public Types

enum class TNF : uint8_t

Type Name Format (TNF) field is a 3-bit value that describes the record type.

Some Common TNF::WELL_KNOWN record type strings:

Text (T)
URI (U)
Smart Poster (Sp)
Alternative Carrier (ac)
Handover Carrier (Hc)
Handover Request (Hr)
Handover Select (Hs)

Values:

enumerator EMPTY: Record is empty.

enumerator WELL_KNOWN: Type field contains a well-known RTD type name.

enumerator MIME_MEDIA: Type field contains a media type (RFC 2046)

enumerator ABSOLUTE_URI: Type field contains an absolute URI (RFC 3986)

enumerator EXTERNAL_TYPE: Type field Contains an external type name.

enumerator UNKNOWN: Payload type is unknown, type length must be 0.

enumerator UNCHANGED: Indicates the payload is an intermediate or final chunk of a chunked NDEF record, type length must be 0.

enumerator RESERVED: Reserved by the NFC forum for future use.

enum class Uic

URI Identifier Codes (UIC), See Table A-3 at https://www.oreilly.com/library/view/beginning-nfc/9781449324094/apa.html and https://learn.adafruit.com/adafruit-pn532-rfid-nfc/ndef

Values:

enumerator NONE: Exactly as written.

enumerator HTTP_WWW: http://www.

enumerator HTTPS_WWW: https://www.

enumerator HTTP: http://

enumerator HTTPS: https://

enumerator TEL: tel:

enumerator MAILTO: mailto:

enumerator FTP_ANON: ftp://anonymous:anonymous@

enumerator FTP_FTP: ftp://ftp.

enumerator FTPS: ftps://

enumerator SFTP: sftp://

enumerator SMB: smb://

enumerator NFS: nfs://

enumerator FTP: ftp://

enumerator DAV: dav://

enumerator NEWS: news:

enumerator TELNET: telnet://

enumerator IMAP: imap:

enumerator RSTP: rtsp://

enumerator URN: urn:

enumerator POP: pop:

enumerator SIP: sip:

enumerator SIPS: sips:

enumerator TFTP: tftp:

enumerator BTSPP: btspp://

enumerator BTL2CAP: btl2cap://

enumerator BTGOEP: btgoep://

enumerator TCPOBEX: tcpobex://

enumerator IRDAOBEX: irdaobex://

enumerator FILE: file://

enumerator URN_EPC_ID: urn:epc:id:

enumerator URN_EPC_TAG: urn:epc:tag:

enumerator URN_EPC_PAT: urn:epc:pat:

enumerator URN_EPC_RAW: urn:epc:raw:

enumerator URN_EPC: urn:epc:

enumerator URN_NFC: urn:nfc:

enum class BtType

Type of Bluetooth radios.

Values:

enumerator BREDR: BT Classic.

enumerator BLE: BT Low Energy.

enum class BtAppearance : uint16_t

Some appearance codes for BLE radios.

Values:

enumerator UNKNOWN: Generic Unknown.

enumerator PHONE: Generic Phone.

enumerator COMPUTER: Generic Computer.

enumerator WATCH: Generic Watch.

enumerator CLOCK: Generic Clock.

enumerator DISPLAY: Generic Display.

enumerator REMOTE_CONTROL: Generic Remote Control.

enumerator GENERIC_HID: Generic HID.

enumerator KEYBOARD: HID Keyboard.

enumerator MOUSE: HID Mouse.

enumerator JOYSTICK: HID Joystick.

enumerator GAMEPAD: HID Gamepad.

enumerator TOUCHPAD: HID Touchpad.

enumerator GAMING: Generic Gaming group.

enum class CarrierPowerState

Power state of a BLE radio.

Representation of the carrier power state in a Handover Select message.

Values:

enumerator INACTIVE: Carrier power is off.

enumerator ACTIVE: Carrier power is on.

enumerator ACTIVATING: Carrier power is turning on.

enumerator UNKNOWN: Carrier power state is unknown.

enum class BtEir

Extended Inquiry Response (EIR) codes for data types in BT and BLE out of band (OOB) pairing NDEF records.

Values:

enumerator FLAGS: BT flags: b0: LE limited discoverable mode, b1: LE general discoverable mode, b2: BR/EDR not supported, b3: Simultaneous LE & BR/EDR controller, b4: simultaneous LE & BR/EDR Host

enumerator UUIDS_16_BIT_PARTIAL: Incomplete list of 16 bit service class UUIDs.

enumerator UUIDS_16_BIT_COMPLETE: Complete list of 16 bit service class UUIDs.

enumerator UUIDS_32_BIT_PARTIAL: Incomplete list of 32 bit service class UUIDs.

enumerator UUIDS_32_BIT_COMPLETE: Complete list of 32 bit service class UUIDs.

enumerator UUIDS_128_BIT_PARTIAL: Incomplete list of 128 bit service class UUIDs.

enumerator UUIDS_128_BIT_COMPLETE: Complete list of 128 bit service class UUIDs.

enumerator SHORT_LOCAL_NAME: Shortened Bluetooth Local Name.

enumerator LONG_LOCAL_NAME: Complete Bluetooth Local Name.

enumerator TX_POWER_LEVEL: TX Power level (1 byte), -127 dBm to +127 dBm.

enumerator CLASS_OF_DEVICE: Class of Device.

enumerator SP_HASH_C192: Simple Pairing Hash C-192.

enumerator SP_RANDOM_R192: Simple Pairing Randomizer R-192.

enumerator SECURITY_MANAGER_TK: Security Manager TK Value (LE Legacy Pairing)

enumerator SECURITY_MANAGER_FLAGS: Flags (1 B), b0: OOB flags field (1 = 00B data present, 0 not), b1: LE Supported (host), b2: Simultaneous LE & BR/EDR to same device capable (host), b3: address type (0 = public, 1 = random)

enumerator APPEARANCE: Appearance.

enumerator MAC: Bluetooth Device Address.

enumerator LE_ROLE: LE Role.

enumerator SP_HASH_C256: Simple Pairing Hash C-256.

enumerator SP_HASH_R256: Simple Pairing Randomizer R-256.

enumerator LE_SC_CONFIRMATION: LE Secure Connections Confirmation Value.

enumerator LE_SC_RANDOM: LE Secure Connections Random Value.

enum class BleRole : uint8_t

Possible roles for BLE records to indicate support for.

Values:

enumerator PERIPHERAL_ONLY: Radio can only act as a peripheral.

enumerator CENTRAL_ONLY: Radio can only act as a central.

enumerator PERIPHERAL_CENTRAL: Radio can act as both a peripheral and a central, but prefers peripheral.

enumerator CENTRAL_PERIPHERAL: Radio can act as both a peripheral and a central, but prefers central.

enum class WifiEncryptionType

Types of configurable encryption for WiFi networks.

Values:

enumerator NONE: No encryption.

enumerator WEP: WEP.

enumerator TKIP: TKIP.

enumerator AES: AES.

enum class WifiAuthenticationType

WiFi network authentication.

Values:

enumerator OPEN: Open / no security.

enumerator WPA_PERSONAL: WPA personal.

enumerator SHARED: Shared key.

enumerator WPA_ENTERPRISE: WPA enterprise.

enumerator WPA2_ENTERPRISE: WPA2 Enterprise.

enumerator WPA2_PERSONAL: WPA2 personal.

enumerator WPA_WPA2_PERSONAL: Both WPA and WPA2 personal.

Public Functions

inline explicit Ndef(espp::Ndef::TNF tnf, std::string_view type, std::string_view payload)

Makes an NDEF record with header and payload.

Parameters

tnf – The TNF for this packet.
type – String view for the type of this packet
payload – The payload data for the packet

inline std::vector<uint8_t> serialize(bool message_begin = true, bool message_end = true)

Serialize the NDEF record into a sequence of bytes.

Parameters

message_begin – True if this is the first record in the message.
message_end – True if this is the last record in the message.

Returns

The vector<uint8_t> of bytes representing the NDEF record.

inline std::vector<uint8_t> payload()

Return just the payload as a vector of bytes.

Returns: Payload of the NDEF record as a vector of bytes.

inline void set_id(int id)

Set the payload ID of the NDEF record.

Parameters: id – ID of the NDEF record.

inline int get_id() const

Get the ID of the NDEF record.

Returns: ID of the NDEF record.

inline int get_size() const

Get the number of bytes needed for the NDEF record.

Returns: Size of the NDEF record (bytes), for serialization.

Public Static Functions

static inline Ndef make_text(std::string_view text)

Static function to make an NDEF record for transmitting english text.

Parameters: text – The text that the NDEF record will hold.
Returns: NDEF record object.

static inline Ndef make_uri(std::string_view uri, espp::Ndef::Uic uic = espp::Ndef::Uic::NONE)

Static function to make an NDEF record for loading a URI.

Parameters

uri – URI for the record to point to.
uic – UIC for the uri - helps shorten the uri text / NDEF record.

Returns

NDEF record object.

static inline Ndef make_android_launcher(std::string_view uri)

Static function to make an NDEF record for launching an Android App.

Parameters: uri – URI for the android package / app to launch.
Returns: NDEF record object.

static inline Ndef make_wifi_config(const espp::Ndef::WifiConfig &config)

Create a WiFi credential tag.

Parameters: config – WifiConfig describing the WiFi network.
Returns: NDEF record object.

static inline Ndef make_handover_select(int carrier_data_ref)

Create a Handover Select record for a Bluetooth device.