Skip to content
Marvin edited this page Jun 26, 2013 · 21 revisions

Network Protocol Specification

This document specifies the network protocol used by our product. The protocol is divided into two parts: UDP multicast for host discovery and TCP unicast for direct communication.

Common characteristics

All communication is based on JSON which is sent in UTF-8. Each JSON object that is sent must have a string value of name type which identifies the message type. Messages which are not JSON objects or which do not have the type field should be discarded.

Reply Messages

If a message needs a positve/negative the appropriate replies are specified below the message. A message ending on Ack always is a positive response and a message ending on Nak is always a negative one. Ack/Nak messages may contain additional data.

UDP multicast

The UDP multicast used is very simple as it consists of a single message type:

{
    "type": "beacon",
    "uuid": "12345678-9abc-def0-1234-56789abcdef0",
    "addresses":
    [
        {
            "address": "192.168.0.42",
            "port": 5000
        },
        {
            "address": "foo.lan",
            "port": 3621
        }
    ]
}
  • type: The type to use is beacon
  • uuid: The UUID of the module that sent the beacon
  • addresses: An array containing addresses which may be used to contact the module. The address have two properties:
    • address: Either a numerical IPv4 or IPv6 address or a hostname
    • port: The port number

For UDP multicast each message has to be sent in its own datagram packet. These packets may not contain other data.

TCP unicast

TCP unicast is used for direct communication between two computers. The message format is the same as for UDP multicast (JSON objects with type field) except that they are now prepended by a length field that is an unsigned integer of 4 bytes sent in most significant byte order. The length field does not include the 4 bytes added by the length field itself.

If a new connection is made, both sides have to send a HelloMessage. Afterwards the module with the lower UUID decides if the connection is kept or closed because it is redundant. The module with the lower UUID either sends a ConnectionEstablishedMessage or ConnectionClosedMessage to inform the other participant whether or not the connection can be used. The moduler with the higher UUID has to respond to a ConnectionEstablishedMessage with another ConnectionEstablishedMessage to fully establish the connection.

HelloMessage

{
    "type": "hello",
    "uuid": "12345678-9abc-def0-1234-56789abcdef0",
    "framesize": 65536,
}
  • type: The type to use is hello
  • uuid: The UUID of the module sending the message
  • framesize: The maximum size for a message that this module can receive

ConnectionEstablishedMessage

{
    "type": "connection established"
}
  • type: The type to use is connection established

ConnectionClosedMessage

{
    "type": "connection closed"
}
  • type: The type to use is connection closed

JoinApplicationMessage

{
    "type": "join application",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "name": "foo"
}

Informs a module that it should start an ApplicationAgent for the given application.

  • type: The type to use is join application
  • appId: The UUID of the application
  • name: The name of the application

JoinApplicationAck

{
    "type": "join application ack",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "name": "foo"
}

JoinApplicationNak

{
    "type": "join application nak",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "name": "foo"
}

Sent in response to an JoinApplicationMessage. Ack is send on success, nak on failure.

  • type: The type to use is join application ack or join application nak
  • appId: The UUID of the application that this module joined
  • name: The name of the application

BlockMessage

{
    "type": "block",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "block": "<base64 data>"
}

Informs a module that it should execute a given FunctionBlock.

  • type: The type to use is block
  • appId: The UUID of the application the block belongs to
  • block: Base64 encoded (Java-)serialised FunctionBlock

StartApplicationMessage

{
    "type": "start application",
    "appId": "12345678-9abc-def0-1234-56789abcdef0"
}

Informs an ApplicationAgentthat all blocks belonging to the application should be started.

  • type: The type to use is start application
  • appId: The UUID of the application

LoadClassMessage

{
    "type": "load class",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "className": "NameOfClass",
    "classByteCode": "<base64 data>"
}

Sends a class.

  • type: The type to use is load class
  • appId: The UUID of the application that requested the class
  • className: The name of the class being sent
  • classByteCode: Base64 encoded class file

LoadClassAck

{
    "type": "load class ack",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "className": "NameOfClass"
}

Sends a class.

  • type: The type to use is load class
  • appId: The UUID of the application that requested the class
  • className: The name of the class that was sent sent

LoadClassNak

{
    "type": "load class nak",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "className": "NameOfClass"
}

Sends a class.

  • type: The type to use is load class
  • appId: The UUID of the application that requested the class
  • className: The name of the class that was sent sent

KillMessage

{
    "type": "kill",
    "appId": "12345678-9abc-def0-1234-56789abcdef0"
}

Informs a module that a given application should be killed.

  • type: The type to use is kill
  • appId: The UUID of the application that should be killed

RequestApplicationsMessage

{
    "type": "request applications"
}

Requests an AppsMessage with information about all running applications on the Module.

  • type: The type to use is request applications

ApplicationsMessage

{
    "type": "applications"
    "apps":
    [
        {
            "appId": "12345678-9abc-def0-1234-56789abcdef0",
            "running": false,
            "name": "application0"
            "blocks":
            [
                {
                    "blockid": "44765678-9abc-def0-1234-56789abcdef0",
                    "blocktype": "trollBlock"
                },
                {
                    "blockid": "33365678-9abc-def0-1234-56789abcdef0",
                    "blocktype": "trollOperator"
                }
            ]
        },
        {
            "appId": "99995678-9abc-def0-1234-56789abcdef0"",
            "running": true,
            "name": "application1"
            "blocks":
            [
                {
                    "blockid": "98765678-9abc-def0-1234-56789abcdef0",
                    "blocktype": "temperatureSensor"
                },
                {
                    "blockid": "66665678-9abc-def0-1234-56789abcdef0",
                    "blocktype": "meetingraumOperator"
                }
            ]
        }
    ]
}
  • type: The type to use is applications
  • apps: An array containing all applications present on the module. The elemnts of the array have the following attributes:
    • appId: the UUID of the application
    • name: the name of the application
    • running: Whether or not the application is running
    • blocks: An array containing information about the blocks belonging to the application. The elements have the following attributes:
      • blockid: The UUID of the block
      • blocktype: The type of the block

ValueMessage

{
    "type": "value",
    "appId": "12345678-9abc-def0-1234-56789abcdef0",
    "blockid": "98765678-9abc-def0-1234-56789abcdef0",
    "input": "name",
    "value": "<base64 data>"
}

Informs an ApplicationAgent that it should update an input of a FunctionBlock.

  • type: The type to use is value
  • appId: The UUID of the application
  • blockid: The UUID of the FunctionBlock
  • input: The name of the input that should be updated
  • value: The new value as a Base64 encoded (Java-)serialized object
Clone this wiki locally