Websocket

Clients can establish a websocket connection with the platform.

The endpoint is located at /piranyaplatform/socket

If you wish to authenticate the connection, then you must supply authentication details using parameters such as ?username=...&password=... or through the Authorization header similar to how API requests are authenticated.

Each websocket connection can only be authenticated with a single user, so you must create a connection for each user and you must authenticate when establishing the connection.

Messages

All messages sent to and from the platform must be formatted in JSON.

Below is an example of a message sent from a client to the server. This message registers that the client is interested in messages from the devicemanager handler. You can read more in the Messages channel section.

{
  'id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'channel': 'messages',
  'parameters': {
    'handler': 'devicemanager',
    'action': 'register'
  }
}

• id is GUID generated by the sender (in this example it is generated client-side) and must be unique for each message
• channel is the server-side channel that this message should be passed through. Each channel is documented in the Channels section below.
• parameters is a JSON object containing additional parameters for the message. Some of these parameters may be required by the specific channel..

Message responses

Server messages will always be in response to another message sent from the client previously. This means that clients must register interest in specific events or kinds of messages, and after that the server would send events in response to the register message.

If the registration message sent from the client has id 46b2942f-e7bf-4425-951d-d4eba04586da then responses would contain a original_message_id with this id and look like:

{
  'id': '75bd4901-c1dd-4306-bafa-3db0aa5a6008',
  'channel': 'messages',
  'original_message_id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'parameters': {
    'device_id': 123,
    'action': 'reboot'
  }
}

Error example:

{
  'id': '75bd4901-c1dd-4306-bafa-3db0aa5a6008',
  'channel': 'messages',
  'original_message_id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'parameters': {
    'result': 'error',
    'error': 'Bla bla bla',
    'error_code': 400,
    'error_subcode': 123
  }
}

Channels

The platform currently has the following channels: events, heartbeats and messages.

Events channel

The events channel is used to send events from the server to registered clients. This could for example be a datachanged when some data of interest changes, which can then be handled on the client and lead to the client reloading the data in its views.

Subscribing to datachanged events

{
  'id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'channel': 'events',
  'parameters': {
    'action': 'subscribe',
    'event_channel': 'platform',
    'event_name': 'datachanged'
  }
}

Receving a datachanged event from the server

{
  'id': '...',
  'channel': 'events',
  'original_message_id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'parameters': {
    'action': 'trigger',
    'event_channel': 'platform',
    'event_name': 'datachanged',
    'variables': {
      'changes': [
        { 
          'entity_type': 'Device',
          'entity_id': 123
        }
      ]
    }
  }
}

Heartbeats channel

This channel is used for clients to send heartbeat "pings" which the server can then keep track of so it can monitor connected clients. This is useful since the server can then close connections when clients fail to send heartbeats instead of waiting for a timeout. Each connection can send and receive messages on multiple channels so the usage of heartbeats can help to ensure that all channels only receive messages while the connection is actually open and valid.

Clients are expected to register on the channel while specifying an interval that the client will send heartbeat events in.

Registering clients on the heartbeats channel

The below example specifies an interval of 1 minute.

{
  'id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'channel': 'heartbeats',
  'parameters': {
    'action': 'register',
    'interval': "00:01:00"
  }
}

Sending heartbeats from the client

{
  'id': '6364b3c0-87da-44da-9955-a43f3e2c9b9c',
  'channel': 'heartbeats',
  'parameters': {
    'action': 'ping'
  }
}

Server responding to the heartbeat

{
  'id': 'd4ad31ed-d7d4-4058-8f44-ca73041c4dd4',
  'channel': 'heartbeats',
  'original_message_id': '6364b3c0-87da-44da-9955-a43f3e2c9b9c',
  'parameters': {
    'action': 'pong'
  }
}

Missed heartbeat

If the client fails to send a heartbeat within it's specified interval then the server will send a reply to to register message telling the client that the connection will be closed, and then the actual connection will be force closed.

{
  'id': '512a11b1-4f46-4009-af9f-116c2c0c91a0',
  'channel': 'heartbeats',
  'original_message_id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'parameters': {
    'action': 'close'
  }
}

Messages channel

The messages channel is used to send commands to and from the server. This could be commands sent from administrators to devices such as asking them to reboot.

Registering interest in messages on the message channel

The message channel may have multiple server-side handlers, depending on which modules are installed. This could for example be devicemanager or infoscreen. Clients must register in each handler that they are interested in receiving messages from.

Example register message from the client:

{
  'id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'channel': 'messages',
  'parameters': {
    'handler': 'devicemanager',
    'action': 'register'
  }
}

Receving a message from the server

{
  'id': '75bd4901-c1dd-4306-bafa-3db0aa5a6008',
  'channel': 'messages',
  'original_message_id': '46b2942f-e7bf-4425-951d-d4eba04586da',
  'parameters': {
    'device_id': 123,
    'action': 'reboot'
  }
}