Mnemonics
A mnemonic defines a single field of numeric data in a XINA model. A datapoint is a single logical piece of data, consisting of:
- time (Unix microseconds)
- mnemonic identifier
- value (numeric)
In other words, the value of a single mnemonic at a moment in time.
A model has one or more mnemonic databases, containing all of the datapoints associated with the model.
Mnemonic Definitions
All mnemonics must be defined in a mnemonic definitions database. Again, it is strongly recommended to use a single definitions database for an entire project to faciliate comparison of data between models.
A core challenge of working with mnemonics is synchronizing mnemonic definitions from XINA to the point of data collection. Especially in early test environments, fields may be frequently added or removed on the the fly and labels may change, but must be consistently associated with a single mnemonic definition. Broadly there are two approaches to manage this challenge.
The first is user maintained mnemonic definitions. This is recommended for environments without frequent changes, and ideally one data source. The end user is responsible for ensuring that imported data has matching mn_id values to mnemonics present in the definitions database. This will typically result in faster imports and support complex or custom data pipeline solutions.
The second solution is allowing XINA to manage mnemonic definitions. With this approach, data can be imported with plain text labels and automatically associated with mnemonic definitions if available, or new definitions can be created on the fly.
Both approaches can be accomplished with the model_mn_import API action, documented here. The details of the required approach will depend on project requirements.
Standard Fields
| field | type | description |
|---|---|---|
mn_id |
int(4) |
unique mnemonic ID |
name |
utf8vstring(128) |
unique mnemonic name |
| | |
desc |
utf8text |
plain text mnemonic description |
meas |
utf8vstring(32) |
measurement label (for example, voltage, current) |
unit |
utf8vstring(32) |
measurement unit (for example, V, mA) |
| | |
state |
model_mn_state |
current state of mnemonic (active, inactive, archived, deprecated) |
|
jsonobject |
map of model(s) to associated origin(s) |
full |
asciivstring(32) |
the primary database for the mnemonic, default f8 (may be null) |
bin |
set(asciivstring(32)) |
the opt-in bin database(s) to include the mnemonic in |
format |
asciivstring(32) |
printf-style format to render values |
enum |
jsonobject |
mapping of permitted text values to numeric values |
labels |
list(jsonobject) |
mapping of numeric values or ranges to labels |
aliases |
set(asciivstring(128)) |
set of additional names associated with the mnemonic |
meta |
jsonobject |
additional metadata as needed |
query |
asciivstring(32) |
query name for meta-mnemonics (may be null) |
conf |
jsonobject |
configuration for meta-mnemonics (may be null) |
Mnemonic names are case insensitive and normalized with any leading/trailing whitespace removed, with any internal whitespace represented by a single underscore character. For example, "v_mon" = "V Mon" = " V MON ". Although not required, XINA tools will interpret the period character (.) to indicate a tree structure of mnemonic relationships, and brackets ([]) to indicate an array of values. Although the mnemonic name is intended to be unique, insertion of a mnemonic with the same name but different unit will create a new mnemonic definition. This is intended to avoid interruption of data flow, but should be corrected with the Mnemonic Management tool when possible. The model and origin are populated automatically for auto-generated mnemonic definitions.
The mnemonic state affects how the mnemonic will be displayed and populated. An inactive mnemonic indicates data is no longer relevant or actively populated and will be hidden by default. A deprecated mnemonic extends this concept but will throw errors if additional data points for the mnemonic are imported.
If enum is provided a mnemonic will apply labels to enumerated numeric values, as provided in values. For example, a 0|1 on|off state could be represented by {"0":"OFF", "1":"ON"}. Values in this map may also be used to parse imported data.
A mnemonic may specify one or more aliases to indicate additional names that should be included in the single mnemonic definition. If present, the aliases are referenced at a higher priority than the mnemonic name during import lookup. For example, a given mnemonic a is erroneously labeled b in some imported data, which creates a new separate mnemonic definition for b. To correct this, b could be added as an alias for a, and the b mnemonic could be deprecated. All a and b data from the source telemetry would then correctly be merged into the a mnemonic.
The mnemonic mode affects how incoming data is optimized. full includes unabridged data, delta includes only points around value changes (see below), and bin includes only binned data.
name, unit, state, mode, enum, models, and aliases may be used during the data import process to validate and interpret data. Full details of how each field is used is documented with the associated API action.
Mnemonic Databases
Within a model, each data source must have a set of one or more mnemonic databases. Each set should be contained by a group, which can be configured to define any relationships between the databases. This will typically include a full database, containing all or delta optimized data (see below for additional information), and one or more types of bin databases, depending on requirements.
While each data source must have its own mnemonic database(s), it may be beneficial for a single data source to further subdivide mnemonics into different types of databases for optimization purposes. For example, a model with a large number of mnemonics that only require single byte precision would see significant performance gains from separate databases using the int(1) type. In practice this could look like:
Full Database
In most cases, there will be a single primary database containing full mnemonic data (all points from original telemetry), delta mnemonic data (an optimization option, see below), or a mix of both. Data is stored with a single data point per row.
Standard Fields
| field | type | description |
|---|---|---|
t |
instant(us) |
time |
mn_id |
int(4) |
unique mnemonic ID |
v |
float(8) |
data point value (may be null) |
n |
int(4) |
number of data points |
ref_id |
int(4) |
mnemonic ID on insert |
A value of null may be used for v to indicate a gap in data, otherwise data will appear visually connected by default in XINA charts. null may also be appropriate to represent NaN or Inf values, as these cannot be stored in the database, but the preference to include these as null or omit them altogether may depend on an individual project.
For large data sets with infrequent value changes, it may be beneficial to employ a delta mnemonic optimization. This requires the n field listed above. In this case, a point is only included in the database at the moment the value for a given mnemonic changes, and the number of points is stored in n. For example, given the set of points:
| t | v |
|---|---|
| 0 | 0 |
| 1 | 0 |
| 2 | 0 |
| 3 | 1 |
| 4 | 1 |
| 5 | 1 |
| 6 | 1 |
| 7 | 2 |
| 8 | 2 |
| 9 | 2 |
Delta optimization would condense the data to:
| t | v | n |
|---|---|---|
| 0 | 0 | 2 |
| 2 | 0 | 1 |
| 3 | 1 | 3 |
| 6 | 1 | 1 |
| 7 | 2 | 2 |
| 9 | 1 | 1 |
Note the final data point of a data set is always included.
Bin Database(s)
The most common data optimization employed with mnemonics is binning, combining multiple data points over a fixed time range into a single data point with a min, max, avg, and standard deviation. A model may define one or more bin databases depending on performance requirements, but four types are supported by default. The time range of bins is interpretted as [start, end).
Time Binning
Bins are applied on a fixed time interval for all points in the database (for example, 1 minute or 1 hour).
Standard Fields
| field | type | description | required |
|---|---|---|---|
t |
instant (matching model standard) |
start time of the bin | yes |
t_min |
instant (matching model standard) |
time of first data point in bin | yes |
t_max |
instant (matching model standard) |
time of last data point in bin | yes |
mn_id |
int(4) |
unique mnemonic ID | yes |
n |
int(4) |
number of data points in bin | yes |
avg |
float(8) |
average of points in bin | yes |
min |
float(8) |
min of points in bin | yes |
max |
float(8) |
max of points in bin | yes |
med |
float(8) |
median of points in bin | no |
var |
float(8) |
variance of points in bin | no |
std |
float(8) |
standard deviation of points in bin | no |
Interval Binning
Bins are based on explicitly defined intervals.
Standard Fields
| field | type | description | required |
|---|---|---|---|
t_start |
instant(us) |
start time of the bin | yes |
t_end |
instant(us) |
end time of the bin | yes |
dur |
duration(us) |
duration | yes |
t_min |
instant(us) |
time of first data point in bin | yes |
t_max |
instant(us) |
time of last data point in bin | yes |
u_id |
UUID |
UUID of associated interval | yes |
p_id |
int(8) |
primary ID of associated interval | yes |
s_id |
int(4) |
secondary ID of associated interval | yes |
mn_id |
int(4) |
unique mnemonic ID | yes |
n |
int(4) |
number of data points in bin | yes |
avg |
float(8) |
average of points in bin | yes |
min |
float(8) |
min of points in bin | yes |
max |
float(8) |
max of points in bin | yes |
med |
float(8) |
median of points in bin | no |
var |
float(8) |
variance of points in bin | no |
std |
float(8) |
standard deviation of points in bin | no |