Heartbeats

As part of the keep-alive strategy for Doshii WebSocket connections, it is necessary to be capable of sending and receiving heartbeats on an established WebSocket connection.

Initiated by Client

As described in the article, Use of WebSockets, it is necessary to periodically send a heartbeat (ping) to Doshii to help maintain the connection and ensure Doshii does not treat the connection as inactive. The recommended interval is every 30 seconds.

The ping event should be of the form:

{
    "doshii": {
        "ping": <unix time in milliseconds>,
        "version": "<pos version>"
    }
}

e.g.

{
    "doshii": {
        "ping": 1539144663417,
        "version": "5.3.72"
    }
}

An example, using NodeJS for the ping event:

ws.on('open', function(event) {
  function heartbeat() {
    const timestamp = Date.now();
    const appVersion = '5.3.72';
    const payload = JSON.stringify({
        doshii: {
            ping: timestamp,
            version: appVersion
        }
    });
    ws.send(payload);
  }

  heartbeat(); // Send one immediately to complete the handshake
  setInterval(heartbeat, 30000); // Then 30 every seconds or so thereafter to keep alive
});

In response to the ping event, Doshii will respond with a pong event. Responding with the unix time in milliseconds that was supplied in the original ping, along with the current API version.

{
    "type": "message",
    "data": { "doshii": { "pong": 1539153237588, "version": "3.2.0" } }
}