GyroPalm Realtime Server

A secure websocket portal for bi-directional communication between GyroPalm devices and computers.

Overview

GyroPalm.com provides a secured websocket server (WSS) on port 3200 exclusively for GyroPalm users and browsers to connect bi-directionally. This server requires authentication before any further communication is processed. Failed attempts to authenticate or invalid payload messages will result in an immediate connection rejection.

Protocol Info

Endpoint: wss://gyropalm.com:3200
Payload Type: JSON
Payload Encoding: UTF-8
Authentication parameters: apiKey, wearableID
Maximum send rate: 15 FPS (once every 66~67 ms)
Keep-Alive Heartbeat: Once every <60 seconds

The heartbeat payload is as follows:

{"action":"heartbeat"}

Note: Heartbeat payload can be sent at any time, even without authentication. Message and command payloads have a maximum send rate of 15 FPS. Any device exceeding this rate will be dropped.

Testing

To familiarize with the concepts of WSS and test your implementations in GyroPalm Realtime without fully building out your app, you may use an online websocket client such as WebsocketKing, which provides many great capabilities such as "multi-pane" parallel connections, saved payload presets, and output logging. Optionally, the Postman client also now offers websocket support.

Here is a demonstration of a test browser and test wearable communication side-by-side in WebsocketKing:

Authentication Protocol

Both GyroPalm wearables and browser connect to the endpoint mentioned above. Upon successful connection, you will be greeted by a prompt. All clients connecting to WSS must authenticate after this message:

{
  "action": "info",
  "stat": "prompt",
  "msg": "Welcome to GyroPalm Realtime. Please provide credentials."
}

This initial authentication helps the server determine whether the client is a wearable or browser.

Here is a template of the authentication JSON payload for a browser client:

{
  "action":"sub",
  "wearableID":"gp00000000",
  "apiKey":"c00000000"
}

Be sure to replace the wearableID and apiKey values with your own.

You can find your wearableID by going to your Wearable Settings in the GyroPalm Dashboard. You can obtain an apiKey for your account by requesting a new GyroPalm Cloud Project from the GyroPalm Dashboard. Remember, these credentials belong to you only. Please do not post them in your open-source repositories or publish them in articles.

For GyroPalm Studio developers only: Here is a template of the authentication JSON payload for a wearable client:

{
  "action":"new",
  "wearableID":"gp00000000",  
  "secret":"00000000000000000000"
}

As noted above, to keep things secure, connecting to WSS as a wearable requires a wearable secret. Unless you are writing a custom firmware using GyroPalm Studio, you do not need to pose as a wearable client.

For GyroPalm Studio users, your wearableID and secret can be retrieved in the main code by calling gplm.myLicense.wearableID and gplm.myLicense.secret respectively. This assumes you instantiated the GyroPalmEngine object and called it gplm. Neither you or the end-user will ever need to look up their secret key.

Successful Auth

For browser clients, after successful authentication, you will get a confirmation similar to this:

{
  "action": "info",
  "stat": "success",
  "msg": "Subscribed to gp00000000"
}

For wearable clients, after successful authentication, you will get a confirmation similar to this:

{
  "action": "info",
  "stat": "success",
  "msg": "Device gp00000000 added"
}

Failed Auth

For browser clients, if your wearableID and/or apiKey do not match GyroPalm's records, you will be shown this message:

{
  "action": "info",
  "stat": "error",
  "msg": "Unauthorized device"
}

For wearable clients, the wearableID and secret are validated using a proprietary licensing algorithm that factors in other user-based parameters. If those fail, the wearable will receive the same error message as shown above.

All failed authorizations get disconnected by the server. You may try again, but persistent failed connections in the same hour will become banned for a period of time.

Requesting Wearable Status

For browser clients, upon successful authentication, you will be automatically subscribed to the wearable's messages. This means the browser client will receive any events sent from the wearable. Additionally, the browser client will also receive updates when the wearable becomes Online or Offline.

Online Status Payload Examples

When wearable is online:

{
  "action": "info",
  "stat": "online",
  "msg": "Wearable gp00000000 is online"
}

When wearable is offline:

{
  "action": "info",
  "stat": "offline",
  "msg": "Wearable gp00000000 is offline"
}

Manually Requesting Device Status

Sometimes, if your browser client needs to retrieve the latest status of the wearable (i.e. browser connected when the wearable is already online), you can request for the wearable's status by sending the following payload:

{"action":"status"}

You will receive a similar response:

{
  "action": "info",
  "stat": "online",
  "msg": "Wearable gp00000000 is online",
  "duration": "1.55 mins"
}

Note that by requesting the status manually, you will also get the duration value, which is the number of minutes the wearable is online. After a wearable goes offline, the duration parameter gets reset to 0. Duration is not counted when a device is offline.

Sending a Command to Wearable

Commands can be sent to the wearable. Here is an example payload to send data to a GyroPalm Encore wearable:

{
  "action":"control",
  "wearableID":"gp00000000",
  "outputVal":"{\"someKey\":\"someVal\"}"
}

In the near future, we will discuss "native commands" that will make the wearable do certain actions such as show alerts, vibrate, set time, etc.

Sending data from the Wearable

This payload is specific to wearable client. If you are not a GyroPalm Studio developer, this does not apply.

{
  "action": "pub",
  "wearableID": "gp00000000",
  "sensorVal": "{\"someKey\":\"someVal\"}"
}

The wearable must be first authenticated prior to sending data. If the wearable sends data without introducing itself, the following error will occur:

{
  "action": "info",
  "stat": "error",
  "msg": "You are not authorized to use this route"
} 

Send REST API from Wearable

The GyroPalm Encore can perform REST API calls over HTTPS. However, for lower latency, the same REST request can be relayed over Websockets by simply adding a key called action with value as api. Note that only wearables may perform this function.

General API Calls

{
    "action": "api",
    "method": "POST",
    "url": "https://webhook.site/2e15a6a5-91e7",
    "headers": {
        'Wearable-Id': 'gp36185824',
        'Secret': 'gp63455028551ce391',
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    "form": {
        "apiKey": "abc123",
        "wearableID": "gp123456"
    }
}

Typical Reply

The msg key will contain the HTML, JSON, or string response given by the API server.

{
  "action": "info",
  "stat": "output",
  "url": "https://webhook.site/2e15a6a5-91e7",
  "msg": "OK"
}

Calls to GyroPalm Central V2

The GyroPalmRealtime object and documentation provides you simplified methods to make API calls to the GyroPalm Central V2 server without sending it the full API request. This makes it easier both sides.

{
    "action": "central",
    "endpoint": "tuya/control",
    "wearableID": "gp123456",
    "secret": "gp00000000",
    "body": "devIndex=9&code=switch&state=on"
}

Incoming Data

When the browser client receives incoming data from the wearable, the payload will be similar to this format:

{
  "action": "data",
  "gp00000000": "{\"someKey\":\"someVal\"}"
}

When the wearable client receives incoming data from the browser, the payload will be similar to this format:

{
  "action": "data",
  "command": "{\"someKey\":\"someVal\"}"
}

Terms and Disclaimer

By using this cloud resource or any GyroPalm SDK, you agree to be legally bound by the GyroPalm Terms of Use and Disclaimer. You can find the complete terms at https://gyropalm.com/legal/terms/