Streaming API
WebSocket API: /signalk/«version»/stream
Initiates a WebSocket connection that will start streaming the server’s updates as Signal K delta messages. You can
specify the contents of the stream by using the subscribe
query parameter.
- ws://hostname/signalk/«version»/stream?subscribe=self
- ws://hostname/signalk/«version»/stream?subscribe=all
- ws://hostname/signalk/«version»/stream?subscribe=none
With no query parameter the default is self
, which will stream the data related to the self
object. all
will
stream all the updates the server sees and none
will stream only the heartbeat, until the client issues subscribe
messages in the WebSocket stream.
If a server does not support some streaming options listed in here it must respond with HTTP status code 501 Not
Implemented
.
See Subscription Protocol for more details.
Connection Hello
Upon connection the server MUST send a 'hello' JSON message, for example:
{
"name": "foobar marine server",
"version": "1.0.4",
"timestamp": "2018-06-21T15:09:16.704Z",
"self": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
"roles": [
"master",
"main"
]
}
This response is defined by the hello.json
schema.
The server MUST provide:
roles
which specifies which roles the server is capable of providing. See roles for details about possible server roles.version
which specifies the version of the SignalK schema and APIs that the server is using. See versioning for details aboutversion
strings.
The server SHOULD provide:
timestamp
but only if the server is equipped with a time source and it has been set.
The server MAY provide:
self
is the unique identifier of the vessel using the URN format specified for the uuid field in the Signal K schema. It may also use the URN format specified for the mmsi field in the Signal K schema if it exists. This is only provided if the server relates to a specific vessel, aircraft, aid to navigation or sar.name
is the name of the Signal K server software, e.g. signalk-server
name
, self
and roles
MUST return the same values as provided in the swname
, self
and roles
properties within the DNS-SD advertisement (if implemented).
version
MUST be the same value as version
within the associated endpoints list provided by the http GET
request to /signalk
within the REST API (if implemented).
History playback
The server MAY support history playback from a certain point in time with a specified rate.
To create a WebSocket connection that plays back data the client uses the request parameter startTime
to specify the start timestamp and the optional request parameter playbackRate
to specify the rate. Rate value parameter is a floating point value with value 1
equal to real time playback and for example 0.5
to half the real time rate and 5
to five times real time rate. Omitting the playbackRate
will result in real time playback.
The playback api is located at /signalk/v1/playback
. An example url for history playback streaming: wss://localhost:3443/signalk/v1/playback?subscribe=self&startTime=2018-08-24T15:19:09Z&playbackRate=5
.
The hello message for a history playback stream MUST NOT contain the timestamp
property and MUST include the properties startTime
and playbackRate
. The delta stream format for history playback is the normal streaming format. Timestamps indicate the time data was originally captured.
{
"name": "foobar marine server",
"version": "1.1.4",
"startTime": "2018-08-24T15:19:09Z",
"playbackRate": 1,
"self": "vessels.urn:mrn:signalk:uuid:c0d79334-4e25-4245-8892-54e8ccc8021d",
"roles": [
"master",
"main"
]
}
A server MAY respond with 501 Not Implemented
status code if it does not support history playback and with 400 Bad Request
if it does not have data to play back for the given time period. A 404 Not Found
response is also acceptable to be backwards compatible.
Streaming over TCP
A server MAY provide streaming delta service over TCP. See Urls and Ports and Discovery and Connection Establishment for more details.
The messages MUST be serialised as JSON with one message per line using line terminator \r\n
(carriage return and newline).
As there is no way to specify the subscription policy using url parameters as when opening a WebSocket connection the initial subscription policy is none
, no active subscriptions. The client can modify the subscriptions after connection is established.
Connection hello
is the same as when using WebSockets.