Overview

1. 1) All calls require an X.509 Certificate to be registered within the GroveStreams organization and assigned a policy. The entire certificate chain needs to be registered. More on certificates can be found here.
2. 2) All calls are rate limited.
3. 3) IDs and UIDs
4. 4) Date and Times

Compression

Payload compression is supported for these calls. Set a user property on the message called "enc" with the value of the compression encoding. See the Raspberry Pi tutorial for an example of using Feed, and other, topics with compression.
Encodings supported:

• BR: BROTLI
• BZIP2
• DEFLATE
• DEFLATE64
• GZ: GZIP
• LZ4-BLOCK
• LZ4-FRAMED
• LZMA
• PACK200
• SNAPPY-FRAMED
• SNAPPY-RAW
• XZ
• Z
• ZSTD: ZSTANDARD

ReplyTo

Some calls support ReplyTo (or also known as the Request-Response pattern). ReplyTo is an MQTT concept to emulate request/response. To receive a reply:

1. 1) Set the correlation data.
2. 2) Set the response topic.
3. 3) Optionally set the user property "replyqos"
4. 4) Optionally set the user property "replyenc" to set the compression encoding if the reply is to be compressed.

See the Using Request-Response pattern of the Raspberry Pi tutorial for more information and examples.

GroveStreams subscribes to these topics and saves the data to streams within an organization. GroveStreams' data processing for these calls is asynchronous. The connection will be dropped if an error occurs during the saving process.

Topic and Payload Design Pattern

All of these topics accept the same message payload. Including the compId and streamId, as part of the topic, helps to minimize the size of the message body and allows for subscriptions specific to a component, stream and data.

The payload data values will be used if compId, streamId, data, or time is included in both the topic and in the body.

This design minimizes publish call sizes to avoid I/O costs.

Expression Derivation

An attempt to derive all precedent streams dependent on the streams being uploaded, will occur after the data has been saved but while the components are still locked.

All streams impacted will be derived while walking up the derivation dependency tree. Derivation will stop when a maximum of 20 streams is reached or the total save time reaches 10 seconds. Derivation will stop working up a precedent branch if a component is locked by another process, derivation fails due to exceptions, derivation did not derive any new intervals. Derivation will only occur for streams that are appending samples.

Normal derivation still occurs within the Job framework on Job servers and will attempt to derive all streams that need deriving every few minutes.

{
  "op": {   
    "cname": "Temperature",
    "folder": "/Components/zone1",
    "ctid": "temp_template", 
    "dtid": "xx",
    "dsid": "xx",
    "autofillGapsWithNulls": true, 
    "freq": 10000, 
    “t” : 1380225121172 
  },
  "data": [
    {
      "cid": "comp2",  
      "sid": "status", 
      "d": "normal",
      "t": 1380225121172 
      "te": 1380225121172 
    }
  ]
}					

Op stands for Options that can be applied during the call. This section is optional.

A collection of tuples containing sample times. This section is optional if it is provided as part of the topic.

Payload compression supported - See compression above.

{
  "data": [
    {
      "cid": "comp1",
      "sid": "status",
      "d": "normal",
      "t": 1380225121172 
    },
    {
      "cid": "comp2",
      "sid": "temp",
      "d": 38.7,
      "t": 1380225121172 
    },
    {
      "cid": "comp2",
      "sid": "windir",
      "d": "ne",
      "t": 1380225121172 
    }
  ]
}

{
  "op": {   
    “t” : 1380225121172 
  },
  "data": [
    {
      "cid": "comp1",
      "sid": "status",
      "d": "normal"
    },
    {
      "cid": "comp2",
      "sid": "temp",
      "d": 38.7
    },
    {
      "cid": "comp2",
      "sid": "windir",
      "d": "ne"
    }
  ]
}

{
  "data": [
    {
      "sid": "temp",
      "d": 38.7,
      "t": 1380225121172 
    },
    {
      "sid": "windir",
      "d": "ne",
      "t": 1380225121172 
    }
  ]
}

{
  "data": [
    {
      "d": 38.7,
      "t": 1380225121172 
    }
  ]
}

none

This call is used to upload and register new certificates for a device in an organization. The current certificates (curCerts) being created must be included in the payload and be a part of the chain used for the current SSL handshake. The new certificates will be registered within the organization in the same folder and with the same settings as the existing certificates. Component pinning will be validated if enabled. The new certificate subject DN must be different than the existing subject DN.

Supports ReplyTo. Returns any exceptions or the org uid upon success.

{
  "curCerts": [X509Certificate string, X509Certificate string],
  "newCerts": [X509Certificate string, X509Certificate string]
}					

This call is used to unregister and remove certificates from an organization. The certificates being removed (certs) must be included in the payload and be a part of the chain used for the current SSL handshake. Component pinning will be validated if enabled.

Supports ReplyTo. Returns any exceptions.

{
  "certs": [{X509Certificate string}, {X509Certificate string}]
}						

This topic is published by Certificate Operations within an organization. Devices can subscribe to handle rolling of certificates.

none				

none				

none