Protocol

NOTE Use of the words, must, should, could, etc. adheres to the best practice suggested in RFC2119 (https://www.ietf.org/rfc/rfc2119.txt)

Description

Protocol messages MUST be specified in the following JSON format:

{
    "version" : <inbus-version>,
    "opcode" : <opcode>,
    "application" :[ <app-key>, <app-type> ],
    "address" : [ <ip-number>, <port> ],
    "payload" : <payload>
}

All messages MUST contain all elements, even if they are not used.

Elements that do not apply to a particular type of message (as defined by its <opcode>), SHOULD be an empty string or zero, depending on the data type.

<inbus-version>

Integer specifying the Inbus protocol version. MUST be 1.

<opcode>

Integer specifying the type of message

• 0: reserved
• 1: subscribe
• 2: unsubscribe
• 3: publish
• 4-999: reserved

<app-key>

String identifying the application to which the message applies.

The values * and _inbus are reserved for future use.

<app-type>

Integer, specifying an application defined value. Can be used to distinguish multiple messages related to the same application.

The element only applies to publish messages.

<ip-number>

String containing an IP number part of the subscriber address. In case of a publish message, the element does not apply.

<port>

Integer containing the port number of the subscriber address. In case of a publish message, the element does NOT apply.

The subscriber address, together with the app-key uniquely identifies a subscription.

<payload>

String specifying a user defined payload. This implies that binary data must be string-encoded. The element only applies to publish messages.

Infrastructure

The protocol SHOULD use port 7222

Example messages

Subscribe

{   "version" : 1 ,
    "opcode" : 1,
    "application" : [ "upnp", 0 ],
    "address" : [ "127.0.0.1", 3456 ],
    "payload" : ""
}

Subscription message indicating that the subscriber wants to receive messages from an application that publishes messages under the “upnp” app-key.

Unsubscribe

{   "version" : 1 ,
    "opcode" : 2,
    "application" : [ "upnp", 0 ],
    "address" : [ "127.0.0.1", 3456 ],
    "payload" : ""
}

Message indicating that the subscriber no longer wants to receive messages from the application that publishes messages under the “upnp” app-key.

Publish

{   "version" : 1 ,
    "opcode" : 3,
    "application" : [ "upnp", 17 ],
    "address" : [ "", 0 ],
    "payload" : "Omega - Gammapolis I. - 0:45"
}

Message sent by the application using the app-key “upnp”, using app-type 17.