The TappyUSB and TappyBLE from TapTrack are NFC reader/writers with an integrated BLE connection or USB connection. It is ideally suited for adding NFC capabilities to tablets and other mobile devices that do not have NFC built in. The Tappy reader line is designed to reduce the development time for integrators and engineers who need an NFC reader for their projects but don’t have the time to learn the intricate details of NFC technology, tag types, ISO standards, and NFC Forum specifications.

The goal of the Tappy readers is to allow you to focus your efforts on application development rather than the time-consuming complexity and interoperability issues associated with the development of an NFC stack.

To accomplish this ease of integration, the Tappy contains a full NFC stack. All tag specific read/write instructions, NFC Data Exchange Format (NDEF) handling, and tag formatting/locking commands are done by the TappyBLE thereby relieving the developer of this effort. The Tappy is designed of off-load all NFC code development and allow developers to focus on the intended application rather than the NFC details.

1.2 Bluetooth Low Energy

The TappyBLE provides the easiest to use and flexible NFC interfaces in the industry. Rather than fuss with tag specific command codes, checksums and length bytes, the hosting BLE device (usually a tablet or laptop) need only transmit basic commands with simple parameters/arguments. Since all the entire NFC stack is implemented in the TappyBLE module, only these simple commands need to be learned. The TappyBLE by default is configured as a BLE peripheral, so the device receiving the NFC information from it should be configured as a central device.

1.3 Keyboard Emulation (Wedge) with true Human Input Device (HID) Profile

Tappy readers version 1.0 and later have the ability to present itself as a keyboard to a computer or mobile device. This allows the keyboard wedge use case, where NFC tag codes or data are read and typed out as keystrokes emulated from the Tappy. For more information regarding how to enable keyboard more on your Tappy and the various configuration options, please consult the application note for Tappy Human Input Device (HID) keyboard emulator. TappyBLE units (v1.0 firmware or later) can also function as a TappyUSB (and hence keyboard) by connecting it through the USB charging port on the TappyBLE which doubles as a USB interface.

2 Tappy Communication Messaging Protocol (TCMP)

The Tappy uses a communication inspired by the HDLC (High-level Data Link Control) protocol, albeit a highly simplified version of it. Since Bluetooth Smart (BLE) has limited data payload capabilities, TappyBLE must rely on its own framing convention for reliable data transmission. This is helpful when transmitting NDEF messages such as URLs, vCards, etc.

2.1 Basic Framing Convention

Figure 1 below illustrates the basic framing convention.

Figure 1: TCMP Basic Framing Convention

2.2 Start / End of Frame

The hex code 0x7E shall be used to denote both the start and end of frames (SOF/EOF).

2.3 Escape Sequences

A 0x7E in the frame contents shall be escaped with the sequence 0x7D,0x5E.

A 0x7D in the frame contents shall be escaped with the sequence 0x7D,0x5D.

2.4 Length Bytes

Length bytes LEN0 and LEN1 shall indicate the length of: command family (CF) bytes (2), command code (CMD) (1), payload, and CRC bytes (2). Thus, the represented length is the payload length plus 5.

LEN0 and LEN1 shall be interpreted as a 2 byte unsigned integer.

2.5 Length Checksum (LCS) byte

The Length Checksum (LCS) byte shall be calculated such that:

Lower byte of:(LEN0 + LEN1 + LCS) = 0x00

2.6 Command Family (CF) bytes

The Command Family (CF) bytes are two bytes that represent the command family of the command code byte to follow. Most command families are reserved for custom NFC firmware implementations for TapTrack enterprise clients, although the following command families are supported in every full featured TappyBLE:

0x00,0x00 : System Command Family

0x00,0x01 : Basic NFC Command Family

0x00,0x03 : Mifare Classic Read/Write Command Family

0x00,0x04 : Type 4 ISO-DEP APDU Transceive Command Family

0x00,0x06 : NTAG 21X Password Protected Tag Command Family (firmware v0.76 or later)

0x00,0x08 : ST Micro M24SR02 NFC EEPROM Configuration Command Family (See Appendix J)

When ordered as a standalone checkin station, the following command family is available. Both the TappyUSB and TappyBLE can be ordered for standalone checkin applications. Contact us at contact@taptrack.com for more information.

0x00,0x05 : Standalone Checkin Station Command Family (see Appendix G)

All other values are Reserved for Future Use (RFU) - contact TapTrack at contact@taptrack.com or 1-800-293-6094 to have your custom reader firmware implemented.

2.7 CRC bytes

Two CRC bytes shall be used to verify data integrity. The CRC shall be a 16 bit CRC (CRC16) with the following polynomial:

In hexadecimal, this polynomial is represented as:

0x1021 - Normal

0x8408 - Reversed

0x8810 - Reverse of reciprocal

The initial value shall be 0x6363. When sending frames to the Tappy, the CRC is calculated over the contents of the packet (length through payload) prior to escaping 0x7D and 0x7E bytes. When verifying frames received from the Tappy, the frame shall be unescaped prior to CRC verification. Please refer to appendix A for example source code implementations of the CRC.

3 Tappy Command Families

Once connected, the TappyBLE makes integrating NFC into tablets that don’t come equipped with it a snap. Listed below are the command families documented in verbose detail here, values in parentheses are the command family codes in hexadecimal:

System (0x00,0x00)

System level commands and errors

Basic NFC (0x00,0x01)

Common NFC operations such as polling for UIDs and NDEF messages (documented in detail here)
Used to write NDEF data to tags (see appendix C for details)

Other command families use the same TCMP communication structure, but with different command and response codes. These command families perform other NFC related actions such as tag writing, emulation, password protected tag writing, etc. These additional command families are not described in verbose detail in the body of this document, but rather are summarized in the appendices.

3.1 Command Structure

The basic command structure shall be two (2) bytes indicating the command family (CF) followed by a single byte command code, followed by parameters, if any. Refer to figure 2 below.

Figure 2: Command Structure

Commands shall be encapsulated in TCMP frames as specified in section 2.

3.2 Response Structure

If the command was received correctly with proper syntax The TappyBLE will not send any response or acknowledgment. It is like a UNIX system in this way.

Should the command be a polling command, where NFC tag information will follow once a tag is discovered, it will be sent at that time. If a timeout occurs before a tag is discovered, this will also be reported by the Tappy.

The basic response structure shall be two (2) bytes indicating the command family (CF) followed by a single byte response code, followed by response data, if any. Refer to figure 3 below.

Figure 3: Response Structure

Responses are encapsulated in TCMP frames as specified in section 2.

3.3 Error Messages

There are two types of error messages: System errors and application errors. System errors are associated with command family 0x00,0x00, whereas application errors are associated with their respective command family. Refer to figure 4 and figure 5 below for the system and application error message structures.

Figure 4: System Error Message Structure

Figure 5: Application Error Message Structure

3.3.1 System Communication Errors (Command Family 0x00,0x00)

TCMP communication errors are reported under the system command family and occur when there was a problem parsing TCMP frames and commands. They are reported by the TappyBLE with the hex error codes (as per figure 4 above):

0x01 Invalid or improperly formatted message
0x02 LCS (Length Checksum) error
0x03 CRC error
0x04 Bad length parameter

3.3.2 System Application Errors (Command Family 0x00,0x00)

When application errors (using a properly formatted command) occur using the system command family, it is reported by the TappyBLE with the hex response code 0x7F (as per figure 5 above) with the error codes listed here.

3.3.2.1 System Application Error Codes (Error Code byte)

0x05 Invalid parameter
0x06 Unsupported command family
0x07 Too few parameters
0x08 RFU
0x09 Invalid PIN supplied for secure Bluetooth PIN pairing configuration
0x0A Error setting 6 digit PIN for secure Bluetooth pairing
0x0B Error setting boot configuration

3.4 Tappy System Family - Command and Response Syntax

3.4.1 Housekeeping Commands

There are numerous housekeeping commands supported within the TappyBLE system family:

Command code 0xFE - Get Tappy hardware version. The response code is 0x05
Command code 0xFF - Get Tappy firmware version. The response code is 0x06
Command code 0xFD - Ping Tappy.The response code is 0xFD, no payload
Command code 0x01 - Set Tappy configuration item (see “set Tappy configuration settings” below)
Command code 0x02 - Battery level (see “battery level command” below, BLE only)
Command code 0x03 - Output test frames (see “output test frames” below)

The format of the get hardware/firmware response is as shown in figure 6 below:

Figure 6: Response structure for get hardware and firmware version commands

3.4.2 Set Tappy Configuration Settings - System command code 0x01

System command code 0x01 is used to enable/disable certain features of the TappyBLE or change its configuration. The first payload byte shall be the setting that is being changed as listed below.

Please note that once changed, these settings do not persist after a power cycle. When using any of these configuration settings, it is recommended to set it each time you connect to the Tappy. To persist these settings, a boot configuration can be used that will have the Tappy execute these configuration commands each time upon bootup. For more information on boot configurations refer to our application note regarding boot configurations.

3.4.2.1 Type 2 Tag Identification - setting 0x01

When configuring this setting (0x01), the second payload byte indicates if this feature is being enabled or disabled. Any other value than 0x00 will enable this capability. The response code is 0x07 with no payload returned.

The exact manufacturer and model of the chip inside an NFC Forum Type 2 compliant tag is not completely identified during tag detection. As such, identifying the exact model (NTAG203, NTAG21X, Ultralight, etc..) involves a few more tag interactions and possibly memory reads. This is known as Type 2 tag identification, and by default it is disabled. When disabled, the TappyBLE will report all Type 2 tags as a generic or unknown type 2 tag (this does not indicate a problem of any kind with the tag).

When enabled, the TappyBLE will report the these tags based on the detected chip model. The reason this feature is disabled by default is because using it drastically reduces the scanning speed. In many applications it is not necessary to hinder scanning speed to determine the type 2 chip model.

3.4.2.2 Enable Data Throttling for slower BLE devices - setting 0x02

This setting only available in firmware versions 0.50 and higher.

Since BLE packets can be no more than 20 bytes, BLE devices must do some buffering to receive higher amounts of data such as TCMP response frames exceeding this 20 byte maximum. For simple BLE devices such as the Bluegiga BLED112 model dongle used in TapTrack’s Windows Tappy demonstration software, the ability to buffer and receive these large TCMP frames correctly is limited and the data transmitted by the Tappy must be throttled in order to accommodate such BLE receivers. iOS and flagship Android devices such as Nexus and Galaxy models do not require this accommodation and hence the default setting of the Tappy does not throttle data transmission. However, if the application calls for a simpler BLE receiver without robust buffering, the Tappy can be configured to limit the rate at which it transmits data.

When configuring this setting (0x02), there are two (2) payload bytes that must follow, and two (2) optional payload bytes :

Required parameter bytes:

Millisecond delay: The number of milliseconds to pause between successive packet groups
Packet multiple: The number of packets (each 20 bytes) to transmit before pausing for the delay

Optional parameter bytes:

Two bytes, representing an unsigned integer, that indicate at what payload length the throttling should be engaged. This allows the throttling to only be applied to larger frames thereby not increasing the communication latency for smaller frames.
If these bytes are not passed, the throttling will be engaged for all payload lengths.

These settings are not saved in nonvolatile memory and must be set upon startup, though the fourth generation Tappy (scheduled for release in early 2017) will persist these settings.

3.4.2.3 Enable dual Type 1 (Topaz.Jewel)/Mifare detection on NDEF write - setting 0x03

This setting only available in firmware versions 0.51 and higher

The Tappy works with NFC Forum Type 1 tags (commonly referred to as Topaz/Jewel) however with limited compatibility. The complete static memory (first 96 bytes of user memory) of an NFC Forum Type 1 tag can be accessed, however the dynamic memory cannot be accessed. As such, NDEF messages that can fit entirely in the static memory can be written to these tags if the Tappy is set to detect both Mifare and NFC Forum Type 1 tags when writing NDEF messages.

When configuring this setting (0x03), the second payload byte indicates if this feature is being enabled or disabled. Any other value than 0x00 will enable this capability. The response code is 0x07 with no payload returned.

3.4.2.4 Set Audible Buzzer Duration for Successful Scans - setting 0x05

By default, only USB Tappy readers have a buzzer. To conserve battery power on BLE Tappy readers, they do not include a buzzer unless specified at order time.

This setting only available on version 4 or later Tappy readers, w/ firmware versions 0.73 and higher. Please also note that this setting applies only the Basic NFC and NTAG21x Password, and M24SR02 command families, buzzer behaviour in other command families are not affected by this setting.

When configuring this setting (0x05), the second and third payload bytes indicates the duration, in milliseconds (ms), that the buzzer should sound upon a successful scan. These two bytes represent an unsigned 16 bit integer. Passing 0x00,0x00 will disable the buzzer entirely. The response code is 0x07 with payload as the current buzzer duration setting.

The default value for this setting is 50 ms.

Note: The buzzer duration is not ‘stacked’ with the success green LED duration but rather carried out in parallel in such a fashion that if the green LED duration exceeds that of the buzzer, the buzzer will stop sounding before the green LED deactivates even though they will begin at the same time. The same will apply if the buzzer duration exceeds that of the green LED

3.4.2.5 Set Green LED Duration for Successful Scans - setting 0x06

This setting is only available on Tappy readers, w/ firmware versions 0.76 and higher. Please also note that this setting applies to only the Basic NFC and NTAG21x Password, and M24SR02 command families, LED behaviour in other command families are not affected by this setting.

When configuring this setting (0x06), the second and third payload bytes indicates the duration, in milliseconds (ms), that the green leds should be lit upon a successful scan. These two bytes represent an unsigned 16 bit integer. Passing 0x00,0x00 will disable the green LEDs entirely. The response code is 0x07 with payload as the current green LED duration setting.

Note: Th green LED duration is not ‘stacked’ with the success buzzer duration but rather carried out in parallel in such a fashion that if the green LED duration exceeds that of the buzzer, the buzzer will stop sounding before the green LED deactivates even though they will begin at the same time. The same will apply if the buzzer duration exceeds that of the green LED

The default value for this setting is 300 ms.

3.4.2.6 Set Red LED Duration for Failed Scans - setting 0x07

This setting only available on Tappy readers, w/ firmware versions 0.76 and higher. Please also note that this setting applies to only the Basic NFC and NTAG21x Password, and M24SR02 command families, LED behaviour in other command families are not affected by this setting.

When configuring this setting (0x07), the second and third payload bytes indicates the duration, in milliseconds (ms), that the red leds should be lit upon an unsuccessful scan. These two bytes represent an unsigned 16 bit integer. Passing 0x00,0x00 will disable the red LEDs entirely. The response code is 0x07 with payload as the current red LED duration setting.

The default value for this setting is 500 ms.

3.4.2.7 Enable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x08

TappyBLE full featured readers with firmware versions 0.85 and higher support the configuration of a six (6) digit PIN for secure Bluetooth BLE pairing using security bode 1 (encryption) with level 3 : authenticated encryption with a passkey.

When configuring this setting (0x08), the second through seventh payload bytes indicate the the six (6) digit PIN, and must be ASCII characters ‘0’ through ‘9’ otherwise the system application error code 0x09 is returned indicating an invalid PIN was supplied.

If successfully set, the response code is 0x07 is returned with no payload bytes, after which the secure Bluetooth PIN pairing with encryption is enabled (this will persist after power cycles). Once the PIN is set, the communication with the TappyBLE is encrypted and no device can connect to the Tappy and transmit or receive data without providing the correct PIN.

When the PIN pairing is configured, the TappyBLE will still connect to host devices in the same way, however once the connection is established the TappyBLE will wait approximately 30 seconds for the host device to successfully complete the PIN pairing process before it disconnects. Before the PIN pairing is complete, no data transmission is possible.

The default value for this setting is to have the PIN pairing disabled.

Please note that it is recommended that setting the personalized PIN be carried out in a secure environment.

3.4.2.8 Disable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x09

TappyBLE readers with firmware versions 0.85 and higher support the configuration of a six (6) digit PIN for secure Bluetooth BLE pairing using security bode 1 (encryption) with level 3 : authenticated encryption with a passkey.

To disable the secure Bluetooth PIN pairing/encryption, use the configuration setting 0x09 with no parameters. If successfully set, the response code is 0x07 is returned with no payload bytes, after which the secure Bluetooth PIN pairing with encryption is disabled. To disable the PIN pairing on a TappyBLE for which the PIN has been forgotten, versions 1.0 firmware and later TappyBLE models are dual interfaces featuring a USB host interface at the USB jack. Connecting the USB jack as if it were a TappyUSB will allow you to perform this action on the Android Tappy Demo App without needing to connect over BLE (and remember the PIN). For firmware versions lower than 1.0, where applicable, the bonding cache.can be cleared by holding an NDEF encoded tag with the text record “TappyBLE Reset PIN” when booting up the TappyBLE.

The default value for this setting is to have the PIN pairing disabled.

3.4.2.9 Disable Blue Light Flashing During Tag Polling - setting 0x0A

This setting only available on Tappy readers, w/ firmware versions 0.85 and higher. To disable the flashing blue lights when the Tappy is polling for an NFC tag or target, issue the set configuration item command the setting 0x0A and one (1) additional parameter byte to indicate the desired behavior of the blue light when polling is active:

0x00 - blue lights will be inactive (off) during polling
0x01 - blue lights will be active (solid but not flashing) during polling
All other values - RFU

If successfully set, the response code is 0x07 is returned with no payload bytes.

The default value for this setting is for the flashing blue light to be enabled.

3.4.2.10 Re-enable Blue Light Flashing During Tag Polling - setting 0x0B

This setting only available on Tappy readers, w/ firmware versions 0.85 and higher. To re-enable the flashing blue lights when the Tappy is polling for an NFC tag or target, issue the set configuration item command the setting 0x0B and no additional parameter bytes. If successfully set, the response code is 0x07 is returned with no payload bytes.

The default value for this setting is for the flashing blue light to be enabled.

3.4.2.11 Clear Bluetooth Gatt Bonding Cache (TappyBLE only) - setting 0x0C

As of firmware v1.0, TappyBLE readers feature Bluteooth version 5 with enhanced security pairing (which as of v1.0 is required to communicate with the TappyBLE over Bluetooth). In some cases, to correct stale connection pairing data that is causing failed or one-way communication with paired devices it is necessary to not only “forget”, or unpair the TappyBLE on the host device but also to clear the bonding cache on the TappyBLE itself so it can “forget”, or unpair the host device’s connection data. Only after this can a new pairing be established to allow proper two way communication.

To clear the bonding cache without requiring to connect over BLE, versions 1.0 firmware and later TappyBLE models are dual interfaces featuring a USB host interface at the USB jack. Connecting the USB jack as if it were a TappyUSB will allow you to perform this action on the Android Tappy Demo App without needing to connect over BLE. For firmware versions lower than 1.0, where applicable, the bonding cache.can be cleared by holding an NDEF encoded tag with the text record “TappyBLE Clear Bonding” when booting up the TappyBLE.

There are no parameters to this command.

3.4.3 Battery Level Command (TappyBLE only)

To query the TappyBLE’s battery level, the system command code 0x02 shall be used. The response code is 0x08 and the single payload byte represents and unsigned integer from 1 to 100 indicating the approximate battery charge level.

3.4.4 Output Test Frames

This features is available on firmware version 0.51 or later. For those implementing TCMP on a platform not supported by an existing Tappy SDK, or re-implementing the framing protocol for some other reason, the output test frames are useful to test the new implementation. This command will cause the Tappy to respond with frames representing various test cases in the order specified below. The command code is 0x03 and the response code for the output test frames command is 0x09. In all test cases, the payload is all dummy bytes with 0xFF values.

With a frame length of less than 20 bytes:

Error in only the LCS byte
A payload that has one fewer byte than indicated by the length bytes
A payload that has one additional byte than indicated by the length bytes
Error in only the CRC bytes

With a frame length of greater than 256 bytes:

Error in only the LCS byte
A payload that has one fewer byte than indicated by the length bytes
A payload that has one additional byte than indicated by the length bytes
Error in only the CRC bytes

A frame with a four (4) byte payload, all 0x7E (test escape sequence)
A frame with a four (4) byte payload, all 0x7D (test escape sequence)
A frame with a 256 byte payload, all 0x7E
A frame with a 256 byte payload, all 0x7D
A SoF byte followed by a number of 0xFF bytes followed by a valid TCMP frame with a seven (7) byte payload. This will test how the implementation handles using a single character as both a start and end of frame. This must be supported in case of frame fragmentation.

The required parameter number of parameter bytes is two, representing an unsigned integer for a millisecond delay desired between successive test frame transmission. Sample versions of this command with CRCs already calculated are presented below. Simply sending these exact bytes will invoke these tests which is useful if the full TCMP transmission is not yet implemented.

No stagger between tests (0 ms):

0x7E,0x00,0x07,0xF9,0x00,0x00,0x03,0x00,0x00,0x98,0x96,0x7E

One second stagger between tests (1000 ms):

0x7E,0x00,0x07,0xF9,0x00,0x00,0x03,0x03,0xE8,0xD9,0xB8,0x7E

Five second stagger between tests (5000 ms):

0x7E,0x00,0x07,0xF9,0x00,0x00,0x03,0x13,0x88,0x2F,0x2F,0x7E

3.4.5 Output Test Frame of Specified Size

Depending on the negotiated Bluetooth connection between the host central device and the Tappy peripheral, larger frames may result in communication errors. The root cause of the issue is the Tappy’s internal buffer on its BLE module has a practical capacity in the order of kB, not MB as it would be on a modern iPad or Android device. In practice, most devices can handle payloads of a few hundred bytes without issues but will encounter issues with larger payload, however, TapTrack engineers have observed that on some mobile devices even payloads of a few hundred bytes can experience an unacceptable transmission error rate.

To allow developers to determine on their own what this practical size limit is, the system command family includes a command which will output a test frame of a specified payload length. The command code is 0x04 and the response code for the output test frame with a specified size command is 0x0A. By issuing this command with increasing sizes, the developer can determine programmatically the maximum payload length is on his/her setup before transmission errors occur. Once this parameter is known, the Tappy can be configured to throttle its transmission rate when the frame has a payload exceeding this length. See the section entitled “Enable Data Throttling for slower BLE devices” for full details of how to specify the data throttling. In many applications payloads will never exceed these practical limits so generally speaking this is an advanced configuration feature needed only if single frames will exceed several hundred bytes.

Sample versions of this command with CRCs already calculated are presented below. Simply sending these exact bytes will invoke these tests which is useful if the full TCMP transmission is not yet implemented.

Send test frame with 1000 byte payload (dummy data):

0x7E,0x00,0x07,0xF9,0x00,0x00,0x04,0x03,0xE8,0x55,0xBD,0x7E

3.4.6 Get Clock Status

The Tappy reader usually includes a clock to allow hosting programs to set a tag scanning timeout of up to 255 seconds. There are however certain variants of the Tappy that do not have this clock installed or circumstances where the clock is not operating correctly. The Tappy reader will still function normally without the clock with the singular exception of tag scanning timeouts which are ignored in such a circumstance. If a Tappy’s clock is not operating and a tag scan command is received with a non zero timeout, the scan will proceed as if the timeout setting was 0 and therefore will not timeout. A stop command can be used to halt the scanning in this circumstance.

To query the state of the clock from the Tappy, the system command code 0x05 is used. The response TCMP frame will contain the response code 0x0B and indicate the status of the clock as a single byte payload indicating if the clock is operating. A value of 0 indicates the clock is not operating and all other values indicate that the clock is functioning normally.

3.4.7 Configure On-Board Cooldown Period for Automatic Scan Filtering

Available only on firmware v0.72 and later

For some use cases, it is desirable to not allow scans of the same tag in close succession. Perhaps there is an amount of time that must pass and/or a minimum number of different tags scanned before a tag can be scanned again. This is known as a cooldown period, and the Tappy gives you the ability to configure one directly on the reader. When active, the onboard cooldown disables the green success indicator if it detects the tag was scanned within the cooldown period. To avoid the user falsely getting the impression that the scan was accepted, the Tappy flashes blue for a brief instant rather than green for a successful scan.

The cooldown has two settings when active:

The size of the cooldown buffer. This defines how many of the recently scanned tags the Tappy will remember. While a tag is in this buffer, the Tappy will not allow the successful scan of that same tag unless the timeout period (below) has elapsed. The maximum size of the cooldown buffer is 10. The default is 10.

The timeout period: This defines the amount of time that must pass after a tag is successfully scanned before the Tappy will allow it to scan successfully again. The default setting for this is five minutes. The timing on the Tappy is accurate to within +/- 10%.

To configure these settings, there are two commands available:

3.4.7.1 Configure Onboard Cooldown for Scan Filtering

Using command code 0x08 in the system command family, the detailed operation of the Tappy’s onboard cooldown feature can be configured. Please note this is only supported on v0.72 firmware and later.. This command’s payload consists of three (3) required parameter bytes:

Enable/Disable Cooldown-

0x00, the Tappy will use the existing setting
0x01 - enables the cooldown
0x02 - disables the cooldown

The default setting for the cooldown is that it is disabled.

Set Cooldown Buffer Size (2 bytes).

This setting is passed as two bytes that represent an integer number of tags that the cooldown buffer will store

0x00,0x00: The Tappy will use the existing setting
All other values: - sets the buffer size

The default setting is 10. The maximum setting is 10.

The response code for this command is 0x0D and the response payload is as follows:

Cooldown enabled status

0x01 - indicates the cooldown is enabled
0x00 - indicates the cooldown is disabled

Cooldown buffer size (2 bytes)

The current setting for the cooldown buffer size represented as a two byte unsigned integer.

3.4.7.2 Set Cooldown Timeout Period

Using command code 0x09 in the system command family, the timeout period of the Tappy’s onboard cooldown feature can be configured. Please note this is only supported on v0.72 firmware and later.. This command’s payload consists of two (2) required parameter bytes:

Set Cooldown Timeout (2 bytes).

This setting is passed as two bytes that represent an integer number of seconds that the Tappy’s onboard cooldown will wait before allowing a tag found in the cooldown buffer t successfully scanned again.

0x00,0x00: This disables this timeout - meaning that if a presented tag is found in the buffer, it will not be allowed to scan until enough subsequent tags are sanned such that this tag is overwritten in the buffer.
All other values: - sets the cooldown timeout period.

The default setting is 5 minutes (600 seconds)

3.4.8 System Commands supported in Kiosk (Heartbeat) and Keyboard Wedge Tappy Configurations (TappyBLE only)

Kiosk and keyboard wedge mode is a special configuration of the Tappy that operates in a standalone fashion. When configured for kiosk/heartbeat mode the Tappy will poll for tags and transmit the UID and any NDEF data found automatically upon bootup. All command families are disabled in this configuration with the exception of the system command family. Furthermore, there is an additional system level configuration command available.

The TappyBLE, when ordered with the kiosk/heartbeat configuration (sometimes referred to as keyboard wedge mode) is able to maintain an active heartbeat with its host. The heartbeat helps overcome two constraints:

When the operator will not regularly have the application’s UI visible do notice if the BLE connection drops. Under normal configuration, the TappyBLE will continue to scan even if the BLE connection is lost. It will only stop scanning if a timeout was set, otherwise the operator may continue scanning without knowledge that the entries are not being made.

The undefined amount of time that passes between the BLE connection failing and the event being raised on the host. On mobile platforms such as Android this may be up to a minute or longer. By maintaining an active heartbeat with the host, the TappyBLE in kiosk mode can have its BLE connection diagnosed and recovered in a more reliable and expedient fashion.

When the TappyBLE is being used for a kiosk or similar application where there will be no operator present for technical support should the BLE connection drop. The kiosk/heartbeat mode allows faster and smoother programmatic detection and repair of failed BLE connections.

When configured to maintain an active heartbeat, a TappyBLE will exhibit the LED light patterns as shown below in table 1.

Table 1: TappyBLE Kiosk/Heartbeat Mode LED Patterns

Meaning	Top LEDs	Side LED
Booting up	Solid blue, beep, followed solid red.	-
Standby - seeking BLE connection	Solid red	Flashing blue
BLE connected, no heartbeat established	Solid red	Solid blue
BLE connected, heartbeat established.	Solid blue	Solid blue
BLE connected, heartbeat established, successful scan	Solid blue to flash green, beep, (configurable, see next section)	Solid blue
BLE connected, heartbeat established, failed scan	Solid blue to flash red (configurable, see next section)	Solid blue
BLE connected, heartbeat established, heartbeat received	Solid blue	Solid blue with pulse of green
Low battery	-	Solid red (may appear purple if BLE is connected)

3.4.8.1 Configure Kiosk and Keyboard Wedge Mode

Using command code 0x06 in the system command family, the detailed operation of the Tappy while in kiosk/keyboard wedge mode can be configured. You must order your Tappy in this mode from TapTrack. This command’s payload consists of four (4) required parameter bytes in the order specified below followed by an additional six (6) optional parameter bytes.

Dual tag detection - configure the polling to include or exclude dual-mode polling, which will detect Type 1 tags (Jewel/Topaz) as well as all other 14443A tags.

0x00, the Tappy will use the existing setting
0x01 - enables dual tag detection (Type 1 is detected)
0x02 - disables dual tag detection
The default setting for dual tag detection is disabled.

NDEF reading - configure the polling to include or exclude NDEF detection. When disabled, the Tappy will only transmit tag UIDs.

0x00, the Tappy will use the existing setting
0x01 - enables NDEF detection
0x02 - disables NDEF detection

The default setting for NDEF detection is enabled.

Heartbeat period - the number of minutes between heartbeat signals (pings) from the host required to keep the Tappy in polling mode. When a heartbeat is not detected before this number of seconds the Tappy will cease polling, reset the BLE connection and show red lights on top until a heartbeat is re-established.

0x00, the Tappy will use the existing setting
All other values, the Tappy will set the heartbeat period to that number of minutes
To disable the heartbeat period entirely, see the next section.

The default setting for the heartbeat period is 30 seconds. The minimum setting is 10 seconds

Send scan error messages - when enabled the Tappy will send a polling error message using the basic NFC command family.

0x00, the Tappy will use the existing setting
0x01 - enables scan error messages
0x02 - disables scan error messages

The default setting for sending scan error messages is disabled.

Successful scan LED indication time and stagger (two (2) bytes)

This setting is passed as two bytes that represent an integer number of milliseconds the Tappy will hold the green LEDs on after a successful scan

The default value for the successful scan LED indication time is 1000ms. The minimum is 1ms (effectively disables the green success LED so the user won’t see it). Note: Under host controlled LED operation, the delay is still in effect, but the green LED won’t activate.

Failed scan LED indication time and stagger (two (2) bytes)

This setting is passed as two bytes that represent an integer number of milliseconds the Tappy will hold the red LEDs on after a failed scan.Note: Under host controlled LED operation, the delay is still in effect, but the red LED won’t activate.

The default value for the failed scan LED indication time is 2000ms. The minimum is 1ms (effectively disables the red fail LED so the user won’t see it)

Post scan delay time and stagger (two (2) bytes)

This setting is passed as two bytes that represent an integer number of milliseconds the Tappy will wait after a tag scan (regardless of the success/fail) before attempting to re-detect a tag.

The default value for the post scan delay time and stagger is 200 ms.

Post successful scan beep (buzzer) duration and stagger (two (2) bytes)

This setting is passed as two bytes that represent an integer number of milliseconds the Tappy will sound the buzzer after a successful tag scan. This time is elapsed before the successful scan LED indication time and stagger

The default value for the post successful scan beep and stagger is 50 ms. The minimum is 1ms (1ms disables the buzzer).
Note: This duration is not ‘stacked’ with the success green LED duration but rather carried out in parallel in such a fashion that if the green LED duration exceeds that of the buzzer, the buzzer will stop sounding before the green LED deactivates even though they will begin at the same time. The same will apply if the buzzer duration exceeds that of the green LED

The response code for this command is 0x0C and the response payload is as follows:

Dual tag detection

0x01 - indicates dual tag detection is enabled (Type 1 is detected)
0x00 - indicates dual tag detection is disabled

NDEF reading

0x01 - indicates NDEF detection is enabled (default setting)
0x00 - indicates NDEF detection is disabled .

Heartbeat period

Value indicates the heartbeat period expected from the host in minutes.

Send scan error messages

0x01 - indicates sending scan error messages is enabled (default setting)
0x00 - indicates sending scan error messages is disabled .

Successful scan LED indication time and stagger (two (2) bytes)

Number of milliseconds the Tappy will hold the green LEDs on after a successful scan

Failed scan LED indication time and stagger (two (2) bytes)

Number of milliseconds the Tappy will hold the red LEDs on after a failed scan

Post scan delay time and stagger (two (2) bytes)

Number of milliseconds the Tappy will wait after a tag scan before attempting to re-detect a tag, regardless of whether the scan was successful or not

Post successful scan buzzer beep duration (two (2) bytes)

Number of milliseconds the Tappy will sound the buzzer after a successful tag scan. This time is elapsed before the successful scan LED indication time and stagger

Please note that these settings do not persist after a power cycling or reboot of the Tappy and must be configured each time upon boot up by the host if non default settings are required.

3.4.8.2 Disable Heartbeat Transmission from Host

To disable the heartbeat check by the Tappy in kiosk mode, use this system configuration command. Using command code 0x07 in the system command family, the need for the Tappy to receive periodic heartbeat pings can be disabled. There are no payload bytes for this command. The response code for this command is 0x17 and contains no response payload.

3.4.8.3 Host Application Light (LED) Control When in Kiosk Heartbeat Mode

TappyBLE readers in kiosk/heartbeat mode still allow programmatic control of the lights (LEDs) and buzzer, and just like in the standard Tappy configurations, the automatic LED behaviour is modified:

After the first time the blue light (LED) is controlled programmatically, to avoid confusion the Tappy will no longer have the blue light active when in idle/standby mode.

After the first time the lights (LEDs) are controlled programmatically, to avoid confusion, automatic LED activations are disabled after any activate and deactivate commands (0x0A,0x0B,0x0D,0x0E,0x10,0x11) but not activate for a specified duration commands (0x0C,0x0F,0x12) which proceed synchronously. These include:

Green light for a successful scan
Red light for a failed scan
Fast flashing blue light when the cooldown filter is invoked.

These behaviours do not persist after a power cycle, they begin the first time manual light control is invoked.

3.4.9 LEDs and Buzzer Commands for Host Controlled Visible/Audible Feedback

Features described in this section are supported by firmware versions 0.85 and higher.

It is sometimes desirable to have the host device (often a tablet or mobile phone) programmatically control the LEDs and buzzer. This can be the case if the application must analyze the response data from the Tappy before indicating to the user that the scan was successful by means of a green light or beep. When using host controlled visual and audible feedback, it may be useful to disable the automatic light patterns used in the Basic NFC Command Family operations and Heartbeat (kiosk) mode operations such as scanning tag UIDs or NDEF data, refer to sections 3.4.2 and 3.4.8.1 respectively. Disabling the automatic lights and buzzer will help prevent the user from falsey thinking the scan was accepted when in fact the host must indicate this after processing the response.

For each of the red, green, and blue LEDs as well as the buzzer there are commands allowing the host device to activate, deactivate, and activate for a specified amount of time. These are summarized in table 2 below:

Table 2: Command Codes for Light and Buzzer Controls

Visible/Audible Option	Activation Cmd Code (no params)	Deactivation Cmd Code (no params)	Activate for specified duration Cmd Code (see params in next column)	Applicable parameters for ‘Activate for duration’ command
Red LED	0x0A	0x0B	0x0C	Duration: 2 bytes,an unsigned integer representing milliseconds.
Green LED	0x0D	0x0E	0x0F	Duration: 2 bytes,an unsigned integer representing milliseconds.
Blue LED	0x10	0x11	0x12	Duration: 2 bytes,an unsigned integer representing milliseconds.
Buzzer	0x13	0x14	0x15	Duration: 2 bytes,an unsigned integer representing milliseconds.

Note: USB models and non-battery powered BLE models will have a buzzer by default, however battery powered units can have buzzers installed if this is specified when ordering.

When one of the visible or audible elements changes state, messages with responses code as per table 2 below are sent by the Tappy. When the duration is specified (command codes 0x0C,0x0F,0x12,0x15), a message is sent when the indicator activates and when it deactivates.

Table 3: Response Codes for Light and Buzzer Controls

Visible/Audible Option	Status Active Response Code	Status Inactive Response Code	Response Payload (both Active and Inactive Responses)
Red LED	0x0E	0x0F	4 bytes: indicator state as per the next section
Green LED	0x10	0x11	4 bytes: indicator state as per the next section
Blue LED	0x12	0x13	4 bytes: indicator state as per the next section
Buzzer	0x14	0x15	4 bytes: indicator state as per the next section

3.4.9.1 Query Status of Audible and Visible Indicators

To query the current state of the indicators, use system command code 0x16 with no parameter bytes. The Tappy will return the response code 0x16 with four (4) payload bytes that indicate the state of the lights and buzzer. A value of 0 signifies the indicator is inactive and 1 signifies the indicator is active. The response payload is formatted as follows:

Byte 0: red light state
Byte 1: green light state
Byte 2: blue light state
Byte 3: buzzer state

3.4.9.2 Important note about host controlled LED operation

The first time the lights (LEDs) are controlled programmatically, to avoid confusion, the Tappy will no longer have the blue light active when in idle/standby mode. This applies to activate and deactivate commands (0x0A,0x0B,0x0D,0x0E,0x10,0x11) but not activate for a specified duration commands (0x0C,0x0F,0x12).

The first time the blue light (LED) is controlled programmatically, to avoid confusion, the Tappy will no longer flash its blue lights when polling/scanning for a tag, but will set the blue light to solid when polling. To set the blue light to be inactive during tag polling, refer to the section entitled “Disable Blue Light Flashing During Tag Polling”

These behaviours do not persist after a power cycle, they begin the first time manual light control is invoked.

3.4.10 Boot Configuration Commands

As of firmware v1.3 (roughly 2021 onwards), the Tappy features a user configurable non-volatile bootup configuration that allows end users and system integrators to make the configuration persist/survive power cycling.

This allows attractive use cases such as user configured standalone operation, keyboard emulation (HID profile) customization, and selecting alternate USB profiles than the default CDC USB serial mode such as HID for keyboard emulation.

Boot configurations must be encoded in TLV (Tag-Length-Value) format as specified in appendix M, and formatted according to appendix K.

3.4.10.1 Get Boot Configuration

To query the current state boot configuration, use system command code 0x17 with no parameter bytes. The Tappy will return the response code 0x19 with the boot configuration as a returned payload. Remember that boot configurations are encoded in TLV format.

3.4.10.2 Set Boot Configuration

To set the current state boot configuration, use system command code 0x18 with the parameter bytes (min. 3 bytes) set to the desired boot configuration. Remember that boot configurations are encoded in TLV format according to appendix M and formatted according to appendix K. The response code 0x18 with no payload is returned upon successfully setting the boot configuration.

3.6 Basic NFC Family - Command and Response Syntax

For each of the following commands, there are two parameters to be included, as per figure 7 below.

Figure 7: TapTrack Command Family Syntax for UID & NDEF Detection

The following values for Timeout are supported:

“0x00” : Tells the TappyBLE to poll indefinitely until a stop command is issued.
“0x01 - 0xFF” : Tells the TappyBLE to timeout after this number of seconds. The minimum timeout is one second and the maximum is 255 seconds. The TappyBLE is accurate to within a few seconds.

Should a timeout occur, a response code of 0x03 is returned with no other response data, as shown in Figure 8 below:

Timeout Response.png

Figure 8: Timeout Response

The following values for Tag Type are supported:

“0x01” : Poll for NFC Forum Type 1 Tags (Topaz/Jewel/Innovation)
“0x02” : Poll for NFC Forum Type 2, Type 4A, Mifare Classic tags
All other values are RFU

3.6.1 Stream Tag UID (continuous polling for a UID) - 0x01

To stream a tag’s uid, the command code 0x01 is used with parameters noted above. Should a tag be discovered before a timeout, this is denoted with response code 0x01 and its UID (tag code) is included as response data stream. Refer to figure 9 below. Appendix B contains an enumeration of all possible single byte values and the associated tag types .

Figure 9: Response Structure for Tag UID

3.6.2 Single Tag UID (poll once for a UID) - 0x02

To detect and return a tag’s uid once, the command code 0x02 is used with parameters as per section 3.5. Should a tag be discovered before a timeout, this is denoted with response code 0x01 and its UID (tag code) is included as response data frame.

3.6.3 Stream NDEF Message (continuous polling for NDEF data) - 0x03

To stream a tag’s NDEF message, the command code 0x03 is used with parameters as per section 3.5. Should a tag be detected that does not contain NDEF data, that tag is ignored, its data is not returned. When NDEF data is detected, it’s returned in a structure shown in figure 10 below. Appendix B contains an enumeration of all possible single byte values and the associated tag types .

NDEF Response Structure.png

Figure 10: Response Structure for NDEF data

3.6.4 Single NDEF Message (poll once for an NDEF message) - 0x04

To return a single tag’s NDEF message once only, the command code 0x04 is used with parameters as per section 3.5. Should tag be detected that does not contain NDEF data, that tag is ignored, it’s data is not returned. When NDEF data is detected, it is returned in structure shown in figure 10 above.

3.6.5 Stop - 0x00

The stop command code is 0x00. This command does not take any parameters and sends no response. It is used to stop the current polling operation.

3.6.6 Lock - 0x08

The lock command code is 0x08. This command takes three parameters: timeout, UID length, and UID. The UID parameters are used to restrict the locking procedure so that it only applies to one specific tag. If the Tappy should lock all tags it encounters, the UID length should be set to 0x00 and no UID should be specified. When a tag is locked, The response code is 0x06 and provides three parameters - a single byte tag type (refer to appendix B), UID length, and the UID of the tag that was locked.

3.6.7 Get Basic NFC Command Family Version - 0xFF

The command code 0xFF is used to request the version of the command family. The response to this command is shown below in figure 11.

Figure 11: Response to Get TapTrack Command Family Version Command

3.6.8 Dispatch Tags (polling for both UID and NDEF tags) -0x0C, 0x0F

This streaming tag dispatch command (command code 0x0C) is available on versions 1.4 or later of the basic NFC command family and only on Tappy readers configured for NDEF reading. Tappy firmware versions 0.53 and later included this upgraded basic NFC command family.

This single tag dispatch command (command code 0x0F) is available on versions 1.6 or later of the basic NFC command family and only on Tappy readers configured for NDEF reading. Tappy firmware versions 0.79 and later included this upgraded basic NFC command family.

Tappy readers that have been shipped with only UID reading capability will not support this command.

When issued, the dispatch tags command will set the Tappy to detect any tag and report either the tag’s UID or both a tag’s UID and any NDEF message discovered. Dispatch tags operates both in stream mode (command code 0x0C) and single tag mode (command code 0x0F) . In stream mode tag dispatch will continuously read tags as long as the timeout has not expired, whereas in single mode tag dispatch, the Tappy will return to standby mode after the first tag is detected.

The command codes is 0x0C and 0x0F accept a single parameter byte only, a timeout in seconds. There is no need for the user to specify the tag type for which to poll since both categories of tags are automatically detected using the dispatch tags command:

NFC Forum Type 1 Tags (Topaz/Jewel/Innovation)
NFC Forum Type 2 (includes NTAG and Ultralight) ,
NFC Forum Type 4A (includes DESFire),
Mifare Classic tags

If the detected tag has no NDEF data on it, the response in figure 9 is sent by the Tappy

If the detected tag contains NDEF data, the response in figure 10 is sent by the Tappy.

Upon a timeout, a timeout response as per figure 8 is transmitted.

3.6.9 Detect Tag UID with Tag Restriction (0x0D,0x0E)

Tag restriction is when the Tappy will detect the UID of a certain tag type, or even a specific tag specified by its UID. When using these commands codes, there are 14 parameter bytes:

Byte 0: Tag type restriction mode

0x00: no tag type restriction

0x01: tag type restriction enabled

Byte 1: Tag type code

-as per appendix B, and by convention, 0x00 if tag type restriction is disabled

Byte 2: Tag code length (0x00 to disable tag code restriction)

Byte 3-12: Tag code (padded with 0x00s following the UID if needed)

Byte 13: Timeout as per section 3.5

The command code is 0x0D for single tag and 0x0E to stream tags

The response code is as per figure 10.

3.6.10 Auto Polling Mode

Automatic polling mode is available on version 1.7 of the Basic NFC command family (Tappy firmware version 0.83 or later)

Automatic polling mode is intended for applications which require automated alerts when tags enter and exit the detection field of the Tappy reader. Unlike streaming modes where tags are continuously read, automatic polling mode makes it simple for the host application to determine which NFC tags are present over the Tappy reader by providing a response when a tag exit the field as well as enters it.

3.6.10.1 General Auto Polling Behavior

Automatic polling mode provides messages to inform the host application of tag-entry and tag-exit events. For Mifare, NTAG, and other ISO14443A tags automatic polling can report up to two tags simultaneously. For all other tag types, only one tag can be detected at a time.

When a tag enters the Tappy’s detection range, a response message is sent indicating which tag has entered. When a tag exits the Tappy’s detection range, a response message is sent indicating which tag exited.

3.6.10.2 Auto Polling Timeout

There is no timeout provided by the host application when automatic polling is enabled. In order to stop the auto polling, the host must send data to the Tappy such as a stop command.

3.6.10.3 Auto Polling with Heartbeat Transmission

For added reliability, there is an option to have the Tappy transmit a periodic heartbeat so the host application knows it is still online. Heartbeats take the form of ping frames as described in section 3.4.1.

3.6.10.4 Auto Polling Buzzer Suppression

By default, Tappy variants with a buzzer option (usually USB only) will sound the buzzer briefly for tag entrance and exit events. This can be disabled if desired.

3.6.10.5 Auto Polling Command Format

The command code for automatic polling is 0x10. It has the parameters as seen below.

Figure 12: Automatic Polling Mode Command Parameter Bytes

3.6.10.6 Auto Polling Response Formats

When active, automatic polling mode will produce the following response codes:

0x0C - Tag entrance event
0x0D - Tag exit event

The format of the responses is as seen below:

Figure 13: Response Format for Tag Entry and Exit Events

Depending on the type of tag, the tag metadata returned from the Tappy varies as seen below in figures 14 through 18. The ATS field in figure 14 applies only to NFC Forum Type 4 tags only.

Figure 14: Tag Metadata for Mifare, NTAG, Type 2 ISO14443A tags

Figure 15: Tag Metadata for Type 1/Jewel/Topaz tags

Figure 16: Tag Metadata for ISO 14443-4B tags

Figure 17: Tag Metadata for FeliCa tags

3.6.10.7 NDEF Detection with Auto Polling

On Tappy models featuring NDEF reading capability (all models except those sold as UID readers only), it is possible to combine auto polling behaviour with NDEF reading/discovery. Using the command code 0x11 the Tappy will begin auto polling with all the same features and behaviour of the standard auto polling command however if a tag enters the Tappy detection range that contains NDEF data, the NDEF message will be reported as an “NDEF found” response (see figure 10, section 3.6.3).

3.6.11 TappyTag™ Handshake Commands - Emulated ISO7816 (NFC Forum Type 4) to push data to or from iPhone/Android app via NFC

This feature is only available on firmware versions 1.0 or later, purchased in 2021 or later (if purchased directly from TapTrack, distributors may have older stock). The command code is 0x12 and it takes parameters specified as TLVs. The supported parameters for the TappyTag™ handshake command are:

Scan timeout (optional, default value is no timeout)
Flag to switch to keyboard HID mode (optional, default is to use the current USB profile)
Custom Application Identifier (AID) - max 16 bytes
Custom Response Data (see below) - max 32,767 bytes

Please refer to appendix N for the exact specification of these TLVs.

3.6.11.1 Transmitting Data from an iPhone/Android (or other reader) to The TappyTag™

Success response code is 0x0F with the response payload as data received from the reader (iPhone/Android) during the initial handshake.

3.6.11.2 Transmitting Data from The TappyTag™ to an iPhone/Android (or other reader)

The TappyTag™ Handshake is also capable of optionally transmitting a response dataset after the initial handshake completes. If provided when the TappyTag™ handshake is initiated (using the parameter TLV tag 0x04), the TappyTag(™) handshake procedure makes this data available to the reader (iPhone/Android). This allows up to 32,767 bytes of data transfer.

When the response data is successfully read, the Tappy will send a response code of 0x10 with a payload containing the offset and number of bytes successfully transmitted - encoded as TLV types 0x05 and 0x06. Please refer to appendix N for the exact specification of these TLV response payload types.

3.6.12 Basic NFC Command Errors

Basic NFC application errors occur when there was a properly formatted command that resulted in an application error. It is reported by the Tappy with the hex response code 0x7F (as per figure 5).

3.6.12.1 Basic Nfc Error Codes (Error Code byte)

The error code byte for the TapTrack command family are listed below:

0x01 Invalid parameter
0x02 Reserved for future use
0x03 Polling error
0x04 Too few parameters
0x05 NDEF message is too big to fit on the tag
0x06 Error creating NDEF content
0x07 Error writing NDEF data to tag
0x08 Error locking the tag
0x09 Unsupported command code
0x0A Invalid Tag Restriction Header
0x0B TappyTag™ Handshake Error

3.6.12.2 Error Byte and NFC Status Byte

The error byte and NFC status byte contain advanced diagnostic information relevant to TapTrack engineering support during development. Contact us should some persistent error be occurring, and these bytes will help TapTrack support diagnose the error.

4 Appendix A - Example Source Code for CRC16 Calculation

4.1 Example CRC16 code in C using reversed representation of polynomial

unsigned short update_crc16(unsigned short crc, unsigned char c){

unsigned short i, v, tcrc = 0;

v = (crc ^ c) & 0xff;

for (i = 0; i < 8; i++)

{

tcrc = ( (tcrc ^ v) & 1 ) ? ( tcrc >> 1 ) ^ 0x8408 : tcrc >> 1;

v >>= 1;

}

return ((crc >> 8) ^ tcrc) & 0xffff;

}

unsigned short crc_16(unsigned char *data, unsigned int len){

unsigned int i;

unsigned short crc= 0x6363;

for(i= 0; i < len ; ++i)

crc= update_crc16(crc, data[i]);

return crc;

}

4.2 Example CRC16 in Java using reversed representation of polynomial

private static byte[] calculateCRCBitwise(byte[] data) {

int crc = 0x6363;

for(int i = 0; i < data.length; ++i) {

crc = update_cr16(crc, data[i]);

}

return shortToByteArray((short)crc);

}

private static int update_cr16(int crc, byte b) {

int i, v, tcrc = 0;

v = (int) ((crc ^ b) & 0xff);

for(i = 0; i < 8; i++) {

tcrc = (int) ((( (tcrc ^ v) & 1) != 0) ? (tcrc >> 1) ^ 0x8408 : tcrc >>1);

v >>= 1;

}

return (int) (((crc >> 8) ^ tcrc) & 0xffff);

}

5 Appendix B: NFC Tag Type Definitions

Tag Type Byte	Tag Type Description
0x00	Unknown tag
0x01	Mifare Ultralight
0x02	NTAG 203
0x03	Mifare Ultralight C
0x04	Mifare Classic Standard - 1k
0x05	Mifare Classic Standard - 4k
0x06	Mifare DESFire EV1 2k
0x07	Generic NFC Forum Type 2 tag
0x08	Mifare Plus 2k CL2
0x09	Mifare Plus 4k CL2
0x0A	Mifare Mini
0x0B	Generic NFC Forum Type 4 tag
0x0C	Mifare DESFire EV1 4k
0x0D	Mifare DESFire EV1 8k
0x0E	Mifare DESFire - Unspecified model and capacity
0x0F	Topaz 512
0x10	NTAG 210
0x11	NTAG 212
0x12	NTAG 213
0x13	NTAG 215
0x14	NTAG 216
0x15	NFC Forum Type B*
0x16	NFC Forum Type F (Felicia)*

*firmware v1.0 and later

6 Appendix C : NDEF Writing Command Family Summary

Reference Documents

[1] TapTrack TappyBLE - Command Reference - v4.2 or later

[2] URI Record Type Definition, Technical Specification, NFC Forum, RTD-URI-1.0, NFCForum-TS-RTD_URI_1.0

[3] NFC Data Exchange Format (NDEF), Technical Specification, NFC Forum, NDEF-1.0, NFCForum-TS-NDEF_1.0

Command Family Code

The command family code shall be 0x00,0x01

Command and Response Structure

The “Write URI” command can be used to encode an NDEF message containing a single record that is a URI type (TNF=0x01 for Well Known Type, Type = ‘U’, IL=0 for No ID present). The URI identifier code (protocol prefix byte) parameter is a single byte that indicates the URI’s prefix and shall be specified as per table 3 of [2].

The “Write Text” command can be used to encode an NDEF message containing a single record that is a text type (TNF=0x01 for Well Known Type, Type = ‘T’, IL=0 for No ID present). The language is automatically set to English (“en”). For other languages please use the custom NDEF writing command described below.

NDEF writing commands (URI, text, or custom) are completely stateless and independent operations - meaning that they each encode a new NDEF message rather than append a record to a tag that has previously had a message encoded to it. To encode multi-record messages, the “Write custom NDEF” command must be used.

For general purpose NDEF writing, the ‘write custom record command is used, however in this case the full formatted NDEF record (as specified by [3]) shall be provided. The lock tag flag is a byte that if set to any value other than 0x00 will make the tag read only after writing the NDEF record.

The command and response structure is specified in table C.1 below.

Table C.1: Command codes and Responses

Command	Code	Num. Payload Bytes	Description of Payload in specified order	Description of Response Payload (size)
Write URI / URL record	0x05	3 + n	Timeout* (1) + lock tag flag(1) + uri code(1)**** + URI (n)	Tag type(1)** + UID
Write text record	0x06	2 + n	Timeout* (1) + lock tag flag(1) + text (n)	Tag type(1)** + UID
Write custom message	0x07	2 + n	Timeout* (1) + lock tag flag(1) + NDEF formatted message (n)***	Tag type(1)** + UID

*as per sec.3.5 of [1]

** as per appendix B of [1]

*** NDEF messages must be formatted as specified in [3]

**** URI codes are also known as “URI abbreviation codes” or “protocol prefix bytes”, and are specified in [2]

Table C.2 below specifies the response codes

Table C.2: Response Codes

Description	Resp.Code	Applicable Commands
Write success	0x05	Write URI / URL record, write text record, write custom record
Timeout	0x03	Write URI / URL record, write text record, write custom record

Table C.3 below specifies the possible error codes

Table C.3: Error Codes

Description	Error Code	Applicable Commands
Too few parameters	0x04	Write URI / URL record, write text record, write custom record
NDEF message too big (exceeds the tag’s memory capacity)	0x05	Write URI / URL record, write text record, write custom record
Error creating NDEF content	0x06	Write URI / URL record, write text record, write custom record
Error writing NDEF content to tag	0x07	Write URI / URL record, write text record, write custom record
Error locking the tag after NDEF writing	0x08	Write URI / URL record, write text record, write custom record

7 Appendix D: Mifare Classic Read/Write Command Family

Reference Documents

[1] TapTrack TappyBLE - Command Reference - v4.2 or later

Command Family Code

The command family code for shall be 0x00,0x03

Command and Response Structure

The command and response structure is specified in table D.1 below. The read command that queries data from the tag returns the tag’s UID (Unique Identifier) as well as the data. The read Mifare Classic command assumes that the range of blocks specified use the same key for reading.

Table D.1: Command codes and Responses

Command	Code	Num. Payload Bytes	Description of Payload in specified order	Description of Response Payload (size)
Read Mifare Classic	0x01	10	Timeout* (1) + start block(1) + end block(1) + key setting**(1) + key (6)	UID length (1) + UID(4 or 7) + start block(1) + end block (1) + data (n)
Detect Mifare Classic	0x02	1	Timeout* (1)	Type*** (1) + UID (4 or 7 bytes)

*as per sec.3.5 of [1]

** specify 0x01 for key A, 0x02 for key B, all other values are invalid.

*** 0x04 for 1k tag, 0x05 for 4k tag, all other values are RFU

Table D.2 below specifies the response codes

Table D.2: Response Codes

Description	Resp.Code	Applicable Commands
Read success	0x01	Read Mifare Classic
Mifare Classic tag detected	0x02	Detect Mifare Classic
Timeout	0x03	Read Mifare Classic and Detect Mifare Classic
Command family version	0x04	Get command family version (command code 0xFF)

Table D.3 below specifies the possible error codes

Table D.3: Error Codes

Description	Error Code	Applicable Commands
Invalid Parameter	0x01	All
Too Few Parameters	0x02	All
Too Many Parameters	0x03	All
Polling Error	0x04	Read Mifare Classic and Detect Mifare Classic
Tag Read Error	0x05	Read Mifare Classic
Invalid block order (start block > end block)	0x06	Read Mifare Classic
Authentication Error	0x07	Read Mifare Classic
Invalid Block Number (occurs if the tag is a 1k model and the block requested exceeds 0x3F)	0x08	Read Mifare Classic
Invalid Key Number	0x09	Read Mifare Classic

8 Appendix E: Type 4 ISO-DEP APDU Transceiving Command Family for Host Controlled Reader & Emulation (HCE) mode

Tappy Type 4 (ISO DEP) APDU Transceive Command Family Reference

This command family is meant to give the host application lower level control to transceive data (often called Application Protocol Data Units (APDUs) with NFC targets using the ISO DEP (Data Exchange Protocol), or “Type 4”, or “ISO 14443-4” mode.

This command family can operates in two ways:

Tappy in reader mode where the target is a passive ISO 14443-4 capable NFC tag
Tappy in emulation mode where the target is an active NFC reader (HCE)

To specify the mode of operation, the host applications first issues a detect command for either a passive or active target. Command codes 0x01,0x03,and 0x04 will have the Tappy to detect a passive target where the Tappy is in reader mode. The command code 0x05 will have the Tappy detect active targets where the Tappy is in tag emulation mode, also known as card emulation mode. After a target is detected, the same transceive command (0x02)will work regardless of what type of target was detected. In other words the Tappy manages this on its own so there’s no need for separate transceive commands for active vs passive targets.

Firmware Version Notes

Host controlled reader mode is available on all Tappy readers.
Host controlled emulation is only available on Tappy readers with firmware v 0.89 and later and Type 4 Command Family version 1.3 or later. (released Oct. 2020)

Command Family Code

The command family code for shall be 0x00,0x04

Command and Response Structure

The command and response structure is specified in table E.1 below. The detect command codes 0x01,0x03,and 0x04 initiate RF polling for type 4 capable passive targets and will returns the tag’s UID (Unique Identifier) as well as the card type. Detect command code 0x05 will initiate RF polling for active targets (NFC readers) where the Tappy is in tag emulation mode (HCE emulating a type 4 NFC tag)

Table E.1: Command codes and Responses

Command	Code	Command family	Description of Payload in specified order (length in bytes)	List of possible response codes
Detect Type 4A (ISO DEP capable) tag	0x01	0x00,0x04	Timeout* (1)	0x01,0x03,0x04
Detect Type 4B (ISO DEP capable) tag	0x03	0x00,0x04	Timeout* (1)	0x07,0x03,0x04
Detect Type 4B (ISO DEP capable) tag w/ specified AFI	0x04	0x00,0x04	Timeout* (1), AFI [Application Family Identifier] (1)	0x07,0x03,0x04
Detect active reader target for emulation (initiate HCE mode)	0x05	0x00,0x04	Timeout* (1)	0x01,0x03,0x04 The Tappy uses a SEL_RES value of 0x60 by default. Command 0x09 to specify a custom one.
Detect active reader target for emulation (initiate HCE mode) without requesting initial command	0x06	0x00,0x04	Timeout* (1)	0x01,0x03,0x04 The Tappy uses a SEL_RES value of 0x60 by default. Command 0x09 to specify a custom one.
Transceive APDU	0x02	0x00,0x04	APDU bytes to be sent to tag (n)**	0x02
Get next command from active reader initiator (HCE mode)	0x07	0x00,0x04	None	0x02
Detect active reader target for emulation customized (initiate HCE mode)	0x09	0x00,0x04	Timeout* (1), SEL_RES byte (1), Flag to get first command (1). If the flag is set to 0 the Tappy will not automatically request the first command Common values for SEL_RES are 0x60,0x38,0x78,0x20	0x01,0x03,0x04
Get command family version	0xFF	0x00,0x04	none	0x05

*as per sec.3.5 of [1]

**maximum of 256 bytes can be transmitted with a single transceive command

Table E.2 below specifies the response codes

Table E.2: Response Codes

Description	Resp. Code	Command family	Description of response payload (length in bytes)
Type 4A tag detected	0x01	0x00,0x04	UID Length (1), UID (n), ATS bytes (if the tag provided one). Note: First byte of the returned ATS is the total length of the returned ATS (i.e the number of ATS bytes + 1 for the length byte itself)
APDU transceive successful	0x02	0x00,0x04	Returned bytes from tag (n)
Timeout	0x03	0x00,0x04	None
Polling Error Detected	0x04	0x00,0x04	None
Command family version	0x05	0x00,0x04	Major and minor version (total 2 bytes)
Type 4B tag detected	0x07	0x00,0x04	ATQB response length (1), ATTRIB response length (1), ATQB response (n),ATTRIB response (n)
Active reader target detected	0x08	0x00,0x04	First valid command returned bytes from reader (n)
Active reader target removed from Tappy	0x09	0x00,0x04	None. This is sent when the initiating reader is removed from the Tappy’s antenna range. Once the Tappy is successfully activated as an emulated tag, it will automatically begin sending this response code to notify the host when the reader is removed from the field. The Tappy will continue to send this response until the type 4 command family is used in reader mode (command codes 0x01,0x03,0x04) or a command from any other command family is issued except for a basic NFC stop command.

Table E.3 below specifies the possible error codes

Table E.3: Error Codes

Description	Error Code	Applicable Commands	Comments
Too Few Parameters	0x01	0x01,0x02,0x05,0x06
Too Many Parameters	0x02	0x01,0x02
Transceive Error	0x03	0x02
Invalid Parameter	0x04	0x01,0x03
No targets present	0x05	0x02,0x07	Transceive APDU. This occurs if the Tappy detects that there are no targets activated in its field when a transceive is requested
NFC reader chip error	0x06	0x02,0x07	Occurs when there was an error requesting status information before a transceive command
Request for the initiator’s first command failed	0x07	0x05	Occurs when the active reader is successfully detected by the Tappy but an error occured when the Tappy requested the first command APDU from the active reader. If this is consistently occurring, try using the command code 0x06 to have the Tappy not attempt to get the first command after detecting the active reader. Then, after taking the required action to ready the active reader to respond with an initial command, use the command code 0x07 to request it from the reader. Tip: When using a reader that’s an Android handset in reader mode, some Android models require the app first call .connect on the IsoDep object (presented when onTagDetected is raised) before the first command can be retrieved.

9 Appendix F: NDEF Tag Emulation Command Codes

TappyBLE NDEF Tag Emulation Command Family Reference

Rev 1.0 - 12-Jan-2017

Basic NFC command family version 1.3 and later

Available on Tappy firmware 0.51 and later.

These command codes allow for the Tappy to become an active tag, also known as tag emulation. The Tappy will emulate an NDEF tag using the type 4 tag platform.

Document Release Notes

V1.0: Initial release

Reference Documents

[1] TapTrack TappyBLE - Command Reference - v5.0 or later

[2] URI Record Type Definition, Technical Specification, NFC Forum, RTD-URI-1.0, NFCForum-TS-RTD_URI_1.0

[3] NFC Data Exchange Format (NDEF), Technical Specification, NFC Forum, NDEF-1.0, NFCForum-TS-NDEF_1.0

Command Family Code

The command family code is 0x00,0x01

Command and Response Structure

The command and response structure is specified in table F.1 below. For URI (including URLs) and text record emulation, the Tappy will automatically create the NDEF formatted message. All that is required from the user is the payload (URI or text string). The URI code parameter is a single byte that indicates the URI’s prefix and shall be specified as per table 3 of [2]. When using the text record emulation, the language is automatically set to English (“en”). For other languages please use the custom NDEF emulation command described below.

For emulation of other NDEF types, the emulate custom record command is used (command code 0x0B), however in this case the full formatted NDEF record (as specified by [3]) shall be provided.

The max scans parameter is a byte that if set to any value other than 0x00 will make the Tappy automatically stop the emulation after a given number of successful scans by an external reader.

The timeout parameter is a byte that if set to any value other than 0x00 will make the Tappy automatically stop the emulation after a given number of seconds.

Table F.1: Command codes and Responses

Command	Code	Command family	Description of Payload in specified order (length in bytes)	List of possible response codes
Emulate URI/URL record	0x0A	0x00,0x01	-Timeout* (1) -Max. Scans (1) -URI code**(1) -URI string (n)	0x07,0x08
Emulate text record	0x09	0x00,0x01	-Timeout* (1) -Max. Scans (1) -Text string (n)	0x07,0x08
Emulate custom NDEF	0x0B	0x00,0x01	-Timeout* (1) -Max. Scans (1) -Custom NDEF byte array (n)	0x07,0x08

*as per sec.3.5 of [1]

** as per table 3 of [2]

Table F.2 below specifies the response codes. When tag emulation is invoked using the command codes above, the Tappy sends a response message after each successful scan as well as when the tag emulation has stopped.

Table F.2: Response Codes

Description	Resp.Code	Applicable Commands	Description of response payload (length in bytes)
Emulation scan success by external reader	0x07	All	None
Emulation complete	0x08	All	Reason the emulation stopped (1) (see table F.3), total number of scans by external readers (2).

Table F.3 below specifies the possible values for the single byte representing the reason the emulation has stopped (applies to response code 0x08).

Table F.3: Possible reasons for NDEF emulation to stop

Reason emulation stopped	Code	Applicable Commands	Description
Timeout reached	0x01	All	Sent if the specified timeout has elapsed
Maximum scans reached	0x02	All	Sent if the specified max. scans is reached
New instruction/ TCMP frame received.	0x03	All	Sent if new data or a new command has been received by the Tappy while the emulation was in progress

Table F.4 below specifies the possible error codes

Table F.4: Error Codes

Description	Error Code	Applicable Commands
Invalid parameter	0x01	All
Too few parameters	0x04	All
Error creating NDEF content	0x06	Emulate URI / URL record (0x0A), Emulate text record (0x09)

10 Appendix G: Standalone Checkin Station Command Family Summary

Command Family Code

The command family code for shall be 0x00,0x05

Command and Response Structure

The command and response structure is specified in table G.1 below. .

Table G.1: Command codes and Responses

Command	Code	Command family	Description of Payload in specified order (length in bytes)	List of possible response codes
Get checkins	0x01	0x00,0x05	2 16 bit integers (4 bytes): Byte 0 - first checkin number (MSB) Byte 1 - first checkin number (LSB) Byte 2 - last checkin number (MSB) Byte 3 - last checkin number (LSB)	0x01,0x08
Get number of checkins	0x02	0x00,0x05	None	0x02
Set station id	0x03	0x00,0x05	1 16 bit integer (2 bytes): Byte 0 - station id number (MSB) Byte 1 - station id number (LSB)	0x03
Set station name	0x04	0x00,0x05	Up to 16 bytes. UTF8 encoded station name.	0x04
Read checkin card uid	0x05	0x00,0x05	1 byte: timeout (0x00=no timeout***)	0x05, 0x0C
Reset checkins	0x06	0x00,0x05	None	0x07
Get station info	0x07	0x00,0x05	None	0x06
Set time and date	0x08	0x00,0x05	7 bytes for the time/date to set: Byte 0 - BCD* encoded year (00-99)** Byte 1 - BCD encoded month (1-12) Byte 2 - BCD encoded month day (1-31) Byte 3 - BCD encoded hour (0-24) Byte 4 - BCD encoded minute (0-59) Byte 5 - BCD encoded second (0-59) Byte 6 - BCD encoded day of week (0-6)	0x09
Get time and date	0x09	0x00,0x05	None	0x0A
Get command family version	0xFF	0x00,0x05	None	0x0B

*BCD format: upper nibble = decimal factor of 10, lower nibble = decimal factor of 1.

** assumes the 21st century, leap years are accounted for.

*** sending another instruction will interrupt the TappyBLE when polling for a tag without any timeout

Table G.2 below specifies the response codes

Table G.2: Response Codes

Description	Response Code	Command family	Description of response payload (length in bytes)
Checkin data	0x01	0x00,0x05	Sequential checkin records, each one is 12 bytes: Byte 0 - 6: Tag code Byte 7 - BCD encoded year (00-99) Byte 8 -BCD encoded month (1-12) Byte 9 - BCD encoded month day (1-31) Byte 10 - BCD encoded hour (0-24) Byte 11 -BCD encoded minute (0-59) Note: If more checkins are requested than are stored in the Tappy, only the records that have been recorded are returned.
Number of checkins	0x02	0x00,0x05	4 unsigned bytes representing the number of checkins stored as an unsigned 32 bit integer, transmitted LSB first. Example, 3 checkins available transmitted as payload: 0x03 0x00 0x00 0x00
Station id set	0x03	0x00,0x05	None
Station name set	0x04	0x00,0x05	None
Checkin tag UID	0x05	0x00,0x05	7 bytes: Tag’s UID
Station info	0x06	0x00,0x05	18 bytes Byte 0-1: Station id (unsigned int) Bytes 2-17: Station name in UTF8, padded with 0x00 bytes if required
Checkins reset	0x07	0x00,0x05	None
No checkins to query	0x08	0x00,0x05	None - sent if checkins are requested when none have been logged.
Time and date set	0x09	0x00,0x05	None. After successful completion of this command, the TappyBLE will enter standalone checkin station mode.
Time and date	0x0A	0x00,0x05	7 bytes: Byte 0 - BCD* encoded year (00-99)** Byte 1 - BCD encoded month (1-12) Byte 2 - BCD encoded month day (1-31) Byte 3 - BCD encoded hour (0-24) Byte 4 - BCD encoded minute (0-59) Byte 5 - BCD encoded second (0-59) Byte 6 - BCD encoded day of week (0-6)
Command family version	0x0B	0x00,0x05	2 Bytes: Byte 0: Major version Byte 1: Minor version
Tag detection timed out	0x0C	0x00,0x05	None.
Error	0x7F	0x00,0x05

Table G.3 below specifies the possible error codes

Table G.3: Error Codes

Description	Error Code	Applicable Commands	Comments
Too Few Parameters	0x01	0x01,0x05
Too Many Parameters	0x02	0x01,0x05
Too many checkins to query at once	0x03	0x01
Error programming name	0x04	0x04	Remember that the name is at most 16 bytes (UTF8 chars)
Oscillator error	0x05	0x09,0x0A	Occurs when there was an error reported when getting or setting the time/date
Real time clock error	0x06	0x09,0x0A	Occurs when there was an error reported when getting or setting the time/date
Unknown clock error	0x07	0x09,0x0A	Occurs when there was an unknown error reported when getting or setting the time/date
Unrecognized command code	0x08	-
Invalid parameter	0x09
Problem detecting card	0x0A	0x0C

11 Appendix H: NTAG 21x Password Protected Tag Command Family Summary

Required Firmware Version

The NTAG21x Password Protected Tag command family is available on firmware versions 0.76 or later. Typically fully featured Tappy readers purchased after September 2018 will include this command family.

Command Family Code

The command family code for shall be 0x00,0x06

Command and Response Structure

The command and response structure is specified in table H.1 below. .

Table H.1: Command codes and Responses

Command	Code	Command family	Description of Payload	List of possible response codes
Write Text NDEF w/ password protection	0x01	0x00,0x06	As per figure H.1 w/ content as the text in English	0x03,0x05
Write URI NDEF w/ password protection	0x02	0x00,0x06	As per figure H.1 w/ content as the URI (see note below re: URI codes)	0x03,0x05
Write custom NDEF w/ password protection	0x03	0x00,0x06	As per figure H.1 w/ content as the custom NDEF message starting at the first record header.	0x03,0x05
Read NDEF from password protected tag	0x04	0x00,0x06	As per figure H.3	0x03,0x01
Write Text NDEF w/ password bytes	0x05	0x00,0x06	As per figure H.2 w/ content as the text in English	0x03,0x05
Write URI NDEF w/ password bytes	0x06	0x00,0x06	As per figure H.2 w/ content as the URI (see note below re: URI codes)	0x03,0x05
Write custom NDEF w/ password bytes	0x07	0x00,0x06	As per figure H.2 w/ content as the custom NDEF message starting at the first record header.	0x03,0x05
Read NDEF from password protected tag with provided password bytes	0x08	0x00,0x06	As per figure H.4	0x03,0x01
Get command family version	0xFF	0x00,0x06	None	0x04

Note about URI code abbreviations:

Although URI codes cannot be supplied by the user, the Tappy will automatically apply the four most common codes based on the content provided. If the URL provided as content begins with any of the four prefixes listed below, the Tappy will automatically apply the appropriate URI code to reduce the amount of memory required to store the URL on the tag.

http://
https://
http://www.
https://www.

Figure H.1: Write NTAG21x with password protection - human provided password

Figure H.2: Write NTAG21x with password protection - password bytes provided

Figure H.3: Read NTAG21x with password protection - human provided password

Figure H.4: Read NTAG21x with password protection - password bytes provided

Table H.2 below specifies the response codes

Table H.2: Response Codes

Description	Response Code	Command family	Description of response payload (length in bytes)
Read success	0x01	0x00,0x06	As per figure 10 (identical to resp. code 0x03 of basic NFC command family)
Polling Timeout	0x03	0x00,0x06	None
Command family version	0x04	0x00,0x06	As per figure 11 but with 0x00 0x06 command family
Write success	0x05	0x00,0x06	Tag type as per appendix B (1) + UID (up to 10 bytes)

Table G.3 below specifies the possible error codes

Table G.3: Error Codes

Description	Error Code	Applicable Commands	Comments
Invalid parameter	0x01	All
Polling error	0x02	All
Too few parameters	0x03	All
NDEF message to big to fit on the NFC tag detected	0x04	0x01,0x02,0x03,0x05,0x06,0x07
Error creating NDEF content	0x05	0x01,0x02,0x05,0x06
Error writing NDEF data to tag	0x06	0x01,0x02,0x03,0x05,0x06,0x07
Error setting password on NTAG21x	0x07	0x01,0x02,0x03,0x05,0x06,0x07
Password provided is too short	0x08	0x01,0x02,0x03	Password must be at least four (4) characters
Invalid command code	0x09
Incompatible tag detected	0x0A	All	This command family only works for NTAG21X models.
Error authenticating to the tag with the password	0x0B	All
Error computing password bytes	0x0C	0x01,0x02,0x03	When a human set password is provided, the Tappy performs a key derivation to derive the 4 password and 2 pack bytes required by the NTAG. This error occurs if that process fails.
Password and/or content lengths invalid	0x0D	0x01,0x02,0x03,0x05,0x06,0x07	Occurs when the length bytes passed for the password and/or content don’t match the length of the overall command.
Error reading NDEF message from tag	0x0E	0x04,0x08

12 Appendix J: ST Micro M24SR02 Configuration Command Family Summary

Required Firmware Version

Tappy readers with firmware 0.79 or later support this command family.

Command Family Code

The command family code for shall be 0x00,0x08

Reference Documents

[1] TapTrack Tappy Command Reference (this document)

[2] NFC Data Exchange Format (NDEF), Technical Specification, NFC Forum, NDEF-1.0, NFCForum-TS-NDEF_1.0

Command and Response Structure

The command and response structure is specified in table J.1 below. .

Table J.1: Command codes and Responses

Command	Code	Command family	Description of Payload	Required current password	List of possible response codes
Change read NDEF password	0x01	0x00,0x08	As per figure J.2	Write password	0x01,0x02,0x03
Change write NDEF password	0x02	0x00,0x08	As per figure J.2	Write password	0x01,0x02,0x04
Password lock NDEF write access	0x03	0x00,0x08	As per figure J.1	Write password	0x01,0x02,0x05
Password lock NDEF read access	0x04	0x00,0x08	As per figure J.1	Write password	0x01,0x02,0x06
Unlock password NDEF write access	0x05	0x00,0x08	As per figure J.1	Write password	0x01,0x02,0x07
Unlock password NDEF read access	0x06	0x00,0x08	As per figure J.1	Write password	0x01,0x02,0x08
Get I2C protection setting	0x07	0x00,0x08	Timeout byte	-	0x01,0x02,0x09
Read password protected NDEF message	0x08	0x00,0x08	As per figure J.1	Read password	0x01,0x02,0x0A
Write password protected NDEF message	0x09	0x00,0x08	As per figure J.3, NDEF message as per [2], starting with the record header	Write password	0x01,0x02,0x0B
Permanently lock NDEF write access	0x0A	0x00,0x08	As per figure J.1	Write password	0x01,0x02,0x0C
Get command family version	0xFE	0x00,0x08	None	-	0x01,0x02,0xFF

Figure J.1: Parameter payload with single 16 byte password

Figure J.2: Parameter payload with two 16 byte passwords

Figure J.3: Parameter payload for write password protected NDEF message

Table J.2 below specifies the response codes

Table J.2: Response Codes

Description	Response Code	Command family	Description of response payload (length in bytes)
Polling Timeout	0x01	0x00,0x08	None
Type 4 (ISO 7816) Error	0x02	0x00,0x08	Status words SW1, SW2 (2)
Change read NDEF password success	0x03	0x00,0x08	Figure J.4
Change write NDEF password success	0x04	0x00,0x08	Figure J.4
Password lock NDEF write success	0x05	0x00,0x08	Figure J.4
Password lock NDEF read success	0x06	0x00,0x08	Figure J.4
Password unlock NDEF write success	0x07	0x00,0x08	Figure J.4
Password unlock NDEF read success	0x08	0x00,0x08	Figure J.4
I2C protection setting	0x09	0x00,0x08	Figure J.5
Found NDEF message	0x0A	0x00,0x08	Figure J.6
NDEF message successfully written	0x0B	0x00,0x08	Figure J.4
Permanent NDEF write lock success	0x0C	0x00,0x08	Figure J.4
Command family version	0xFF	0x00,0x08	As per figure 11 of [1] but with 0x00,0x08 as the command family

Figure J.4: Response payload structure, only UID returned

Figure J.5: Response payload structure for Get I2C PROTEC setting

Figure J.6: Response payload structure for Read Password Protected NDEF message

Table J.3 below specifies the possible error codes

Table J.3: Error Codes

Description	Error Code	Applicable Commands	Comments
Too few parameters	0x01	All
Polling error	0x02	All
Invalid command code	0x03
Physical communication error	0x04	All	Occurs when a physical error has occurred when communicating with the NFC tag, such a timeout waiting for the tag to respond.
Tag not NDEF formatted	0x05	All
Tag not NDEF writable	0x06	0x09
NDEF length invalid	0x07	0x09	Occurs when the length bytes passed for the NDEF message don’t match the length of the overall command.
Unrecognized NDEF mapping version	0x08	0x09
NDEF message too big	0x09	0x08,0x09	When writing an NDEF message, this occurs if the size of the message exceeds the maximum NDEF size the tag can support. When reading an NDEF message, this occurs if the length bytes read from the tag represent a length unsupported by the tag.
Unknown error when reading NDEF message	0x0A	0x08

13 Appendix K: Tappy Boot Configuration Usage (v1.0+)

As of firmware v1.0 and later (roughly 2021 onwards), the Tappy features a user configurable boot configuration whereby one can set persistent (non volatile) boot configuration the Tappy will read upon bootup. Please refer to the boot configuration application note for more details.

Shown below in table K.1 are the various boot configuration TLV types.

Table K.1 - Boot Configuration TLV Types

Name	Type Value	Value Usage / Description
Startup USB profile (v1.3+)	0x01	Used to specify an alternate USB profile to use upon bootup. The default is the CDC (USB serial port) profile, but users can specify alternates as follows: 0x01 - No USB profile 0x02 - CDC profile (USB serial port) 0x03 - RFU 0x04 - Native USB profile (raw bulk transfer) 0x05 - HID profile (keyboard emulation / wedge)
Keyboard emulator prefix (v1.3+)	0x02	The keystrokes to emulate as a prefix before NFC data is outputted as keystrokes. Specified as UTF8 characters.
Keyboard emulator suffix / postfix (v1.3+)	0x03	The keystrokes to emulate as a suffix after NFC data is outputted as keystrokes. Specified as UTF8 characters. Often a carriage return/line feed is appropriate in which case this is specified as 0x0D,0x0A.
Keyboard emulator NFC UID (tag code) hex delimiter sequence (v1.3+)	0x04	The keystrokes to emulate as a delimiter sequence when entering NFC tag UIDs (tag codes) as keystrokes. Specified as UTF8 characters, this is what the user wants to enter between hex elements of the UID. For example, a colon (:) is often used to improve readability or to comply with the desired entry format of the keyboard data. Specified as 0x3A, a colon delimiter will format a UID output as the following example illustrates: 04:58:4F:7E:65:3D:81
RFU	0x05	RFU
Startup command	0x06	Used to specify a startup command the user wants to run immediately upon bootup. This can be used to implement a standalone mode or ensure that a certain runtime configuration of the Tappy is immediately set upon bootup without relying on the host device to do so upon connecting. The format of the command is specified as an unframed TCMP command as follows: Command family: byte numbers 0,1 Command code: byte number 2 Command payload: byte numbers 3 onwards
Keyboard emulator mode (v1.3+)	0x07	Used to specify an alternate keyboard emulator configuration.The default is to read NDEF data and output payload data as keystrokes, but users can specify alternates as follows: 0x01 - Output Keystrokes of Tag Codes (UIDs) only 0x02 - Output Keystrokes of NDEF payloads. Note that text records are handled without outputting the language code. The Tappy keyboard emulator does support international characters. To enable accented and other international character support on your platform please refer to the steps in this application note.
Keyboard emulator tag type to scan for (v1.3+)	0x08	Used to specify an alternate NFC tag technology to scan for when using the TappyUSB keyboard emulator mode. The default is to scan for Mifare/NTAG/Type 2 NFC tags, but users can specify alternates as follows: 0x00 - Mifare/NTAG/Type 2 (default) 0x01 - Type 1/Jewel/Topaz 0x02 - Type ISO 14443-4B (supports only UIDs) 0x03 - Felicia (supports only UIDs) 0x04 - Type ISO 14443-4A (ISO-DEP) 0x05 - Scan for all
Periodic (background) command configuration (v1.4+)	0x09	Used to specify a set of Tappy commands that should be performed periodically even without any host command instruction. Periodic commands are automatically scheduled at the interval specified. This may be used to accomplish a number of use cases such as: -a standalone reader mode that is set to broadcast NFC tag data automatically upon tag detection -sending periodic pings automatically so the host application can monitor the application level connection status passively. The Tappy can schedule up to 16 periodically executed commands each at its own specified interval. To specify a command and interval, use this tag (0x09), and include in the value field two nested TLVs as follows: -TLV specifying the period as tag 0x0A -TLV specifying the periodic command as tag 0x0B
Periodic command period (v1.4+)	0x0A	Specifies the period (interval) of a periodic command. The value shall be encoded as a four (4) byte unsigned integer representing the number of seconds.
Period command (v1.4+)	0x0B	Specifies the periodic command as an unframed TCMP command as follows: -Command family: byte numbers 0,1 -Command code: byte number 2 -Command payload: byte numbers 3 onwards

14 Appendix M: Tag Length Value (TLV) Encoding Format (v1.0+)

As of firmware v1.0 and later (roughly 2021 onwards), new Tappy commands and features may use Tag-Length-Value (TLV) encoded data as parameters. This allows a more flexible and robust means of passing customization parameters to the Tappy. The details of this are specified here however in practice these details will be handled by the platform specific SDK which will be updated to compose and parse TLV data.

M.1 TLV Format

M.1.1 Type Field

The type value is generally a 0x01->0xFE single byte corresponding to the type of the value. 0x00 and 0xFF are special values with 0x00 corresponding to a special NULL TLV that has no length or value fields. The NULL TLV should not be used for transaction signing. If 0xFF is used, this indicates that a two byte type is in use, which will follow the 0xFF. Legal values for the two-byte TLV are 0x00FF->0xFEFF. All values from 0x0000 to 0x00FE are not legal and should be represented using the single-byte type format. 0xFF00->0xFFFF are reserved for future use in extending the protocol (RFU).

M.1.2 Length Field

Similarly to the Type field specified in 4.1.1, the length field is generally a single byte 0x00-0xFE, corresponding to the number of bytes in the value field. Unlike the Type field, the length 0x00 does not have a special meaning and merely indicates that the value is of zero length. This is a legal situation if the mere presence of the TLV is all that is needed to transmit the information it represents. If the value is longer than 0xFE (254) bytes, a two-byte length is in use. Similar to the Type field, the length field is set to 0xFF to indicate a two-byte type followed by a value of 0x00FF->0xFEFF. Values from 0x0000 to 0x00FE are not legal and should be represented using the single-byte length format. Values from 0xFF00 to 0xFFFF are reserved for future use in extending the protocol.

M.1.3 Value Field

The value field’s format and content varies depending on the type of TLV, but can currently be anything from 0-65,279 bytes.

M.2 TLV Types

The main index of TLVs is shown below in table M.1 where you will find a list of all the categories of TLVs and where you can find more detailed specifications of these.

Table M.1 - TLV Type Main Index

Name	Refer to Section	Comment
Boot configuration TLVs	Appendix K	These are used to specify a boot configuration for the Tappy. To Read and Write this boot configuration refer to section 3.4.10 .
Command parameter TLVs	Appendix N	Used in TappyTag handshake and other commands introduced in v1.0 firmware.

15 Appendix N: Command/Response Parameter TLV Types

As of firmware v1.0 and later (roughly 2021 onwards), the Tappy may use TLV encoding to specify command and response parameters. Shown below in table N.1 are the various command and response parameter TLV types.

Table N.1 - Command Parameter TLV Types

Name	Type Value	Value Usage / Description
Scan / NFC polling timeout	0x01	Used to specify a scan timeout value in seconds as a single unsigned byte. Specifying 0 indicates no timeout (indefinite polling)
TappyTag™ custom AID (Application Identifier)	0x02	A custom AID (Application Identifier) to use when initiating the TappyTag™ handshake.. This shall have a value no greater than 16 bytes.
Flag to indicate that the TappyTag™ initiate handshake command should switch to keyboard emulation mode	0x03	This will configure the Tappy to output any data received from a reader (often an iPhone or Android) during a TappyTag™ emulated data handshake as keystrokes. When provided, this TLV will have the TappyTag™ handshake ignore any scan timeout and from thereafter be in a standalone mode that will enter all received data as keystrokes. The TLV can have a zero length value and still have the effect of setting the flag
TappyTag™ custom response data	0x04	Custom response data that can be sent back to the reader (i.e iPhone/Android device) after a TappyTag™ initial handshake success. The maximum size of this data is 32,767 bytes.
TappyTag™ response data acknowledgement - offset	0x05	When TappyTag™ custom response data is successfully transmitted, the Tappy will send a response message as an acknowledgement back to the host, and will include this TLV type to indicate the offset from which the bytes were read by the reader.
TappyTag™ response data acknowledgement - length	0x06	When TappyTag™ custom response data is successfully transmitted, the Tappy will send a response message as an acknowledgement back to the host, and will include this TLV type to indicate the number of bytes successfully transmitted.
TappyTag™ data received during handshake initiation	0x07	This TLV type indicates initial data when the TappyTag™ handshake is successfully initiated. The initiating device (iPhone/Android or other reader) will transmit an initial dataset encoded in the response using this TLV type.
RFU	All other values	RFU

of | Page

TapTrack Tappy ∘ Command Reference May 5th, 2022

​1​ General Overview

​1.1​ What is the TappyUSB and TappyBLE?

​1.2​ Bluetooth Low Energy

1.3 Keyboard Emulation (Wedge) with true Human Input Device (HID) Profile

​2​ Tappy Communication Messaging Protocol (TCMP)

​2.1​ Basic Framing Convention

​2.2​ Start / End of Frame

​2.3​ Escape Sequences

​2.4​ Length Bytes

​2.5​ Length Checksum (LCS) byte

​2.6​ Command Family (CF) bytes

​2.7​ CRC bytes

​3​ Tappy Command Families

​3.1​ Command Structure

​3.2​ Response Structure

​3.3​ Error Messages

​3.3.1​ System Communication Errors (Command Family 0x00,0x00)

​3.3.2​ System Application Errors (Command Family 0x00,0x00)

​3.3.2.1​ System Application Error Codes (Error Code byte)

​3.4​ Tappy System Family - Command and Response Syntax

​3.4.1​ Housekeeping Commands

​3.4.2​ Set Tappy Configuration Settings - System command code 0x01

​3.4.2.1​ Type 2 Tag Identification - setting 0x01

​3.4.2.2​ Enable Data Throttling for slower BLE devices - setting 0x02

​3.4.2.3​ Enable dual Type 1 (Topaz.Jewel)/Mifare detection on NDEF write - setting 0x03

​3.4.2.4​ Set Audible Buzzer Duration for Successful Scans - setting 0x05

​3.4.2.5​ Set Green LED Duration for Successful Scans - setting 0x06

​3.4.2.6​ Set Red LED Duration for Failed Scans - setting 0x07

​3.4.2.7​ Enable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x08

​3.4.2.8​ Disable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x09

​3.4.2.9​ Disable Blue Light Flashing During Tag Polling - setting 0x0A

​3.4.2.10​ Re-enable Blue Light Flashing During Tag Polling - setting 0x0B

​3.4.2.11​ Clear Bluetooth Gatt Bonding Cache (TappyBLE only) - setting 0x0C

​3.4.3​ Battery Level Command (TappyBLE only)

​3.4.4​ Output Test Frames

​3.4.5​ Output Test Frame of Specified Size

​3.4.6​ Get Clock Status

​3.4.7​ Configure On-Board Cooldown Period for Automatic Scan Filtering

​3.4.7.1​ Configure Onboard Cooldown for Scan Filtering

​3.4.7.2​ Set Cooldown Timeout Period

​3.4.8​ System Commands supported in Kiosk (Heartbeat) and Keyboard Wedge Tappy Configurations (TappyBLE only)

​3.4.8.1​ Configure Kiosk and Keyboard Wedge Mode

​3.4.8.2​ Disable Heartbeat Transmission from Host

​3.4.8.3​ Host Application Light (LED) Control When in Kiosk Heartbeat Mode

​3.4.9​ LEDs and Buzzer Commands for Host Controlled Visible/Audible Feedback

​3.4.9.1​ Query Status of Audible and Visible Indicators

​3.4.9.2​ Important note about host controlled LED operation

​3.4.10​ Boot Configuration Commands

​3.4.10.1​ Get Boot Configuration

​3.4.10.2​ Set Boot Configuration

​3.6​ Basic NFC Family - Command and Response Syntax

​3.6.1​ Stream Tag UID (continuous polling for a UID) - 0x01

​3.6.2​ Single Tag UID (poll once for a UID) - 0x02

​3.6.3​ Stream NDEF Message (continuous polling for NDEF data) - 0x03

​3.6.4​ Single NDEF Message (poll once for an NDEF message) - 0x04

​3.6.5​ Stop - 0x00

​3.6.6​ Lock - 0x08

​3.6.7​ Get Basic NFC Command Family Version - 0xFF

​3.6.8​ Dispatch Tags (polling for both UID and NDEF tags) -0x0C, 0x0F

​3.6.9​ Detect Tag UID with Tag Restriction (0x0D,0x0E)

​3.6.10​ Auto Polling Mode

​3.6.10.1​ General Auto Polling Behavior

​3.6.10.2​ Auto Polling Timeout

​3.6.10.3​ Auto Polling with Heartbeat Transmission

​3.6.10.4​ Auto Polling Buzzer Suppression

​3.6.10.5​ Auto Polling Command Format

​3.6.10.6​ Auto Polling Response Formats

​3.6.10.7​ NDEF Detection with Auto Polling

​3.6.11​ TappyTag™ Handshake Commands - Emulated ISO7816 (NFC Forum Type 4) to push data to or from iPhone/Android app via NFC

​3.6.11.1​ Transmitting Data from an iPhone/Android (or other reader) to The TappyTag™

​3.6.11.2​ Transmitting Data from The TappyTag™ to an iPhone/Android (or other reader)

​3.6.12​ Basic NFC Command Errors

​3.6.12.1​ Basic Nfc Error Codes (Error Code byte)

​3.6.12.2​ Error Byte and NFC Status Byte

​4​ Appendix A - Example Source Code for CRC16 Calculation

​4.1​ Example CRC16 code in C using reversed representation of polynomial

​4.2​ Example CRC16 in Java using reversed representation of polynomial

​5​ Appendix B: NFC Tag Type Definitions

​6​ Appendix C : NDEF Writing Command Family Summary

​7​ Appendix D: Mifare Classic Read/Write Command Family

1 General Overview

1.1 What is the TappyUSB and TappyBLE?

1.2 Bluetooth Low Energy

2 Tappy Communication Messaging Protocol (TCMP)

2.1 Basic Framing Convention

2.2 Start / End of Frame

2.3 Escape Sequences

2.4 Length Bytes

2.5 Length Checksum (LCS) byte

2.6 Command Family (CF) bytes

2.7 CRC bytes

3 Tappy Command Families

3.1 Command Structure

3.2 Response Structure

3.3 Error Messages

3.3.1 System Communication Errors (Command Family 0x00,0x00)

3.3.2 System Application Errors (Command Family 0x00,0x00)

3.3.2.1 System Application Error Codes (Error Code byte)

3.4 Tappy System Family - Command and Response Syntax

3.4.1 Housekeeping Commands

3.4.2 Set Tappy Configuration Settings - System command code 0x01

3.4.2.1 Type 2 Tag Identification - setting 0x01

3.4.2.2 Enable Data Throttling for slower BLE devices - setting 0x02

3.4.2.3 Enable dual Type 1 (Topaz.Jewel)/Mifare detection on NDEF write - setting 0x03

3.4.2.4 Set Audible Buzzer Duration for Successful Scans - setting 0x05

3.4.2.5 Set Green LED Duration for Successful Scans - setting 0x06

3.4.2.6 Set Red LED Duration for Failed Scans - setting 0x07

3.4.2.7 Enable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x08

3.4.2.8 Disable Secure Bluetooth PIN Pairing (TappyBLE only) - setting 0x09

3.4.2.9 Disable Blue Light Flashing During Tag Polling - setting 0x0A

3.4.2.10 Re-enable Blue Light Flashing During Tag Polling - setting 0x0B

3.4.2.11 Clear Bluetooth Gatt Bonding Cache (TappyBLE only) - setting 0x0C

3.4.3 Battery Level Command (TappyBLE only)

3.4.4 Output Test Frames

3.4.5 Output Test Frame of Specified Size

3.4.6 Get Clock Status

3.4.7 Configure On-Board Cooldown Period for Automatic Scan Filtering

3.4.7.1 Configure Onboard Cooldown for Scan Filtering

3.4.7.2 Set Cooldown Timeout Period

3.4.8 System Commands supported in Kiosk (Heartbeat) and Keyboard Wedge Tappy Configurations (TappyBLE only)

3.4.8.1 Configure Kiosk and Keyboard Wedge Mode

3.4.8.2 Disable Heartbeat Transmission from Host

3.4.8.3 Host Application Light (LED) Control When in Kiosk Heartbeat Mode

3.4.9 LEDs and Buzzer Commands for Host Controlled Visible/Audible Feedback

3.4.9.1 Query Status of Audible and Visible Indicators

3.4.9.2 Important note about host controlled LED operation

3.4.10 Boot Configuration Commands

3.4.10.1 Get Boot Configuration

3.4.10.2 Set Boot Configuration

3.6 Basic NFC Family - Command and Response Syntax

3.6.1 Stream Tag UID (continuous polling for a UID) - 0x01

3.6.2 Single Tag UID (poll once for a UID) - 0x02

3.6.3 Stream NDEF Message (continuous polling for NDEF data) - 0x03

3.6.4 Single NDEF Message (poll once for an NDEF message) - 0x04

3.6.5 Stop - 0x00

3.6.6 Lock - 0x08

3.6.7 Get Basic NFC Command Family Version - 0xFF

3.6.8 Dispatch Tags (polling for both UID and NDEF tags) -0x0C, 0x0F

3.6.9 Detect Tag UID with Tag Restriction (0x0D,0x0E)

3.6.10 Auto Polling Mode

3.6.10.1 General Auto Polling Behavior

3.6.10.2 Auto Polling Timeout

3.6.10.3 Auto Polling with Heartbeat Transmission

3.6.10.4 Auto Polling Buzzer Suppression

3.6.10.5 Auto Polling Command Format

3.6.10.6 Auto Polling Response Formats

3.6.10.7 NDEF Detection with Auto Polling

3.6.11 TappyTag™ Handshake Commands - Emulated ISO7816 (NFC Forum Type 4) to push data to or from iPhone/Android app via NFC

3.6.11.1 Transmitting Data from an iPhone/Android (or other reader) to The TappyTag™

3.6.11.2 Transmitting Data from The TappyTag™ to an iPhone/Android (or other reader)

3.6.12 Basic NFC Command Errors

3.6.12.1 Basic Nfc Error Codes (Error Code byte)

3.6.12.2 Error Byte and NFC Status Byte

4 Appendix A - Example Source Code for CRC16 Calculation

4.1 Example CRC16 code in C using reversed representation of polynomial

4.2 Example CRC16 in Java using reversed representation of polynomial

5 Appendix B: NFC Tag Type Definitions

6 Appendix C : NDEF Writing Command Family Summary

7 Appendix D: Mifare Classic Read/Write Command Family

8 Appendix E: Type 4 ISO-DEP APDU Transceiving Command Family for Host Controlled Reader & Emulation (HCE) mode