Skip to main content

Core Concepts

Hivekit is designed as a data platform for geospatial applications. To get the most out of it, it is important to understand its core concepts and how they relate to each other.

Realm​

A realm is a space within which something happens. It can be as small as a single room or as large as the entire world. All other concepts, such as Objects, Areas, Instructions, Subscriptions exist within the scope of a realm.

Object​

An object represents a single physical entity within a realm. It can be a vehicle, a worker with a smartphone, a sensor, or any other thing with a location and associated data.

Each object can have the following properties:

  • an id that is unique for this object within the realm
  • a label that describes the object
  • a connection status, telling you if the object is receiving regular updates
  • a location that can be as simple as latitude and longitude coordinates or can encompass additional information like altitude, heading, speed, precision, etc.
  • a map of arbitrary data - e.g., the charge of an e-scooter, the value reading of a sensor, or the phone number of a delivery driver

Area​

An area represents a space within the world, e.g. a part of a city, a field on a farm, or a security zone within a mining site. Areas can be rectangles, circles, or polygons. You can use areas for subscriptions and instructions, e.g. to find all objects inside an area or trigger a function if an object leaves an area. You can also use areas within the Hivekit App to visualize things on a map, e.g. to show soil moisture as a heatmap overlayed over a field.

Each area can have the following properties:

  • an id that is unique to this area within the realm
  • a label describing the area
  • a shape that defines the boundaries of the area
  • a map of arbitrary data such as the color of the area, the name of the part of the city that it represents, etc.

Subscription​

A subscription provides a realtime data feed based on a set of criteria. You can subscribe to pretty much everything within Hivekit, e.g., objects in an area, realm creation, instruction output, etc. Subscriptions take a set of query arguments that let you define what exactly you would like updates for, e.g., "give me a feed of all scooters in Manhattan with a charge below 20%" or "show me all of my employees within 15 meters of the watercooler".

Instruction​

An instruction is a bit of code, written in HiveScript that is executed by Hivekit based on incoming changes. Instructions are extremely powerful when it comes to automatically reacting to changes or to automating business processes.

Task​

A task is something that one or multiple objects have to do. You can use tasks to tell workers to go to a specific location and perform a certain action there. Or you can use tasks to remote control machines. Hivekit makes it easy to create external processes that subscribe to the list of existing tasks and translate them into e.g., smartphone notifications, machine commands, or cards in a project management tool. Each task can have the following properties:

  • a status (e.g. open, in progress, done)
  • a priority (from 1 to infinity)
  • one or more objects that need to perform the task
  • a subject - another object that the task has to be performed on. Think "maintenance worker Frank (object), check on faulty sensor #17 (subject)"
  • a location where the task needs to be performed at. If a subject is configured, the location is the location of the subject

Task List​

Task lists combine multiple tasks into a schedule. This makes it possible to create routes for delivery drivers, provide agendas for workers or define maintenance schedules for machines. -->

Presence​

Presence tells you which objects within your realm are actively being supplied with data. This is useful if you want to know if your delivery rider's smartphones are still connected, if a user has just come online or if your server-side data-sources are up and running.

Publish/Subscribe​

Each realm comes with a generic publish/subscribe mechanism that makes it easy to share information between users or send notifications from the backend.

History​

Every update to any object within Hivekit is stored and accessible via the realm's history. This makes it possible to show the routes a driver took on a map or to analyze the movements leading up to an accident.

Meta Data​

Most Hivekit concepts like Realms, Objects, Areas or Instructions have a data property that lets you specify free form meta data. This is useful in countless ways, e.g. to store the values of a sensor, the charge of a battery, to specify how an area should be displayed on your map, which categories a realm should structure objects in, the person and time that created an instruction and much more.

Hivekit provides a lot of functionality to search, filter or subscribe to entities using their meta data.

IDs & Id Patterns​

Almost all concepts within Hivekit, such as Objects, Areas, Instructions etc. are identified by an id. Ids are simple strings that must be unique within a given realm. You can create a unique ID from most client libraries, using client.getId('car/') which will return a nanoid with the given prefix.

Many Hivekit concepts such as Permissions, PubSub, Presence or the Hivekit App also support the use of "Id Patterns". If you assign ids with slashes, e.g. "car/mycar-123" or "courier/cyclist/OJV0PQXRhLPKqRHKAMiiF" you can use these to permission or register data providers against, e.g. by denoting "car/*" to match all cars or "courier/*/OJV0PQXRhLPKqRHKAMiiF" to specify a courier, regardless of mode of transport.

Attribute Selectors​

Certain methods like listing or subscribing allow you to specify the results you are interested in by using "attribute selectors". These are key-comparator-value strings that Hivekit uses to match against an entities data. Say, e.g. we only want our list to include scooters with a charge lower than 20%, we'd add the following set of attribute selectors: ["type=scooter", "charge<0.2"].

All attribute selectors are combined as AND - meaning an object only matches if all criteria are fulfulled. Attribute Selectors support the following operators:

  • = equals
  • != not equal
  • < lesser than
  • > greater than

There are also some special attributes that can be filtered against. These are prefixed by $ and include:

  • $id the id of the object or area
  • $lastUpdate the time of the last update made to an object, as a UNIX timestamp in seconds

Using these, you can e.g. filter out subscription updates for your own object by adding ['$id!=myId'] or ignore objects created more than 60 minutes ago via ['$lastUpdate>' + Math.floor(Date.now()/1000) - 3600]