# Alarms and Events
Until now, in the type definitions overview you have learnt that your models may contain:
- variables
- methods
- attributes
In this article we will present to you two other categories of data that your models could use:
- events
- alarms
The reason why we did not describe them in the overview of type definitions is because these categories are a bit different. Instead of defining them in the type definitions themselves, they have their own definitions, separate from the types that use them. Actually, this is not only type definitions that may use alarms and events. Type definitions, model definitions, and object extensions all allow you to add alarm/events information to them. This makes alarms/events reusable - you define them once, and you're able to reuse them many times. You may think of it as an analogy to composition in the object-oriented programming.
Whatever is your target for the alarm/event, first you need to create their definitions.
# Definitions
# Alarm Definition
{
"alarmDefinitionId": "abb.ability.Unique.Identificator",
"name": "Alarm Definition for Unique Identificator",
"tags": ["BaseAlarm",
"alarm"],
"version": "1.0.0",
"state": {
"acknowledgeTimeStamp": {
"dataType": "string"
},
"category": {
"limitState": {
"dataType" : "string",
"enum" : ["low", "high", "none"]
}
}
}
}
Above you can see an example of an alarm. It has its own unique
alarmDefinitionId (just like a type definition has its unique typeId),
semantic version, and, optionally, a state. The state is where you define a
custom set of information that your alarm should be carrying. Whenever your
alarm is raised, it will most likely have some information attached - that's
state. Similar to type definitions, names and tags can also be specified for alarms.
# Event Definition
{
"eventDefinitionId": "abb.ability.Unique.Identificator",
"name": "Event Definition for Event Identificator",
"tags": ["BaseEvent",
"events"],
"version": "1.0.0",
"fields": {
"kilos": {
"dataType": "number",
"unit": "Kg"
},
"category": {
...
"limitState": {
"dataType" : "string",
"enum" : ["low", "high", "none"]
}
}
}
}
Just like with alarms, each event definition is characterized by a unique
eventDefinitionId, semantic version, and a set of metadata - this time it's
called fields. The role of fields is pretty much the same as alarm's state -
this is where you may include any information that a given event requires to
have to be useful. Similar to type definitions, alarm/event names and tags can also be specified.
API Specifications
You can find more details about APIs of these definitions in their respective API specifications: alarms, events.
# Usage
As mentioned already, alarms/events may be used in model definitions, type definitions, and object extensions. Let's have a look at how to attach them to these.
Definitions must have unique IDs
It is not allowed to use the same ID for multiple Alarms and Events definitions.
Alarms and Events IDs duplication is not supported.
Order of definitions creation
The order of definitions creation is important - before making use of some alarm/event definition, make sure that it has already been created by you or someone else. Otherwise, the model/type/object extension creation will return an error. It is the same as with the type definitions and objects. Before you create an object based on some type, the type needs to exist.
# Model Definitions
{
"modelId": "abb.processAutomation.control",
"name": "ModelDefinition for control elements",
"description": "ModelDefinition for control elements in the process automation domain.",
"tags": [
"Process Automation",
"Control",
"IEC61131-3"
],
"components": {
"properties": {
"propertyName": {
"dataType": "string"
}
},
"variables": {
"variableName": {
"dataType": "number"
}
},
"events": {
"eventName": {
"dataType": "EventDefinitionId@Mj"
}
},
"alarms": {
"alarmName": {
"dataType": "AlarmDefinitionId@Mj"
}
}
}
}
As you can see above, the exemplary model definition is defined to contain:
- some property
- some variable
- an event of type
EventDefinitionId@Mj - an alarm of type
AlarmDefinitionId@Mj
Both the alarm and the event have some names assigned (alarmName and
eventName) in the context of this specific model definition.
# Type Definition
{
"model": "abb.processAutomation.control",
"typeId": "abb.processAutomation.sensors.smartSensorTag",
"version": "1.0.0",
"name": "SmartSensor Tag Type Version 1.0.0",
"tags": [
"Process Automation",
"Sensor"
],
"properties": {
"someProperty": {
"dataType": "string"
}
},
"variables": {
"someVariable": {
"dataType": "number"
}
},
"events": {
"someEvent": {
"dataType": "EventDefinitionId@1"
}
},
"alarms": {
"someAlarm": {
"dataType": "AlarmDefinitionId@1"
}
}
}
In the type definition, it's not really different from what we have seen in a model definition. We just reused the existing event and alarm to include it in the type as well. Any object model based on this type will be able to make use of the included events/alarms.
# Holistic View
One interesting point about type definitions is that they might be viewed holistically. This is how a type definition above will be seen holistically:
{
"model": "abb.processAutomation.control",
"typeId": "abb.processAutomation.sensors.smartSensorTag",
"version": "1.0.0",
"name": "SmartSensor Tag Type Version 1.0.0",
"tags": [
"Process Automation",
"Sens"
],
"properties": {
"someProperty": {
"dataType": "string"
}
},
"variables": {
"someVariable": {
"dataType": "number"
}
},
"events": {
"someEvent": {
"fields": {
"var1": {
"dataType": "string"
},
"var2": {
"dataType": "string"
}
}
}
},
"alarms": {
"someAlarm": {
"state": {
"var1": {
"dataType": "number"
}
}
}
}
}
As you can see, the alarm and event definitions have been "injected" into the type definition's JSON. This way, you can see the complete type, as if the events and alarm definitions were part of it - in reality, they're not. The type just uses them, and they were defined separately.
# Attributes
A type that includes some alarm or event may add some attributes to them. Have a look at an example below:
{
"model": "abb.processAutomation.control",
"typeId": "abb.processAutomation.sensors.smartSensorTag",
"version": "2.0.0",
"name": "SmartSensor Tag Type Version 1.0.0",
"tags": [
"Process Automation",
"Sens"
],
"properties": {
"someProperty": {
"dataType": "string"
}
},
"variables": {
"someVariable": {
"dataType": "number"
}
},
"events": {
"someEvent": {
"dataType": "EventDefinitionId@1",
"definitionAttr": "Start",
"eventAttr": "Low"
}
},
"alarms": {
"someAlarm": {
"dataType": "AlarmDefinitionId@1",
"alarmAttr": "high"
}
},
"attributes": {
"definitionAttr": {
"dataType": "string",
"appliesTo": [
"alarm",
"event"
]
},
"alarmAttr": {
"dataType": "string",
"appliesTo": [
"alarm"
]
},
"eventAttr": {
"dataType": "string",
"appliesTo": [
"event"
]
}
}
}
As you can see, three attributes were defined:
definitionAttr- it may be applied to both alarms and events, as specified in theappliesToarray;alarmAttr- it may be applied only to alarms;eventAttr- it may be applied only to events.
All of the mhave been used for our alarms and events.
# Extensions
When creating an object model extension, you may extend it with an alarm/event. Have a look at an example below:
"alarms": {
"alarmName": {
"dataType": "AlarmDefinitionId@1"
}
}
}
This is a paylaod that could be sent to the PUT extensions
endpoint.
It would add an alarmName to the specific objectId.
# Summary
Alarms and evnet are another kinds of definitions that are there to help you model your devices (or, more generally, use-cases). You may use them whenever it fits into your project.