Tiip NPM | npm.io

TIIP

Thin Industrial Internet Protocol

TIIP is a wire protocol using JSON as its infoset. It is created for lightweight messaging in IoT solutions. It is loosely defined to support API creation.

Key	Description	Json data type	Valid values	Mandatory
protocol	Protocol name/version	String	tiip.0.8	Yes
timestamp	Seconds since 1 Jan 1970, as String. Controlled by the server.	String		No (Yes if no clientTime)
clientTime	Timestamp from client. Seconds since 1 Jan 1970, as String.	String		No (Yes if no timestamp)
mid	Message ID.	String		No
sid	Session ID.	String		No
type	Message type (see recommended values in details below).	String		No
source	ID(s) of the origin module(s) or node(s).	Array of String		No
pid	Id of the targeted process or sub-system.	String		No
signal	The intended operation or command.	String		No
arguments	Named arguments or data.	Object		No
payload	List of data.	Array		No
ok	Boolean indicating success or failure. (Only for replies)	Boolean		No
tenant	ID of a tenant in a multi-tenancy solution.	String		No

Key details

protocol

The name/ID of the protocol (including version). Ex: "tiip.0.8"

timestamp

Seconds since 1 Jan 1970, as String. Include as many decimals as needed for increased accuracy (millisecond accuracy is often convenient). Handeled centrally - for instance set by the server for each messages on their arrival. See also clientTime.

clientTime

The timestamp set by clients (devices) when a message is constructed. This is separate to timestamp because it can not be trusted by the central point (server) to be correct or same as every other message creator in the system.

mid

Message ID. To identify an answer to a request for instance, in asyncronous communication.

sid

Session ID. To identify a session in case of non-implicit sessions.

type

Some different standard values are:

init, kill: Messages for persistant connections, a "login" message (answered with rep) and a disconnect message.
req, rep: Request-reply pattern.
sub: Publish-subscribe pattern: Subscription request.
pub, unsub: Publish-subscribe pattern: Publication and unsubscribe messages (no replies).
create, read, update, delete: The standard "CRUD": the four basic functions of persistant storage, to use instead of req if desired.

source

Origin ID, with prepended nodes further along the communication chain if needed.

pid

The targeted process or sub-system. An ID or address that the receiver can use to route the message internally.

signal

Meant to be used as the "function" of the API between 2 communication nodes -- the command to the receiver. (payload contains the functions "arguments".)

arguments

The actual content that needs to be sent to the other side. Often regarded as the "arguments" to the API "function" specified in signal.

payload

Content to be sent, as a list.

Ex:

Sensor values (push data from a device)
User records (requested from a database)
Notification records published on an internal bus channel for instance
An error message
etc.

ok

Simple key in a reply message that indicates the outcome of a request as a boolean.

tenant

ID of a tenant in a multi-tenancy solution. Depending on the communication,

By example

A gateway sends position data to the server:

{
    "protocol": "tiip.0.8",
    "clientTime": "1379921889.4",
    "type": "pub",
    "signal": "updatePosition",
    "source": ["gpsSensor239"],
    "arguments": {"long": 59.21625, "lat": 10.93167}
}

Message from the server to a gateway that the motor should be stopped:

{
    "protocol": "tiip.0.8",
    "timestamp": "1387345934.702",
    "type": "req",
    "pid": "motor",
    "signal": "stop"
}

Message from a web client to make a change in the configuration data of a user:

{
    "protocol": "tiip.0.8",
    "clientTime": "1387349004.221",
    "type": "req",
    "pid": "configuration",
    "signal": "updateUserDashboard",
    "arguments": {"id": "4Xd0hN3z", "widgets": ["map", "temperature", "alarms"]}
}