# Mnemonic Limit Definitions

This page defines the format of the limit definitions used by the Data Viewer application.

A Limit Definition is a JSON object that describes limit thresholds for a single mnemonic telemetry value. The operator/user will be notified when a limit is triggered.

The top level object supports the following fields:

| Field | Required | Value Format |  Meaning |
|---|---:|---|---|
| `limits` | Yes | JSON Array | Array of 1 or more limit objects. Each object defines a set of limit thresholds. If a Limit Definition does not define a context mnemonic, the array should contain a single object. |
| `cm` | No | String or integer | Context Mnemonic. The optional mnemonic that is used to determine if a limit should be checked. Can be provided as the mnemonic name or numeric ID. For example, you may want to only check a current limit when a temperature is between 25 and 30 celsius. |

Each limit object supports the following fields:

| Field | Required | Value Format | Meaning |
|---|---:|---|---|
| `cr` | No | Single number or range syntax | Context range. Only used if `cm` is provided at the top level. If the context mnemonic equals this value or falls within this range, the limit will be checked. If `cm` is provided but `cr` is not, the limit object will be used as the "default" limit. Single number example: `1.5` the limit will be used when the context mnemonic's value equals `1.5.`. Range example: `"5.2..10.3"` the limit will be used when the context mnemonic's value falls between 5.2 and 10.3, inclusive.
| `ec` | No | Integer | Excursion count. Number of consecutive telemetry values that must exceed a threshold before the limit is triggered. Defaults to 2 if not provided. |
| `yh` | No | Number | Yellow high threshold. Triggers a yellow high alarm when the telemetry value is greater than or equal to this value for the required excursion count. |
| `yl` | No | Number | Yellow low threshold. Triggers a yellow low alarm when the telemetry value is less than or equal to this value for the required excursion count. |
| `rh` | No | Number | Red high threshold. Triggers a red high alarm when the telemetry value is greater than or equal to this value for the required excursion count. |
| `rl` | No | Number | Red low threshold. Triggers a red low alarm when the telemetry value is less than or equal to this value for the required excursion count. |

> Note: At least 1 of the threshold values must be defined

#### Example A:

* Limit definition for a `BOARD_TEMP` mnemonic
* Single limit with no context mnemonic
* Yellow high undefined
* Excursion count of 5 means the value must exceed the threshold for 5 consecutive values

```json
{
  "limits": [
    {
      "ec": 5,
      "rh": 20,
      "yl": -5,
      "rl": -12
    }
  ]
}
```

The below visualizes how the limit thresholds are evaluated:

```
y-axis: Telemetry value
      ^
      |
      |   RED HIGH alarm zone
      |   value >= 20 for 5 consecutive samples
  20  +------------------------------------------------ rh
      |
      |
      | 
      |   Nominal range
      |
      |
      |
  -5  +------------------------------------------------ yl
      |   YELLOW LOW alarm zone
      |   value =< -5 for 5 consecutive samples
      |
 -12  +------------------------------------------------ rl
      |   RED LOW alarm zone
      |   value =< -12 for 5 consecutive samples
      |
      +----------------------------------------------------> x-axis: time / samples
      |
```

#### Example B:

* Limit definition for a `CURRENT_MONITOR` mnemonic
* `BOARD_TEMP` context mnemonic is used to determine which limit should be checked
* Defines a "default" limit that is used when none of the context ranges are satisfied
* Defines a limit with a context range using the range syntax. If the `BOARD_TEMP` is [0, 25], then this limit will be used.

```json
{
  "cm": "BOARD_TEMP",
  "limits": [
    {
      "rh": 2.5,
      "yh": 2.0
    },
    {
      "cr": "0..25",
      "ec": 3,
      "rh": 2.3,
      "yh": 1.8
    }
  ]
}
```