Using TCMP

Overview

The Tappy Command Messaging Protocol (TCMP) is the communication protocol used to tell a TappyBLE what to do, as well as get responses back from the Tappy. The TCMP protocol defines a method of transmission as well as separating all commands into Command Families. The details of the transmission protocol and the format of commands are not going to be covered here as the SDK handles those details, but a full specification is here.

Command Families

Tappy Commands are grouped into families based off of their function. Command families are specified by a two-byte command family identifier. Within the command family, a single byte command/response code is used for identifying specific commands or responses. Note that command ids and response ids are independent -- thus, it is possible for a command family to specify command and response codes that overlap. Therefore, in order to correctly interpret a TCMP message, one must know whether the TCMP message is a command set to the Tappy or a response from the Tappy. Several built-in command families are described below; however, this specification is here for convenience and may be out of date relative to the official specification available from TapTrack directly.

Command Family Resolution

Each command family is independent and there is no need to make use of command families your application does not care about. In order to resolve a command you have received, you should first must construct a RawTCMPMessage from the byte array and then make use of a CommandFamilyResolver to resolve it to a specific command type. By default, a CommandFamilyResolver does not have knowledge of any command families, so you must register an instance of CommandFamily corresponding to each command family your application cares about.

CommandFamilyMessageResolver resolver = new CommandFamilyMessageResolver();
{
    resolver.registerCommandLibrary(new SystemLibrary());
    resolver.registerCommandLibrary(new BasicNfcLibrary());
    // etc
}
public TCMPMessage resolveCommand(TCMPMessage message) throws FamilyCodeNotSupported, 
        CommandCodeNotSupportedException,MalformedPayloadException {
    return resolver.resolveCommand(message);
}
public TCMPMessage resolveResponse(TCMPMessage message) throws FamilyCodeNotSupported, 
        ResponseCodeNotSupportedException,MalformedPayloadException {
    return resolver.resolveResponse(message);
}

Note that you must call the appropriate resolve function as command codes and response codes are allowed to overlap. Additionally, CommandFamilyMessageResolver is threadsafe, so feel free to share one instance throughout your application.

Universal Commands

There are a couple of commands and responses supported by all families.

Application-error

Some sort of error occurred in command family-specific operation, all use the same format with an error code, error byte (0x7F), NFC controller status, and an optional English description of the error in ASCII. The error code is generally sufficient for determining the problem, the additional bytes are primarily used for internal debugging.

Family version

Requests the version of the command family supported by this Tappy. A command family version contains a single byte major version and a single byte minor version. Note that the system command family does not support a command that requests its version. The system firmware version is intended to determine the features of the system command family.

Framing Errors

Framing errors are not reported in the same fashion as application errors. These errors are reported under the system command family however indicate the Tappy has detected a framing level error in the received frame. Unlike application errors, framing errors don't use the response code 0x7F but rather one that indicates the error as listed below. There are no payload bytes included in framing errors.