Models #

In order to model a use case, it is possible to define models of sensors and assets that will be used when creating digital twins.

Each sensor or asset is an instance of a previously defined model.

Models can be defined upstream through the backend framework but also dynamically using the API.

Sensor Model #

A sensor model contains the following information:

• model: model name
• measures: received measurements
• icon: (optional) Icon representing the device model. Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup — the format is up to the application. Not indexed for search.
• decoder: (optional) instance of a [Decoder] to normalize the data
• metadataMappings: (optional) metadata mappings (See Collection Mappings)
• defaultMetadata: (optional) default metadata values
• metadataDetails: (optional) Translations, metadata group and editor hint.
  • Translations: you can use it to keep consistency on translations between your apps.
  • Group: metadata can be displayed grouped, you need to define metadataGroups to use it.
  • Editor hint: it unlock functionalities depending on the metadata type you define.
• metadataGroups: (optional) Map of group names to their translations. You can use it to group metadata.

It is possible to create new models on the Kuzzle IoT Platform using either:

• the API through the action device-manager/models:writeDevice
• the framework with the method deviceManager.models.registerDevice

Example: declaration of a model via API

import {
  ApiModelWriteDeviceRequest,
  ApiModelWriteDeviceResult,
} from "kuzzle-device-manager-types";

(await sdk.query) < ApiModelWriteDeviceRequest,
  ApiModelWriteDeviceResult >
    {
      controller: "device-manager/models",
      action: "writeDevice",
      body: {
        model: "Enginko",
        measures: [
          { name: "temperatureInternal", type: "temperature" },
          { name: "temperatureExternal", type: "temperature" },
        ],
      },
    };

The API also allows to:

• list available devices models device-manager/models:listDevices
• get a device model device-manager/models:getDevices
• search device models device-manager/models:searchDevices
• delete a device model device-manager/models:deleteDevice

Measure Model #

A measure model contains the following information:

• model: model name
• measure: type of the measure
• icon: (optional) Icon representing the measure model. Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup — the format is up to the application. Not indexed for search.
• valuesMappings: measurements mappings (See Collection Mappings)
• valuesDetails: (optional) Metadata and translations of measurements. You can use it to keep consistency on translations between your apps
• locales: (optional) Translation for the measure model

It is possible to create new models on the Kuzzle IoT Platform using either:

• the API through the action device-manager/models:writeMeasure
• the framework with the method deviceManager.models.registerMeasure

Example: declaration of a model via API

await sdk.query({
  controller: "device-manager/models",
  action: "writeMeasure",
  body: {
    type: "light",
    valuesMappings: {
      light: { type: "integer" },
    },
    valuesDetails: {
      light: {
        en: {
          friendlyName: "Light intensity",
          unit: "lux",
        },
        fr: {
          friendlyName: "Intensité lumineuse",
          unit: "lux",
        },
      },
    },
    locales: {
      en: {
        modelFriendlyName: "Light measurement",
        modelDescription: "Light measurement",
      },
      fr: {
        modelFriendlyName: "Mesure de lumière",
        modelDescription: "Mesure de lumière",
      },
    }
  },
});

The API also allows to:

• list registered measures device-manager/models:listMeasures
• get a measure model device-manager/models:getMeasure
• search measure models device-manager/models:searchMeasures
• delete a measure model device-manager/models:deleteMeasure

Asset Model #

Unlike sensors and metrics which are available for all engine groups, asset models are specific to a particular engine group.

An asset model contains the following information:

• model: model name
• engineGroup: engine group to which the model belongs.
• measures: received measurements
• icon: (optional) Icon representing the asset model. Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup — the format is up to the application. Not indexed for search.
• metadataMappings: (optional) metadata mappings (See Collection Mappings)
• defaultMetadata: (optional) default metadata values-
• metadataDetails: (optional) Translations, metadata group and editor hint.
  • Translations: you can use it to keep consistency on translations between your apps.
  • Group: metadata can be displayed grouped, you need to define metadataGroups to use it.
  • Editor hint: it unlock functionalities depending on the metadata type you define.
• metadataGroups: (optional) Map of group names to their translations. You can use it to group metadata.
• tooltipModels: (optional) Tooltip model list, each containing labels and tooltip content to be shown. You can use it to create templates that displays relevant information in dashboards
• locales: (optional) Translation for asset model

It is possible to create new models on the Kuzzle IoT Platform using either:

• the API through the device-manager/models:writeAsset action
• the framework with the method deviceManager/models.registerAsset

Example: declaration of a model via API

import {
  ApiModelWriteAssetRequest,
  ApiModelWriteAssetResult,
} from "kuzzle-device-manager-types";

(await sdk.query) < ApiModelWriteAssetRequest,
  ApiModelWriteAssetResult >
    {
      controller: "device-manager/models",
      action: "writeAsset",
      engineGroup: "asset_tracking",
      body: {
        model: "Container",
        measures: [
          { name: "temperatureInternal", type: "temperature" },
          { name: "temperatureExternal", type: "temperature" },
        ],
        locales: {
          en: {
            friendlyName: "Container translated by model",
            description: "Containerized container",
          },
          fr: {
            friendlyName: "Conteneur traduit par modèle",
            description: "Conteneur conteneurisé",
          },
        }
      },
    };

INFO: If the locales has changed, use updateModelLocales to update all assets manually and make the search on assets up to date

The API also allows to:

• list available models device-manager/models:listAssets
• get a model device-manager/models:getAssets
• search asset models device-manager/models:searchAssets
• delete a asset model device-manager/models:deleteAsset

Group Model #

A group model defines the structure and metadata for groups of devices or assets. Group models allow you to organize devices and assets into logical collections, apply permissions, and manage group-specific metadata.

A group model contains the following information:

• model: Group model name.
• affinity: Specifies the types and models of elements accepted in the group.
  • type: Array of accepted element types, possible values are "assets" and/or "devices".
  • models: Object specifying which models are accepted for each type.
    • assets: List of asset model names accepted in the group.
    • devices: List of device model names accepted in the group.
  • strict: Boolean indicating whether the affinities are a strict restriction (true) or just a suggestion (false). If strict is true, only the specified types and models can be added to the group.
• icon: (optional) Icon representing the group model. Free-form string, e.g. a FontAwesome icon name, a URL to a PNG/SVG image, or inline SVG markup — the format is up to the application. Not indexed for search.
• metadataMappings: (optional) Metadata mappings for group-specific information (see Collection Mappings).
• defaultMetadata: (optional) Default metadata values for the group.
• metadataDetails: (optional) Translations, metadata group, and editor hints for group metadata.
  • Translations: Ensures consistency of metadata translations across applications.
  • Group: Allows metadata to be displayed in groups; define metadataGroups to use this feature.
  • Editor hint: Unlocks functionalities depending on the metadata type you define.
• metadataGroups: (optional) Map of group names to their translations, used to group metadata fields.
• tooltipModels: (optional) Tooltip model list, each containing labels and tooltip content to be shown. You can use it to create templates that display relevant information in dashboards.
• locales: (optional) Translation for group model

You can create new group models on the Kuzzle IoT Platform using either:

• the API through the action device-manager/models:writeGroup
• the framework with the method deviceManager.models.registerGroup

Example: declaration of a group model via API

await sdk.query({
  controller: "device-manager/models",
  action: "writeGroup",
  body: {
    model: "ParkingGroup",
    affinity: {
      type: ["assets", "devices"],
      models: {
        assets: ["ParkingSpot", "ParkingBarrier"],
        devices: ["ParkingSensor"]
      },
      strict: true
    },
    metadataMappings: {
      location: { type: "geo_point" }
    },
    defaultMetadata: {
      location: {
        lat: 41.12,
        lon: -71.34
      }
    },
    metadataDetails: {
      location: {
        group: "geolocation",
        locales: {
          en: {
            friendlyName: "Parking location",
            description: "The coordinates of the parking area"
          },
          fr: {
            friendlyName: "Localisation du parking",
            description: "Les coordonnées GPS du parking"
          }
        }
      }
    },
    metadataGroups: {
      geolocation: {
        locales: {
          en: {
            groupFriendlyName: "Parking geolocation",
            description: "The parking geolocation"
          },
          fr: {
            groupFriendlyName: "Localisation du parking",
            description: "La localisation du parking"
          }
        }
      }
    },
    tooltipModels: {
      defaultTooltipKey: {
        tooltipLabel: "Default Tooltip Model",
        content: [
          {
            category: "metadata",
            label: {
              locales: {
                en: {
                  friendlyName: "Parking location",
                  description: ""
                },
                fr: {
                  friendlyName: "Localisation du parking",
                  description: ""
                }
              }
            },
            metadataPath: "location"
          }
        ]
      }
    },
    locales: {
      en: {
        friendlyName: "Parking group translated by model",
        description: "Group of parking assets and devices"
      },
      fr: {
        friendlyName: "Groupe de parking traduit par modèle",
        description: "Groupe d'actifs et d'appareils de parking"
      }
    }
  }
});

The API also allows you to:

• list available group models device-manager/models:listGroups
• get a group model device-manager/models:getGroup
• search group models device-manager/models:searchGroups
• delete a group model device-manager/models:deleteGroup