{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Connectware Message (OKM) Format","type":"text"}]},{"type":"expand","attrs":{"title":"Click here for the OKM format for interface - JSON with expected elements"},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"JSON","type":"text"}]},{"type":"paragraph","content":[{"text":"JSON, pronounced \"Jason\", is a standard syntax for encoding structured data in a programming language independent and human readable format. Every OKM is a valid, well-formed JSON object. This specification defines the proper semantics of constructing OKMs using JSON.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are many excellent references for JSON syntax, but for the purposes of this document several basic syntax elements will be defined:","type":"text"}]},{"type":"bulletList","content":[{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Opening and closing curly braces {} is an unordered object.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Opening and closing square brackets [] is an ordered array.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Name/value pairs are called fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A name is a string.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A value may be an object, array, number, string, Boolean, or null.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"Fields may be nested in the value of other fields.","type":"text"}]}]},{"type":"listItem","content":[{"type":"paragraph","content":[{"text":"A set of fields encapsulated by top-level curly braces is called a message.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example OKM (this example can be improved, and more examples should be added to spec):","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\"_src\":[\"0102030405060708\"],\"_cmd\":\"wr\",\"_id\":192,\"_ts\":\"2019-12-26T14:40:00\",\"_crc\":\"8813\",\"_pld\":{\"_hbt\":{\"door\":56}}}","type":"text"}]},{"type":"paragraph","content":[{"text":"The message is ","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\"_src\":[\"0102030405060708\"],\"_cmd\":\"wr\",\"_id\":192,\"_ts\":\"2019-12-26T14:40:00\",\"_crc\":\"8813\",\"_pld\":{\"_hbt\":{\"door\":56}}}","type":"text"}]},{"type":"paragraph","content":[{"text":"_src","type":"text","marks":[{"type":"strong"}]},{"text":" is the name of an array where the first element's value is the string 0102030405060708.","type":"text"}]},{"type":"paragraph","content":[{"text":"_cmd ","type":"text","marks":[{"type":"strong"}]},{"text":"is the Name of a Field whose Value is the string wr.","type":"text"}]},{"type":"paragraph","content":[{"text":"_id","type":"text","marks":[{"type":"strong"}]},{"text":" is the Name of a Field whose Value is the integer 192.","type":"text"}]},{"type":"paragraph","content":[{"text":"_ts","type":"text","marks":[{"type":"strong"}]},{"text":" is the Name of a Field whose Value is the string 2019-12-26T14:40:00.","type":"text"}]},{"type":"paragraph","content":[{"text":"_pld ","type":"text","marks":[{"type":"strong"}]},{"text":"is the Name of a Field whose Value is the object {\"_hbt\":{\"door\":56}}.","type":"text"}]},{"type":"paragraph","content":[{"text":"_hbt","type":"text","marks":[{"type":"strong"}]},{"text":" is the Name of a Field whose Value is the object {\"door\":56}.","type":"text"}]},{"type":"paragraph","content":[{"text":"door","type":"text","marks":[{"type":"strong"},{"type":"em"}]},{"text":" ","type":"text","marks":[{"type":"em"}]},{"text":"is the Name of a Field whose Value is the number 56.","type":"text"}]},{"type":"paragraph","content":[{"text":"_crc","type":"text","marks":[{"type":"strong"}]},{"text":" is the Name of a Field whose Value is the string 8813.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hierarchical Path Notation","type":"text"}]},{"type":"paragraph","content":[{"text":"A simple path notation, used by the CWL, is used to identify fields within the hierarchical structure of an OKM.","type":"text"}]},{"type":"paragraph","content":[{"text":"A dollar sign $","type":"text","marks":[{"type":"strong"}]},{"text":" represents the field name of the root level message.","type":"text"}]},{"type":"paragraph","content":[{"text":"A dot .","type":"text","marks":[{"type":"strong"}]},{"text":" separates field names of additional levels.","type":"text"}]},{"type":"paragraph","content":[{"text":"From the previous section, $._pld._hbt is the path to the object value {\"door\":56}.","type":"text"}]},{"type":"paragraph","content":[{"text":"And, $._pld._hbt.door is the path to the integer value 56.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"End to End Transport","type":"text"}]},{"type":"paragraph","content":[{"text":"An OKM Message payload, the contents of the _pld object, is transported in its entirety and unmodified between the Cloud or Edge Server (OKC) and the Open Kitchen Equipment (OKE). OKM Messages may traverse multiple intermediary networks and nodes on its way between the cloud and equipment. Intermediary nodes will interpret and extend portions of the message envelope, parts of the message outside of the _pld object.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Source and Destination","type":"text"}]},{"type":"paragraph","content":[{"text":"A source may either be the Cloud or Edge Server (OKC) or Open Kitchen Equipment (OKE). Likewise, a destination may either be the OKC or OKE.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Inbound and Outbound","type":"text"}]},{"type":"paragraph","content":[{"text":"A source generates an OKM Message and a destination processes it. An OKM is outbound when a source generates and transmits it. An OKM is inbound when a destination receives and processes it.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Command Semantics","type":"text"}]},{"type":"paragraph","content":[{"text":"OKM Messages contain a command that is either a read or a write operation. An inbound message may or may not trigger an outbound message. Sometimes a triggered outbound message from an OKE includes the inbound message identifier from the OKC. This allows the OKC to match the two messages.","type":"text"}]},{"type":"paragraph","content":[{"text":"Inbound/outbound message terminology is deliberately used instead of request/response terminology because it more accurately describes the loosely coupled message passing between OKE and the OKC.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Connectware Message (OKM) Syntax","type":"text"}]},{"type":"expand","attrs":{"title":"Click to review formatting rules. The rules are in addition to being a valid JSON object "},"content":[{"type":"paragraph","content":[{"text":"All transported messages must be valid JSON syntax and include NULL termination. Vendor specific extensions to OKMs must adhere to the specification rules.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Maximum Length","type":"text"}]},{"type":"paragraph","content":[{"text":"The maximum message length is 1000 bytes including NULL termination.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Escape Sequences","type":"text"}]},{"type":"paragraph","content":[{"text":"JSON strings, which includes field names, must follow the JSON standard as it pertains to escaping special characters otherwise the resulting JSON message will not be valid. Field names should only use printable, non-control characters.","type":"text"}]},{"type":"paragraph","content":[{"text":"Except for normally escaped string characters, non-printable ASCII characters should be encoded as a JSON Unicode escape sequence \\u00XX. This keeps the OpenKitchen JSON message human readable and minimizes the potential for extraneous control sequences to cause unexpected problems during message creation, transmission, and processing.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Unicode Character Sets","type":"text"}]},{"type":"paragraph","content":[{"text":"The current implementation of the CWL interprets strings as a set of 8-bit ASCII characters and does not natively handle Unicode character sets.","type":"text"}]},{"type":"paragraph","content":[{"text":"OKE that support Unicode character strings, and which intend to transfer those strings to and from the OKC will use the Base64 encode those strings, essentially treating them as binary data, when creating OKMs. The OKE data dictionary will specify which fields contain Unicode strings, the specific Unicode encoding (UTF-16, etc.) and that those strings are Base64 encoded within the OKM.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Field Ordering","type":"text"}]},{"type":"paragraph","content":[{"text":"Except for arrays, the order of fields within a JSON message must not confer information and must not be interpreted to convey information. For example, a source generating a JSON message cannot ensure the destination will process the fields of the message in a specific order.","type":"text"}]},{"type":"paragraph","content":[{"text":"The following two JSON messages contain the same information and destinations handling these messages may process either _cmd or _id first followed by the other:","type":"text"}]},{"type":"paragraph","content":[{"text":"{\"_cmd\":\"wr\",\"_id\":5612}","type":"text"}]},{"type":"paragraph","content":[{"text":"{\"_id\":5612,\"_cmd\":\"wr\"}","type":"text"}]},{"type":"paragraph","content":[{"text":"However, the source can be certain that fields organized in a nested hierarchy are processed by the destination within the context of the hierarchy.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use an array when the order of data and its processing matters.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Encoding Binary Data","type":"text"}]},{"type":"paragraph","content":[{"text":"Binary data, data containing mainly non-printable characters, shall be encoded either as an ASCII hexadecimal string or as a Base64 encoded string.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"ASCII Hexadecimal String","type":"text"}]},{"type":"paragraph","content":[{"text":"Binary data should be encoded as an ASCII hexadecimal string when the data can be decoded into a meaningful value that is helpful for debugging. For example, a 2-byte bit-field value such as 0x6A05 should be encoded as the string 6A05 in the JSON message. A leading “0x” will not be prepended to the string. ASCII letters should be uppercase.","type":"text"}]},{"type":"paragraph","content":[{"text":"Multi-byte integer values should be encoded in big endian format.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Base64 encoding","type":"text"}]},{"type":"paragraph","content":[{"text":"Binary data should be encoded as a Base64 string when the data does not have an obvious meaningful value for debugging or when the amount of binary data is large. Base64 encoding increases the size to represent a binary string by about 1 1/3 of the original data, whereas an ASCII hexadecimal string would double the size. A typical use case for Base64 encoding would be to represent a portion of a file or firmware image.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWL substitutes the pipe character ","type":"text"},{"text":"|","type":"text","marks":[{"type":"strong"}]},{"text":" for the standard forward slash character ","type":"text"},{"text":"/","type":"text","marks":[{"type":"strong"}]},{"text":" when encoding and decoding Base64 strings. This is done to eliminate the required escaping of the forward slash within the JSON string. This makes the length of the Base64 encoded string more predictable and results in less memory consumption.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Whitespace","type":"text"}]},{"type":"paragraph","content":[{"text":"Although whitespace, including newlines and carriage returns, are allowed between JSON elements they do not add any meaning to the data being represented and will consume additional bandwidth and memory that is at a premium on many embedded devices and low bandwidth networks.","type":"text"}]},{"type":"paragraph","content":[{"text":"Therefore, it is strongly recommended that all whitespace characters whose sole purpose is to make the JSON format nicely, be removed before the message is transported between the OKE and the OKC.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"ConnectWare Library","type":"text"}]},{"type":"paragraph","content":[{"type":"inlineCard","attrs":{"url":"https://sitesage.atlassian.net/wiki/x/Z4BFHQ"}},{"text":" ","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWL includes a memory efficient JSON parser and emitter that can be used by implementors for processing and generating CWMs.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Field Names","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Standard Field Names","type":"text"}]},{"type":"paragraph","content":[{"text":"The names of all standard fields will be preceded by an underscore.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Custom ","type":"text","marks":[{"type":"annotation","attrs":{"annotationType":"inlineComment","id":"eef82c58-bba8-4eae-b693-f85c166c01ba"}}]},{"text":"Field Names","type":"text"}]},{"type":"paragraph","content":[{"text":"Custom field names shall not begin with an underscore character.","type":"text"}]},{"type":"paragraph","content":[{"text":"Custom defined field names shall not contain a period/dot character.","type":"text"}]},{"type":"paragraph","content":[{"text":"It is recommended that field names defined by OKE vendors be descriptive and short.","type":"text"}]},{"type":"paragraph","content":[{"text":"One of the benefits of using JSON is that a human can readily read and decode the message. So meaningful field names are essential. However, very long field names can unnecessarily waste bandwidth and memory. The recommendation is that field names are generally 3 to 5 characters in length.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Hierarchical Complexity","type":"text"}]},{"type":"paragraph","content":[{"text":"JSON syntax permits hierarchical nesting of elements that helps represent the logical organization of data.","type":"text"}]},{"type":"paragraph","content":[{"text":"However, this can greatly increase the memory and time requirements for parsing a message.","type":"text"}]},{"type":"paragraph","content":[{"text":"For incoming messages generated by the OKC and meant to be consumed by the OKE it is recommended to keep JSON data nesting to a minimum. Typically, a message would have no more than 3-4 levels of nesting at maximum.","type":"text"}]},{"type":"paragraph","content":[{"text":"For outgoing messages generated by the OKE and meant to be consumed by the OKC significant data nesting should still be avoided to keep processing overhead low. Typically, a message would have no more than 3-4 levels of nesting at maximum.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Connectware Message (OKM) Standard Fields","type":"text"}]},{"type":"expand","attrs":{"title":"Click to review expected JSON key-value pairs and what they mean"},"content":[{"type":"paragraph","content":[{"text":"Standard fields provide the common language for OKMs. Vendor specific extensions to OKMs allow an infinite variety of information to be represented and exchanged.","type":"text"}]},{"type":"paragraph","content":[{"text":"Field definitions use hierarchical path notation to explicitly define the relationship fields have with each other.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Command - _cmd","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._cmd field has a string value of either rd or wr.","type":"text"}]},{"type":"paragraph","content":[{"text":"This field is present in every message regardless of source.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Write - wr","type":"text"}]},{"type":"paragraph","content":[{"text":"The wr value indicates that the source is writing the message to the destination.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKC writes a message to the OKE, the equipment should interpret the $._pld field as the context for changing the state of the equipment’s configuration, operating mode, or other attributes.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKE writes a message to the OKC, the cloud should interpret the $._pld as the data to record or process in the cloud.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Read - rd","type":"text"}]},{"type":"paragraph","content":[{"text":"The rd value indicates that the source is reading data from the destination.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKC sends a read message to the OKE, the equipment should interpret the $._pld as the context to read specific data associated with the equipment. This allows the cloud to read configuration, operating mode, or other attributes from the equipment.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKE sends a read message to the OKC, the cloud should interpret the $._pld as context for reading specific data from the cloud.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Transaction IDs - _id, _rid","type":"text"}]},{"type":"paragraph","content":[{"text":"$._id and $._rid are unsigned 16-bit transaction IDs whose value is represented as an integer.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every outgoing message will have a unique $._id value assigned to it. Implementations will minimize the reuse of $._id values.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._rid field is included by OKE when an outgoing message was in reaction to a specific incoming message from the OKC.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC can match the message received from the OKE to its original message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Timestamp - _ts","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._ts field’s value is local time formatted as an ISO 8601 string. The time zone designator is not required. Time must include seconds and may optionally include sub-second resolution as appropriate. $._ts represents the time that the message was created and should be coincident to the latching of varying data values represented in the value of $._pld.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every outgoing message from OKE will have a $._ts field.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Payload - _pld","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld field’s value is a variable object. The context of the $._cmd read or write is determined by the $._pld field’s value.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every outgoing message will have a $._pld field.","type":"text"}]},{"type":"paragraph","content":[{"text":"Developers for OKE systems using the CWL will primarily be focused on creating and processing JSON encoded telemetry and configuration contained in the $._pld value.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Priority - _pri","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pri field is included when the message should be sent via the PSFQ and the $._rid field is not applicable. The value is the Boolean true.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pri field is only included by OKE having a CWM, since it is used by the CWM to place the message into the PSFQ.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Store and Forward Queue - _sf","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._sf field’s value is an integer representing the total number of queued store and forward messages in both the PSFQ and TSFQ. This field is updated in real-time right before a message is delivered to the cloud.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only OKE or its CWM should include this field in a message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Store and Forward Queue - _psf","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._psf field’s value is an integer representing the total number of queued store and forward messages in the PSFQ. This field is updated in real-time right before a message is delivered to the cloud.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only OKE or its CWM should include this field in a message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inbound Store and Forward Queue - _isf","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._isf field’s value is an integer representing the total number of queued store and forward messages in the ISFQ. This field is updated in real-time right before a message is delivered to the cloud.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only OKE or its CWM should include this field in a message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":" ","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Store and Forward Sequence Number - _seq","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._seq field and its value is an integer that identifies a message based on its internal store and forward representation, and differentiates it from other messages.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only OKE or its CWM should include this field in a message.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Device ID - _src, _dst","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Equipment Device IDs","type":"text"}]},{"type":"paragraph","content":[{"text":"A device ID is string that must remain constant for the OKE system lifetime, be globally unique, and contain information about the type of device.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"OKE manufacturers will contact the OKC team at Powerhouse Dynamics to register for a 16-bit Make/Model code. Each 16-bit code is meant for a specific model, when there are more than one model then multiple Make/Model codes must be requested.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Device ID is then created by encoding the 16-bit Make/Model id as a 4-byte ASCII hexadecimal string in big endian order prefixing a manufacturer specific unique ID.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, if the assigned Make/Model is 0x1234 and the manufacturer specific unique ID is the string \"ABCDEFGH\" then the resulting Device ID string is \"1234ABCDEFGH\". The total maximum length of the Device ID string is 24. Therefore, manufacturer specific unique ID portion of the string should not exceed 20-bytes. However, it is not necessary and is discouraged to try to make the Device ID longer than necessary since it is included in every OKM which consumes storage space and network bandwidth.","type":"text"}]},{"type":"paragraph","content":[{"text":"For example, it is not necessary that the manufacturer specific unique ID portion of the string contain make and model information since that is already encoded in the Make/Model identifier. The OKC will be able to map this Device ID to other information such as product Serial Numbers in the cloud so long as the Serial Numbers are reported by the equipment in an OKM field.","type":"text"}]},{"type":"paragraph","content":[{"text":"An ideal manufacturer unique ID would be one which does not need to be programmed at the factory. For example, some microcontrollers have embedded Ethernet Controllers with associated MAC addresses burned in. Others may have die specific serial numbers, or other serialized data burned in. Using this data eliminates the need for additional process overhead at the factory.","type":"text"}]},{"type":"paragraph","content":[{"text":"Alternatively, for equipment controllers without microcontroller burned in serialized data, those may opt to use the existing product serial number as the unique portion of the Device ID.","type":"text"}]},{"type":"paragraph","content":[{"text":"If encoding the manufacturer specific unique ID causes the Device ID string length to exceed 24-bytes then an alternate encoding might be used. For example, encoding a 120-bit manufacturer specific unique ID as a hexadecimal string is 30 bytes, whereas a Base64 encoding is only 20 bytes.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWL MJSON interface contains formatters for converting binary data, such as an unique identifier, into a hexadecimal or Base64 encoded string; see %h and %v in the ConnectWare API User's Guide for more details.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"OpenKitchen Device ID","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC’s device ID will be the string OKC regardless if used as a source or destination. However, normally the OKC device ID will not be present in OKMs since the lack of a source or destination field assumes it is the OKC.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Equipment to CWM Device IDs","type":"text"}]},{"type":"paragraph","content":[{"text":"Sometimes OKE systems using a CWM will need to send and receive messages pertaining to each other and not the OKC.","type":"text"}]},{"type":"paragraph","content":[{"text":"For messages between the OKE and the CWM the device ID will use a shorthand notation. The device ID of the OKE will be OKE and the device ID of the CWM will be CWM.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Source - _src","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._src field is a mandatory field whose value is an array of device ID strings. The $._src field indicates the source of an OpenKitchen message.","type":"text"}]},{"type":"paragraph","content":[{"text":"When an OKE system sends a message to the OKC it will populate the first array element with its Device ID. If message passes through a CWM before reaching the OKC the module will add its Device ID as the second element of the array. The OKC will be able to determine that the OKE is connected via the CWM.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every OKM must include this field if the source is not OKC. When this field is not in an OKM then the source is assumed to be OKC.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Destination - _dst","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._dst field is a mandatory field whose value is an array of device ID strings. The $._dst field indicates the destination of an OpenKitchen message.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every OKM must include this field if the destination is not OKC. If the field is not included in an OKM then the destination is assumed to be OKC. When the OKC sends a message to an OKE that is connected through a CWM then the first element is the Device ID of the OKE, and the second element is the Device ID of the CWM. Adding the device ID of the CWM allows the IoT gateway to more easily route the message via the MiWi network.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CRC - _crc","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._crc field is used to verify the integrity of the JSON message. The value of the field is a 4-character hexadecimal string. The CRC is 16-bits.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CRC is computed once the entire message is constructed including the $._crc field where the value is initially set to 0000. The CRC is then computed over the entire message including the NULL terminator. The ASCII encoded hexadecimal value in big endian byte order is then written to the $._crc value field.","type":"text"}]},{"type":"paragraph","content":[{"text":"To verify the CRC of a message, the value of $._crc is saved, and the actual CRC is computed over the message after setting the $._crc string value to 0000. If the CRCs match, then the message integrity is good. If not, then the message is discarded since data corruption has likely occurred. An event may be logged indicating a CRC failure.","type":"text"}]},{"type":"paragraph","content":[{"text":"Every OKM must include this field.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Heartbeats and Event Triggers","type":"text"}]},{"type":"paragraph","content":[{"text":"A Heartbeat is a set of one or more OKMs periodically generated by OKE that contain telemetry about the equipment’s current operational state. Each of the individual messages must have a $._pld._hbt field.","type":"text"}]},{"type":"paragraph","content":[{"text":"Generally, OKE should generate a Heartbeat at the top of every minute. Rarely changing configuration does not need to be sent as Heartbeat telemetry since it can be read on demand by the OKC, or it may be sent on a slower or event triggered basis.","type":"text"}]},{"type":"paragraph","content":[{"text":"Sometimes events occur that change the state of the OKE and are of interest to data consumers. In this case the OKE will simply generate a Heartbeat at the time the event occurred, independent of the periodic 1-minute heartbeat. In all other respects an event triggered Heartbeat is identical to the periodic heartbeat.","type":"text"}]},{"type":"paragraph","content":[{"text":"OKE systems should throttle event triggered Heartbeats such that they will not cause an unnecessary or extreme number of messages. For example, no more than 1 heartbeat set will be sent in a 10 second window.","type":"text"}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Queuing Messages from the Equipment - Store and Forward","type":"text"}]},{"type":"expand","attrs":{"title":"Click to review how data is queued on the Connectware device"},"content":[{"type":"paragraph","content":[{"text":"Outbound messages generated by Open Kitchen Equipment (OKE) are queued by the Connectware Module or Network Device (CWM) before being transmitted to the Cloud or Edge Server (OKC).","type":"text"}]},{"type":"paragraph","content":[{"text":"CWM queuing ensures outbound messages can be delivered with confirmation to the Cloud or Edge Server (OKC) regardless of intermittent network connectivity, or other events that may affect the equipment’s operational state.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the network connection allows, the queue is emptied in the order the messages were written.","type":"text"}]},{"type":"paragraph","content":[{"text":"Typically, when network connectivity is good the queue is empty, and messages are delivered to the OKC with minimal delay.","type":"text"}]},{"type":"paragraph","content":[{"text":"There are two outbound store and forward queues, one is for priority messages and the other is for telemetry.","type":"text"}]},{"type":"paragraph","content":[{"text":"Likewise, inbound messages from the OKC are queued by the CWM before processing by the OKE.","type":"text"}]},{"type":"paragraph","content":[{"text":"Queueing ensures inbound messages can be reliably handled regardless of the disparity between the speed of the network connection versus the speed of message processing.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Priority Queue","type":"text"}]},{"type":"paragraph","content":[{"text":"Any OKM containing a $._rid or a $._pri field is put into the CWM's PSFQ. The PSFQ is always emptied before the TSFQ. This allows certain messages to be processed ahead of telemetry data. Messages in this queue do not need confirmation from the OKC before being removed from the queue.","type":"text"}]},{"type":"paragraph","content":[{"text":"The PSFQ is sized to hold an entire file transfer containing at least 2MB file of file data.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Telemetry Queue","type":"text"}]},{"type":"paragraph","content":[{"text":"All non-priority OKMs are put into the TSFQ. Messages in the TSFQ are only removed once they have been confirmed as received by the OKC.","type":"text"}]},{"type":"paragraph","content":[{"text":"A TSFQ typically can hold up to two to four weeks of equipment telemetry.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Inbound Queue","type":"text"}]},{"type":"paragraph","content":[{"text":"OKMs inbound from the OKC are put into the ISFQ. Messages are pulled off the ISFQ and processed in order.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ISFQ is sized to hold an entire file transfer containing at least 2MB of file data.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"Standard Payload Commands","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"paragraph","content":[{"text":"Payload commands are encapsulated in the $._pld value. A standard payload command is one that is implemented on all OKE platforms.","type":"text"}]},{"type":"paragraph","content":[{"text":"While it is possible to include multiple payload commands in a single message, the OKC will generally only include one payload command per message. Likewise, it is recommended that OKE only include one payload command per message to maintain message processing simplicity.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Heartbeat - _hbt","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._hbt field value is an object. An OKE vendor encodes their equipment specific telemetry extensions as the object value.","type":"text"}]},{"type":"paragraph","content":[{"text":"This field is present in outbound OKE messages. The $._cmd field’s value must be wr.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC may request a heartbeat to be generated at anytime by sending a message with $._pld._hbt set to true and the $._cmd field set to rd. When received the CWM or OKE will immediately generate a heartbeat message.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"ConnectWare Version - _cwv","type":"text"}]},{"type":"paragraph","content":[{"text":"The $_pld._cwv field value is a string of the form \"Major.Minor.Build\" where each of the fields is an integer.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Uptime - _upt","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._upt field value is an integer representing the uptime of the OKE since last startup in minutes.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Restart - _rst","type":"text"}]},{"type":"paragraph","content":[{"text":"After a restart the $._pld._rst field with a Boolean value of true is added once to the first message of the first Heartbeat set by the OKE or its CWM.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Version - _ver","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ver field value is an array.","type":"text"}]},{"type":"paragraph","content":[{"text":"Within the $._pld._ver field array is zero or more arrays. Each of these arrays reports the device type, firmware version, and hardware version of every logical device within the OKE as strings.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only an OKE and its CWM should include this field and only once in each Heartbeat message set.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Set Time - _time","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._time field value is an ISO 8601 formatted string, and is only processed when the $._cmd field value is wr. When processed the device will update its internal clock to the new time and use it for all subsequent timestamps.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"OKE Implementation","type":"text"}]},{"type":"paragraph","content":[{"text":"An OKE must only support an ISO 8601 format of \"yyyy-mm-ddThh:mm:ss\" and this format shall be interpreted as local time. Other ISO 8601 formats may be ignored.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC should not send this command to the OKE. The CWM is responsible for ensuring that the OKE has the correct time by periodically sending this command to the OKE.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"CWM Implementation","type":"text"}]},{"type":"paragraph","content":[{"text":"The SPOD CWM ignores this command. It gets current time from the IoT Gateway in the same manner as other MiWi devices do.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Sphere WiFi CWM supports this command and will accept the default format of \"yyyy-mm-ddThh:mm:ss\" however this is not useful or necessary for the Sphere CWM since it is already able to get GMT time from NTP. Therefore, the cloud should use one of the following formats so that the CWM can determine and save the time zone offset. The time zone offset is used by the CWM for two purposes. First it allows the CWM to convert the local time timestamps reported by the OKE into GMT time before sending them to the OKC. Second, it will allow the CWM to report time zone information to the OKE so that the OKE may optionally display the time zone to the user (not yet implemented).","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ssZ - GMT time with 0 offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss+hh:mm - GMT time with positive offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss+hhmm - GMT time with positive offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss+hh - GMT time with positive offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss-hh:mm - GMT time with negative offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss-hhmm - GMT time with negative offset","type":"text"}]},{"type":"paragraph","content":[{"text":"yyyy-mm-ddThh:mm:ss-hh - GMT time with negative offset","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC is responsible for sending this command when the time zone changes, for example during daylight savings, otherwise the GMT timestamps will be wrong.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ping - _ping","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ping field value is a Boolean with a value of true and is only processed when the $._cmd field is rd. When a CWM or OKE receives this command it will respond with a message containing $._pld._ping set to true, $._rid set to the $._id of the incoming message, and $._cmd set to wr. The OKC may use this command to verify that roundtrip communication between the OKC and CWM or OKE is functioning correctly.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reset - _reset","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._reset field value is a Boolean with a value of true, and is only processed when the $._cmd field value is wr. When processed the CWM or OKE will perform a soft reset. Only a Serial Data Link Layer acknowledgement is expected from the equipment before it resets.","type":"text"}]},{"type":"paragraph","content":[{"text":"This field is only present for inbound OKE and CWM messages.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reset To Defaults - _rtd","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._rtd field value is a Boolean with a value of true, and is only processed when the $._cmd field value is wr. When processed the CWM will perform a factory Reset to Defaults. The CWM will perform a soft reset as necessary for the new default configuration to take effect.","type":"text"}]},{"type":"paragraph","content":[{"text":"This field is only present for inbound CWM messages.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Port Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"This command is only supported by the CWM, it allows the OKC to manually set the desired port and communication settings for OKE communication, thereby overriding previous settings or ongoing OKE discovery.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC sends a message with $_cmd set to wr, $._pld._oke._port set to usb, ttl, 232, or 485, and $._pld._oke._baud set to an integer value. Baud is ignored when the port is usb.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Queue Flush - _flush","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._flush field value is a Boolean with a value of true, and is only processed when the $._cmd field value is wr. When processed the CWM will empty the PSFQ, TSFQ, and ISFQ.","type":"text"}]},{"type":"paragraph","content":[{"text":"This field is only present for inbound CWM messages and is optionally implemented in the OKE.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"File and Firmware Transfers","type":"text"}]},{"type":"paragraph","content":[{"text":"The file transfer command allows large files such as firmware, images, and event logs to be transferred between the OKC and OKE.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"File Transfer - _ft","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ft field indicates a file transfer operation and its value is an object. The $._cmd field indicates if the transfer is a read or write.","type":"text"}]},{"type":"paragraph","content":[{"text":"Supporting file transfer does not presume that OKE has a traditional organized file system. Also only reading or writing one file at a time is supported.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Writing","type":"text"}]},{"type":"paragraph","content":[{"text":"A sequence of one or more messages where the $._cmd field value is wr the $._pld._ft._name, $._pld._ft._off, and $._pld._ft._frg fields are present is a file transfer.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ft._name field value is a string that is the file being written. The maximum length of a name is 16 characters not including NULL termination.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ft._off is a 32-bit signed integer that indicates the byte offset at which the data should be written.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ft._frg field is Base64 encoded binary data that should be written to the file offset.","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._frg will contain between 0 and 512 bytes of binary data. When less than 512 bytes of binary data is received it indicates the end of file. If a file is an exact multiple of 512 bytes then the last $._pld._ft._frg will be an empty string \"\" to indicate end of file.","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._sz is an optional 32-bit signed integer field that should only be sent when _pld._ft._off is 0 to avoid unnecessary overhead. The value of the field is -1 if the total size of the file being transferred is not known, otherwise it is >=0 and is the total byte size of the file being transferred. The file receiver must not use this field to determine when the file transfer ends.","type":"text"}]},{"type":"paragraph","content":[{"text":"When a destination receives a $._pld._ft command and the offset is zero, this has the logical effect of opening the file for writing.","type":"text"}]},{"type":"paragraph","content":[{"text":"When a file is open for writing the destination processing a $._pld._ft command will ignore write requests when fragments are received out of order or are a duplicate.","type":"text"}]},{"type":"paragraph","content":[{"text":"The destination will also automatically close an open file when end of file is reached or a new file transfer command is received with an offset of zero for a different file.","type":"text"}]},{"type":"heading","attrs":{"level":6},"content":[{"text":"File Transfer Status - _fts","type":"text"}]},{"type":"paragraph","content":[{"text":"When a file is open an OKE and CWM will indicate the file transfer status to the OKC. This allows the OKC to continue a partially completed file transfer without starting the transfer over from the beginning.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._fts field indicates the status of an open file being written to the OKE and its value is an object. The object contains the $._pld._fts._name field which is the name of the open file as a string, and the $._pld._fts._off field which is the offset of the next file fragment that should be written to the file. If $._pld._fts._off is -1 this indicates an unexpected error has occurred and the file transfer must be restarted.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKE and CWM will send an OKM containing the $._pld._fts field via the PSFQ once per minute.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Reading","type":"text"}]},{"type":"paragraph","content":[{"text":"When the $._cmd field value is rd the $._pld._ft._name field is present.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._ft._name field value is a string that is the file to be read.","type":"text"}]},{"type":"paragraph","content":[{"text":"This read command triggers the destination to write the requested file back to the message source.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the destination is already reading a file to another destination, then that operation ends and a new file read is started.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"File Status","type":"text"}]},{"type":"paragraph","content":[{"text":"OKE will include status of files, their name, size, and CRC, in their heartbeat. This allows the OKC to determine the state of files on the OKE.","type":"text"}]},{"type":"paragraph","content":[{"text":"The $._pld._fs field indicates the status of files on the OKE and its value is an array.","type":"text"}]},{"type":"paragraph","content":[{"text":"Within the $._pld._fs field array is zero or more arrays. Each of these arrays reports the file name. The file name is a string. It is possible that future revisions of the CWL will add additional fields about each file.","type":"text"}]},{"type":"paragraph","content":[{"text":"When a file write completes the OKE will report the updated file status via the heartbeat and the OKC can determine that the file transfer was successful.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Acting on File Transfers","type":"text"}]},{"type":"paragraph","content":[{"text":"When a file transfer writes firmware to the OKE system, the OKE system will not immediately install it. The OKE system will wait until it receives a reset command from the OKC. The new firmware will be installed before the application boots up again.","type":"text"}]},{"type":"paragraph","content":[{"text":"For transfers of other file types, it is up to the vendor to determine if the newly written file will be acted upon automatically or only after a vendor specific command is issued.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"File Directory","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC may request a file directory from either a CWM or OKE. When received the CWM or OKE will report on all files it supports excluding firmware files which are reported in the $._pld._ver field.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC requests the file directory by sending $._pld._fdir with a value of true and $._cmd with a value of rd. The CWM or OKE will respond a message where $._pld._fdir is an array of files and metadata, $._rid is set to the $._id of the incoming message, and $._cmd is set to wr.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"File Erase","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC may issue a file erase command to a CWM or OKE. The OKC generates a message containing $._pld._fdel._name where the value is the name of the file to erase, and $._cmd is set to wr. The behavior of the erase command is implementation specific for each platform and each file on each platform. The OKC can determine the result of the delete by subsequently requesting a file directory.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"High Performance File Transfer","type":"text"}]},{"type":"paragraph","content":[{"text":"The file transfer protocol described earlier in this section (legacy file transfer) keeps the bulk file transfer data encapsulated in an OKM from the OKC through to the OKE. This means that file transfer fragments are treated the same as any other OKM simplifying the CWM implementation. However, due to the additional OKM protocol overhead its throughput is unable to match that of a dedicated bulk file transfer protocol, such as FTP or HTTP.","type":"text"}]},{"type":"paragraph","content":[{"text":"This section describes a bulk file transfer mechanism for Connectware that does not require any changes to OKE implementations. If an OKE implements file transfer it will continue to work regardless of using the legacy file transfer or the optimized file transfer mechanism. Only CWM implementations are aware if the file transfer is optimized or not.","type":"text"}]},{"type":"paragraph","content":[{"text":"Just like legacy file transfer, only one file transfer may be active at a time in either the inbound and outbound direction.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Inbound High-Performance OKC to OKE/CWM File Transfer","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKC sends a file to an OKE (or even when a file is intended for a CWM) instead of generating OKMs with file transfer fragments it will write the following request to the CWM:","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._dst is a string indicating the intended destination device ID of the file. The $._dst field is always the device ID of the CWM.","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._url is a string indicating the file resource to fetch from an HTTP server.","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._name is the logical filename of the data being transferred, and has the same meaning as in legacy file transfers. If the filename is an empty string “” then no file transfer will be started and any ongoing file transfers to that destination will be immediately cancelled.","type":"text"}]},{"type":"paragraph","content":[{"text":"$._pld._ft._to is an optional parameter and is a positive integer that represents a timeout in minutes at which the file transfer will be aborted. The timeout starts as soon as the file transfer request is received by the CWM. When the timeout expires the file transfer operation will end regardless of the OKE receiving none or some file data. If this parameter is not specified, then the default timeout is 1440 minutes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Upon receiving this request, the CWM will start fetching the file from the provided URL and begin creating and transmitting OKM file fragments (per the legacy file transfer specification) to the intended recipient (either the attached OKE, or the CWM itself.) During the transfer, the CWM will monitor the $._pld._fts to ensure that file reception at the destination is advancing. If it is not advancing, then the CWM will virtually rewind the transfer and start sending OKM fragments at the offset where the transfers stalled.","type":"text"}]},{"type":"paragraph","content":[{"text":"While the CWM is transferring the file, all normal file transfer status will be sent to the OKC so that it can also monitor the file transfer progress. All other file transfer management mechanisms, such as file directories work the same way as in the legacy file transfer scenario. Lastly, regular heartbeat data will also continue to be delivered normally during the file transfer.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM can only perform one high performance file transfer at a time. The CWM will track high performance file transfer requests for the OKE and itself separately and perform the transfers sequentially.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Outbound High Performance OKE/CWM to OKC File Transfer","type":"text"}]},{"type":"paragraph","content":[{"text":"The need for high performance outbound file transfers is not as critical as inbound, so the legacy file transfer mechanism for transfers from the OKE/CWM to the OKC will remain the only mechanism for outbound file uploads to the OKC.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"CWM High Performance Status","type":"text"}]},{"type":"paragraph","content":[{"text":"Both the OKE and CWM will continue to send regular file transfer status messages to the OKC periodically regardless if a legacy file or high performance transfer is in progress. When a CWM supports High Performance file transfer it will additionally send status about the file transfers it is directly managing so the the OKC can understand how the transfer is progressing from the CWM’s point of view.","type":"text"}]},{"type":"paragraph","content":[{"text":"$_pld._hbt.ft is present in the regular CWM heartbeat only when it supports high performance file transfer. The value of $_pld._hbt.ft is an array containing the status of transfers being managed by the CWM. The array is empty if there are no file transfers in progress or pending. When not an empty array it will contain 1 or 2 elements. Each element is an object type containing the following properties: _dst, _url, _name, _off, and _st. _dst, _url, and _name will match that of the original transfer request. If _name is an empty string “” then it will not be reported in the array. _off will be 0 if the file transfer is pending and not yet started. _off will be -1 when a file transfer completes. Otherwise, _off will indicate the offset that is being fetched from the file server at the time the message is created. _st is an array of integer values for transfer diagnostics. The first array element is the number of connections made to the server, and the second element is the number of rewind events that occurred during the transfer. The third array element is 0 if the file transfer timeout has not been reached, and 1 if the file transfer timeout has been reached. Additional array elements may be added in the future, but the order and meaning of the array elements will not be changed. Again, this CWM file transfer status is in addition to the existing file transfer status messages that are periodically sent from both the OKE and CWM, and specifically for the purpose of understanding the state of the CWM when performing a high-performance file transfer.","type":"text"}]},{"type":"heading","attrs":{"level":5},"content":[{"text":"Server-side Rewind/offset GET Argument.","type":"text"}]},{"type":"paragraph","content":[{"text":"File transfers should rarely lose file fragments, however there are some scenarios where the destination misses one or more file fragments. The CWM can recognize this situation and rewind the transfer back to the next expected fragment required by the destination. Since there is no mechanism in an http transfer to rewind, the CWM closes the current connection and reopens a new connection to read the file, and passes a GET argument named offset. When offset is not present the server must return the requested file from offset 0. When the offset argument is present it must send the requested file starting from offset bytes. This is demonstrated in the OKS example implementation.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"1.1.9 Scheduling","type":"text"}]},{"type":"paragraph","content":[{"text":"UPCOMING FEATURE – PRELIMINARY DOCUMENTATION – SUBJECT TO CHANGE","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Schedule File","type":"text"}]},{"type":"paragraph","content":[{"text":"To set an OKE schedule the OKC will write a file named \"schedule\" to the OKE's CWM. The CWM will report the version and the CRC of the schedule file via the file directory command.","type":"text"}]},{"type":"paragraph","content":[{"text":"The reported file version is extracted from the \"ver\" field contained in the schedule file.","type":"text"}]},{"type":"paragraph","content":[{"text":"The reported CRC is computed over the entire file using the same algorithm as used for OKMs, where the value of the CRC field embedded in the schedule is set to \"0000\" before computing the CRC.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the schedule's computed CRC matches the embedded CRC, and the JSON is valid then the CWM will run the schedule, else the schedule will not run.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the file version is out of date, or the reported CRC does not match the expected value then the OKC should transfer a new schedule file to the CWM.","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC may overwrite an existing schedule by sending a new schedule. The OKC may remove the existing schedule by sending a file delete request to the CWM. The OKC may read the schedule file by issuing a file read request.","type":"text"}]},{"type":"codeBlock","content":[{"text":"{\n \"ver\":,\n \"crc\":\"\",\n \"sun\":[{\"\":[…]}…],\n \"mon\":[{\"\":[…]}…],\n \"tue\":[{\"\":[…]}…],\n \"wed\":[{\"\":[…]}…],\n \"thu\":[{\"\":[…]}…],\n \"fri\":[{\"\":[…]}…],\n \"sat\":[{\"\":[…]}…],\n \"cmds\":[{…}…]\n}\n\nEx:\n{\n \"ver\":123,\n \"crc\":\"12AB\",\n \"sun\": [{\"0\": [0, 2]}, {\"360\": [1, 3]}, {\"1000\": [1, 4]}],\n \"mon\": [{\"0\": [0, 2]}, {\"300\": [1, 3]}, {\"1060\": [1, 4]}],\n \"tue\": [{\"0\": [0, 2]}, {\"300\": [1, 3]}, {\"1060\": [1, 4]}],\n \"wed\": [{\"0\": [0, 2]}, {\"300\": [1, 3]}, {\"1060\": [1, 4]}],\n \"thu\": [{\"0\": [0, 2]}, {\"300\": [1, 3]}, {\"1060\": [1, 4]}],\n \"fri\": [{\"0\": [0, 2]}, {\"300\": [1, 3]}, {\"1060\": [1, 4]}],\n \"sat\": [{\"0\": [0, 2]}, {\"360\": [1, 3]}, {\"1000\": [1, 4]}],\n \"cmds\": [{\"rly\": 1}, {\"rly\": 0}, {\"setpt\": 72}, {\"setpt\": 78}, {\"setpt\": 80}]\n}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"CWM Schedule Status","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWL will periodically report the following schedule status:","type":"text"}]},{"type":"codeBlock","content":[{"text":"\"_sch\":{\"_dow\":<0-6>,\"_mpm\":<0-1439>,\"_sts\":,\"_to\":}\n\n: 0 == Running, 1 == Invalid CRC, 2 == Invalid JSON, 3 == No period defined, 4==No Schedule File\n\nEx: \"_sch\":{\"_dow\":3,\"_mpm\":721,\"_sts\":0,\"_to\":1}","type":"text"}]},{"type":"paragraph","content":[{"text":"Schedule is running Wednesday's schedule at minute 721, and 1 timeout has occurred sending scheduled commands to the OKE.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"OKE Remote Override Configuration","type":"text"}]},{"type":"paragraph","content":[{"text":"These commands are sent by the OKC and processed by the OKE to control override states:","type":"text"}]},{"type":"paragraph","content":[{"text":"Sets a remote override state in an OKE: \"_rovrs\":[, ]","type":"text"}]},{"type":"paragraph","content":[{"text":"Clears a remote override state in an OKE: \"_rovrc\":","type":"text"}]},{"type":"paragraph","content":[{"text":"Clears a local override state in an OKE: \"_lovrc\":","type":"text"}]},{"type":"paragraph","content":[{"text":"Ex:","type":"text"}]},{"type":"paragraph","content":[{"text":"\"_rovrs\":[0, 1] - Enables remote override 0 and allows local clearing.","type":"text"}]},{"type":"paragraph","content":[{"text":"\"_rovrc\":0 – Clears remote override 0","type":"text"}]},{"type":"paragraph","content":[{"text":"\"_lovrc\":1 – Clears local override 1, if it is locally clearable.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"1.1.9.4 OKE Schedule Status","type":"text"}]},{"type":"paragraph","content":[{"text":"When an OKE supports overrides it will periodically report the following status message:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"_ovr\":{\"_loc\":[[,,,]…], \"_rem\":[[,,,]…]}","type":"text"}]},{"type":"paragraph","content":[{"text":"isEnabled","type":"text","marks":[{"type":"strong"}]},{"text":" is 1 if override is in effect, else 0","type":"text"}]},{"type":"paragraph","content":[{"text":"enabledCnt ","type":"text","marks":[{"type":"strong"}]},{"text":"is incremented each time an override goes into effect.","type":"text"}]},{"type":"paragraph","content":[{"text":"remotelyClearable","type":"text","marks":[{"type":"strong"}]},{"text":" is 1 if the OKC can clear the local override, else 0","type":"text"}]},{"type":"paragraph","content":[{"text":"remoteClearedCnt ","type":"text","marks":[{"type":"strong"}]},{"text":"is incremented each time a _lovrc command is processed regardless if clearing is successful.","type":"text"}]},{"type":"paragraph","content":[{"text":"locallyClearable ","type":"text","marks":[{"type":"strong"}]},{"text":"is 1 if the OKE can clear the remote override, else 0","type":"text"}]},{"type":"paragraph","content":[{"text":"localClearedCnt ","type":"text","marks":[{"type":"strong"}]},{"text":"is incremented each time the OKE attempts to clear a remote override regardless if clearing is successful.","type":"text"}]},{"type":"paragraph","content":[{"text":"Ex:","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c"},"content":[{"text":"typedef enum CW_PORT_OVERRIDE\n{\n CW_PORT_TSTAT_SET_POINT_OVERRIDE,\n CW_PORT_TSTAT_MODE_OVERRIDE,\n CW_PORT_MAX_OVERRIDE /* Must be last */\n} CW_PORT_OVERRIDE_t;","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"\"_ovr\":{\"_loc\":[[1,4,0,0],[0,0,1,0]],\"_rem\":[[0,1,1,2],[1,2,1,1]]}","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"ConnectWare Module","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"paragraph","content":[{"text":"The ConnectWare module (CWM) provides network connectivity, either WiFi or MiWi, and store and forward capabilities for the OKE.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Heartbeats","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM is a separate entity from the OKE and will generate its own heartbeats.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will minimally generate a heartbeat containing an empty $._pld field object.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Store and Forward Queues","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM module has two outbound queues, PSFQ and TSFQ, and one inbound queue, ISFQ.","type":"text"}]},{"type":"paragraph","content":[{"text":"When OKE sends an OKM to the CWM via the serial port the CWM will save the message to the appropriate store and forward queue. The OKE does not add the $._sf or $._seq fields to the JSON message, that is the responsibility of the CWM.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Set Time","type":"text"}]},{"type":"paragraph","content":[{"text":"When then CWM has valid time it will periodically set time to the OKE system.","type":"text"}]}]},{"type":"heading","attrs":{"level":1},"content":[{"text":"RESTful Interface","type":"text"}]},{"type":"expand","attrs":{"title":""},"content":[{"type":"paragraph","content":[{"text":"When OKE has a WiFi network interface, either directly integrated into the equipment or via a WiFi CWM, it will interface with the OKC as a secure HTTP client using the RESTful API documented in this section.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OKC Server Name","type":"text"}]},{"type":"paragraph","content":[{"text":"The DNS name of the OKC is TBD.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Security","type":"text"}]},{"type":"paragraph","content":[{"text":"OKE will use TLS 1.2 or later to secure the HTTP connection between the OKE and OKC.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Timeouts","type":"text"}]},{"type":"paragraph","content":[{"text":"When making HTTP requests OKE will wait at least 20 seconds for an HTTP response before timing out.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Connection Persistence","type":"text"}]},{"type":"paragraph","content":[{"text":"OKE will maintain its TCP/TLS session with the OKC between RESTful requests.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reconnection Back-off","type":"text"}]},{"type":"paragraph","content":[{"text":"CWM will implement a back-off algorithm for reconnecting to the server when a connection fails. The back-off timeout will increase exponentially for each consecutive connection failure up to 2 minutes in duration.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Server Error Back-off","type":"text"}]},{"type":"paragraph","content":[{"text":"Like the reconnection back-off, OKE will follow the same back-off algorithm when the server indicates it is busy, or when an unexpected error has occurred.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"/push","type":"text"}]},{"type":"paragraph","content":[{"text":"The OKC /push interface allows the CWM to push OKMs to the OKC and confirm their delivery. It also provides a mechanism for the OKC to have the CWM invoke the OKC /pull interface to fetch OKMs going downstream to the CWM or connected OKE.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will URL encode GET argument values.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"paragraph","content":[{"text":"/push?sha256hmac=XX..XX&req={\"okm\":{…},\"ts\":\"2020-09-16T12:13:47\"}","type":"text"}]},{"type":"paragraph","content":[{"text":"HTTP Status 200","type":"text"}]},{"type":"paragraph","content":[{"text":"{\"push\":true,\"pull\":true}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/push request","type":"text"}]},{"type":"paragraph","content":[{"text":"When the CWM has a message in either its PSFQ or TSFQ and the $._dst is OKC or not present, then the CWM will POST to the /push URI of the OKC server.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will include a sha256hmac argument on the URL which is a hexadecimal string used to authenticate the message and verify its integrity. In order to authenticate the CWM the OKC must compute the SHA256 HMAC of the req argument's URL decoded value using the Provisioning Key associated with the CWM's device ID.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the computed value exactly matches the hexadecimal string encoded value of the sha256hmac argument, then the OKC may process the req field. Otherwise the OKC must not process the req argument and may log an authentication error. Regardless, the OKC should not process any other arguments passed in the URL as these are not authenticated by the Provisioning Key.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will include a req argument on the URL which is a JSON string containing two fields. The first field is named okm and its value is the OKM being pushed to the OKC. The OKC can determine the source of the OKM from the _src field. The second field is ts, which is an ISO 8601 string indicating when the /push request was generated by the CWM.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/push response","type":"text"}]},{"type":"paragraph","content":[{"text":"If the server responds with HTTP status code 200 then the CWM will process the response data as a JSON string. This JSON string should contain the following fields: push and pull.","type":"text"}]},{"type":"paragraph","content":[{"text":"The push value is either true or false. When true the OKM pushed by the CWM to the OKC was successfully received and the CWM will free the OKM from its queue. When false or the push field is not present the CWM will not free the OKM from the queue and will attempt to resubmit the OKM again.","type":"text"}]},{"type":"paragraph","content":[{"text":"The pull value is either true or false. When true the OKC is requesting that the CWM invoke the /pull interface. When false or the pull field is not present the CWM will not invoke the /pull interface.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM can simultaneously invoke both the /push and /pull interfaces on separate connections with the OKC. However, the CWM will never invoke more than one /push or /pull request simultaneously.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"/pull","type":"text"}]},{"type":"paragraph","content":[{"text":"When the OKE ISFQ is not full and the OKC has indicated to make a request to the /pull URI then the CWM will make a GET request for that resource.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will URL encode GET argument values.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"paragraph","content":[{"text":"/pull?sha256hmac=XX…XX&req={\"devid\":\"00000102030405060708\",\"ts\":\"2020-09-16T12:13:47\",\"lokm\":true}","type":"text"}]},{"type":"paragraph","content":[{"text":"HTTP Status 200","type":"text"}]},{"type":"codeBlock","attrs":{"language":"json"},"content":[{"text":"{\"okm\":{\"_dst\": [\"00006hgCB20O8Az|8PL|8Rz|\"],\"_cmd\": \"rd\",\"_id\": 4,\"_ts\": \"2020-09-21T17:20:58Z\",\"_crc\": \"79F1\",\"_pld\": {\"_ping\": true}},\"pull\":false}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/pull Request","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will include a sha256hmac argument on the URL which is a hexadecimal string used to authenticate the message and verify its integrity.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will include a sha256hmac argument on the URL which is a hexadecimal string used to authenticate the message and verify its integrity. In order to authenticate the CWM the OKC must compute the SHA256 HMAC of the req argument's URL decoded value using the Provisioning Key associated with the CWM's device ID.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the computed value exactly matches the hexadecimal string encoded value of the sha256hmac argument, then the OKC may process the req field. Otherwise the OKC must not process the req argument and may log an authentication error. Regardless, the OKC should not process any other arguments passed in the URL as these are not authenticated by the Provisioning Key.","type":"text"}]},{"type":"paragraph","content":[{"text":"The CWM will include a req argument on the URL which is a JSON string containing three fields.","type":"text"}]},{"type":"paragraph","content":[{"text":"The first field is named devid and its value is the Device ID of the CWM. The OKC can use this field to determine which OKM should be sent in response to the /pull request.","type":"text"}]},{"type":"paragraph","content":[{"text":"The second field is ts, which is an ISO 8601 string indicating when the /pull request was generated by the CWM.","type":"text"}]},{"type":"paragraph","content":[{"text":"The third field is lokm with a value of either true or false. When true the last OKM sent in response to the last /pull request was successfully queued by the CWM and the OKC can advance to the next OKM for delivery. When false or not present the OKC should send the same OKM as the previous /pull response.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"/pull Response","type":"text"}]},{"type":"paragraph","content":[{"text":"If the server responds with a status code of 200 the CWM will expect a JSON string in the response data. The JSON string will contain two fields: okm and pull.","type":"text"}]},{"type":"paragraph","content":[{"text":"The okm field value is a JSON object that is the OKM to be queued by the CWM. This OKM should be addressed to either the CWM or the connected OKE.","type":"text"}]},{"type":"paragraph","content":[{"text":"The pull field is either true or false. When true the CWM will schedule another /pull request once it has successfully queued the OKM, or the queuing fails. When false the CWL will not invoke /pull again until the pull field is set to true in a /push response.","type":"text"}]}]}],"version":1}

Browser not supported