Data Collections Manager

Data Collections Manager (DCM) creates a realtime and historical REST interface for managing location and sensor data.
The concept is built around collections. You can have collections of nearly anything, like pallets, products, forklifts, etc. Each collection item than can be enchanced with various profiles.
By using Sunstone RTLS all of you collections will have the possibility to update it's location profile with precise real-time indoor position information.

This documentation is generated from DCM version: 0.0.3-31

Collections

Collections are defined at compile time.
We are working hard to create easy to use collections for your application requirements.
If you cannot find a suitable one for your use-case, please get in touch.

[GET /generalTags]

Returns all generalTags

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "secondaryId": {
        "description": "the unique hardware ID of the Tag, printed on back",
        "type": "integer",
        "minimum": 0
      },
      "primaryId": {
        "description": "<tag.secondaryId>",
        "type": "string"
      },
      "uuid": {
        "description": "guaranteed to be unique locally, globally probably unique ID",
        "type": "string",
        "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1-5][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
      },
      "accelerometerA": {
        "description": "x,y,z acceleration affecting the tag in m/s2",
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number"
        }
      },
      "temperatureC": {
        "description": "temperature of the tag in celsius",
        "type": "number"
      },
      "humidityRH": {
        "description": "relative humidtiy",
        "type": "number"
      },
      "pressurePa": {
        "description": "pressure measured in Pa",
        "type": "number"
      },
      "batteryVoltage": {
        "description": "the battery voltage",
        "type": "number"
      },
      "externalVoltage": {
        "description": "the battery external voltage",
        "type": "number"
      },
      "profileIds": {
        "description": "number to identify the exact application types. The meaning of this value can be obtained from a look-up table.",
        "type": "array",
        "items": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "required": [
      "secondaryId",
      "primaryId",
      "uuid",
      "profileIds"
    ]
  }
}

[GET /zones]

Returns all zones

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "secondaryId": {
        "description": "the name of the zone",
        "type": "string"
      },
      "uuid": {
        "description": "guaranteed to be unique locally, globally probably unique ID",
        "type": "string",
        "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1-5][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
      },
      "baseArea": {
        "description": "polygon area control points in meter. Closed polygon (last point == first point) in clockwise direction",
        "type": "array",
        "items": {
          "type": "array",
          "minItems": 2,
          "maxItems": 2,
          "items": {
            "type": "number"
          }
        }
      },
      "height": {
        "description": "area height bounds in meter",
        "type": "array",
        "minItems": 2,
        "maxItems": 2,
        "items": {
          "type": "number"
        }
      },
      "tags": {
        "description": "tags currently in this zone",
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "secondaryId",
      "uuid",
      "baseArea",
      "height",
      "tags"
    ]
  }
}

[GET /boxes]

Returns all boxes

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "secondaryId": {
        "description": "barCode of the box decoded in base64",
        "type": "string"
      },
      "uuid": {
        "description": "guaranteed to be unique locally, globally probably unique ID",
        "type": "string",
        "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1-5][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
      },
      "barCode": {
        "description": "barCode of the box",
        "type": "string"
      },
      "content": {
        "description": "content of the box",
        "type": "string"
      },
      "pairedUuid": {
        "description": "paired general tag uuid",
        "type": "string",
        "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1-5][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
      }
    },
    "required": [
      "secondaryId",
      "uuid",
      "barCode"
    ]
  }
}

Profiles

Profiles are property groups in order to create new features for a collection item.
Each collection item can be enhanced with multiple profiles.
For example to enable location data for a collection item, the id of the locations profile have to be listed in the profileId array of that collection item.

[GET /locations]

Returns all locations

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "description": "Profile#0001 location related properties",
    "$comment": "after updating the position the containing zone list is recalculated",
    "properties": {
      "primaryId": {
        "description": "guaranteed to be unique locally. If referenced other collections will have same id.",
        "type": "string"
      },
      "isMoving": {
        "description": "tag reports that it is not standing still",
        "type": "boolean"
      },
      "position": {
        "description": "3 element array in meters. Position vector represented in the local coordinate system",
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number"
        }
      },
      "gpsPosition": {
        "description": "2 element array: lat, long",
        "type": "array",
        "minItems": 2,
        "maxItems": 2,
        "items": {
          "type": "number"
        }
      },
      "velocity": {
        "description": "3 element array in m/2, speed vector of tag",
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number"
        }
      },
      "orientation3d": {
        "description": "quaternion describing a 3d orientation in local coordinate system",
        "type": "array",
        "minItems": 4,
        "maxItems": 4,
        "items": {
          "type": "number"
        }
      },
      "orientation2d": {
        "description": "2d orientation in local coordinate x-y plane in rad",
        "type": "array",
        "minItems": 3,
        "maxItems": 3,
        "items": {
          "type": "number"
        }
      },
      "inZones": {
        "description": "items of the secondaryId of the zones where the tag is located",
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "required": [
      "primaryId",
      "inZones"
    ]
  }
}

[GET /sclpositions]

Returns all sclpositions

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "description": "Profile#0002 for calculated SCL position.",
    "$comment": "after updating the rawPosition, the filter recalculate the position.",
    "properties": {
      "primaryId": {
        "description": "guaranteed to be unique locally. If referenced other collections will have same id.",
        "type": "string"
      },
      "sclProfiles": {
        "description": "profiles comes from scl",
        "type": "array",
        "uniqueItems": true,
        "items": {
          "type": "object",
          "properties": {
            "uuid": {
              "description": "the unique ID of this scl tag position calculator profile",
              "type": "string",
              "pattern": "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[1-5][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}"
            },
            "rawPositions": {
              "description": "the position array calculated by Sunstone Computation Layer",
              "type": "array",
              "items": {
                "type": "array",
                "minItems": 3,
                "maxItems": 3,
                "items": {
                  "type": "number"
                }
              }
            },
            "filteredPosition": {
              "description": "calculated by backend filter",
              "type": "array",
              "minItems": 3,
              "maxItems": 3,
              "items": {
                "type": "number"
              }
            },
            "filterSettings": {
              "description": "reserved for any setting for filter",
              "type": "object"
            }
          },
          "required": [
            "uuid",
            "filterSettings"
          ]
        }
      },
      "selector": {
        "description": "selector logic settings, selects one of sclProfile position",
        "type": "object"
      }
    },
    "required": [
      "primaryId",
      "sclProfiles",
      "selector"
    ]
  }
}

[GET /scanners]

Returns all scanners

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "uniqueItems": true,
  "items": {
    "type": "object",
    "description": "Profile#0003 scanner related properties",
    "properties": {
      "primaryId": {
        "description": "guaranteed to be unique locally. If referenced other collections will have same id.",
        "type": "string"
      },
      "pairingCode": {
        "description": "code scanned from the tag used for pairing objects",
        "type": "integer",
        "minimum": 0
      },
      "barCode": {
        "description": "barcode or QR-code of any length scanned from the object",
        "type": "string"
      },
      "scanCounter": {
        "description": "Scan counter is incremented by one on every barcode or QR-code scan ( not incremented when scanning pairingCode )",
        "type": "integer",
        "minimum": 0
      },
      "status": {
        "description": "Status variables",
        "type": "object"
      }
    },
    "required": [
      "primaryId"
    ]
  }
}

History queries

[GET /history?parameters]

get data from past

Possible parameters:

  • collection string
    The collection path name (locations, boxes, etc)
  • field string
    The collection field name (position, gpsPosition, pairedUuid)
  • from string (optional)
    From date filter in UTC, UTC time in the selected format. Default is from the short time history first timepoint
  • to string (optional)
    To date filter, UTC time in the selected format. Default is until now
  • timeformat string (optional)
    Timeformat of the from and to parameters and the output. Default is iso8601, other formats are available (see below)
  • limit number (optional)
    Maximum change per (collection, id, field) triplet. Default is all (0)
  • id filter query (optional)
    An ID filter query with a field filter structure, default is empty (no filter).

Return data schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "the ID of the thing",
        "type": "string"
      },
      "changes": {
        "description": "this array contains the changes",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "dcmTime": {
              "description": "Storage time",
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer",
                  "minimum": 0
                }
              ]
            },
            "measurementTime": {
              "description": "The device relative measured time",
              "type": "integer",
              "minimum": 0
            },
            "sensorsetbufferTime": {
              "description": "The buffered data relative sent time",
              "type": "integer",
              "minimum": 0
            },
            "value": {
              "description": "New value",
              "type": "object"
            }
          },
          "required": [
            "dcmTime",
            "value"
          ]
        }
      }
    },
    "required": [
      "id",
      "changes"
    ]
  }
}

[GET /queries/zoneTimes?parameters]

get zone statistics

Possible parameters:

  • from string (optional)
    From date filter in UTC, UTC time in the selected format. Default is from the short time history first timepoint
  • to string (optional)
    To date filter, UTC time in the selected format. Default is until now
  • timeformat string (optional)
    Timeformat of the from and to parameters and the output. Default is iso8601, other formats are available (see below)
  • zoneList list (optional)
    list of zones secondary id-s comma separated
  • id filter query (optional)
    An ID filter query with a field filter structure, default is empty (no filter).

Return data schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "description": "the ID of the thing",
        "type": "string"
      },
      "zones": {
        "description": "the zone statistics for this object",
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "zoneId": {
              "description": "The zone secondary Id",
              "type": "string"
            },
            "avgTimeSpentMs": {
              "description": "Average time spent this tag in this zone, millisec",
              "type": "number"
            },
            "stdevTimeSpentMs": {
              "description": "Standard Deviation of this tag in this zone, millisec.",
              "type": "number"
            },
            "cycleInside": {
              "description": "number of times this object went through this zone",
              "type": "integer",
              "minimum": 0
            }
          },
          "required": [
            "zoneId",
            "avgTimeSpentMs",
            "stdevTimeSpentMs",
            "cycleInside"
          ]
        }
      },
      "sampleNumber": {
        "description": "measurements count calculated to this statistics",
        "type": "integer",
        "minimum": 0
      }
    },
    "required": [
      "id",
      "zones",
      "sampleNumber"
    ]
  }
}

Timeformat examples

  • iso8601 - 2020-07-05T13:11:01.871250954+0000
  • iso8601sec - 2020-07-05T13:11:01+0000
  • asctime - Sun Jul 5 13:11:01 2020
  • sortable - 2020-07-05 13:11:01.871250954
  • rfc822 - Sun, 05 Jul 20 13:11:01 UTC
  • rfc850 - Sunday, 05-Jul-20 13:11:01 UTC
  • rfc1036 - Sunday, 05 Jul 20 13:11:01 UTC
  • rfc1123 - Sun, 05 Jul 2020 13:11:01 UTC
  • http - Sun, 05 Jul 2020 13:11:01 GMT
  • secFromEpoch - 1593954688
  • msecFromEpoch - 1593954688871
  • usecFromEpoch - 1593954688871250
  • nsecFromEpoch - 1593954688871250954

Filter query

The following format accepted in query value:

start -> andcondition
andcondition -> orcondition and
and -> nil | ';' andcondition
orcondition -> condition or
or -> nil | ',' condition
condition -> text | operator ':' text
text -> [^;,:&#]+
operator -> nil | 'equals'
operator -> '^' | 'startswith'
operator -> '$' | 'endswith'
operator -> '~' | 'contains'
operator -> '!=' | 'notequals'
operator -> '>' | 'gt'
operator -> '<' | 'lt'
operator -> '>=' | 'gte'
operator -> '<=' | 'lte'

Example:
primaryId=^:tag;~:11,$:2
this means we only want to see primaryid, whose starts to tag, and contains 11 or ends with 2