Home / Downloads / Software / Texmate Data Server /

Documentation

Texmate Tiger Transfer Protocol (TTP) Specification

The Tiger Transfer Protocol (TTP) is a simple text based protocol accessed over TCP/IP. It was designed for small message size for GPRS and other wireless pay-per-byte networks, and runs happily over a regular LAN or Internet connection from any device. TTP was originally conceived (and based on) a highly stripped down version of standard HTTP to meet the low payload requirements outlined above. TTP is a single line request-response protocol because of this.

By Default TCP/IP Connections remain open. That is the Data Server does not close the TCP/IP socket once it sends a response to a request. Rather, the socket is left open for further communications thus saving TCP/IP byte overhead and therefore bandwith cost for mobile network usage scenarios. You can change this default in the Server Configuration File. So it is up to the Connected Device (Usually a Texmate Tiger Controller) to close the socket it opened when it is no longer needed.

Examples

A few simple examples of the protocol are given below as an introduction to the protocol and how it works.

Upload some data from a Tiger controller:
TTP /up/unitcode/<2009-1-16 15:30:45;11;22;33;44> unitkey
response:
OK

Download the last posted data sample from a Tiger controller:
TTP /dl/unitcode/last unitkey
response:
OK <123 2009-01-16 15:30:45 11 22 33 44>

Note: By default the download of data will not include channel labels. You can include these labels in the download (edit the unit details in the administration panel) in which case your download might look something like this:
OK <123 2009-01-16 15:30:45 CH1=11 CH2=22 CH3=33 CH4=44>

Transmission terminators

Each transmission, both request and response, terminates with a single ASCII Carriage Return (CR) character.

You can send a Line Feed (LF) character after the Carriage Return transmission terminator which will allows you to use Terminal programs such as PuTTY on Windows for convenient testing purposes (these programs tend to send a CR/LF combo when the Enter/Return key is pressed). The resulting Line Feed is ignored as the request was deemed finished and processing started after the Carriage Return was received.

TTP Commands

Currently, there are five* included commands in TTP:

  1. Upload a timestamped packet of numeric data samples for a particular Unit.
  2. Download the last sample uploaded for a given Unit. For an explanation of Units see the Installation Guide.
  3. Send email messages from a particular unit to a pre-defined list of recipients.
  4. Send pre-defined alarm messages (via email) from a particular unit to a pre-defined list of recipients.
  5. Check the connection details of the unit and the server.

*See the Data Server App Guide for details on adding new TTP commands to your server.

The five included TTP commands are detailed as below:

  1. Upload data:
    TTP /up/unitcode/<timestamp;value;value;value;value> unitkey

    1. Multiple sample upload in a single request (all on a single line this example is wrapped for readability):
      TTP /up/unitcode/<timestamp;value;value;value;value><timestamp;value;value;value;value> unitkey
      No hard limit is set for the number of data packets (enclosed by < & >) that can be sent in a single request. Practically you will want to sort out how many samples you want to upload at a time versus the frequency of sending the samples to work out what is best for your application.

    A simple response is sent by the Data Server if the sample(s) was accepted: OK. If the request failed for any reason, then see the Error Codes and Responses section for responses and their meanings taking note of the 406 Duplicate Sample error response - uploaded samples must be unique according to their timestamp and unitcode combination.

    The number of values you need to place in the Data Packet (or sample) sent depends on the configuration for that particular Unit identified by unitcode.

  2. Download the last sample for a given Unit:
    TTP /dl/unitcode/last unitkey

    Downloading data receives the same error responses as the upload command. If successful, the response format is detailed as follows. There are two formats for returning the last data sample for a unit, the default is shown first:

    1. OK <sampleid timestamp value1 value2 value3 value4>
    2. OK <sampleid timestamp label1=value1 label2=value2 label3=value3 label4=value4>

    Notes:

    1. sampleid is a globally unique Integer ID assigned to each data sample. It is a chronological record of all samples stored. E.g. if sampleid is 26540 this denotes you are receiving sample #26540 in the store of all data samples. This is not sample #26450 sent by the Unit identified by unitcode, but sample #26540 of all samples sent by all Units - so it is guaranteed unique.
    2. Timestamps are returned as per the specification (YYYY-MM-DD HH:MM:SS[.microseconds]) with leading zeros, ie: 2009-01-16 15:30:45. Microseconds are sent if non-zero (in other words if seconds is not an integer you will get microseconds.)
    3. Channel Labels are optional, and off by default to save transmission space/bandwidth. They can be enabled on a per unit basis in the Unit configuration screen in the Web Administration Control Panel. More information is available here.

     

  3. Send email to a pre-defined list of recipients:
    TTP /em/unitcode/Subject of alert/<message goes here> unitkey

    Sending email receives the same error responses as the upload command. If successful, the OK signal is returned.

    Notes: The Subject must not contain the forward slash character /, and the Message must be contained between the < and > characters. You message cannot contain the Carriage Return character as that is the TTP transmission terminator - you can have New Line characters inside the message, but be aware that they will be removed by the Data Server before passing to the Email producer - so they will not appear in the email message you receive.

    Mailing lists are set up on a per unit basis in the Administration Control Panel. Click on the Unit Mailing Lists link to manage mailing lists. Mailing lists link Users to Units. For each email address you want to add, just add/select a User with an email address.

    Email Server settings are setup in your Configuration file.

    Emails are stored in the database and can be viewed in the Administration Control Panel as well. This is also useful as Emails that failed to send are also listed here as well as ones that succeeded in sending.

  4. Send an alarm (via email) to a pre-defined list of recipients:
    TTP /al/unitcode/level unitkey
    or
    TTP /al/unitcode/level/<optional;semicolon;delimited;data;> unitkey

    Sending an email alarm receives the same error responses as the upload command. If successful, the OK signal is returned.

    Notes: Alarms are sent out to the Unit Mailing List for each unit.

    level must be an integer.

    Alarm messages are predefined within the Administration Interface. You can send out alarms without pre-defining Alarm messages, in that case some default text will be used.

    Data, delimited by semicolons, as in the data upload, can be sent with the alarm as well. This data does not have to match the data for the upload command. Data must be contained between the < and > characters if it is sent. If the first piece of data is a timestamp, then the alarm, level, and the timestamp it occurred at, will be stored in the database and will be available for display to users.

    Alarms messages are set up on a per unit basis in the Administration Control Panel. Click on the Unit Alarms link to manage alarm messages. Unit Alarms link messages to Units and are sent to the Unit Mailing List.

    Email Server settings are setup in your Configuration file.

    Alarms are sent as Emails, are stored in the database, and can be viewed in the Administration Control Panel as well. This is also useful as Alarms (Emails) that failed to send are also listed here as well as ones that succeeded in sending.

  5. Check the connection details of the unit and the server:
    TTP /ok/unitcode unitkey

    This is useful for debugging to check the connection details programmed into the Unit match what the server has for the Unit. If successful, the OK signal is returned, otherwise 405 Unit not found or 402 Unauthorized are the likely responses.

    The OK Producer is implemented as an example producer in the TTPApps/ folder for you to copy and build upon. This also means this producer can be disabled by removing (or commenting out) its entry in the Server Configuration File.

Timestamp format

  1. Timestamps are expressed like so: YYYY-MM-DD HH:MM:SS[.microseconds].
  2. Leading digits on the year are optional, and will be interpreted as filling out to 2000 if missing. Thus, 9-1-16 is equivalent to 2009-1-16, and 97-09-12 is equivalent to 2097-09-12.
  3. Leading digits on the month, day, and hour, minute, seconds are optional as well.
  4. Microseconds are optional (denoted by square brackets), and can be sent, so that the upload could look like this:
    TTP /up/unitcode/<2009-1-16 15:30:45.10;11;22;33;44> unitkey
    Trailing zeros can be truncated from the microseconds. If you choose to truncate the microseconds portion, an implicit specification of 0 is assumed for each missing digit. Thus, 2009-1-16 15:30:45.10 is equivalent to 2009-1-16 15:30:45.10.100000, and 2009-1-16 15:30:45 is obviously equivalent to 2009-1-16 15:30:45.000000.

     

  5. Notes: Internally the optional python dateutil module is used (http://labix.org/python-dateutil) as the parsing mechanism for dates with the "yearfirst" option enabled. In reality this means that any date that can be parsed according to dateutil.parser.parse('datetime string', yearfirst=True) will yield expected results.

In practce if you stick to the basic specification above you will have no problems with dates being misinterpreted.

Multiple samples can be uploaded at once (as many as you wish):
TTP /up/unitcode/<2009-1-16 15:30:45;11;22;33;44><2009-1-16 15:30:46;12;23;34;45> unitkey
response:
OK

Error Codes and Responses

Possible TTP error responses (you might notice similarity with HTTP Error Codes here):

  • 400 Bad request This means the request was not formed correctly. You will want to check your request and modify accordingly. Most likely it was missing the initial TTP which lets the Server know what protocol to expect in the transmission.
  • 402 Unauthorized The supplied Unit Key does not match for the Unit Code.
  • 404 Data not found No data was found for the requested Unit. Upload some data first and try the request again.
  • 405 Unit not found The supplied Unit Code does not exist.

  • 406 Duplicate sample
    The 406 Duplicate sample error is a special case, in that when multiple samples are uploaded in a single transaction, and a duplicated timestamp is detected, processing of the remaining samples in the transaction continues and the duplicated timestamp(s) are returned appended to the error message, along with their offset. eg:
    TTP /up/unitcode/<2009-1-16 15:30:45;11;22;33;44><2009-1-16 15:30:45;11.50;23;34.5;46><2009-1-16 15:30:46;12;23;34;45> unitkey
    response:
    406 Duplicate sample 2<2009-1-16 15:30:45>
    But sample 1 and 3 completed successfully. Multiple duplicates are returned if more than one sample timestamp is duplicated. Timestamps are returned as sent, thus 7-1-16 15:30:45 is returned unchanged if duplicated.

  • 500 Internal error An error occurred on the Server - no further detail of this is given. It is recommended to try the request again as it is likely a temporary error.
  • 501 Not implemented Only upload and download the last uploaded sample is supported - other correctly formed requests will return this error.

Extending TTP

The TTP is a flexible protocol, and easily extended with custom TTP Apps. The code below shows the TTP Protocol for extension:
TTP /command/unitcode/stuff unitkey

  • command can be anything you dream up - just make sure there are no spaces or forward slashes.
  • unitcode is the Unit Code to identify the Unit sending the request.
  • stuff can be anything your custom request handler expects, including spaces, forward slashes, etc. There is no set length restriction.
  • unitkey is the text after the last space and before the carriage return ends the transmission. This is the Unit Key for the given unitcode.

Sample Tiger Apps for Tiger Controllers from Texmate

Below are links to some sample Apps for both the Tiger 380 and 320 Series of Controllers on Texmate.com:

Texmate also has a comprehensive set of documentation for our Texmate Tiger Apps available at http://www.texmate.com/apps/.

↑ Top

Texmate Data Server Documentation

(top)