nfc.ndef

Warning

The nfc.ndef submodule is superseded by the separate ndeflib module and will eventually be removed from nfcpy.

Deprecated since version 0.12: Use ndeflib.

Support for decoding and encoding of NFC Data Exchange Format (NDEF) records and messages.

Deprecated since version 0.12: Use ndeflib.

nfc.ndef.Message

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.Message(*args)

Bases: object

Wraps a sequence of NDEF records and provides methods for appending, inserting and indexing. Instantiation accepts a variable number of positional arguments. A call without argument produces a Message object with no records. A single str or bytearray argument is parsed as NDEF message bytes. A single list or tuple of nfc.ndef.Record objects produces a Message with those records in order. One or more nfc.ndef.Record arguments produce a Message with those records in order.

>>> nfc.ndef.Message(b'\x10\x00\x00')     # NDEF data bytes
>>> nfc.ndef.Message(bytearray([16,0,0])) # NDEF data bytes
>>> nfc.ndef.Message([record1, record2])  # list of records
>>> nfc.ndef.Message(record1, record2)    # two record args
append(record)

Add a record to the end of the message. The record argument must be an instance of nfc.ndef.Record.

extend(records)

Extend the message by appending all the records in the given list. The records argument must be a sequence of nfc.ndef.Record elements.

insert(i, record)

Insert a record at the given position. The first argument i is the index of the record before which to insert, so message.insert(0, record) inserts at the front of the message, and message.insert(len(message), record) is equivalent to message.append(record). The second argument record must be an instance of nfc.ndef.Record.

pop(i=-1)

Remove the record at the given position i in the message, and return it. If no position is specified, message.pop() removes and returns the last item.

type

The message type. Corresponds to the record type of the first record in the message. None if the message has no records. This attribute is read-only.

name

The message name. Corresponds to the record name of the first record in the message. None if the message has no records. This attribute is read-only.

pretty()

Returns a message representation that might be considered pretty-printable.

nfc.ndef.Record

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.Record(record_type=None, record_name=None, data=None)

Bases: object

Wraps an NDEF record and provides getting and setting of the record type name (type), record identifier (name) and record payload (data).

Parameters:
  • record_type – NDEF record type name
  • record_name – NDEF record identifier
  • data – NDEF record payload or NDEF record data

All arguments accept a str or bytearray object.

Interpretation of the data argument depends on the presence of record_type and record_name. If any of the record_type or record_name argument is present, the data argument is interpreted as the record payload and copied to data. If none of the record_type or record_name argument are present, the data argument is interpreted as a NDEF record bytes (NDEF header and payload) and parsed.

The record_type argument combines the NDEF TNF (Type Name Format) and NDEF TYPE information into a single string. The TNF values 0, 5 and 6 are expressed by the strings ‘’, ‘unknown’ and ‘unchanged’. For TNF values 2 and 4 the record_type is the prefix ‘urn:nfc:wkt:’ and ‘urn:nfc:ext:’, respectively, followed by the NDEF TYPE string. TNF values 2 and 3 are not distinguished by regular expressions matching the either the media-type format ‘type-name/subtype-name’ or absolute URI format ‘scheme:hier-part’

>>> nfc.ndef.Record('urn:nfc:wkt:T', 'id', b'enHello World')
>>> nfc.ndef.Record('urn:nfc:wkt:T', data=b'enHello World')
>>> nfc.ndef.Record(data=b'ÑTenHello World')
type

The record type. A string that matches the empty string ‘’, or the string ‘unknown’, or the string ‘unchanged’, or starts with ‘urn:nfc:wkt:’, or starts with ‘urn:nfc:ext:’, or matches the mime-type format, or matches the absolute-URI format.

name

The record identifier as an octet string. Any type that can be coverted into a sequence of characters in range(0,256) can be assigned.

data

The record payload as an octet string. Any type that can be coverted into a sequence of characters in range(0,256) can be assigned.

pretty(indent=0)

Returns a string with a formatted representation that might be considered pretty-printable. The optional argument indent specifies the amount of indentation added for each level of output.

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.record.RecordList(iterable=())

Bases: list

A specialized list type that only accepts Record objects.

nfc.ndef.TextRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.TextRecord(text=None, language='en', encoding='UTF-8')

Bases: nfc.ndef.record.Record

Wraps an NDEF Text record and provides access to the encoding, language and actual text content.

Parameters:
  • text – Text string or nfc.ndef.Record object
  • language – ISO/IANA language code string
  • encoding – Text encoding in binary NDEF

The text argument may alternatively supply an instance of class nfc.ndef.Record. Initialization is then done by parsing the record payload. If the record type does not match ‘urn:nfc:wkt:T‘ a ValueError exception is raised.

>>> nfc.ndef.TextRecord(nfc.ndef.Record())
>>> nfc.ndef.TextRecord("English UTF-8 encoded")
>>> nfc.ndef.TextRecord("Deutsch UTF-8", language="de")
>>> nfc.ndef.TextRecord("English UTF-16", encoding="UTF-16")
text

The text content. A unicode string that specifies the TEXT record text field. Coerced into unicode when set.

language

The text language. A string that specifies the ISO/IANA language code coded into the TEXT record. The value is not verified except that a ValueError exception is raised if the assigned value string exceeds 64 characters.

encoding

The text encoding, given as a string. May be ‘UTF-8’ or ‘UTF-16’. A ValueError exception is raised for anythinge else.

nfc.ndef.UriRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.UriRecord(uri=None)

Bases: nfc.ndef.record.Record

Wraps an NDEF URI record and provides access to the uri content. The URI RTD specification defines the payload of the URI record as a URI identifier code byte followed by a URI string. The URI identifier code provides one byte code points for abbreviations of commonly used URI protocol names. The UriRecord class handles abbreviations transparently by expanding and compressing when decoding and encoding.

Parameters:uri – URI string or nfc.ndef.Record object

The uri argument may alternatively supply an instance of class nfc.ndef.Record. Initialization is then done by parsing the record payload. If the record type does not match ‘urn:nfc:wkt:U‘ a ValueError exception is raised.

>>> nfc.ndef.UriRecord(nfc.ndef.Record())
>>> nfc.ndef.UriRecord("http://nfcpy.org")
uri

The URI string, including any abbreviation that is possibly available. A ValueError exception is raised if the string contains non ascii characters.

nfc.ndef.SmartPosterRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.SmartPosterRecord(uri, title=None, icons=None, action='default', resource_size=None, resource_type=None)

Bases: nfc.ndef.record.Record

Wraps an NDEF SmartPoster record and provides access to the encoding, language and actual text content.

Parameters:
  • uri – URI string or nfc.ndef.Record object
  • title – Smart poster title(s), assigned to title
  • icons – Smart poster icons, assigned to icons
  • action – Recommended action, assigned to action
  • resource_size – Size of the referenced resource
  • resource_type – Type of the referenced resource

The uri argument may alternatively supply an instance of class nfc.ndef.Record. Initialization is then done by parsing the record payload. If the record type does not match ‘urn:nfc:wkt:Sp‘ a ValueError exception is raised.

>>> nfc.ndef.SmartPosterRecord(nfc.ndef.Record())
>>> nfc.ndef.SmartPosterRecord("http://nfcpy.org", "nfcpy")
>>> nfc.ndef.SmartPosterRecord("http://nfcpy.org", "nfcpy", action="save")
uri

The smart poster URI, a string of ascii characters. A ValueError exception is raised if non ascii characters are contained.

title

A dictionary of smart poster titles with ISO/IANA language codes as keys and title strings as values. Set specific title strings with obj.title['en']=title. Assigning a string value is equivalent to setting the title for language code ‘en’. Titles are optional for a smart poster record

icons

A dictionary of smart poster icon images. The keys specify the image mime sub-type and the values are strings of image data. Icons are optional for a smart poster record.

action

The recommended action for the receiver of the smart poster. Reads as ‘default’, ‘exec’, ‘save’, ‘edit’ or a number string if RFU values were decoded. Can be set to ‘exec’, ‘save’, ‘edit’ or None. The action is optional in a smart poster record.

resource_size

The size of the resource referred by the URI. A 32 bit unsigned integer value or None. The resource size is optional in a smart poster record.

resource_type

The type of the resource referred by the URI. A UTF-8 formatted string that describes an Internet media type (MIME type) or None. The resource type is optional in a smart poster record.

nfc.ndef.HandoverRequestMessage

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.HandoverRequestMessage(message=None, version=None)

Bases: object

The handover request message is used in the the NFC Connection Handover protocol to send proposals for alternative carriers to a peer device.

Parameters:

Either the message or version argument must be supplied. A ValueError is raised if both arguments are present or absent.

The message argument must be a parsed NDEF message with, according to the Connection Handover Specification, at least two records. The first record, and thus the message, must match the NFC Forum Well-Known Type ‘urn:nfc:wkt:Hr‘.

The version argument indicates the Connection Handover version that shall be used for encoding the handover request message NDEF data. It is currently limited to major-version ‘1’ and minor-version ‘0’ to ‘15’ and for any other value a ValueError exception is raised.

>>> nfc.ndef.HandoverRequestMessage(nfc.ndef.Message(ndef_message_data))
>>> nfc.ndef.HandoverRequestMessage(version='1.2')
type

The message type. This is a read-only attribute which returns the NFC Forum Well-Known Type ‘urn:nfc:wkt:Hr

name

The message name (identifier). Corresponds to the name of the handover request record.

version

Connection Handover version number that the messsage complies to. A read-only Version object that provides the major and minor version int values.

nonce

A nonce received or to be send as the random number for handover request collision resolution. This attribute is supported only since version 1.2.

carriers

List of alternative carriers. Each entry is an Carrier object that holds properties of the alternative carrier. Use add_carrier() to expand this list.

add_carrier(carrier_record, power_state, aux_data_records=None)

Add a new carrier to the handover request message.

Parameters:
  • carrier_record (nfc.ndef.Record) – a record providing carrier information
  • power_state (str) – a string describing the carrier power state
  • aux_data_records (RecordList) – list of auxiliary data records
>>> hr = nfc.ndef.HandoverRequestMessage(version="1.2")
>>> hr.add_carrier(some_carrier_record, "active")
pretty(indent=0)

Returns a string with a formatted representation that might be considered pretty-printable.

nfc.ndef.HandoverSelectMessage

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.HandoverSelectMessage(message=None, version=None)

Bases: object

The handover select message is used in the the NFC Connection Handover protocol to send agreements for alternative carriers to a peer device as response to a handover request message.

Parameters:

Either the message or version argument must be supplied. A ValueError is raised if both arguments are present or absent.

The message argument must be a parsed NDEF message with, according to the Connection Handover Specification, at least one record. The first record, and thus the message, must match the NFC Forum Well-Known Type ‘urn:nfc:wkt:Hs‘.

The version argument indicates the Connection Handover version that shall be used for encoding the handover select message NDEF data. It is currently limited to major-version ‘1’ and minor-version ‘0’ to ‘15’ and for any other value a ValueError exception is raised.

>>> nfc.ndef.HandoverSelectMessage(nfc.ndef.Message(ndef_message_data))
>>> nfc.ndef.HandoverSelectMessage(version='1.2')
type

The message type. This is a read-only attribute which returns the NFC Forum Well-Known Type ‘urn:nfc:wkt:Hs

name

The message name (identifier). Corresponds to the name of the handover select record.

version

Connection Handover version number that the messsage complies to. A read-only Version object that provides the major and minor version int values.

error

A HandoverError structure that provides error reason and data received or to be send with the handover select message. An error.reason value of 0 means that no error was received or is to be send.

carriers

List of alternative carriers. Each entry is an Carrier object that holds properties of the alternative carrier. Use add_carrier() to expand this list.

add_carrier(carrier_record, power_state, aux_data_records=[])

Add a new carrier to the handover select message.

Parameters:
  • carrier_record (nfc.ndef.Record) – a record providing carrier information
  • power_state (str) – a string describing the carrier power state
  • aux_data_records (RecordList) – list of auxiliary data records
>>> hs = nfc.ndef.HandoverSelectMessage(version="1.2")
>>> hs.add_carrier(some_carrier_record, "active")
pretty(indent=0)

Returns a string with a formatted representation that might be considered pretty-printable.

nfc.ndef.HandoverCarrierRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.HandoverCarrierRecord(carrier_type, carrier_data=None)

Bases: nfc.ndef.record.Record

The handover carrier record is used to identify an alternative carrier technology in a handover request message when no carrier configuration data shall be transmitted.

Parameters:
  • carrier_type (str) – identification of an alternative carrier
  • carrier_data (str) – additional alternative carrier information
>>> nfc.ndef.HandoverCarrierRecord('application/vnd.bluetooth.ep.oob')
carrier_type

Identification of an alternative carrier. A string formatted as an NFC Forum Well-Known or External Type or Internet Media Type or absolute URI. This attribute is read-only.

carrier_data

An octet string that provides additional information about the alternative carrier.

nfc.ndef.handover.Version

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.handover.Version

Bases: object

major

Major version number. A read-only attribute.

minor

Mainor version number. A read-only attribute.

nfc.ndef.handover.Carrier

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.handover.Carrier

Bases: object

type

The alternative carrier type name, equivalent to Carrier.record.type or Carrier.record.carrier_type if the carrier is specified as a HandoverCarrierRecord.

record

A carrier configuration record. Recognized and further interpreted records are: HandoverCarrierRecord, BluetoothConfigRecord, WifiConfigRecord, WifiPasswordRecord.

power_state

The carrier power state. This may be one of the following strings: “inactive”, “active”, “activating”, or “unknown”.

auxiliary_data_records

A list of auxiliary data records providing additional carrier information.

nfc.ndef.handover.HandoverError

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.handover.HandoverError

Bases: object

reason

The error reason. An 8-bit unsigned integer.

data

The error data. An 8-bit unsigned integer if reason is 1 or 3, a 32-bit unsigned integer if reason is 2.

nfc.ndef.BluetoothConfigRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.BluetoothConfigRecord

Bases: nfc.ndef.record.Record

device_address

Bluetooth device address. A string of hexadecimal characters with 8-bit quantities spearated by colons and the most significant byte first. For example, the device address '01:23:45:67:89:AB' corresponds to 0x0123456789AB.

local_device_name

Bluetooth Local Name encoded as sequence of characters in the given order. Received as complete (EIR type 0x09) or shortened (EIR type 0x08) local name. Transmitted as complete local name. Set to None if not received or not to be transmitted.

simple_pairing_hash

Simple Pairing Hash C. Received and transmitted as EIR type 0x0E. Set to None if not received or not to be transmitted. Raises nfc.ndef.DecodeError if the received value or nfc.ndef.EncodeError if the assigned value is not a sequence of 16 octets.

simple_pairing_rand

Simple Pairing Randomizer R. Received and transmitted as EIR type 0x0F. Set to None if not received or not to be transmitted. Raises nfc.ndef.DecodeError if the received value or nfc.ndef.EncodeError if the assigned value is not a sequence of 16 octets.

service_class_uuid_list

Listq of Service Class UUIDs. Set and retrieved as a list of complete 128-bit UUIDs. Decoded from and encoded as EIR types 0x02/0x03 (16-bit partial/complete UUIDs), 0x04/0x05 (32-bit partial/complete UUIDs), 0x06/0x07 (128-bit partial/complete UUIDs).

class_of_device

Class of Device encoded as unsigned long integer. Received and transmitted as EIR type 0x0D in little endian byte order. Set to None if not received or not to be transmitted.

nfc.ndef.WifiConfigRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.WifiConfigRecord

Bases: nfc.ndef.record.Record

version

The WiFi Simple Configuration version, coded as a ‘major.minor’ string

credentials

A list of WiFi credentials. Each credential is a dictionary with any of the possible keys 'network-name', 'network-key', 'shareable', 'authentication', 'encryption', 'mac-address', and 'other'.

credential

The first WiFi credential. Same as WifiConfigRecord().credentials[0].

other

A list of WiFi attribute (key, value) pairs other than version and credential(s). Keys are two character strings for standard WiFi attributes, one character strings for subelements within a WFA vendor extension attribute, and three character strings for other vendor ecxtension attributes.

nfc.ndef.WifiPasswordRecord

Deprecated since version 0.12: Use ndeflib.

class nfc.ndef.WifiPasswordRecord

Bases: nfc.ndef.record.Record

version

The WiFi Simple Configuration version, coded as a ‘major.minor’ string

passwords

A list of WiFi out-of-band device passwords. Each password is a dictionary with the keys 'public-key-hash', 'password-id', and 'password'.

password

The first WiFi device password. Same as WifiPasswordRecord().passwords[0].

other

A list of WiFi attribute (key, value) pairs other than version and device password. Keys are two character strings for standard WiFi attributes, one character strings for subelements within a WFA vendor extension attribute, and three character strings for other vendor extension attributes.