Skip to main content

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 required
mn_id int(4) unique mnemonic ID yes
name utf8vstring(128) unique mnemonic name
yesmodelasciivstring(32)originating model, if auto generated
originasciivstring(32)originating origin, if auto generated
desc utf8text plain text mnemonic descriptionyes
meas utf8vstring(32) measurement label (for example, voltage, current) yes
unit utf8vstring(32) measurement unit (for example, V, mA) yes
meta jsonobject additional metadata as neededyes
state model_mn_state current state of mnemonic (active, inactive, deprecated)yes
mode model_mn_mode data processing mode (full, delta, bin), default full yes
format asciivstring(32) printf-style format to render valuesno
enum jsonobject mapping of permitted text values to numeric valuesno
labels list(jsonobject) mapping of numeric values or ranges to labels no
models jsonarray list of model(s) containing the mnemonicno
aliases set(asciivstring(128)) set of additional names associated with the mnemonicno

Each mnemonic name must be unique, are case insensitive, and are normalized with any leading/trailing whitespace removed, and 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.

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 required
t instantinstant(us) (model standard) timeyes
mn_id int(4) unique mnemonic ID yes
v numeric (typically float(8)) data point value (may be null)yes
n int(4) number of data points no (used for delta, see below)
ref_id int(4) mnemonic ID on insertno (used for auto ID, see below)

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).

Fixed 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
Multi Time Binning

Bins for multiple time intervals are collected into the a single database. This involves some additional storage overhead but provides more flexibility. duration provides the size of the bin, starting at t.

Standard Fields

fieldtypedescriptionrequired
tinstant (matching model standard)start time of the binyes
durdurationduration (matching model standard precision)yes
t_mininstant (matching model standard)time of first data point in binyes
t_maxinstant (matching model standard)time of last data point in binyes
mn_idint(4)unique mnemonic IDyes
nint(4)number of data points in binyes
avgfloat(8)average of points in binyes
minfloat(8)min of points in binyes
maxfloat(8)max of points in binyes
medfloat(8)median of points in binno
varfloat(8)variance of points in binno
stdfloat(8)standard deviation of points in binno
Interval Binning

Bins are based on explicitly defined intervals.

Standard Fields

field type description required
t_start instantinstant(us) (matching model standard) start time of the bin yes
t_end instantinstant(us) (matching model standard) end time of the bin yes
dur durationduration(us) duration (matching model standard precision) yes
t_min instantinstant(us) (matching model standard) time of first data point in bin yes
t_max instantinstant(us) (matching model standard) 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