Core Metadata

Introduction

The core metadata micro service has the knowledge about the devices and sensors and how to communicate with them used by the other services, such as core data, core command, and so forth.

Specifically, metadata has the following abilities:

• Manages information about the devices connected to, and operated by, EdgeX Foundry
• Knows the type, and organization of data reported by the devices
• Knows how to command the devices

Although metadata has the knowledge, it does not do the following activities:

• It is not responsible for actual data collection from devices, which is performed by device services and core data
• It is not responsible for issuing commands to the devices, which is performed by core command and device services

Data Models

To understand metadata, its important to understand the EdgeX data objects it manages. Metadata stores its knowledge in a local persistence database. Redis is used by default, but a database abstraction layer allows for other databases to be used.

Device Profile

Device profiles define general characteristics about devices, the data they provide, and how to command them. Think of a device profile as a template of a type or classification of device. For example, a device profile for BACnet thermostats provides general characteristics for the types of data a BACnet thermostat sends, such as current temperature and humidity level. It also defines which types of commands or actions EdgeX can send to the BACnet thermostat. Examples might include actions that set the cooling or heating point. Device profiles are typically specified in YAML file and uploaded to EdgeX. More details are provided below.

Device Profile Details

Metadata device profile object model

name: "BAC-9001"
manufacturer: "KMC"
model: "BAC-9001"
labels: 
    - "B-AAC"
description: "KMC BAC-9001 BACnet thermostat"

name: Temperature
description: "Get the current temperature"
isHidden: false

name: ActiveCoolingSetpoint
description: "The active cooling set point"
isHidden: false

-
    name: Temperature
    description: "Get the current temperature"
    isHidden: false
    attributes: 
        { type: "analogValue", instance: "1", property: "presentValue", index: "none"  }
-
    name: ActiveCoolingSetpoint
    description: "The active cooling set point"
    isHidden: false
    attributes:
        { type: "analogValue", instance: "3", property: "presentValue", index: "none"  }

name: Temperature
description: "Get the current temperature"
attributes: 
    { type: "analogValue", instance: "1", property: "presentValue", index: "none"  }
properties: 
    valueType: "Float32"
    readWrite: "R"
    units: "Degrees Fahrenheit"

Device

Data about actual devices is another type of information that the metadata micro service stores and manages. Each device managed by EdgeX Foundry registers with metadata (via its owning device service. Each device must have a unique name associated to it.

Metadata stores information about a device (such as its address) against the name in its database. Each device is also associated to a device profile. This association enables metadata to apply knowledge provided by the device profile to each device. For example, a thermostat profile would say that it reports temperature values in Celsius. Associating a particular thermostat (the thermostat in the lobby for example) to the thermostat profile allows metadata to know that the lobby thermostat reports temperature value in Celsius.

Device Service

Metadata also stores and manages information about the device services. Device services serve as EdgeX's interfaces to the actual devices and sensors.

Device services are other micro services that communicate with devices via the protocol of that device. For example, a Modbus device service facilitates communications among all types of Modbus devices. Examples of Modbus devices include motor controllers, proximity sensors, thermostats, and power meters. Device services simplify communications with the device for the rest of EdgeX.

When a device service starts, it registers itself with metadata. When EdgeX provisions a new devices the device gets associated to its owning device service. That association is also stored in metadata.

Metadata Device, Device Service and Device Profile Model

Metadata's Device Profile, Device and Device Service object model and the association between them

Provision Watcher

Device services may contain logic to automatically provision new devices. This can be done statically or dynamically. In static device configuration (also known as static provisioning) the device service connects to and establishes a new device that it manages in EdgeX (specifically metadata) from configuration the device service is provided. For example, a device service may be provided with the specific IP address and additional device details for a device (or devices) that it is to onboard at startup. In static provisioning, it is assumed that the device will be there and that it will be available at the address or place specified through configuration. The devices and the connection information for those devices is known at the point that the device service starts.

In dynamic discovery (also known as automatic provisioning), a device service is given some general information about where to look and general parameters for a device (or devices). For example, the device service may be given a range of BLE address space and told to look for devices of a certain nature in this range. However, the device service does not know that the device is physically there – and the device may not be there at start up. It must continually scan during its operations (typically on some sort of schedule) for new devices within the guides of the location and device parameters provided by configuration.

Not all device services support dynamic discovery. If it does support dynamic discovery, the configuration about what and where to look (in other words, where to scan) for new devices is specified by a provision watcher. A provision watcher, is specific configuration information provided to a device service (usually at startup) that gets stored in metadata. In addition to providing details about what devices to look for during a scan, a provision watcher may also contain “blocking” indicators, which define parameters about devices that are not to be automatically provisioned. This allows the scope of a device scan to be narrowed or allow specific devices to be avoided.

Metadata's provision watcher object model

Data Dictionary

High Level Interaction Diagrams

Sequence diagrams for some of the more critical or complex events regarding metadata. These High Level Interaction Diagrams show:

1. Adding a new device profile (Step 1 to provisioning a new device) via metadata
2. Adding a new device via metadata (Step 2 to provisioning a new device)
3. EdgeX Foundry device service startup (and its interactions with metadata)

Add a New Device Profile (Step 1 to provisioning a new device)

Add a New Device (Step 2 to provisioning a new device)

What happens on a device service startup?

Configuration Properties

Please refer to the general Common Configuration documentation for configuration settings common to all services. Below are only the additional settings and sections that are specific to Core Metadata.

V3 Configuration Migration Guide

• Removed RequireMessageBus
• UoMFile value changed to point to YAML file instead of TOML file

See Common Configuration Reference for complete details on common configuration changes.

Device System Events

Device System Events are events triggered by the add, update or delete of devices. A System Event DTO is published to the EdgeX MessageBus each time a new Device is added, an existing Device is updated or when an existing Device is deleted.

System Event DTO

The System Event DTO has the following properties:

Publish Topic

The System Event DTO for Device System Events are published to the edgex/system-events base topic with the following data items, which are added to allow receivers to filter by subscription.

• source = core-metadata
• type = device
• action = add/update/delete
• owner = [device service name which owns the device]
• profile = [device profile name associated with the device]

edgex/system-events/core-metadata/device/add/device-onvif-camera/onvif-camera
edgex/system-events/core-metadata/device/update/device-rest/sample-numeric
edgex/system-events/core-metadata/device/delete/device-virtual/Random-Boolean-Device

Units of Measure

Core metadata will read unit of measure configuration (see configuration example below) located in UoM.UoMFile during startup. The specified configuration may be a local configuration file or the URI of the configuration. See the URI for Files section for more details.

Source: reference to source for all UoM if not specified below
Units:
  temperature:
    Source: www.weather.com
    Values:
      - C
      - F
      - K
  weights:
    Source: www.usa.gov/federal-agencies/weights-and-measures-division
    Values:
      - lbs
      - ounces
      - kilos
      - grams

When validation is turned on (Writable.UoM.Validation is set to true), all device profile units (in device resource, device properties) will be validated against the list of units of measure by core metadata.

In other words, when a device profile is created or updated via the core metadata API, the units specified in the device resource's units field will be checked against the valid list of UoM provided via core metadata configuration.

If the units value matches any one of the configuration units of measure, then the device resource is considered valid - allowing the create or update operation to continue. If the units value does not match any one of the configuration units of measure, then the device profile or device resource operation (create or update) is rejected (error code 500 is returned) and an appropriate error message is returned in the response to the caller of the core metadata API.

API Reference

Core Metadata API Reference