chimps

Spatial-temporal dynamics processor for context-aware physical spaces and companion to barnacles.

chimps ingests a real-time stream of raddec objects and outputs spatem (SPAtial-TEMporal) objects based on positions calculated internally by positioning engines and/or externally by third-party systems.

chimps is a lightweight Node.js package that can run on resource-constrained edge devices as well as on powerful cloud servers and anything in between. It is typically connected with a barnowl and/or barnacles instance which sources real-time radio decodings from an underlying hardware layer. Together these packages are core components of reelyActive's Pareto Anywhere open source middleware.

Getting Started

Follow our step-by-step tutorials to get started with chimps bundled within Pareto Anywhere:

• Run Pareto Anywhere on a PC
• Run Pareto Anywhere on a Raspberry Pi

Learn "owl" about the spatem JSON data output:

• reelyActive Developer's Cheatsheet

Quick Start

Clone this repository, install package dependencies with npm install, and then from the root folder run at any time:

npm start

chimps will listen for raddec UDP packets on 0.0.0.0:50001 and print the spatial-temporal (spatem) data to the console.

spatem

The format of the spatem object, which is the sole output of chimps, is as follows:

{
  deviceId: "bada55beac04",
  deviceIdType: 2,
  type: "location", // "position" or "location"
  data: { /* FeatureCollection */ },
  timestamp: 1645568542222
}

In the case where the position of the associated raddec cannot be matched with any Features in chimps' FeatureCollection, the spatem type will be a position and include a FeatureCollection of exactly one item, a "Point", as its data property. Else, the spatem type will be a location and include a FeatureCollection which adds all matched Features as its data property. Each type of spatem is described in full detail below.

position

A spatem of type position has the following format:

{
  deviceId: "bada55beac04",
  deviceIdType: 2,
  type: "position",
  data: {
    type: "FeatureCollection",
    features: [{
      type: "Feature",
      properties: { isDevicePosition: true, positioningEngine: "External" },
      geometry: {
        type: "Point",
        coordinates: [ 0.0, 0.0, 0.0 ]
      }
    }]
  },
  timestamp: 1645568542222
}

chimps adds the property isDevicePosition to indicate that the "Point" represents the device position, as per the raddec.

location

A spatem of type location has the following format:

{
  deviceId: "bada55beac04",
  deviceIdType: 2,
  type: "location",
  data: {
    type: "FeatureCollection",
    features: [{
      type: "Feature",
      properties: { isDevicePosition: true,
                    positioningEngine: "AnchorAndPull" },
      geometry: {
        type: "Point",
        coordinates: [ 0.0, 0.0, 0.0 ]
      }
    },{
      type: "Feature",
      id: "(from chickadee)",
      properties: { name: "" },
      geometry: {
        type: "Polygon",
        coordinates: [[[ 0, 1 ], [ 1, 0 ], [ 0, -1 ], [ -1, 0 ], [ 0, 1 ]]]
      }
    }
  ]},
  timestamp: 1645568542222
}

Note that the first feature in the FeatureCollection will always be the "Point" representing the device position as per the raddec, with chimps adding the property isDevicePosition to differentiate from any other associated "Point" which may be present in the FeatureCollection.

Positioning Engines

chimps supports both internal and external positioning engines for estimating the real-time position of devices based on radio decodings and metadata. Positioning engines are configured through the positioningEngines option which has the following default setting:

[
  { inputFilterParameters: {}, engine: PositioningEngines.External },
  { inputFilterParameters: {
        acceptedEvents: [ Raddec.events.APPEARANCE,
                          Raddec.events.DISPLACEMENT,
                          Raddec.events.KEEPALIVE ] },
    engine: PositioningEngines.AnchorAndPull }
]

The first positioning engine in the array to meet the inputFilterParameters criteria and return a position will be observed. In other words, the positioning engines are priority-based and mutually exclusive.

The default setting prioritises external (third-party) positioning engines which add a position property to the raddec before it is ingested by chimps. If no position property is present, instead the anchor-and-pull engine will provide a position estimate, when possible, upon ingestion of a raddec from barnacles which corresponds with an appearance, displacement or keepalive event.

A user-defined positioning engine can be specified by providing as the engine property a Class which includes an estimatePosition function which takes as parameters a raddec and associations. For example:

engine:
  class AlwaysAtParc {
    constructor(options) {}
    estimatePosition(raddec, associations) {
      return [ -73.57123, 45.50883 ];
    }
  }

Be advised that RSSI-based positioning in real-world conditions, especially with ambient devices and existing infrastructure, is inherently limited in accuracy. The anchor-and-pull method is provided as a low-overhead means to output "good enough" positions for applications which must consume data in the form of coordinates. If highly-accurate coordinate-based positioning is absolutely required, instead select the appropriate technologies and infrastructure that add a position property before it is ingested by chimps.

Options

chimps supports the following options:

| Property | Default | Description | |:-----------------------|:--------|:---------------------------------------| | inputFilterParameters | {} | Filter on inbound raddecs (see raddec-filter) | | observedEvents | [ 'position', 'location' ] | List of event types that will produce a spatem output | | maxStoredSpatems | 1 | The number of historic spatems to maintain in memory per device | | historyMilliseconds | 5000 | How long to retain spatem data before it is flushed from memory | | featureCollection | {} | Explicit FeatureCollection to use in the absence of a connected chickadee instance | | associations | Map() | Explicit device associations to use in the absence of a connected chickadee instance | | positioningEngines | (see above) | The positioning engines and parameters to use to estimate device positions | | barnowl | null | barnowl instance providing source data | | barnacles | null | barnacles instance providing source data |

What's in a name?

Chimpanzees (chimps) have outstanding spatial awareness. chimps is our first mascot-nameworthy module since perhaps 2015, and we intend to continue our tradition of mascot name storytelling, so check back soon!

Project History

chimps v1.0.0 was released in October 2022, developed to accommodate 2D and 3D real-time location data, initially from barnowl-rfcontrols.

Contributing

Discover how to contribute to this open source project which upholds a standard code of conduct.

Security

Consult our security policy for best practices using this open source software and to report vulnerabilities.

License

MIT License

Copyright (c) 2022-2023 reelyActive

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.