Event types
←Message types · Index↑ · Core models→
This document specifies the supported event types and the strategies employed to define them.
Other sections can be accessed from the Overview.
1. Introduction
These are the supported event types:
- boolean
- string
- number
- enum
- object (out of scope for version 1.0 of this specification)
The types are identified by the corresponding values in the event_type field in an event message and the NMOS source. When additional restrictions are applied to an event type, the type definition object will be provided using the Event & Tally REST API (see Event & Tally REST API). The type definition object will always define the type of the value
field and can define restrictions on the value.
2. Base types
The base type payloads always contain the "value"
field and the type of the field in JSON corresponds to the base type.
2.1 boolean
The boolean event type will be identified as "boolean"
in the NMOS source.
Example:
A simple button indicating its condition as a boolean value (is the button pressed)
Event Type:
boolean
Payload:
{
"value": true
}
or
{
"value": false
}
Type definition:
{
"type": "boolean"
}
2.2 string
The string event type will be identified as "string"
in the NMOS source.
The event type may be associated with a type definition object that may apply the following restrictions:
- minimum length [optional]
- maximum length [optional]
- pattern (regular expression) [optional]
Example:
A simple label on a button or on another UI element.
Event Type:
string
Payload:
{
"value": "my label"
}
Type definition:
{
"type": "string",
"min_length": 1,
"max_length": 30
}
2.3 number
The number event type will be identified as "number"
in the NMOS source.
In addition to the mandatory value
field, an optional scale
field is introduced to help carrying rational numbers without any loss of the precision. In that case the value
field represents the numerator and the scale
field represents the denominator of the fraction.
The event type may be associated with a type definition object that may apply the following restrictions:
- indicate an optional
scale
field for representing rational numbers [optional] (default = 1) - indicate minimum value [mandatory]
- indicate maximum value [mandatory]
- indicate step value [optional] (default = 1)
- indicate the measurement unit [optional]
Payload examples:
Example:
A simple 32-bit counter.
Event Type:
number
Payload:
{
"value": 16342
}
Type definition:
{
"type": "number",
"min": {
"value": 1
},
"max": {
"value": 4294967295
}
}
2.3.1 measurements
In the case where a unit of measure is specified for the number type, the event type will be identified as "number/{Name}/{Unit}"
in the NMOS source, where Name
is the name of the measurement and Unit
is the measurement unit, for example: "number/temperature/C"
.
The definition of the units of measure is out of scope of this specification but the SI system of units is highly recommended.
The recommended strategy for naming measurement units can be read in the Measurement units guidelines section.
Example:
Temperature sensor with precision of 0.1°C
Event Type:
number/temperature/C
Payload:
{
"value": 201,
"scale": 10
}
(representing the value of 20.1°C)
or
{
"value": 305,
"scale": 10
}
(representing the value of 30.5°C)
Type definition:
{
"type": "number",
"min": {
"value": -200,
"scale": 10
},
"max": {
"value": 1000,
"scale": 10
},
"step": {
"value": 1,
"scale":10
},
"unit": "C"
}
Example:
Logarithmic fader reporting its position
Event Type:
number/attenuation/dB
Payload:
{
"value": 0
}
or
{
"value": -40
}
Type definition:
{
"type": "number",
"min": {
"value": -80
},
"max": {
"value": 20
},
"step": {
"value": 1
},
"unit": "dB"
}
3. enum
Enums can be defined on top of any of the three base types and provide both the list of allowed values and metadata that describe those values.
The enum event type has to be associated with a type definition object that has to provide the following:
- a label for all the possible value options [mandatory]
- a description for all possible value options [mandatory]
The enum
event type will be identified as "{BaseType}/enum/{Name}"
in the NMOS source, where Name
is the name of the enum.
Example:
A numerical enum exposing the current studio usage and defining the button labels and description of the states.
Event Type:
number/enum/StudioCondition
Payload:
{
"value": 0
}
Type definition:
{
"type" : "number",
"values" : [
{
"value": 0,
"label": "idle",
"description": "Studio condition is idle"
},
{
"value": 1,
"label": "reh",
"description": "Studio condition is rehearsal"
},
{
"value": 2,
"label": "tx",
"description": "Studio condition is tx"
}
]
}
Example:
An on/off switch with a bit of added metadata.
Event Type:
boolean/enum/OnOff
Payload:
{
"value": true
}
Type definition:
{
"type" : "boolean",
"values" : [
{
"value": false,
"label": "OFF",
"description": "The device is off"
},
{
"value": true,
"label": "ON",
"description": "The device is on"
}
]
}
Example:
String based device status
Event Type:
string/enum/DeviceStatus
Payload:
{
"value": "ok"
}
Type definition:
{
"type" : "string",
"values" : [
{
"value": "unknown",
"label": "Device state is unknown",
"description": "Device state is unknown. Check extension card is plugged in correctly."
},
{
"value": "ok",
"label": "Device state is ok",
"description": "Device state is ok."
},
{
"value": "warn",
"label": "Device state is warning",
"description": "Device state is warning. PSU 1 shows signs of failure."
},
{
"value": "fail",
"label": "Device state is fail",
"description": "Device state is fail. No PTP reference found."
}
]
}
4. object (out of scope for version 1.0 of this specification)
The usage of the object
event type is out of scope of this specification for version 1.0
The object event type has to be associated with a type definition object that has to provide the object structure. It will consist of fields that can have following types:
- other base types (boolean, number, string, enum)
- other objects
- arrays of other base types or objects
This definition file will describe the payload types and metadata associated in detail. The available metadata for each base type will be identical to the metadata defined for standalone types.
The object
event type will be identified as "object/{Name}"
in the NMOS source, where Name
is the name of the object.
Event types capability management
Sources "event_type"
field always needs to have an exact specific event type (cannot use wildcard).
Receivers "event_types"
field can have a specific event type or may have a derived partial event type using a wildcard (*
).
A wildcard (*
) must replace a whole word and can only be used at the end of an event_type definition.
More details about NMOS resources in the section Core models.
The wildcard allows a smart receiver to advertise a wider capability with a specific category above. This is useful information when building a user interface which handles connection management but also matches capabilities between senders and receivers.
An example of a receiver which may use a wildcard could be a smart software gauge which can auto-calibrate. This could advertise its capability as number/*
.
Another example could be for a temperature receiver which supports any measurement unit. This could advertise its capability as number/Temperature/*
.
A third example could be that of a temperature receiver which only supports degrees Celsius. It would advertise its capability as number/Temperature/C
.
The following examples are invalid uses for a wildcard:
number/Tempera*
number/*/C