Platform Websocket interface Reference

The Platform Websocket interface is responsible for recording telemetry data and performing device-to-device messaging. Although this page describes the pure message format for platform operations the recommended way to reach the Platform Websocket interface is though client libraries that are currently available for .NET-based devics and devices running Linux (Raspberry Pi, etc.).

It’s important to mention that there are two interfaces where the platform services can be reached:

  • The Platform API that’s discussed in Platform REST API
  • Platform Websocket interface what this page is about

The Platform API is for devices that mostly record telemetry data and/or send message to other devices quite rarely (eg. every minute once or more infrequently) and does not receive messages too frequently and doesn’t require incoming messages to arrive ASAP. So this API is for devices that are measuring something, controlling other devices however are not controlled too often or with low latency. The Platform Websocket interface is for devices that need to respond to control messages in a short period of time. The Websocket interface maintains a persistent connection between the devices and the service which makes it able to receive push notification about new messages and to respond faster even in fraction of a second.

In the following description you will see some placeholders:

  • <APIURL>: the full url root of the WS interface. Like ws://websocket.thriot.io
  • <DEVICEID>: 32 characters long unique identifier for device
  • <APIKEY>: 32 characters long crypto-safe random key

 

Login a close operations

Login device
Description Login device and creates a persistent websocket connection
Command
login <DEVICEID> <APIKEY>
 Successful response
login ack
 Error response login badcommand: Already logged in
login unauthorized: Bad authentication parameters passed

 

Close connection
Description Closes an already open connection
Command
close
Successful response none
Error response none

 

Telemetry data

Record telemetry data
Description Record telemetry data. Requires the device to be logged in. The payload must be in JSON format while the maximum payload length is 1024 bytes.
Command
telemetrydata <PAYLOAD>
Successful response
telemetrydata ack
Error response telemetrydata unauthorized: Device is not logged in.
telemetrydata error: Error occurred while recording telemetry data

 

Subscriptions and messaging

Subscribe to the device’s message channel
Description Subscribe to the device’s message channel. This operation requires the device to be logged in.
Command
subscribe <MODE>

Mode can be receiveandforget and peekandcommit. Receiveandforget implements QoS 0-level reliability from the receives perspective while the latter implements Q0S 1-level reliability.

Successful response
subscribe ack
Error response subscribe unauthorized: Not logged in
subscribe already: Already subscribed
subscribe badcommand: The <MODE> parameter has an invalid value

 

Unsubscribe
Description Unsubscribe the device from the previous subscription
Command
unsubscribe
Successful response
unsubscribe ack
Error response unsubscribe unauthorized: Not logged in
unsubscribe notsubscribed: There is no active subscription. Can’t unsubscribe

 

Send message to an other device
Description Send message to an other device. This operation doesn’t require the sender to be subscribed. Just login and the operation will work.
Command
sendto <DEVICEID> <PAYLOAD>

DeviceId is the target device’s id, while payload is a custom string with the maximum length of 512 bytes.

Successful response
sendto ack
Error response sendto unauthorized: Not logged in
sendto error: Failed to send the message due to some kind of internal error
sendto throttled: There were too many sendto operations. Request throttled. Try again later.

 

Receive message from the service
Description This is a pushed message. It is initiated by the service not by the client. In case of receiveandforget subscription mode  there is no response from the client while in peekandcommit mode the client sends a commit message (described below)
Message from the server
pushedmessage <MESSAGEID> <TIMESTAMP> <SENDERDEVICEID> <PAYLOAD>

Where the messageid is the unique autoincremented id of the message, the timestamp is a Unix timestamp indicating the recording time of the message in seconds since 1970.1.1.  SenderDeviceId is the 32 characters long unique id of the device that sent the message. Payload is the actual message content (maxlength 512 bytes)

Successful response from the client Send commit message from the client in case of peekandcommit mode.

 

Commit message
Description Commits the message in case of peekandcommit subscription mode. Issue this command immediately after receiving a pushedmessage. The command must not be sent in case of receiveandforget mode.
Command
commit
Successful response none
Error response none

 

Heartbeat

heartbeat request
Description Occasionally the client needs to send heartbeat messages to the server to ensure that the server doesn’t drop the connection (once in every minute). The server’s response is a yo message. The client libraries will handle heartbeat automatically using the spin operations.
Message from the client
heartbeat
Successful response from the server
yo

 

Advertisements