Basic NFC Command Family - TapTrack/TappyBLE GitHub Wiki

The Basic NFC command family defines several commands for performing several basic operations on NFC tags. In particular, this family include commands for reading and writing NDEF data from a variety of tag types.

Commands

Several commands specify a timeout and a polling type.

Timeout is a single byte duration in seconds (0x00 for indefinite). The Tappy may end up polling for a second longer than was specified, depending on where its hardware timer ticks fall. Different commands have different behaviour when the timeout is reached.

At a hardware level, the Tappy supports two polling modes. In the first polling mode, the Tappy will only look for NFC Forum Type 1 tags, while in the second it searches for MIFARE Classic as well as NFC Forum Type 2 and 4. The tag type command parameter controls which of these modes the Tappy should execute the command in - 0x01h corresponds to Type 1-only polling, and 0x02h instructs the Tappy to look for Classic/Type 2/Type 4. Note that this is not the same as the tag type parameter used in the responses.

The NDEF writing commands all support a locking flag. If this flag is set to anything other than 0x00, the tag will be locked after writing. Note that locking is a one-way operation, there is no way to recover writeability for a locked tag, so use this option with care.

Stream Tags

Instructs the Tappy to scan for tags entering its field and report each one it sees. Takes both a timeout and a polling type. When the timeout is reached, the Tappy will send a timeout response regardless of whether it encountered any tags or not. Note that if a tag remains in the TappyBLE's field, it will get reported multiple times.

Stream NDEF

Instructs the Tappy to scan for tags entering its field with NFC Forum-compliant NDEF data present. Takes both a timeout and a polling type. When the timeout is reached, the Tappy will send a timeout response regardless of whether it encountered any tags or not. Note that if a tag remains in the TappyBLE's field, it will get reported multiple times.

Scan Tag

This command is identical to Stream Tags, but will stop after a single tag is detected. Will only send a timeout response if the timeout is reached without detecting a tag.

Scan NDEF

This command is identical to Stream NDEF, but will stop after a single tag is detected. Will only send a timeout response if the timeout is reached without detecting an NDEF-formatted tag.

Stop

Cancels an ongoing polling command. Will do nothing if no such process is occurring.

Write NDEF Text Record

Instructs the Tappy to write a single text record NDEF message to a tag. Takes three parameters - timeout, lock flag, and the text in a UTF-8 byte array.

Write NDEF URI Record

Writes a single URI record to a tag. Takes four parameters - timeout, lock flag, uri code, and URI code. The URI code corresponds to an NDEF URI prefix code.

Write NDEF Custom Record

Writes a single custom NDEF record to the tag. Takes three parameters - timeout, lock flag, and the custom message. The custom message should be the bytes of the NDEF record to write.

Get Library Version

Request the version of the basic NFC command family the connected Tappy supports.

Responses

Several responses make use of a tag type parameter that enumerates the type of the tag.

Basic NFC Error Response

Uses the standard library error response format.

Basic NFC Library Version Response

Uses the standard command family version response format

NDEF Found Response

The Tappy has read a tag that contains NDEF data. Response contains the tag UUID, a tag type identifier byte, and the NDEF record.

Scan Timeout Response

Polling operation has timed out.

Tag Found Response

The Tappy has found a tag. Response contains the tag UUID and a tag type identifier byte.

Tag Written Response

The Tappy has written data to a tag. Response contains the tag UUID and a tag type identifier byte.

Error Codes

0x01h - Invalid parameter specified

0x02h - RFU

0x03h - A polling error occurred. This indicates a hardware-level problem on the Tappy. If it is persistent, please record the error byte as well as the NFC status byte and contact TapTrack.

0x04h - Too few parameters specified

0x05h - NDEF message too large to fit on presented tag

0x06h - Error creating NDEF content

0x07h - Error writing NDEF content to tag

0x08h - Error locking tag