Parameter Definition
- nicholas pearson
- Andy Malinowski (Unlicensed)
The following properties instruct our integration layer on how to parse, store, and display data received from the equipment. If the equipment supports multi-cavities, then these definitions apply to all elements in the array of values.
Sections:
The key for the JSON key/value pair. It is also used as the internal database attribute name. It must consist of alpha-numeric and underscore characters only. It is case sensitive.
E.g.: set_temp
Label
The user-friendly name of the data point to be displayed in several places throughout Open Kitchen: graphs, charts, widgets, reports, and alerts. Display Name may consist of alphanumeric characters, whitespace, and UTF-8 punctuation. US English is the default/standard language.
Language files will need to be provided/created to support additional languages. If translations exist, these should be provided as additional columns in the data dictionary spreadsheet.
E.g.: Kettle Setpoint
Parameter Type
Instructs Open Kitchen on how to decode and handle the values send to the cloud. This deals with the structure of the data and how to interpret it rather that the contents
Numbers can be integers, floating point or ASCII strings of numerals. Open Kitchen will convert them to the appropriate internal representation. Only integers and floating-point numbers are supported, binary numbers and hexadecimal numbers must be sent up as Text strings.
ENUMs are useful for reporting telemetry data such as operating state or operating there are discrete set of possible readings.
If translations are available for the Enumerated Value definitions, they should be provided.
For visualization purposes, Open Kitchen sometimes will plot enumerated values on a chart. This is useful if trying to correlate data (e.g., temperature) with something like operating state. If there is a desire to plot an enumerated value on a chart, it is best to pick the enumerated values to be in monotonic order with the same separation between values. Ideally the default or off state would be the lowest value and the running or exception states would be the higher values.
Binary or Boolean data is represented in Open Kitchen through ENUMs. A binary reading such as whether a door is in the open or closed state is represented by an ENUM with two values: Open, Closed. This way the implementer can freely define how switches or binary sensors can be displayed.
e.g.:
● On/Off
● Open/Closed
● Dry/Wet
● Etc
The mapping of the ENUM integers to labels are controlled by the ENUMs sheet.
The Alert attribute indicates whether to send an Open Kitchen Alert message if the key described has the enumerated value indicated.
Bitmasks are useful for densely encoding information into a single field, or more commonly used for things like alarms/faults where multiple faults can occur at the same time.
Bitmap: Value to be decoded as a bitmask. If multiple bits are set, multiple values will be reported for that data point. Raw reading should be passed as integer or string representing a hexadecimal number (e.g. 128 or "80")
In Figure 7 Bitmask, a simple example of a 5-bit bitmask is shown. This example is for a piece of equipment that has 5 possible fault conditions. These faults can occur simultaneously, so it is desired to be able to report multiple faults at the same time. Each bit in the binary number represented by the integer or hexadecimal number represents the state of the fault. i.e., Active or not.
If {"fault": 21} or {"fault": "0015"} was passed by ConnectWare to Open Kitchen would decode the bitmask to (0001 0101) and Open Kitchen would interpret the currently active faults as " E-01 Bad Bottom Temp Sensor, E-03 Over Current (peak), E-07 Low Line Voltage".
The mapping of the bitmask bit fields is configured on the bitmask sheet.
The Alert attribute indicates to Open Kitchen that it should generate an alert notification if a payload with the corresponding value is set. Alert Messages is defined in Section 5 Alert Messaging.
If translations are available for the Enumerated Value definitions, they should be provided.
The JSON Parameter Type is typically not decoded by Open Kitchen. It is typically used for logging or capturing important information. Open Kitchen has an Event Viewer Widget that will display JSON data in a nicely formatted manner. JSON data can also be exported as well.
Class
The class of parameter is used by Open Kitchen to determine where to present the data in the UI/UX and Open Kitchen developers understand the type of data and the frequency that it may be delivered.
This describes essentially static data. It is information about the model and configuration of equipment. It would also include things like serial numbers, detailed model numbers, manufacturing date, optional configurations, firmware revisions, etc. This information is static information that rarely changes. Normally this is sent to Open Kitchen whenever the unit powers on, resets or when any of the information changes. Best practice is to send this data at least once per day, or on a regular but infrequent basis. This information should not be included in regular 1-minute heartbeats or combined with telemetry data as it does not change often.
Telemetry data is data that should be sent to Open Kitchen regularly (at least once per minute). It is the dynamic data with the equipment that is constantly changing. It should include all critical measurements, e.g. temperature, pressure, power, current, fan speed etc., operating state, e.g. off, on, standby, preheat, heat, hold, etc., mode e.g. proofing, baking, etc. Telemetry data normally would be included in several Open Kitchen Widgets to provide near real time status of the equipment and could also be included on history charts and spreadsheet exports.
This would include static information that is changed infrequently but is adjustable on the equipment by the user or through Open Kitchen. E.g. Menu item, setpoint temperature, fan speed set point, etc.
These are normally asynchronous events that are sent to Open Kitchen when they occur. E.g. fault/alarm where an event is sent when the alarm triggers and when the alarm clears. It could also be a cook start and a cook end. Or door open, door close.
Unit
Unit is used only for telemetry data and defines the type of reading. Open Kitchen supports full localization of units, si units will be converted to the standard units used in the locale chosen by the Open Kitchen user. E.g. In the US, all temperatures will be displayed in degrees Fahrenheit (F) and distances in miles, feet or inches. In the UK, all temperatures will be displayed in degrees Celsius (C) and distances in km, meters or millimeters.
The unit in the data dictionary defines the unit the equipment is using to send the data. E.g. If the soup kettle is sending data in degrees Celsius, the Unit in the dictionary would be "C". If the Open Kitchen user selected US for the locale (en-US) then the units will automatically be converted and displayed in Fahrenheit (F).
The unit abbreviations are ISO standard units and Open Kitchen contains conversion libraries for converting units within type families.
Appendix A - Measurement units contain the set of units currently supported by Open Kitchen. Additional units can be added by contacting Powerhouse Dynamics.
Scaling
Scale factor or equation used to convert raw data provided by equipment into defined units. In most cases, the scale factor will be 1, i.e. no scaling. Scaling is useful for converting non-standard units. E.g. If a piece of equipment is measuring temperature in tens of degrees Fahrenheit, these readings can automatically be scaled to degrees Fahrenheit by specifying a scaling of "0.1".
More complex scaling can be handled by specifying an equation. In the equation the variable "v" represents the value being sent by the equipment.
An example of a complex scaling is a thermistor equation. Figure 8 Scaling Example Thermistor Equation shows the scaling for converting a voltage measured across at Type 2 10K thermistor to degrees Fahrenheit. This example uses a five-degree polynomial to fit the voltage reading to the provided thermistor resistance vs temperature chart.
1.44655638* pow((v)/1000,5) - 17.93260027* pow((v)/1000,4) + 86.28428718* pow((v)/1000,3)- 198.64734294* pow((v)/1000,2)+ 249.18717215*(v)/1000 - 166.80099373
If the equation (scaling) is an integer or floating-point number then the reading is just multiplied by the scaling factor.
Precision
For numbers, this field simply supplies the precision (number of positions to the right of the decimal point) that Open Kitchen should use to display the reading. This is useful if floating point numbers are used to send data. E.g. If a temperature reading of 70.013456 degrees Fahrenheit is sent to Open Kitchen, it would be displayed verbatim by Open Kitchen unless the precision field is set. If precision is set to "2", it would be displayed as 70.01° F.
Min
For numbers, this would be the minimum value accepted for the reading. This is important to set, because it can filter out bad readings from being saved in Open Kitchen and displayed on graphs.
A good example is temperature readings. Some devices will report a temperature of 0 degrees when not in use. In the case of this warming kettle, that likely means that the kettle is not currently in use. If 0 was accepted as a valid temperature reading the charts would like temperature drops to 0° F when there is no data being reported and it should be reported as missing (null) and the chart should show a gap, rather than a zero.
To solve this problem, setting the Min attribute to 1 for this reading will cause Open Kitchen to discard all zero readings. In this case it may make more sense to set Min to 32 as freezing temperatures should not be possible.
Max
For numbers this sets the maximum allowable value accepted for readings. This will filter out high readings. A good example of using this attribute is to filter out erroneous values. If a thermistor probe is being used for measurement, a bad or open probe may report an erroneously high value. Setting Max to the highest expected value can filter out the bad readings.
Alert
Open Kitchen can automatically send alarm/alert messages to the user when an alarm condition is detected by a piece of equipment. If the Alert attribute is set in the data dictionary it indicates Open Kitchen can automatically generate a text message, email or mobile app notification based on the value for the key.
Normally alertable keys are of type Bitmask or ENUM. The ENUM or Bitmask field can be further modified to only make certain values generate an alert. E.g. There may be some type of faults that are informational only and not important enough to want to notify a user with a text message. See Section 5 Alert Messaging.
It is also possible to create alerts on a Boolean event. The simplest way to implement this feature is to make the datatype ENUM rather than Boolean. Then in the ENUM definition, simply define the value 1 as the alarm and provide the alarm messaging as a regular ENUM or Bitmask type.
HACCP
Open Kitchen has features for automatic HACCP report generation and tracks critical temperatures to ensure compliance with food safety regulations. Setting the HACCP attribute to true (1) will make the reading report available for inclusion in the automated HACCP reporting system. Normally these would be temperatures measured in freezers, refrigerators or food warming/holding cabinets.
Translate
Open Kitchen has support for many languages. Labels provided in the data dictionary will be translated into foreign languages by professional translators contracted by Powerhouse Dynamics if this attribute is set.
Commercial kitchen equipment can be complex, and many of the terms are scientific or specialized terms and abbreviations. Professional translators that have no knowledge of the equipment are unlikely to be able to translate internal terms meaningfully. It may be best to leave the complex terms in English or for the OEM/Brand to provide the desired translations. Only those labels that can be translated by a "lay person" should have the Translate attribute set.
Usage Alertable
Open Kitchen has a configurable alert that can let you know if a parameter hasn’t had any usage in a specific amount of time. If you would like a parameter to be able to be configured for use in that alert you can indicate that in the “Usage Alertable” column with a 1. Note: this is currently only available for parameters whos “unit” is “count”.