From 693d7698bfb5c1aee1d477d8d9f0b2bdb15be0ef Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 08:39:46 -0400 Subject: [PATCH 01/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 2a4b398d..c7195692 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -69,7 +69,9 @@ values. The `lower` and `upper` indicate the extent of the scale to be shown. So scale, for example logarithmic for luminosity, depth, signal strength, etc. whilst others may be better on a squareroot scale eg. depth, windspeed. `type` has possible values of `linear` (default), `logarithmic`, `squareroot` or `power`. When `"type": "power"` is specified an additional property `power` must be present to define the power. Note that a power of -0.5 is equivalent to `squareroot` and a power of 1 is equivalent to linear. In using these scales the type defines the +0.5 is equivalent to `squareroot` and a power of 1 is equivalent to linear. + +In using these scales the type defines the function which is applied to all values in order to calculate % scale deflection of the pointer/needle/plot: | Type | Formula for % deflection | From 12aa55795ba56f3a7f4630396d51d6d701521f5d Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 08:40:29 -0400 Subject: [PATCH 02/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index c7195692..add92540 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -65,7 +65,9 @@ The `timeout` property tells the consumer how long it should consider the value in seconds, so for a high speed GPS sensor it may 0.1 or even 0.05. The `displayScale` object provides information regarding the recommended type and extent of the scale used for displaying -values. The `lower` and `upper` indicate the extent of the scale to be shown. Some values are better shown on a non linear +values. + +The `lower` and `upper` indicate the extent of the scale to be shown. Some values are better shown on a non linear scale, for example logarithmic for luminosity, depth, signal strength, etc. whilst others may be better on a squareroot scale eg. depth, windspeed. `type` has possible values of `linear` (default), `logarithmic`, `squareroot` or `power`. When `"type": "power"` is specified an additional property `power` must be present to define the power. Note that a power of From 313d60a416c6458dc09c0dafea8f5498125d484b Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 08:41:11 -0400 Subject: [PATCH 03/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index add92540..3835eebe 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -64,6 +64,8 @@ version may be used by consumers where space is at a premium. As with displayNam The `timeout` property tells the consumer how long it should consider the value valid. This value is specified in seconds, so for a high speed GPS sensor it may 0.1 or even 0.05. +### displayScale + The `displayScale` object provides information regarding the recommended type and extent of the scale used for displaying values. From 0eccfd5a36357b7a342a6c56a274b7b01b8f9026 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 08:57:13 -0400 Subject: [PATCH 04/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 3835eebe..396b79a3 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -71,7 +71,9 @@ values. The `lower` and `upper` indicate the extent of the scale to be shown. Some values are better shown on a non linear scale, for example logarithmic for luminosity, depth, signal strength, etc. whilst others may be better on a squareroot -scale eg. depth, windspeed. `type` has possible values of `linear` (default), `logarithmic`, `squareroot` or `power`. When +scale eg. depth, windspeed. + +`type` has possible values of `linear` (default), `logarithmic`, `squareroot` or `power`. When `"type": "power"` is specified an additional property `power` must be present to define the power. Note that a power of 0.5 is equivalent to `squareroot` and a power of 1 is equivalent to linear. @@ -89,12 +91,12 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. -The `alertMethod`, `warnMethod`, `alarmMethod` and -`emergencyMethod` properties tell the consumer how it should respond to an abnormal data condition. Presently the +### alertMethod, etc +Methods are normalMethod, nominal `alertMethod`, `warnMethod`, `alarmMethod` and +`` properties tell the consumer how it should respond to an abnormal data condition. Presently the values for these properties are `sound` and `visual` and the method is specified as an array containing one or both of these options. It is up to the consumer to decide how to convey these alerts. -### alertMethod, etc The `alertMethod`, `warnMethod`, `alarmMethod` and `emergencyMethod` properties tell the consumer how it should respond to an abnormal data condition. Presently the values for these properties are `sound` and `visual` and the method is specified as an array containing one or both of these options. It is up to the consumer to decide how to convey these alerts. From d6abce41c3cfb07d1c98e6bf38916e25bfe3866b Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 08:58:40 -0400 Subject: [PATCH 05/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 396b79a3..a05b31d8 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -27,16 +27,16 @@ The `meta` object exists at the same level as `value` and `$source` in each key "units": "Hz", "timeout": 1, "displayScale": {"lower": 0, "upper": 75, "type": "linear"}, + "zones": [ + {"upper": 4, "state": "alarm", "message": "Stopped or very slow"}, + {"lower": 4, "upper": 60, "state": "normal"}, + {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, + {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} + ] "alertMethod": ["visual"], "warnMethod": ["visual"], "alarmMethod": ["sound", "visual"], - "emergencyMethod": ["sound", "visual"], - "zones": [ - {"upper": 4, "state": "alarm", "message": "Stopped or very slow"}, - {"lower": 4, "upper": 60, "state": "normal"}, - {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, - {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} - ] + "emergencyMethod": ["sound", "visual"] } ``` [<]: # From 2c5a6c262bf1aaa791da705c43831be907913f5f Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 10:27:21 -0400 Subject: [PATCH 06/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index a05b31d8..0f792ce5 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -33,8 +33,10 @@ The `meta` object exists at the same level as `value` and `$source` in each key {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} ] + "normalMethod": [], + "nominalMethod": ["visual"], "alertMethod": ["visual"], - "warnMethod": ["visual"], + "warnMethod": ["sound", "visual"], "alarmMethod": ["sound", "visual"], "emergencyMethod": ["sound", "visual"] } @@ -91,9 +93,8 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. -### alertMethod, etc -Methods are normalMethod, nominal `alertMethod`, `warnMethod`, `alarmMethod` and -`` properties tell the consumer how it should respond to an abnormal data condition. Presently the +### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod +Methods are properties tell the consumer how it should respond to an abnormal data condition. Presently the values for these properties are `sound` and `visual` and the method is specified as an array containing one or both of these options. It is up to the consumer to decide how to convey these alerts. From 5a5a6b1d3768ddbfd13efb803d1aee2db903d44f Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 12:35:01 -0400 Subject: [PATCH 07/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 0f792ce5..8dbe3ca8 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -94,9 +94,9 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. ### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod -Methods are properties tell the consumer how it should respond to an abnormal data condition. Presently the -values for these properties are `sound` and `visual` and the method is specified as an array containing one or both of -these options. It is up to the consumer to decide how to convey these alerts. +Methods are properties that suggests to the consumer how it should act upon notification reception. Presently the +values for these properties are `sound` and `visual` and the method is specified as an array containing one, both or none [] of +these options. It is up to the consumer to decide how to convey these notifications. The `alertMethod`, `warnMethod`, `alarmMethod` and `emergencyMethod` properties tell the consumer how it should respond to an abnormal data condition. Presently the values for these properties are `sound` and `visual` and the method is specified as an From a48acd6a2b23cbfc4a91fcbd1b0d4dce5af4e6ff Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:07:17 -0400 Subject: [PATCH 08/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 50 ++++++++++++++----------------- 1 file changed, 23 insertions(+), 27 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 8dbe3ca8..361b01e8 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -93,51 +93,47 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. -### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod -Methods are properties that suggests to the consumer how it should act upon notification reception. Presently the -values for these properties are `sound` and `visual` and the method is specified as an array containing one, both or none [] of -these options. It is up to the consumer to decide how to convey these notifications. +### zones +Zones serve a dual purpose by defining data operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge data and notify end users effectively. Zones are invaluable for configuring various display scale setups. -The `alertMethod`, `warnMethod`, `alarmMethod` and `emergencyMethod` properties tell the consumer how it should respond to an -abnormal data condition. Presently the values for these properties are `sound` and `visual` and the method is specified as an -array containing one or both of these options. It is up to the consumer to decide how to convey these alerts. +The items within the `zones` array define segments of data states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. -### zones -The last property in the `meta` object is the `zones` array. This provides a series of hints to the consumer which can -be used to properly set a range on a display gauge and also color sectors of a gauge to indicate normal or dangerous -operating conditions. It also tells the consumer which state the data is in for a given range. Combined with the alert -method properties, all Signal K consumers can react the same way to a given state. +As data transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. + +The `upper` and `lower` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. + +In cases where zones overlap, the zones with the highest `state` severity takes precedence, affecting both notifications and gauge/display rendering. Any range not explicitly within a zone is considered `normal` by default. Therefore, zones with a `normal` state have no effect - do not alter displays or generate audio prompts. -The possible states in ascending order of severity are: +Zones can technically have from zero to an infinite number of zone segments. Then same state can be present in multiple segments ie. you have have a low and high temperature `"state": "alarm"`. In pactice, less is more. Too many zone will constanly fireup gauges and notifications like a chrismat tree. + +The possible `states` in ascending order of severity are: -| State/Zone | Description | +| State | Description | |------------|--------| -| nominal | this is a special type of normal state/zone (see below) | -| normal | the normal operating range for the value in question (default) | -| alert | Indicates a safe or normal condition which is brought to the operators attention to impart information for routine action purposes | +| normal | The normal operating range for the value in question (default - auto managed) | +| nominal | The recommended optimal operation condition (see below) | +| alert | Indicates a safe or normal condition which is brought to the operators attention to impart information | | warn | Indicates a condition that requires immediate attention but not immediate action | | alarm | Indicates a condition which is outside the specified acceptable range. Immediate action is required to prevent loss of life or equipment damage | -| emergency | the value indicates a life-threatening condition | +| emergency | The value indicates a life-threatening condition | `nominal`: A example use of this is for engine monitoring eg. coolant temperature where there is a normal (no warnings) (green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at -all (typically remains vertical or horizontal). This is really useful if you have many gauges (multiple motors with multiple +all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple sensors) where it is very easy to spot that every needle is pointing in exactly the same direction. Use of nominal will only be relevant if the gauge/display design permits it. -The `upper` and `lower` values in the zones do not need to be contiguous, they don't have to both be present in a zone, nor do -they need to be within the bounds of the `upper` and `lower` specified in `displayScale`. When they are outside of the -`displayScale` range they will still give rise to alerts. Both `upper` and `lower` values are considered to be inclusive. - -If zones overlap each other the state/zone with the highest severity will take precedence. This is true for both alerts and -gauge/display rendering. Any part of the range which is not explicitly within a zone is considered to be `normal` (the default). -As such, zones with a state of `normal` have no effect and their removal would result in no changes to either displays or alerts. - There can be multiple zones with the same `state`, for example if a different message is required, or if they are on different parts of the scale. Signal K servers will use the `zone` information to monitor any data which has a `meta` object and raise a generic alarm event. See the section on [Alarm Handling](notifications.md) for more. +### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod +Methods are meta properties that suggests to consumers how they should convey notification message upon reception. Presently the +values for these properties are `sound` and `visual` and the method is specified as an array containing one, both or none `[]` of +these options. A method with value `[]` suggests the notification message should neither have a visual, nor an audio representation. It +is up to the consumer to interpret how to applies those to their usecase and choose how to best convey these notifications. + ## Implicit Metadata All keys in the Signal K specification must have a `description`, and where the key is a numeric value it must have From 49026f14d98b032c18b3479aa9c97ac2e8100a2e Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:29:28 -0400 Subject: [PATCH 09/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 361b01e8..2813d2e6 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -1,4 +1,4 @@ -# Metadata +o# Metadata A key part of Signal K is the ability for data consumers such as apps or MFDs to automatically configure themselves based on settings retrieved from the server. The metadata component of Signal K facilitates this through an optional From 3b4c0c313a31558b701f5eec7fc6c1d81970448b Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:31:41 -0400 Subject: [PATCH 10/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 2813d2e6..475d1825 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -94,7 +94,7 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. ### zones -Zones serve a dual purpose by defining data operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge data and notify end users effectively. Zones are invaluable for configuring various display scale setups. +Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge data and notify end users effectively. Zones are invaluable for configuring various display scale setups. The items within the `zones` array define segments of data states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. From f62374b04ddf4ea0e0b1385f1e9db89824faffc0 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:33:42 -0400 Subject: [PATCH 11/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 475d1825..cf028fd3 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -96,7 +96,7 @@ Note that on a logarithmic scale neither L nor U can be zero. ### zones Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge data and notify end users effectively. Zones are invaluable for configuring various display scale setups. -The items within the `zones` array define segments of data states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. +The items within the `zones` array define segments of value states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. As data transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. From 255ffcdff4d095ea3ebeb79347192452de8fa278 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:34:20 -0400 Subject: [PATCH 12/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index cf028fd3..8d7113ec 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -94,7 +94,7 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. ### zones -Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge data and notify end users effectively. Zones are invaluable for configuring various display scale setups. +Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge values and notify end users effectively. Zones are invaluable for configuring various display scale setups. The items within the `zones` array define segments of value states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. From a3190ef789b7a7e6e742c56f7c0a84983702a21b Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:36:25 -0400 Subject: [PATCH 13/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 8d7113ec..cb6c9953 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -94,7 +94,7 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. ### zones -Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge values and notify end users effectively. Zones are invaluable for configuring various display scale setups. +Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge values status and notify end users effectively. Zones are invaluable for configuring various display scale setups. The items within the `zones` array define segments of value states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. From cb08b876395cb376ca3a2e3b1791abaa52994268 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:38:16 -0400 Subject: [PATCH 14/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index cb6c9953..1b22d380 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -96,7 +96,7 @@ Note that on a logarithmic scale neither L nor U can be zero. ### zones Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge values status and notify end users effectively. Zones are invaluable for configuring various display scale setups. -The items within the `zones` array define segments of value states, with each `state` representing the severity of the given condition. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. +The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. As data transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. From 7a253452e9d751aa9d09f01dedff1d074b97f3e3 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:39:38 -0400 Subject: [PATCH 15/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 1b22d380..c4525d3e 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -98,7 +98,7 @@ Zones serve a dual purpose by defining value operating conditions and associated The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. -As data transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. +As values transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. The `upper` and `lower` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. From 135e2a58672a4323134a2eef0c628ea5bd83cb9c Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:40:34 -0400 Subject: [PATCH 16/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index c4525d3e..bb5737ab 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -98,7 +98,7 @@ Zones serve a dual purpose by defining value operating conditions and associated The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. -As values transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. +As the path's values transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. The `upper` and `lower` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. From 45ef4f08468c85d19c8839a261b24fba2c4e00dc Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:42:40 -0400 Subject: [PATCH 17/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index bb5737ab..039d01df 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -98,7 +98,7 @@ Zones serve a dual purpose by defining value operating conditions and associated The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. -As the path's values transitions between zones, notifications are dispatched to inform consumers about the data's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all data-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. +As the path's values transitions between zones, notifications are dispatched to inform consumers about the value's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all value-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. The `upper` and `lower` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. From 3e34abb0bfe91752f36875f2ce0b2a2fc79d1e0f Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:46:24 -0400 Subject: [PATCH 18/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 039d01df..dcc7d188 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -100,7 +100,7 @@ The items within the `zones` array define segments of value states, with each `s As the path's values transitions between zones, notifications are dispatched to inform consumers about the value's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all value-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. -The `upper` and `lower` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. +The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. In cases where zones overlap, the zones with the highest `state` severity takes precedence, affecting both notifications and gauge/display rendering. Any range not explicitly within a zone is considered `normal` by default. Therefore, zones with a `normal` state have no effect - do not alter displays or generate audio prompts. From 5727545cbb4aa1f416ff453100e310c419f7fb66 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:52:32 -0400 Subject: [PATCH 19/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index dcc7d188..c6919d77 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -102,7 +102,7 @@ As the path's values transitions between zones, notifications are dispatched to The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. -In cases where zones overlap, the zones with the highest `state` severity takes precedence, affecting both notifications and gauge/display rendering. Any range not explicitly within a zone is considered `normal` by default. Therefore, zones with a `normal` state have no effect - do not alter displays or generate audio prompts. +In cases where zones overlap, the zones with the highest `state` severity takes precedence, affecting both notifications and gauge/display rendering. Any range not explicitly within a zone is considered `normal` by default. Therefore, zones with a `normal` state have no effect - they should not alter displays or generate audio prompts. they are meant to indicate the value is leaving a noteworthy state. Zones can technically have from zero to an infinite number of zone segments. Then same state can be present in multiple segments ie. you have have a low and high temperature `"state": "alarm"`. In pactice, less is more. Too many zone will constanly fireup gauges and notifications like a chrismat tree. From a5e2ba678121b983667856ac2b7eeba1d0eb6195 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:53:35 -0400 Subject: [PATCH 20/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index c6919d77..7f9f2d5f 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -98,7 +98,7 @@ Zones serve a dual purpose by defining value operating conditions and associated The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. -As the path's values transitions between zones, notifications are dispatched to inform consumers about the value's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all value-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications—whether they are normal, noteworthy, or alarming. +As the path's values transitions between zones, notifications are dispatched to inform consumers about the value's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all value-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications ie. whether they are normal, noteworthy, or alarming. The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. From e0cbbb0824cd4fb7f0d306dc0a1a25c846ae1aef Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 18:57:42 -0400 Subject: [PATCH 21/46] update --- mdbook/src/data_model_metadata.md | 48 +++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 15 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 7f9f2d5f..e3074b5f 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -91,22 +91,30 @@ function which is applied to all values in order to calculate % scale deflection Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and P = power -Note that on a logarithmic scale neither L nor U can be zero. +Note that on a logarithmic scale neither L nor U can be zero. ### zones -Zones serve a dual purpose by defining value operating conditions and associated notification prompts. They provide audio and visual cues for each state, guiding consumers on how to present gauge values status and notify end users effectively. Zones are invaluable for configuring various display scale setups. +Zones define value operating conditions and associated notification prompts. They help in presenting display scales and notifying end users effectively. -The items within the `zones` array define segments of value states, with each `state` representing the severity of the given segment. When zones are specified for a path, any data not part of a defined zone defaults to the `normal` state, managed automatically by the Signal K server. Zones use other states to provide insights to consumers about the data's state relative to its scale range. For example, zones for an engine RPM path can indicate the engine's redline segment. +Each item in the `zones` array represents a segment of value states. The `state` of each item indicates the severity of the segment. Any data not part of a zone range defaults to the `normal` state. -As the path's values transitions between zones, notifications are dispatched to inform consumers about the value's state. For detailed information on Notifications, refer to [Alarm Handling](notifications.md). While notifications/messaging is a separate topic, it's essential to note that all value-related notifications are defined within zones. Therefore, a zone's state determines the severity of the notifications ie. whether they are normal, noteworthy, or alarming. +As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. Even when outside the `displayScale` range, they still trigger notifications. Both `upper` and `lower` values are considered inclusive. +If defined, Signal K servers use the `zones` information in each path `meta` object to monitor the value and raise value state notifications. -In cases where zones overlap, the zones with the highest `state` severity takes precedence, affecting both notifications and gauge/display rendering. Any range not explicitly within a zone is considered `normal` by default. Therefore, zones with a `normal` state have no effect - they should not alter displays or generate audio prompts. they are meant to indicate the value is leaving a noteworthy state. +The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. -Zones can technically have from zero to an infinite number of zone segments. Then same state can be present in multiple segments ie. you have have a low and high temperature `"state": "alarm"`. In pactice, less is more. Too many zone will constanly fireup gauges and notifications like a chrismat tree. - -The possible `states` in ascending order of severity are: +In cases where zones overlap, the zone with the highest `state` severity takes precedence. Any range not explicitly within a zone is considered `normal` by default. + +Zones can technically have from zero to an infinite number of zone segments. The same `state` can be present in multiple segments. + +`message`is the message that will be included in the notification when the value enters the zone. + +Zones should be configured with care. In practice, less is more. + +For detailed information on Notifications, refer to [Alarm Handling](notifications.md). + +The possible `state` values in ascending order of severity are: | State | Description | |------------|--------| @@ -117,17 +125,27 @@ The possible `states` in ascending order of severity are: | alarm | Indicates a condition which is outside the specified acceptable range. Immediate action is required to prevent loss of life or equipment damage | | emergency | The value indicates a life-threatening condition | -`nominal`: A example use of this is for engine monitoring eg. coolant temperature where there is a normal (no warnings) +Examples: +An engine RPM path can indicate the engine's redline segment, say one zone lower 3200 to 3500 rpm using the '"state": "alarm"' severity. With this +information consumers can opt to draw a red marker over this segment on it's gauge and sound an alarm when the RPM enters this zone. + +```json + "zones": [ + {"upper": 4, "state": "alarm", "message": "Stopped or very slow"}, + {"lower": 4, "upper": 60, "state": "normal"}, + {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, + {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} + ] +``` + +you can have a refrigeration temperature sensor with one low and one high critical state configured with `"state": "alarm"`, or if zones are on different parts of the scale but a different `message` is required. + +An example of using `nominale` is for engine monitoring eg. coolant temperature where there is a normal (no warnings) (green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple sensors) where it is very easy to spot that every needle is pointing in exactly the same direction. Use of nominal will only be relevant if the gauge/display design permits it. -There can be multiple zones with the same `state`, for example if a different message is required, or if they are on different parts of the scale. - -Signal K servers will use the `zone` information to monitor any data which has a `meta` object and -raise a generic alarm event. See the section on [Alarm Handling](notifications.md) for more. - ### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod Methods are meta properties that suggests to consumers how they should convey notification message upon reception. Presently the values for these properties are `sound` and `visual` and the method is specified as an array containing one, both or none `[]` of From ab9df6d90039ea705710ee5c420d3b1a172a43e9 Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 18:59:49 -0400 Subject: [PATCH 22/46] u --- mdbook/src/data_model_metadata.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index e3074b5f..899e6c31 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -130,12 +130,14 @@ An engine RPM path can indicate the engine's redline segment, say one zone lower information consumers can opt to draw a red marker over this segment on it's gauge and sound an alarm when the RPM enters this zone. ```json + ... "zones": [ {"upper": 4, "state": "alarm", "message": "Stopped or very slow"}, {"lower": 4, "upper": 60, "state": "normal"}, {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} ] + ... ``` you can have a refrigeration temperature sensor with one low and one high critical state configured with `"state": "alarm"`, or if zones are on different parts of the scale but a different `message` is required. From c16641cfaf7d4d4ede439a8443f8e7ca1b45274b Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 20:04:51 -0400 Subject: [PATCH 23/46] f --- mdbook/src/data_model_metadata.md | 52 ++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 18 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 899e6c31..c096954f 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -108,7 +108,7 @@ In cases where zones overlap, the zone with the highest `state` severity takes p Zones can technically have from zero to an infinite number of zone segments. The same `state` can be present in multiple segments. -`message`is the message that will be included in the notification when the value enters the zone. +`message`is the message that will be included in the notification when the value enters the zone. The message should be concise and short ie. a few words. The message may end up on a gauges with limited space. Zones should be configured with care. In practice, less is more. @@ -118,7 +118,7 @@ The possible `state` values in ascending order of severity are: | State | Description | |------------|--------| -| normal | The normal operating range for the value in question (default - auto managed) | +| normal | Server generated - The normal operating range for the value in question (default) | | nominal | The recommended optimal operation condition (see below) | | alert | Indicates a safe or normal condition which is brought to the operators attention to impart information | | warn | Indicates a condition that requires immediate attention but not immediate action | @@ -126,33 +126,49 @@ The possible `state` values in ascending order of severity are: | emergency | The value indicates a life-threatening condition | Examples: -An engine RPM path can indicate the engine's redline segment, say one zone lower 3200 to 3500 rpm using the '"state": "alarm"' severity. With this +An engine RPM path can indicate the engine's redline segment from 3200 to 3500 rpm at the alarm severity. With this information consumers can opt to draw a red marker over this segment on it's gauge and sound an alarm when the RPM enters this zone. ```json - ... "zones": [ - {"upper": 4, "state": "alarm", "message": "Stopped or very slow"}, - {"lower": 4, "upper": 60, "state": "normal"}, - {"lower": 60, "upper": 65, "state": "warn", "message": "Approaching maximum"}, - {"lower": 65, "state": "alarm", "message": "Exceeding maximum"} + {"lower": 3200, "upper": 3500, "state": "alarm", "message": "Risk of engine damage"} ] - ... ``` -you can have a refrigeration temperature sensor with one low and one high critical state configured with `"state": "alarm"`, or if zones are on different parts of the scale but a different `message` is required. +A refrigeration temperature sensor with duplicate state severity but with different messages. + +```json + "zones": [ + {"upper": -2, "state": "warm", "message": "Freezing temperature reached"}, + {"lower": -2, "upper": 1, "state": "alert", "message": "Excessive energy usage"}, + {"lower": 5, "upper": 8, "state": "warn", "message": "Perishable storage at risk"}, + {"lower": 8, "state": "alarm", "message": "Risk of bacterial growth and food spoilage"} + ] +``` -An example of using `nominale` is for engine monitoring eg. coolant temperature where there is a normal (no warnings) -(green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at -all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple +For engine monitoring eg. coolant temperature where there is a 'normal' (no warnings) +(green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple sensors) where it is very easy to spot that every needle is pointing in exactly the same direction. Use of nominal will only be relevant if the gauge/display design permits it. -### normalMethod, nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod -Methods are meta properties that suggests to consumers how they should convey notification message upon reception. Presently the -values for these properties are `sound` and `visual` and the method is specified as an array containing one, both or none `[]` of -these options. A method with value `[]` suggests the notification message should neither have a visual, nor an audio representation. It -is up to the consumer to interpret how to applies those to their usecase and choose how to best convey these notifications. +```json + "zones": [ + {"upper": 60, "state": "alert", "message": "Cold or Startup Temperature"}, + {"lower": 70, "upper": 80, "state": "nominal", "message": "Temperature Nominal"}, + {"lower": 85, "upper": 95, "state": "warn", "message": "High Temperature"}, + {"lower": 95, "state": "alarm", "message": "Engine Overheat"} + ] +``` + +### nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod + +These properties guide consumers on handling `zones` notifications, each corresponding to a different severity level. They are arrays that may include `sound`, `visual`, or both. An empty array `[]` signifies no visual or audio notification. The automatically generated `normalMethod` notification always has `[]`. + +A `alertMethod` would typically use +```json + "alertMethod": ["visual"] +``` +Consumers have the flexibility to interpret and apply these methods, enabling them to effectively communicate notifications based on their specific use cases. ## Implicit Metadata From 45e8fa78752c3ece209dcc38b787ec0c1706fdab Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 20:08:56 -0400 Subject: [PATCH 24/46] s --- mdbook/src/data_model_metadata.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index c096954f..32db5127 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -126,6 +126,7 @@ The possible `state` values in ascending order of severity are: | emergency | The value indicates a life-threatening condition | Examples: + An engine RPM path can indicate the engine's redline segment from 3200 to 3500 rpm at the alarm severity. With this information consumers can opt to draw a red marker over this segment on it's gauge and sound an alarm when the RPM enters this zone. @@ -135,12 +136,12 @@ information consumers can opt to draw a red marker over this segment on it's gau ] ``` -A refrigeration temperature sensor with duplicate state severity but with different messages. +A refrigeration temperature sensor with duplicate state severity and different messages. ```json "zones": [ - {"upper": -2, "state": "warm", "message": "Freezing temperature reached"}, - {"lower": -2, "upper": 1, "state": "alert", "message": "Excessive energy usage"}, + {"upper": -2, "state": "warn", "message": "Freezing temperature reached"}, + {"lower": -2, "upper": 1, "state": "alert", "message": "Excessive energy expenditure"}, {"lower": 5, "upper": 8, "state": "warn", "message": "Perishable storage at risk"}, {"lower": 8, "state": "alarm", "message": "Risk of bacterial growth and food spoilage"} ] @@ -164,7 +165,7 @@ be relevant if the gauge/display design permits it. These properties guide consumers on handling `zones` notifications, each corresponding to a different severity level. They are arrays that may include `sound`, `visual`, or both. An empty array `[]` signifies no visual or audio notification. The automatically generated `normalMethod` notification always has `[]`. -A `alertMethod` would typically use +Typically, an `alertMethod` would be configured as: ```json "alertMethod": ["visual"] ``` From 1a1994b360b7815ab3fd6091757b6bad573b32d7 Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 22:16:41 -0400 Subject: [PATCH 25/46] aa --- mdbook/src/data_model_metadata.md | 25 +------ mdbook/src/notifications.md | 118 ++++++++++++++++++------------ 2 files changed, 74 insertions(+), 69 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 32db5127..2bb9a097 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -1,4 +1,4 @@ -o# Metadata +# Metadata A key part of Signal K is the ability for data consumers such as apps or MFDs to automatically configure themselves based on settings retrieved from the server. The metadata component of Signal K facilitates this through an optional @@ -173,14 +173,12 @@ Consumers have the flexibility to interpret and apply these methods, enabling th ## Implicit Metadata -All keys in the Signal K specification must have a `description`, and where the key is a numeric value it must have -`units`. +All keys in the Signal K specification must have a `description`, and where the key is a numeric value it must have `units`. If a client requests the `meta` property for a valid Signal K key via the HTTP REST interface, the server must return the `description` and, if applicable, `units`, even if no value has ever been generated for that key. -If a key has values determined by an enum, the server should include the enum in the meta. NB. in future versions -it is likely that this will become a mandatory requirement for the server. +If a key has values determined by an enum, the server should include the enum in the meta. NB. in future versions it is likely that this will become a mandatory requirement for the server. ```javascript // GET /signalk/v1/api/vessels/self/environment/depth/belowKeel/meta @@ -199,23 +197,6 @@ Signal K does not provide a default set of metadata, it is up to the owner or th K environment appropriately for their vessel. However, by centralizing this configuration they will only need to do it one time and any future consumers will automatically use this configuration. -## Alarm Management - -An alarm watch is set by setting the `meta.zones` array appropriately. A background process on the server checks for -alarm conditions on any attribute with a `meta.zones` array. If the keys value is within a zone the server sets an -alarm key similar to `vessels.self.notifications.[original_key_suffix]`, e.g. an alarm set on -`vessels.self.navigation.courseOverGroundTrue` will become -`vessels.self.notifications.navigation.courseOverGroundTrue`. - -The object found at this key should contain the following: - -```json -{ - "message": "any text", - "state": "[normal|alert|warn|alarm|emergency]" -} -``` - ## Other Benefits While not strictly part of the Signal K specification, metadata configuration could be shared between boats or even diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index fa89461a..d85e6e90 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -1,36 +1,38 @@ -# Alarm, Alert, and Notification Handling +# Notification Handling -Handling alarms, alerts, and notifications in Signal K is a multi-stage process. Alarms, alerts and notifications are -all handled the same way, and are all referred to as alarms below. +Signal K handles notifications through a multi-stage process, treating all notifications uniformly. Notifications originate from two sources: -We need a flexible model to define alarm conditions, and a standard way to announce and record them. +1. Path value state information +2. Vessel and crew information -## Alarm Process +A flexible model is required to define various informative and alarming severities, along with a standard method for announcement and management. -* Define alarm states as zones in the meta object attached to any Signal K value. See [[Metadata for Data Values]] -* If the value is within an alarm zone raise the defined alarm. -* If the value goes out of the zone, remove the alarm by setting its value to null -* Alarms are raised by placing an alarm object in the `vessels.self.notifications` tree +## Notification Process -## Expected implementation behaviour +* Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [[Metadata for Data Values]]. +* If `meta.zones` contains at least one item, the server sends a notification to qualify the value, even if the value doesn't fall within a defined `meta.zones` item. +* When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. +* If the value transitions to or enters a zone, the server raises the defined notification. +* If the value leaves all zones, the server sends a normal state value notification. +* Notifications are raised by placing a notification object in the `vessels.self.notifications` tree. -* The server (or device) should monitor the current value and compare it to the defined zones. -* If a value enters an alarm zone, then a key is written to `vessels.self.notifications..` -* If a value leaves an alarm zone, then the key is removed from `vessels.self.notifications..` -* Alarms raised are monitored by an alarm process on the server, which takes appropriate action, sounding alarms, or - displaying messages. -* Clients interested in alarms can subcribe to the `vessels.self.notifications...` tree in the usual way and be informed - of alarms in the same way as normal signalk keys. -* When an alarms is removed, a delta should be sent to subscribers with the path and a null value. +## Expected Implementation Behavior + +* The server (or device) should monitor the current value and compare it to the defined meta zones. +* If the value changes zone, a key is written to `vessels.self.notifications..`. +* If the value matches no zone, a key indicating normal state is written to `vessels.self.notifications..`. +* Notifications raised are monitored by a notification process on the server, which takes appropriate action, such as sounding alarms or displaying messages. +* Clients interested in alarms can subscribe to the `vessels.self.notifications...` tree in the usual way and be informed of notifications in the same way as normal Signal K keys. +* When a notification is cleared, a delta should be sent to subscribers indicating the notification has returned to its normal state. ## Example eg If we exceed our anchor alarm radius: `vessels.self.navigation.anchor.currentRadius` enters `vessels.self.navigation.anchor.currentRadius.meta.zones : [ {lower: "0", upper: maxRadius, state : "normal"}, {lower: maxRadius, upper: 999999, state: "alarm"}]` -The alarm is : `vessels.self.notifications.navigation.anchor.currentRadius` +The notification is : `vessels.self.notifications.navigation.anchor.currentRadius` -The alarm object is +The notification object is [>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip currentRadius --ellipsify timestamp "'$..['\$source']'") ``` @@ -45,25 +47,25 @@ The alarm object is } ``` [<]: # -The server alarm manager will see this new entry and turn on the alarm. Using a manager process allows flexibility in -situations where multiple alarms are triggered and your vessel is a mass of flashing and beeping. eg A single 'Pause' +The server notification manager will see this new entry and turn on the sound. Using a manager process allows flexibility in +situations where multiple notifications of various severity are triggered and your vessel is a mass of flashing and beeping. eg A single 'Pause' button can give you 5-10 minutes to take action, stopping annoying noise, and removing popup messages from screens. Since the `vessels.self.notifications` tree mirrors the other data in the signal k model, we can selectively watch or -react to specific branches or keys. When displaying multiple alarms a screen can also sort and filter them. +react to specific branches or keys. When displaying multiple notifications a screen can also sort and filter them. -## Other Alarms +## Other notifications -Above we have discussed monitoring existing values and raising alarms. There are other alarms that must be considered, +Above we have discussed monitoring existing values and raising notification. There are other notifications that must be considered, eg MOB, fire, sinking etc, and misc alerts "GPS signal lost".etc. The `vessels.[uuid].notifications` tree is the same as any other Signal k branch. Keys can be added and removed as required in the usual way. Since the branch is being monitored we only need to add a key of any sort to create a suitable alarm. -In the case of an emergency, create a unique key: The alarm is : `vessels.[uuid].notifications.[alarm.key]` +In the case of an emergency, create a unique key: The notification is : `vessels.[uuid].notifications.[alarm.key]` -The alarm object is +The notification object is [>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip mob --ellipsify $ ~value) ``` @@ -77,13 +79,13 @@ The alarm object is } ``` [<]: # -Alarm objects that have been raised this way must be cleared manually, or by the process that created them. You can use -any suitable path, keeping in mind the context of the alarm. +Notification objects that have been raised this way must be cleared manually, or by the process that created them. You can use +any suitable path, keeping in mind the context of the notification. -eg In the case of an alert, create a unique key by generating a path: The alarm is : +eg In the case of an alert, create a unique key by generating a path: The notification is : `vessels.[uuid].notifications.navigation.gnss` -The alarm object is +The notification object is [>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --snip gnss --ellipsify $ ~value) ``` @@ -99,7 +101,7 @@ The alarm object is [<]: # ### Well Known Names -Some alarms are especially important, eg MOB. This is a list of keys for special alarms. +Some notifications are especially important, eg MOB. This is a list of keys for special notifications. * `..notifications.mob.*` * `..notifications.fire.*` * `..notifications.sinking.*` @@ -111,7 +113,7 @@ Some alarms are especially important, eg MOB. This is a list of keys for special * `..notifications.piracy.*` * `..notifications.abandon.*` -An example to send an MOB alarm from an N2K source, the gateway would convert and send something like: +An example to send an MOB notification alarm from an N2K source, the gateway would convert and send something like: [>]: # (mdpInsert ``` fsnip ../../samples/delta/docs-notifications.json --delKeys $.updates[1] --ellipsify source) ``` @@ -136,7 +138,7 @@ An example to send an MOB alarm from an N2K source, the gateway would convert an } ``` [<]: # -The resulting full signalk tree would be: +The resulting full Signal K tree would be: [>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --ellipsify $ ~vessels --delKeys navigation --ellipsify uuid "'$..['\$source']'") ``` @@ -161,7 +163,8 @@ The resulting full signalk tree would be: } ``` [<]: # -To clear the alarm condition, send: + +To clear the notification condition, send: [>]: # (mdpInsert ``` fsnip ../../samples/delta/docs-notifications.json --delKeys $.updates[0] --ellipsify source) ``` @@ -170,11 +173,15 @@ To clear the alarm condition, send: "updates": [ { "source": {...}, - "timestamp": "2017-08-15T16:00:05.538Z", + "timestamp": "2017-08-15T16:00:05.200Z", "values": [ { "path": "notifications.mob", - "value": null + "value": { + "message": "", + "state": "normal", + "method": [] + } } ] } @@ -182,22 +189,39 @@ To clear the alarm condition, send: } ``` [<]: # -## Multiple cases of the same alarm -Should multiple cases of the same alarm occur (eg a gps loses signal, then a second gps loses signal) the alarms are -handled the same as any other multiple values in signalk. However alarms will tend to be re-issued whenever the +## Multiple cases of the same notification + +Should multiple cases of the same notification occur (eg a gps loses signal, then a second gps loses signal) the notifications are +handled the same as any other multiple values in Signal K. However notification will tend to be re-issued whenever the underlying data changes. -The servers alarm monitoring processes are expected to be smart enough to know that the anchor alarm is triggered, and -its not necessary to raise a second copy of the same alarm, after all there is only one boat dragging! +The servers notification monitoring processes are expected to be smart enough to know that the anchor notification of state alarm is triggered, and +its not necessary to raise a second copy of the same notification and state, after all there is only one boat dragging! This may be handled differently for notifications. It may be useful to know that your gps's are all failing -intermittently, or that . Hence the handling of multiple copies of alarms is an implementation issue, and may vary. +intermittently, or that . Hence the handling of multiple copies of notifications is an implementation issue, and may vary. ## The key should be unique -If we have an alarm `vessels.self.notifications.navigation.anchor.currentRadius` and we attempt to write another higher -in the same tree at `vessels.self.notifications` it must not replace or remove the existing alarm. Since the -`meta.zones` structure is only valid on signalk leaf values this occurs naturally in most circumstances. But it is -possible to set an alarm value arbitrarily (eg MOB) and care should be taken in implementations that keys do not +If we have a notification `vessels.self.notifications.navigation.anchor.currentRadius` and we attempt to write another higher +in the same tree at `vessels.self.notifications` it must not replace or remove the existing notification. Since the +`meta.zones` structure is only valid on Signal K leaf values this occurs naturally in most circumstances. But it is +possible to set a notification value arbitrarily (eg MOB) and care should be taken in implementations that keys do not overwrite existing paths. + +## Notification Management + +An notification watch is set by setting the `meta.zones` array appropriately. A background process on the server checks for +notification conditions on any attribute with a `meta.zones` array. If the keys value is within a zone the server sets a notification key similar to `vessels.self.notifications.[original_key_suffix]`, e.g. a notification set on +`vessels.self.navigation.courseOverGroundTrue` will become +`vessels.self.notifications.navigation.courseOverGroundTrue`. + +The object found at this key should contain the following: + +```json +{ + "message": "any text", + "state": "[normal|alert|warn|alarm|emergency]" +} +``` From 81726f22f458e05ae4d9f16b8d07caf15afb7102 Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 22:32:05 -0400 Subject: [PATCH 26/46] final --- mdbook/src/notifications.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index d85e6e90..fc53beed 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -1,4 +1,4 @@ -# Notification Handling +# Notifications Signal K handles notifications through a multi-stage process, treating all notifications uniformly. Notifications originate from two sources: @@ -25,6 +25,20 @@ A flexible model is required to define various informative and alarming severiti * Clients interested in alarms can subscribe to the `vessels.self.notifications...` tree in the usual way and be informed of notifications in the same way as normal Signal K keys. * When a notification is cleared, a delta should be sent to subscribers indicating the notification has returned to its normal state. +## Severity and Presentation Definition + +* Every notification must include a `state` property to specify its severity level. +* Every notification must include a `method` array property to determine if the notification should result in an audio, visual, both, or no presentation. + +| State | Description | +|------------|--------| +| normal | Server generated - The normal value (default) | +| nominal | All systems OK | +| alert | Indicates a safe or normal condition which is brought to the operators attention to impart information | +| warn | Indicates a condition that requires immediate attention but not immediate action | +| alarm | Indicates a condition which is outside the specified acceptable range. Immediate action is required to prevent loss of life or equipment damage | +| emergency | The value indicates a life-threatening condition | + ## Example eg If we exceed our anchor alarm radius: `vessels.self.navigation.anchor.currentRadius` enters From 5277422aa8b692b56e7c418c15330eb53ee965c0 Mon Sep 17 00:00:00 2001 From: godind Date: Wed, 24 Apr 2024 22:50:46 -0400 Subject: [PATCH 27/46] asdfds --- mdbook/src/notifications.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index fc53beed..dd5ad2ed 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -9,6 +9,8 @@ A flexible model is required to define various informative and alarming severiti ## Notification Process +* The definition of an "alarming" notification is defined by the notification's state severity. +* The lowest state severity is considered normal - not alarming. * Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [[Metadata for Data Values]]. * If `meta.zones` contains at least one item, the server sends a notification to qualify the value, even if the value doesn't fall within a defined `meta.zones` item. * When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. @@ -28,7 +30,7 @@ A flexible model is required to define various informative and alarming severiti ## Severity and Presentation Definition * Every notification must include a `state` property to specify its severity level. -* Every notification must include a `method` array property to determine if the notification should result in an audio, visual, both, or no presentation. +* Every notification must include a `method` array property to determine if the notification should result in a sound, visual, both, or no presentation. | State | Description | |------------|--------| @@ -39,6 +41,10 @@ A flexible model is required to define various informative and alarming severiti | alarm | Indicates a condition which is outside the specified acceptable range. Immediate action is required to prevent loss of life or equipment damage | | emergency | The value indicates a life-threatening condition | +## Resolving and silencing notifications +* To silence a notification, resend the original notification, less method array sound item value. This will preserve the notification but remove sound. +* To resolve a notification, send to the path with a state equal normal. Alarming notifications are difined by there state severity, not by their existance. + ## Example eg If we exceed our anchor alarm radius: `vessels.self.navigation.anchor.currentRadius` enters @@ -113,6 +119,7 @@ The notification object is } ``` [<]: # + ### Well Known Names Some notifications are especially important, eg MOB. This is a list of keys for special notifications. @@ -152,6 +159,7 @@ An example to send an MOB notification alarm from an N2K source, the gateway wou } ``` [<]: # + The resulting full Signal K tree would be: [>]: # (mdpInsert ``` fsnip ../../samples/full/docs-notifications.json --ellipsify $ ~vessels --delKeys navigation --ellipsify uuid "'$..['\$source']'") From f20f5d6247dad66a01e57aaaf0be1701f8160cd7 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 12:53:50 -0400 Subject: [PATCH 28/46] Update notifications.md --- mdbook/src/notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index dd5ad2ed..acda691e 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -12,7 +12,7 @@ A flexible model is required to define various informative and alarming severiti * The definition of an "alarming" notification is defined by the notification's state severity. * The lowest state severity is considered normal - not alarming. * Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [[Metadata for Data Values]]. -* If `meta.zones` contains at least one item, the server sends a notification to qualify the value, even if the value doesn't fall within a defined `meta.zones` item. +* If `meta.zones` contains at least one item, the server deternies the value's state and sends a notification, even if the value doesn't fall within a defined `meta.zones` item. * When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. * If the value transitions to or enters a zone, the server raises the defined notification. * If the value leaves all zones, the server sends a normal state value notification. From dcbcdddadab2f5620fc6fe740ae04c449853bf15 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 12:56:27 -0400 Subject: [PATCH 29/46] Update notifications.md --- mdbook/src/notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index acda691e..446d9b6d 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -12,7 +12,7 @@ A flexible model is required to define various informative and alarming severiti * The definition of an "alarming" notification is defined by the notification's state severity. * The lowest state severity is considered normal - not alarming. * Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [[Metadata for Data Values]]. -* If `meta.zones` contains at least one item, the server deternies the value's state and sends a notification, even if the value doesn't fall within a defined `meta.zones` item. +* If `meta.zones` contains at least one item, the server deternies the value's state and sends a notification. * When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. * If the value transitions to or enters a zone, the server raises the defined notification. * If the value leaves all zones, the server sends a normal state value notification. From cd4a61fb67506729524ee3f5a64ce81f139377fa Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 13:07:17 -0400 Subject: [PATCH 30/46] Update notifications.md --- mdbook/src/notifications.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index 446d9b6d..ae1a6cdf 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -42,8 +42,8 @@ A flexible model is required to define various informative and alarming severiti | emergency | The value indicates a life-threatening condition | ## Resolving and silencing notifications -* To silence a notification, resend the original notification, less method array sound item value. This will preserve the notification but remove sound. -* To resolve a notification, send to the path with a state equal normal. Alarming notifications are difined by there state severity, not by their existance. +* To silence a notification, the serve or clients, send delta notification replica without the `sound` item the method array. +* To resolve a notification, the serve or clients, send delta notification replica with a state value of `normal`. Alarming notifications are difined by there state severity, not by their existance. ## Example From 86fbf9090daa53b427dca6041e91d001635339fe Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 16:46:37 -0400 Subject: [PATCH 31/46] Update notifications.md --- mdbook/src/notifications.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index ae1a6cdf..74ae4bb7 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -29,8 +29,8 @@ A flexible model is required to define various informative and alarming severiti ## Severity and Presentation Definition -* Every notification must include a `state` property to specify its severity level. -* Every notification must include a `method` array property to determine if the notification should result in a sound, visual, both, or no presentation. +* Notification must include a `state` property to specify its severity level. +* Notification must include a `method` array property to determine if the notification should result in a sound, visual, both, or no presentation. | State | Description | |------------|--------| From b965efec17fb3677ad0fe5e13a70183b50bb9dd5 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 16:49:31 -0400 Subject: [PATCH 32/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 2bb9a097..695f42da 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -112,7 +112,7 @@ Zones can technically have from zero to an infinite number of zone segments. The Zones should be configured with care. In practice, less is more. -For detailed information on Notifications, refer to [Alarm Handling](notifications.md). +For detailed information on Notifications, refer to [Notifications](notifications.md). The possible `state` values in ascending order of severity are: From 3d56049a47e7e658589b5d70b6a9a305b0e3b98c Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 16:50:53 -0400 Subject: [PATCH 33/46] Update notifications.md --- mdbook/src/notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index 74ae4bb7..61ceef9c 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -11,7 +11,7 @@ A flexible model is required to define various informative and alarming severiti * The definition of an "alarming" notification is defined by the notification's state severity. * The lowest state severity is considered normal - not alarming. -* Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [[Metadata for Data Values]]. +* Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [Metadata](data_model_metadata.md). * If `meta.zones` contains at least one item, the server deternies the value's state and sends a notification. * When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. * If the value transitions to or enters a zone, the server raises the defined notification. From fc8f33c7e5a6d98fa312115a2acacd2727f2037c Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 16:54:13 -0400 Subject: [PATCH 34/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 695f42da..27ac65a8 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -96,7 +96,7 @@ Note that on a logarithmic scale neither L nor U can be zero. ### zones Zones define value operating conditions and associated notification prompts. They help in presenting display scales and notifying end users effectively. -Each item in the `zones` array represents a segment of value states. The `state` of each item indicates the severity of the segment. Any data not part of a zone range defaults to the `normal` state. +Each item in the `zones` array represents a segment (a zone) of value states. The `state` of each item indicates the severity of the segment. Any value not part of a zone range defaults to the `normal` state. As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. From 5016ca789600017a4935c47e2888c0e8b8b1e9e1 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:02:41 -0400 Subject: [PATCH 35/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 27ac65a8..cafb2ad7 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -96,11 +96,11 @@ Note that on a logarithmic scale neither L nor U can be zero. ### zones Zones define value operating conditions and associated notification prompts. They help in presenting display scales and notifying end users effectively. -Each item in the `zones` array represents a segment (a zone) of value states. The `state` of each item indicates the severity of the segment. Any value not part of a zone range defaults to the `normal` state. +Each item in the `zones` array represents a segment (a zone) of value states. The `state` of each item indicates the severity of the zone. Any value not part of a zone range defaults to the `normal` state. As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -If defined, Signal K servers use the `zones` information in each path `meta` object to monitor the value and raise value state notifications. +If defined, Signal K servers use the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 22b7b1160fe37d549ac468566f1d9d9cff16038e Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:03:37 -0400 Subject: [PATCH 36/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index cafb2ad7..72972b76 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -100,7 +100,7 @@ Each item in the `zones` array represents a segment (a zone) of value states. Th As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -If defined, Signal K servers use the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. +Signal K servers use the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 51c4a04321b4826e7a6f40206f75d9a47da20ec5 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:04:01 -0400 Subject: [PATCH 37/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 72972b76..ddf73b60 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -100,7 +100,7 @@ Each item in the `zones` array represents a segment (a zone) of value states. Th As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -Signal K servers use the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. +Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 0a6d561df7d97523386f473421afe75c34b0104a Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:05:01 -0400 Subject: [PATCH 38/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index ddf73b60..747796a3 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -100,7 +100,7 @@ Each item in the `zones` array represents a segment (a zone) of value states. Th As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array stated configuration in place, value-related notifications are disabled. +Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array configuration, value-related notifications are disabled. The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 02509804957c6e3d5f369fa20f1325a0e393907f Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:06:48 -0400 Subject: [PATCH 39/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 747796a3..8a958c74 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -100,7 +100,7 @@ Each item in the `zones` array represents a segment (a zone) of value states. Th As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. -Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, no value-related notifications will be sent. In short, without `meta.zones` array configuration, value-related notifications are disabled. +Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, value-related notifications are disabled (including normal state). The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 8687bf3daf8a25b60e261d594e4951727a5d4a22 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:09:11 -0400 Subject: [PATCH 40/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 8a958c74..b9c81447 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -98,9 +98,7 @@ Zones define value operating conditions and associated notification prompts. The Each item in the `zones` array represents a segment (a zone) of value states. The `state` of each item indicates the severity of the zone. Any value not part of a zone range defaults to the `normal` state. -As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. - -Signal K server uses the `zones` array information in each path `meta` object to monitor the value and raise value state notifications. If the `meta.zones` array does not contains items or is undefined, value-related notifications are disabled (including normal state). +As values transition between zones, notifications are dispatched to inform about the value's state. All value-related notifications are defined within zones, and a zone's state determines the severity of the notifications. If the `meta.zones` array does not contains items or is undefined, value-related notifications are disabled (including `normal` state notifications). The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. From 1074019b4d88e5c0b83b957d7774242650327b17 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:13:04 -0400 Subject: [PATCH 41/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index b9c81447..419758b8 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -102,7 +102,7 @@ As values transition between zones, notifications are dispatched to inform about The `lower` and `upper` values in zones need not be contiguous or both present within a zone, nor do they have to fall within the upper and lower bounds specified in `displayScale`. They still trigger notifications even when outside the `displayScale` range. -In cases where zones overlap, the zone with the highest `state` severity takes precedence. Any range not explicitly within a zone is considered `normal` by default. +In cases where zones overlap, the zone with the highest `state` severity takes precedence. Any range not explicitly within a zone will dispatch a notification with state `normal`. Zones can technically have from zero to an infinite number of zone segments. The same `state` can be present in multiple segments. From bb61ee7e0865cef34a2ad5c53f94c8ada5f9470b Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 17:15:22 -0400 Subject: [PATCH 42/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 419758b8..75d4eb4b 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -106,7 +106,7 @@ In cases where zones overlap, the zone with the highest `state` severity takes p Zones can technically have from zero to an infinite number of zone segments. The same `state` can be present in multiple segments. -`message`is the message that will be included in the notification when the value enters the zone. The message should be concise and short ie. a few words. The message may end up on a gauges with limited space. +Property `message` represent the informationnal text that will be included in the notification. The message should be concise ie. a few words. The message may end up on a gauges with limited space. Zones should be configured with care. In practice, less is more. From 7d8e3615ca4eb79b6cdc886b8d80a75b4d26093a Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 18:48:13 -0400 Subject: [PATCH 43/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 81 ++++++++++++++++--------------- 1 file changed, 43 insertions(+), 38 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 75d4eb4b..aa86d026 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -94,7 +94,7 @@ Where: V = value, L = lower bound of the gauge, U = upper bound of the gauge and Note that on a logarithmic scale neither L nor U can be zero. ### zones -Zones define value operating conditions and associated notification prompts. They help in presenting display scales and notifying end users effectively. +Zones define operating conditions and associated severity. They help in presenting display scales and informing end users effectively. Each item in the `zones` array represents a segment (a zone) of value states. The `state` of each item indicates the severity of the zone. Any value not part of a zone range defaults to the `normal` state. @@ -112,7 +112,7 @@ Zones should be configured with care. In practice, less is more. For detailed information on Notifications, refer to [Notifications](notifications.md). -The possible `state` values in ascending order of severity are: +#### The possible `state` values in ascending order of severity | State | Description | |------------|--------| @@ -123,45 +123,13 @@ The possible `state` values in ascending order of severity are: | alarm | Indicates a condition which is outside the specified acceptable range. Immediate action is required to prevent loss of life or equipment damage | | emergency | The value indicates a life-threatening condition | -Examples: - -An engine RPM path can indicate the engine's redline segment from 3200 to 3500 rpm at the alarm severity. With this -information consumers can opt to draw a red marker over this segment on it's gauge and sound an alarm when the RPM enters this zone. - -```json - "zones": [ - {"lower": 3200, "upper": 3500, "state": "alarm", "message": "Risk of engine damage"} - ] -``` - -A refrigeration temperature sensor with duplicate state severity and different messages. - -```json - "zones": [ - {"upper": -2, "state": "warn", "message": "Freezing temperature reached"}, - {"lower": -2, "upper": 1, "state": "alert", "message": "Excessive energy expenditure"}, - {"lower": 5, "upper": 8, "state": "warn", "message": "Perishable storage at risk"}, - {"lower": 8, "state": "alarm", "message": "Risk of bacterial growth and food spoilage"} - ] -``` - -For engine monitoring eg. coolant temperature where there is a 'normal' (no warnings) -(green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple -sensors) where it is very easy to spot that every needle is pointing in exactly the same direction. Use of nominal will only -be relevant if the gauge/display design permits it. +### nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod -```json - "zones": [ - {"upper": 60, "state": "alert", "message": "Cold or Startup Temperature"}, - {"lower": 70, "upper": 80, "state": "nominal", "message": "Temperature Nominal"}, - {"lower": 85, "upper": 95, "state": "warn", "message": "High Temperature"}, - {"lower": 95, "state": "alarm", "message": "Engine Overheat"} - ] -``` +Methods properties define what kind of prompts consumers should render when receiving a notification. -### nominalMethod, alertMethod, warnMethod, alarmMethod, emergencyMethod +Methods are arrays that accepts string items of values `sound` and `visual`. The array lenght should be no more then 2. It can contain either or both values, or be empty. An empty array `[]` signifies no visual and no audio prompts are to be enacted by consumers. The automatically generated `normalMethod` notifications is always `[]`. -These properties guide consumers on handling `zones` notifications, each corresponding to a different severity level. They are arrays that may include `sound`, `visual`, or both. An empty array `[]` signifies no visual or audio notification. The automatically generated `normalMethod` notification always has `[]`. +Each method name prefixes matches zones severity levels. When a value enters a zone, that zone will trigger a notification. The notification message will include the zone's `state` value, and the corresponding severity prefixed method array. Typically, an `alertMethod` would be configured as: ```json @@ -201,3 +169,40 @@ While not strictly part of the Signal K specification, metadata configuration co provided by manufacturers of production boats or by component suppliers such as engine or refrigerator manufacturers. Also, any device which implements Signal K should provide a baseline metadata configuration. As this standard becomes more widespread, less individual configuration will need to be performed. + +## Examples + +An engine RPM path's redline segment, from 3200 to 3500 rpm, triggering a visual and sound prompt: With this +configuration, consumers can opt to draw a red marker over a gauge segment, flash a light on the gauge and sound an alarm when the RPM enters this zone. + +```json + "zones": [ + {"lower": 3200, "upper": 3500, "state": "alarm", "message": "Risk of engine damage"} + ] +``` + +A refrigeration temperature sensor with duplicate state severity containing different messages: With this +configuration, consumers can opt to draw a multiple markers on a gauge, flash a light on the gauge and sound an alarm when the RPM enters this zone. + +```json + "zones": [ + {"upper": -2, "state": "warn", "message": "Freezing temperature reached"}, + {"lower": -2, "upper": 1, "state": "alert", "message": "Excessive energy expenditure"}, + {"lower": 5, "upper": 8, "state": "warn", "message": "Perishable storage at risk"}, + {"lower": 8, "state": "alarm", "message": "Risk of bacterial growth and food spoilage"} + ] +``` + +For engine monitoring eg. coolant temperature where there is a 'normal' (no warnings) +(green) zone between say 70C and 110C, but when the temperature is between 80C and 90C (`nominal`) the needle doesn't move at all (typically remains vertical or horizontal) indicating typical or desired range. This is really useful if you have many gauges (multiple motors with multiple +sensors) where it is very easy to spot that every needle is pointing in exactly the same direction. Use of nominal will only +be relevant if the gauge/display design permits it. + +```json + "zones": [ + {"upper": 60, "state": "alert", "message": "Cold or Startup Temperature"}, + {"lower": 70, "upper": 80, "state": "nominal", "message": "Temperature Nominal"}, + {"lower": 85, "upper": 95, "state": "warn", "message": "High Temperature"}, + {"lower": 95, "state": "alarm", "message": "Engine Overheat"} + ] +``` From df1660dbe8e98a389b269e6ed801138305b80404 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 19:07:00 -0400 Subject: [PATCH 44/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index aa86d026..56e19e6d 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -127,9 +127,9 @@ For detailed information on Notifications, refer to [Notifications](notification Methods properties define what kind of prompts consumers should render when receiving a notification. -Methods are arrays that accepts string items of values `sound` and `visual`. The array lenght should be no more then 2. It can contain either or both values, or be empty. An empty array `[]` signifies no visual and no audio prompts are to be enacted by consumers. The automatically generated `normalMethod` notifications is always `[]`. +Methods are arrays that accepts string items of values `sound` and `visual`. The array lenght should be 2 or less. It can contain either or both values, or be empty. An empty array `[]` signifies that no visual and no audio prompts should be enacted by consumers. -Each method name prefixes matches zones severity levels. When a value enters a zone, that zone will trigger a notification. The notification message will include the zone's `state` value, and the corresponding severity prefixed method array. +Each method property name is prefixe to match zone state severities. For exemple, a notification message for zone with `"state": "warn"` will include `warnMethod` values. Typically, an `alertMethod` would be configured as: ```json @@ -182,7 +182,7 @@ configuration, consumers can opt to draw a red marker over a gauge segment, flas ``` A refrigeration temperature sensor with duplicate state severity containing different messages: With this -configuration, consumers can opt to draw a multiple markers on a gauge, flash a light on the gauge and sound an alarm when the RPM enters this zone. +configuration, consumers can opt to draw a multiple markers on the gauge, maybe flash a light on the gauge and sound an alarm when the RPM enters this zone. ```json "zones": [ From f4d7bdde0b1e4c63b77f37016e532d834078fe73 Mon Sep 17 00:00:00 2001 From: David G <34038713+godind@users.noreply.github.com> Date: Thu, 25 Apr 2024 22:41:38 -0400 Subject: [PATCH 45/46] Update data_model_metadata.md --- mdbook/src/data_model_metadata.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 56e19e6d..61973674 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -178,11 +178,14 @@ configuration, consumers can opt to draw a red marker over a gauge segment, flas ```json "zones": [ {"lower": 3200, "upper": 3500, "state": "alarm", "message": "Risk of engine damage"} - ] + ], + ... + "alarmMethod": ["sound", "visual"], + ... ``` A refrigeration temperature sensor with duplicate state severity containing different messages: With this -configuration, consumers can opt to draw a multiple markers on the gauge, maybe flash a light on the gauge and sound an alarm when the RPM enters this zone. +configuration, consumers can opt to draw a multiple markers on the gauge, light up a visual indicator on the gauge and sound an alarm when the RPM enters this zone. ```json "zones": [ @@ -191,6 +194,12 @@ configuration, consumers can opt to draw a multiple markers on the gauge, maybe {"lower": 5, "upper": 8, "state": "warn", "message": "Perishable storage at risk"}, {"lower": 8, "state": "alarm", "message": "Risk of bacterial growth and food spoilage"} ] + ... + "alertMethod": ["visual"], + "warnMethod": ["sound", "visual"], + "alarmMethod": ["sound", "visual"], + ... + ``` For engine monitoring eg. coolant temperature where there is a 'normal' (no warnings) @@ -204,5 +213,10 @@ be relevant if the gauge/display design permits it. {"lower": 70, "upper": 80, "state": "nominal", "message": "Temperature Nominal"}, {"lower": 85, "upper": 95, "state": "warn", "message": "High Temperature"}, {"lower": 95, "state": "alarm", "message": "Engine Overheat"} - ] + ], + "nominalMethod": ["visual"], + "alertMethod": ["visual"], + "warnMethod": ["sound", "visual"], + "alarmMethod": ["sound", "visual"], + ... ``` From e7d02be9f7d736d85f06b4df8bf3d7b88b03f5e9 Mon Sep 17 00:00:00 2001 From: godind Date: Thu, 25 Apr 2024 22:45:06 -0400 Subject: [PATCH 46/46] final --- mdbook/src/data_model_metadata.md | 8 ++++---- mdbook/src/notifications.md | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/mdbook/src/data_model_metadata.md b/mdbook/src/data_model_metadata.md index 61973674..3e1189f3 100644 --- a/mdbook/src/data_model_metadata.md +++ b/mdbook/src/data_model_metadata.md @@ -73,7 +73,7 @@ values. The `lower` and `upper` indicate the extent of the scale to be shown. Some values are better shown on a non linear scale, for example logarithmic for luminosity, depth, signal strength, etc. whilst others may be better on a squareroot -scale eg. depth, windspeed. +scale eg. depth, wind speed. `type` has possible values of `linear` (default), `logarithmic`, `squareroot` or `power`. When `"type": "power"` is specified an additional property `power` must be present to define the power. Note that a power of @@ -106,7 +106,7 @@ In cases where zones overlap, the zone with the highest `state` severity takes p Zones can technically have from zero to an infinite number of zone segments. The same `state` can be present in multiple segments. -Property `message` represent the informationnal text that will be included in the notification. The message should be concise ie. a few words. The message may end up on a gauges with limited space. +Property `message` represent the informational text that will be included in the notification. The message should be concise ie. a few words. The message may end up on a gauges with limited space. Zones should be configured with care. In practice, less is more. @@ -127,9 +127,9 @@ For detailed information on Notifications, refer to [Notifications](notification Methods properties define what kind of prompts consumers should render when receiving a notification. -Methods are arrays that accepts string items of values `sound` and `visual`. The array lenght should be 2 or less. It can contain either or both values, or be empty. An empty array `[]` signifies that no visual and no audio prompts should be enacted by consumers. +Methods are arrays that accepts string items of values `sound` and `visual`. The array length should be 2 or less. It can contain either or both values, or be empty. An empty array `[]` signifies that no visual and no audio prompts should be enacted by consumers. -Each method property name is prefixe to match zone state severities. For exemple, a notification message for zone with `"state": "warn"` will include `warnMethod` values. +Each method property name is prefix to match zone state severities. For example, a notification message for zone with `"state": "warn"` will include `warnMethod` values. Typically, an `alertMethod` would be configured as: ```json diff --git a/mdbook/src/notifications.md b/mdbook/src/notifications.md index 61ceef9c..fb0a2dcb 100644 --- a/mdbook/src/notifications.md +++ b/mdbook/src/notifications.md @@ -12,7 +12,7 @@ A flexible model is required to define various informative and alarming severiti * The definition of an "alarming" notification is defined by the notification's state severity. * The lowest state severity is considered normal - not alarming. * Notification states are defined as zone segments (array items) in the meta object attached to any Signal K path. See [Metadata](data_model_metadata.md). -* If `meta.zones` contains at least one item, the server deternies the value's state and sends a notification. +* If `meta.zones` contains at least one item, the server determines the value's state and sends a notification. * When a value doesn't fall within any `meta.zones`, the server raises a default notification indicating a normal value state. * If the value transitions to or enters a zone, the server raises the defined notification. * If the value leaves all zones, the server sends a normal state value notification. @@ -43,7 +43,7 @@ A flexible model is required to define various informative and alarming severiti ## Resolving and silencing notifications * To silence a notification, the serve or clients, send delta notification replica without the `sound` item the method array. -* To resolve a notification, the serve or clients, send delta notification replica with a state value of `normal`. Alarming notifications are difined by there state severity, not by their existance. +* To resolve a notification, the serve or clients, send delta notification replica with a state value of `normal`. Alarming notifications are defined by there state severity, not by their existence. ## Example