135 lines
3.6 KiB
ReStructuredText
135 lines
3.6 KiB
ReStructuredText
|
|
.. _ntscalar:
|
|
|
|
NTScalar and NTScalarArray
|
|
==========================
|
|
|
|
The ``epics:nt/NTScalar:1.0`` and related ``epics:nt/NTScalarArray:1.0``
|
|
definitions describe a primary 'value' and supporting meta-data.
|
|
In the case of NTScalarArray the value is a 1-d array of primitive type.
|
|
In the case of NTScalar the value is a single primitive value.
|
|
|
|
Both variants include time and alarm meta-data fields,
|
|
and optionally display and control meta-data fields.
|
|
|
|
.. code-block:: c++
|
|
|
|
using namespace pvxs;
|
|
|
|
// single integer
|
|
Value iscalar = nt::NTScalar{TypeCode::Int64}.create();
|
|
|
|
// eg. access "value" field
|
|
iscalar["value"] = 42;
|
|
|
|
.. code-block:: c++
|
|
|
|
// Functionally equivalent pseudo-C++
|
|
struct NTScalar_Int64 {
|
|
int64_t value;
|
|
struct alarm_t {
|
|
int64_t secondsPastEpoch;
|
|
int32_t nanoseconds;
|
|
int32_t userTag
|
|
} alarm;
|
|
struct time_t {
|
|
int32_t severity;
|
|
int32_t status;
|
|
std::string message
|
|
} timeStamp;
|
|
// if NTScalar::display
|
|
struct display_t {
|
|
int64_t limitLow, limitHigh;
|
|
std::string description, units;
|
|
// if NTScalar::form
|
|
int32_t precision;
|
|
struct enum_t {
|
|
int32_t index;
|
|
std::vector<std::string> choices;
|
|
} form;
|
|
} display;
|
|
// if NTScalar::control
|
|
struct control_t {
|
|
int64_t limitLow, limitHigh;
|
|
} control;
|
|
// ...
|
|
};
|
|
|
|
auto iscalar = new NTScalar_Int64(); // not safe!
|
|
iscalar->value = 42;
|
|
|
|
Fields
|
|
------
|
|
|
|
**"value"**
|
|
The primary field. May be any `pvxs::TypeCode` other than ``Struct``, ``Union``, ``StructA``, ``UnionA``, or ``Null``.
|
|
|
|
**"timeStamp.secondsPastEpoch"**,
|
|
**"timeStamp.nanoseconds"**,
|
|
**"timeStamp.userTag"**
|
|
|
|
See common :ref:`time_t`.
|
|
|
|
**"alarm.severity"**,
|
|
**"alarm.status"**,
|
|
**"alarm.message"**
|
|
|
|
See common :ref:`alarm_t`.
|
|
|
|
**"display.description"**
|
|
Text providing some context about what this value/PV represents.
|
|
|
|
**"display.units"**
|
|
Text identifying units of value. eg. "V" or "Hz"
|
|
|
|
Meta-data for numeric types.
|
|
|
|
**"display.limitLow"**
|
|
|
|
**"display.limitHigh"**
|
|
Hints for clients which can indicate inclusive range of possible values. eg. a UI gauge widget.
|
|
Ignore unless limitLow < limitHigh
|
|
|
|
**"control.limitLow"**
|
|
|
|
**"control.limitHigh"**
|
|
Hints for clients on the inclusive range of values which may reasonably be written to this PV.
|
|
Ignore unless limitLow < limitHigh
|
|
Not authoritative.
|
|
|
|
**"valueAlarm.lowAlarmLimit"**
|
|
|
|
**"valueAlarm.highAlarmLimit"**
|
|
|
|
**"valueAlarm.lowAlarmSeverity"**
|
|
|
|
**"valueAlarm.highAlarmSeverity"**
|
|
|
|
**"valueAlarm.lowWarningLimit"**
|
|
|
|
**"valueAlarm.highWarningLimit"**
|
|
|
|
**"valueAlarm.lowWarningSeverity"**
|
|
|
|
**"valueAlarm.highWarningSeverity"**
|
|
Hints for clients on the ranges of values which will result in a alarms of the given severities.
|
|
Could be used by eg. a UI gauge widget to place markers colored by alarm severity.
|
|
Actual alarms are signals with **"alarm.severity"**.
|
|
|
|
Two value ranges are defined. The names Alarm vs. Warning do not have a special significance.
|
|
|
|
Ignore \*Alarm\* range unless lowAlarmLimit < highAlarmLimit
|
|
|
|
Ignore \*Warning\* range unless lowWarningLimit < highWarningLimit
|
|
|
|
If a value is within a range [low\*Limit, high\*Limit] inclusive then no alarm is expected.
|
|
If a value is < low\*Limit then the alarm severity low\*Severity is expected.
|
|
If a value is > high\*Limit then the alarm severity high\*Severity is expected.
|
|
|
|
|
|
Builder API
|
|
-----------
|
|
|
|
.. doxygenstruct:: pvxs::nt::NTScalar
|
|
:members:
|