Tag Entry/Exit Protocol

When a recipe has tag entry/exit mode, the first reader in the recipe keeps track of all the tags that match the recipe (that is, tags whose angles fit the recipe's angle range). The reader uses the entry/exit protocol to send messages to the remote device so that it can keep track of this set of tags too. This section defines the protocol in a form suitable for implementation.

For actual protocol code, see Tag Entry/Exit Server Protocol Source Code.

Transport and Session Layers

The entry/exit protocol uses TCP. The reader is responsible for making connections to the remote device (using the IP address and port number specified in the recipe), monitoring the status of the session, and re-establishing it if necessary.

Recipe Multiplexing

A reader multiplexes each recipe into one protocol stream if:

  • It is the first reader in more than one recipe.
  • All recipes have different ID pairs.
  • Each recipe has the same remote device IP address and port number.

The reader uses the entry/exit protocol to send messages to the remote device so that it can track the set of tags that is in each recipe.

Protocol Format

The entry/exit protocol is guaranteed to fit every message into a 256-byte array, so it can be implemented easily without requiring a big buffer. All messages have the same format:

  • Size: Three ASCII characters representing the length of the whole message in bytes (in decimal).
  • Type: One ASCII characters representing the message type (in decimal).
  • Id 1: Optionally, five ASCII characters representing the recipe's Id 1 (in decimal).
  • Id 2: Optionally, five ASCII characters representing the recipe's Id 2 (in decimal).
  • Tags: Between zero and fifteen blocks of sixteen ASCII characters, each block representing a 64bit tag id (in hex).
  • End: A terminating zero byte.

Protocol Message Types

There are only six entry/exit protocol message type codes:

  • 0: EXIT is sent when any tag stops matching the recipe, and includes the id of the tag that stops matching the recipe.
  • 1: ENTRY is sent when any tag matches the recipe, and includes the id of the newly-matching tag.
  • 2: KEEPALIVE is sent about every 10 seconds, and at the end of a session dump.
  • 3: COMM_START is sent once only at the start of each new session just before a session dump.
  • 4: STOP may be sent at the end of a session.
  • 5: ACK is sent by the remote device to acknowledge each message.

All message types have the Size, Type, and End message parts. But only EXIT and ENTRY message types have the Id 1, Id 2 and Tags parts.

EXIT Messages

An EXIT message communicates that the tags in its Tags section no longer match the recipe identified by its Id 1, Id 2 sections.

ENTRY Messages

An ENTRY message communicates that the tags in its Tags section now match the recipe identified by its Id 1, Id 2 sections.

KEEPALIVE Messages

A KEEPALIVE message communicates that the remote device has received up-to-date information completely characterizing the recipe-tag matching relationship for each of the recipes being multiplexed down the current protocol stream.

COMM_START Messages and Session Dumps

A COMM_START message is only sent at the start of a session. It warns the remote device that its current state may be invalid and that the reader is about to send messages to establish the new valid state.

After a COMM_START message, there is a session dump made up of a sequence of ENTRY and EXIT messages, followed immediately by a KEEPALIVE message that indicates that the session dump has been completed.

The ENTRY messages communicate the set of tags currently matching each recipe. If a recipe has more than 15 matching tags in a set, that recipe will have more than one ENTRY message.

An EXIT message is used for any recipe that does not have any matching tags, so that the remote device can be shown that the recipe is 'empty'.

Finally, the KEEPALIVE message terminates the session dump.

STOP Messages

When the reader wants to shutdown a connection, it sends a STOP message to enable the remote device to clean up any connection state. No remote behavior is compulsory, aside from subsequently at some point being able to accept a new connection.

ACK Messages

An ACK message is sent by the remote device to communicate that it has successfully received the previously-sent message.