OKE File Transfer Confirmation

Problem: Many ConnectWare integrations have not implemented any method of feedback for

the OKC to confirm whether a file distribution has fully completed or failed. Without this

verification, the OKC can only go so far as to indicate a file distribution has been successfully

Downloaded. We cannot know if the file has been loaded into the OKE file system.

Solution 1: Implement support for the File Directory Request command. This is specifically for

menu and other non-firmware file distributions.

The ConnectWare Library has a built-in command (CWPortGetFileDir()) which allows the

OKC to request the OKE/CWM to report on the files available on the system.

For the OKC to effectively utilize the OKE’s response to this command, it must contain

meaningful values for each of the following arguments passed for each file:

1. fileStr: a pointer to a file string pointer that is the name of the file. This should

match the name of the file that was uploaded to Open Kitchen and subsequently

distributed to the OKE.

1. fileVerStr: a pointer to a file string pointer that is the version of the file, or a NULL

pointer. Ideally this will match the version number input when the file is uploaded.

1. fileCRCStr: a pointer to a file string pointer that is the CRC of the file, or a NULL

pointer. This is very important as it will allow the OKC to confirm without a doubt that

this is the precise file that was distributed. You can either use a simple MD5 hash (the

OKC already stores an MD5 of every file uploaded), or the provided CWCRC16()

method, or a custom checksum scheme which must either be provided to the OKC

either at the time of the file upload or detailed in the Data Dictionary process.

Correct implementation will enable the OKC to determine whether the file was loaded into the

OKE file system and update the file distribution status in Open Kitchen accordingly (Complete,

Failed, etc).

Solution 2: Implement support for the CWPortGetVersion() function. This is specifically for

firmware file distributions.

The CWPortGetVersion() function returns platform type, software/firmware version, and hardware

revision information about the OKE. The function allows the CWL to sequentially read zero or more sets

of version information about the platform so that it can be reported to the OKC.

1. type: this tells the OKC which OKE component this file is relevant to. We’ll be adding a

new form field to the file upload form to capture this element.

1. Fwver: this is the version of the firmware image. This must match exactly the version

supplied in the file upload form for the validation to work

1. Hwrev: this field will not be used by the OKC at this time, but may be required in the

future.Details from the pertinent section of the Open Kitchen ConnectWare API User Guide are

included below, but feel free to reach out to connectware@powerhousedynamics.com with any

questions.

7.10.9 File Directory Request

The OKC may issues a file directory request to either the CWM or OKE. When the request is received the

CWL will invoke the CWPortGetFileDir() function up to 32 times or until the function returns

false.

The purpose of the file directory command is to allow the CWM or OKE to report on the files available

on the system, their version, and their CRC. The version information of firmware installed should be

reported by the CWPortGetVersion() function and not the CWPortGetFileDir() function.

The CWPortGetFileDir() function is passed 4 arguments. The first argument is index, that starts

at 0 and is incremented each time the function is called when responding to a directory request. For

subsequent requests, the index will restart at 0.

The second argument, fileStr, is a pointer to a file string pointer that is the name of the file.

Implementors should use short descriptive names for their files and not encode information that can be

derived from other fields. For example, "recipe" is sufficient to indicate a recipe configuration file,

whereas "recipe.maytag.oven.version_1" encodes other information that could be derived from other

OKM fields.

The third argument, fileVerStr, is a pointer to a file string pointer that is the version of the file, or a

NULL pointer. When the version of a file is known by the host system it should be reported via the

fileVerStr parameter. When it is not known the value should be set to NULL. Implementors should

update their data dictionary to indicate how the OKC should interpret the version field for each

supported file reported by the directory message. The purpose of the version field is to allow the OKC to

know if the device has the correct file data saved locally.

The fourth argument, fileCRCStr, is a pointer to a file string pointer that is the CRC of the file, or a

NULL pointer. When the CRC of a file is known by the host system it should be reported via the

fileCRCStr parameter. When it is not known the value should be set to NULL. Implementors should

use the CRC routine, CWCRC16(), supplied by the CWL when reporting the file CRC. However,

implementors may use other file integrity routines of their choosing if it is more convenient. The

purpose of the CRC field is to allow the OKC to know if the file saved locally has not been altered and

matches what is expected.

7.8 Versions

bool CWPortGetVersion(uint8_t index, int8_t **typeStr, int8_t

**fwverStr, int8_t **hwrevStr);

The CWPortGetVersion() function returns platform type, software/firmware version, and

hardware revision information about the OKE. The function allows the CWL to sequentially read zero or

more sets of version information about the platform so that it can be reported to the OKC.This means it is possible for a controller running the CWL to report versions for multiple components of

the system. This is particularly important so the OKC can determine if firmware updates must be

applied. Even when a component is not in-system upgradeable, having an inventory of the versions is

critical for remote asset management. So, when in doubt report the version information of as much of

the OKE system as possible.

The CWL reports version information to the OKC automatically, and calls the CWPortGetVersion()

to fetch the versions. The CWL will call the CWPortGetVersion() in a loop initially passing an index

of 0. If there is version information for index 0, which should always be the case, then the

CWPortGetVersion() will set the parameter pointers to static strings for the type, firmware, and

hardware NULL terminated strings, and then return true. It is important that the string buffers are not

on the stack frame of the CWPortGetVersion() function, since they must be accessible after the

function returns. Next the CWL will invoke CWPortGetVersion() again with an index of 1. If there

are additional versions to report then the pointers will be updated and the function will return true,

then the CWL will then ask for index 2. Else the function will return false and the CWL will know that no

more version information is available. When CWPortGetVersion() returns true, all of the pointers

must point to a valid NULL terminated string.

The type, software/firmware version, and hardware revisions are NULL terminated strings. The CWL

does not impose any restrictions on the format of any of the version strings. However, it is

recommended that implementors consider how the version information will be handled by the OKC. The

goal is for the OKC to reliably detect what version is running and initiate configured firmware updates.

This means the type and firmware version strings should be unambiguous and consistent across

versions. In some cases, the hardware revision of a component may not be known, in this case a pointer

to an empty string "" should be returned.