Adding Private Records

Private (or experimental) NDEF Record decoding and encoding can be easily made recognized by the message_decoder() and message_encoder(). It just requires a record class that inherits from ndef.record.GlobalRecord and provides the desired record type value as well as the payload decode and encode methods. The following sections document the decode/encode interface by way of example, with increasing complexity.

Record with no Payload

This is the most simple yet fully functional record class. It inherits from the abstract class ndef.record.GlobalRecord (which is actually just an abstract version of Record to make sure the dervied class implements the payload decode and encode methods. The record type string is set via the _type class attribute. The _encode_payload method must return the bytes for the NDEF Record PAYLOAD field, usually encoded from other record attributes but here it’s just empty. The _decode_payload classmethod receives the NDEF Record PAYLOAD field the bytes type octets and returns a record object populated with the decoded PAYLOAD data, again nothing for the record with no payload. The _decode_min_payload_length and _decode_max_payload_length class attributes (put at the end of the class definition only to align with the explanation) inform the record decoder about the minmum required and maximum acceptable PAYLOAD size, thus the octets argument will never have less or more data. If a class does not set those values, the default min value is 0 and the default max value is Record.MAX_PAYLOAD_SIZE.

import ndef

class ExampleRecordWithNoPayload(ndef.record.GlobalRecord):
    """An NDEF Record with no payload."""

    _type = ''

    def _encode_payload(self):
        # This record does not have any payload to encode.
        return b''

    def _decode_payload(cls, octets, errors):
        # This record does not have any payload to decode.
        return cls()

    _decode_min_payload_length = 0
    _decode_max_payload_length = 0


record = ExampleRecordWithNoPayload()
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))
encoded: b'\xd4\x11\'
decoded: NDEF Example Record With No Payload ID '' PAYLOAD 0 byte

Example Temperature Record

This record carries an unsigned 32-bit integer timestamp that is the seconds since 1.1.1970 (and will overflow on February 7, 2106 !) and a signed 16-bit integer with a temperature. The payload is thus a fixed structure with exactly 6 octets for which the inherited _decode_struct and _encode_struct methods are perfectly suited. They are quite the same as using struct.unpack_from and struct.pack but return a single value directly and not as a (value, ) tuple.

This example also shows how the __format__ method is used to provide an arguments and a data view for the str() and repr() functions.

import ndef
import time

class ExampleTemperatureRecord(ndef.record.GlobalRecord):
    """An NDEF Record that carries a temperature and a timestamp."""

    _type = ''

    def __init__(self, timestamp, temperature):
        self._time = timestamp
        self._temp = temperature

    def __format__(self, format_spec):
        if format_spec == 'args':
            # Return the init args for repr() but w/o class name and brackets
            return "{r._time}, {r._temp}".format(r=self)
        if format_spec == 'data':
            # Return a nicely formatted content string for str()
            data_str = time.strftime('%d.%m.%Y', time.gmtime(self._time))
            time_str = time.strftime('%H:%M:%S', time.gmtime(self._time))
            return "{}°C on {} at {}".format(self._temp, data_str, time_str)
        return super(ExampleTemperatureRecord, self).__format__(format_spec)

    def _encode_payload(self):
        return self._encode_struct('>Lh', self._time, self._temp)

    def _decode_payload(cls, octets, errors):
        timestamp, temperature = cls._decode_struct('>Lh', octets)
        return cls(timestamp, temperature)

    # Make sure that _decode_payload gets only called with 6 octets
    _decode_min_payload_length = 6
    _decode_max_payload_length = 6


record = ExampleTemperatureRecord(1468410873, 25)
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))
encoded: b'\xd4\x10\\x86+\xf9\x00\x19'
decoded: NDEF Example Temperature Record ID '' 25°C on 13.07.2016 at 11:54:33

Type Length Value Record

This record class demonstrates how _decode_struct and _encode_struct can be used for typical Type-Length-Value constructs. The notion ‘BB+’ is a slight extension of the struct module’s format string syntax and means to decode or encode a 1 byte Type field, a 1 byte Length field and Length number of octets as Value. The _decode_struct method then returns just the Type and Value. The _encode_struct needs only the Type and Value arguments and takes the Length from Value. Another format string syntax extension, but not not used in the example, is a trailing ‘*’ character. That just means that all remaining octets are returned as bytes.

This example also demonstrates how decode and encode error exceptions are generated with the _decode_error and _encode_error methods. These methods return an instance of ndef.DecodeError and ndef.EncodeError with the fully qualified class name followed by the expanded format string. Two similar methods, _type_error and _value_error may be used whenever a TypeError or ValueError shall be reported with the full classname in its error string. They do also check if the first word in the format string matches a data attribute name, and if, the string is joined with a ‘.’ to the classname.

The _decode_payload method also shows the use of the errors argument. With ‘strict’ interpretation of errors the payload is expected to have the Type 1 TLV encoded in first place (although not a recommended design for TLV loops). The errors argument may also say ‘relax’ and then the order won’t matter.

import ndef

class ExampleTypeLengthValueRecord(ndef.record.GlobalRecord):
    """An NDEF Record with carries a temperature and a timestamp."""

    _type = ''

    def __init__(self, *args):
        # We expect each argument to be a tuple of (Type, Value) where Type
        # is int and Value is bytes. So *args* will be a tuple of tuples.
        self._tlvs = args

    def _encode_payload(self):
        if sum([t for t, v in self._tlvs if t == 1]) != 1:
            raise self._encode_error("exactly one Type 1 TLV is required")
        tlv_octets = []
        for t, v in self._tlvs:
            tlv_octets.append(self._encode_struct('>BB+', t, v))
        return b''.join(tlv_octets)

    def _decode_payload(cls, octets, errors):
        tlvs = []
        offset = 0
        while offset < len(octets):
            t, v = cls._decode_struct('>BB+', octets, offset)
            offset = offset + 2 + len(v)
            tlvs.append((t, v))
        if sum([t for t, v in tlvs if t == 1]) != 1:
            raise cls._encode_error("missing the mandatory Type 1 TLV")
        if errors == 'strict' and len(tlvs) > 0 and tlvs[0][0] != 1:
            errstr = 'first TLV must be Type 1, not Type {}'
            raise cls._encode_error(errstr, tlvs[0][0])
        return cls(*tlvs)

    # We need at least the 2 octets Type, Length for the first TLV.
    _decode_min_payload_length = 2


record = ExampleTypeLengthValueRecord((1, b'abc'), (5, b'xyz'))
octets = b''.join(ndef.message_encoder([record]))
print("encoded: {}".format(octets))

message = list(ndef.message_decoder(octets))
print("decoded: {}".format(message[0]))
encoded: b'\xd4\x10\\x01\x03abc\x05\x03xyz'
decoded: NDEF Example Type Length Value Record ID '' PAYLOAD 10 byte '0103616263050378797a'