Skip to content

Data Point Naming

Data point structure

The format of a data point name is: 

liveValue.<subclass>.<asset>.<functionality>.<instance>.<topic>.<subtopic>.

The subtopic is an optional field

liveValue is the top level category of data points which are "live"; they reflect the current state of something such as a measurement of a physical system, a calculated value, or a software diagnostic. Other top value groups exist, but they are for data that is not exposed to the Rest API for performance or practical reasons.

The subclasses beneath liveValue are:

  • production. The contents of the Production subclass reflect the measured or calculated state of a physical system. Generally they should be used for inter-application communication as they reflect the process being controlled and not the source of the data. This simplifies configuration of the system.
    • liveValue.production.asset.wellHead.0.pressure.
  • state. The State subclass is used to convey the state of some software or a part of the system. They are used for the 'up' data point that apps must publish to indicate they are available.
    • liveValue.state.this.configuration.commissioning.
    • liveValue.state.this.configManager.up.
  • diagnostics. The Diagnostics subclass contains diagnostic info such as the raw voltage at a analog input, or the number of communication failures on an interface.
- ``` liveValue.diagnostics.this.io.0.hart.ch1.advancedDiagnosticReadFailed. ```
  • prevalidConfig. & postvalidConfig. The PrevalidConfig. and PostvalidConfig. subclasses enable non-volatile (persistent) data points to be re-published with their last valid value on system start. The behavior of the configuration subsystem is described in more detail below.
    • liveValue.postvalidConfig.this.modbus.0.port.tcp502.socketTimeout.
  • alarm. Alarms is a type of complex data point that is only published by the alarm and event manager service. They contain the state and details of alarms within the system.
    • liveValue.alarm.this.core.0.lowInputPowerVoltageLevel|.IsAsserted.
  • event. Events, like alarms, are also only published by the alarm and event manager service. They contain the state and details of events within the system.
    • liveValue.event.this.core.0.highInputPowerVoltageLevel|.IsAsserted.

Production, state, and diagnostics subclasses are referred to as "general" data points, and pre/postvalidConfig subclasses are referred to as "configuration" data points elsewhere in this documentation and in the Swagger UI. Alarms and events are defined via another mechanism as inputs to the alarm and event manager service. These groupings are made to simplify the APIs and documentation of these related subclasses.

Use meaningful, consistent "production" names for data points that will be mapped to an external system. This will simplify the configuration of the system and ease application inter-communication.

"Asset" refers to the physical asset connected to the HCC2 or the HCC2 itself. Currently, the only two supported values are 'this' which refers to the state of the HCC2 or software within it, and 'asset' which refers to the attached physical asset the HCC2 is controlling. These asset values will be expanded in the future to accommodate multiple assets. New asset values may take on the form asset1, asset2... with another datapoint linking the asset index to a descriptive name.

"Functionality" refers to either - The name of the application if under a this asset field - The physical system that is being managed if under an asset asset field

"Instance" refers to the instance number of the functionality. For example, it uniquely identifies each runtime if multiple instances of an application are running simultaneously. Likewise, if there are multiple of the same class of physical device as part of an asset that are not distinguished by their functionality, such as a redundant input measurement.

"Topic," possibly combined with a subtopic, is the descriptive portion of the name that ensures the data point is unique.

Naming rules

General Rules

Do not change the definition or meaning of a data point:

When a data point has been defined, do not change what it means and in turn, do not change its content. If you must change this information, define a new data point and deprecate the older data point. This will ensure that a change to data points in one application will not break an older application that uses the same data points and the applications will remain backward compatible.

Logical Grouping:

The logical grouping of the data points should be from the device viewpoint and not from the internal Application or Module viewpoint.

Device-Wide Data Points:

“All data points are device-wide“ means that Sensia does not duplicate information as two data points. E.g. A wellhead pressure sensor is connected to a device and the ESP and the BOM both need that pressure data point as an input. In this scenario, both products will subscribe to one data point only, and its definition is the same for both applications.

Maintaining this arrangement requires discipline. Before defining a new data point, one must confirm that the data point doesn't already exist in an application.

Naming Convention

Make sure names are aligned with the names used in Avalon. The following are salient points:

  • use camel case
  • do not use abbreviated names unless explicitly listed below (i.e., use temperature instead of temp)
    • Min/Max
    • VFD when referring to Variable Frequency Drive
  • do not use underscores or hyphens

Special Characters

The following characters require special attention

. (period) - A period delineates the data point name as described above. A trailing period allows a subscription to explicitly refer to a single data point. For example, a subscription ending in alarm.low. would not accidentally return the data point published on the topic ending in alarm.lowlow.

[ and ] - To avoid confusion or parsing errors, square brackets are not allowed in a data point name for two reasons. First, they are used to reference the index of a value within a data point that contains array data, a type of complex message. Secondly, they are sometimes used in documentation to reference parts of a data point name that are optional.

| (pipe) - A pipe indicates a message that contains multiple data points. When used, there shall be only one pipe and it must be placed immediately before the trailing dot in the message name/subscription topic. This is known as a complex data point or a complex message

_ (underscore) - An underscore identifies a metadata data point that is a property of another data point.