How to Update

Follow the instructions in the Equipment Firmware Development Process Outline section, with the exception that implementors should compare and merge changes to cwport.c and cwport.h as required.

Changes are tracked in this specification which allows implementors to easily identify changes between revisions.

For cwport.c if the function signatures match it is generally safe to bring over your existing code without modification, however care should be taken to follow any new porting guidelines for those functions.

For cwport.h make sure to bring over your port configuration settings and configure any new settings as appropriate for your system.

Minimum CWL version

The minimum recommended CWL version is 1.0.15

The latest version of the CWL is 1.0.16

Version History

CWL version 1.0.0 first release.

CWL version 1.0.1 introduced minor changes to the types of 16-bit integers pushed on the stack as variable arguments for JSON API calls. This change was made to avoid problems on some system compilers. When upgrading from 1.0.0 to 1.0.1 implementors should verify that all JSON API calls in cwport.c follow the new conventions.

CWL version 1.0.2 was primarily an update for the CWM source code which does not impact OKE implementors, therefore there is no need to update to this version from 1.0.1.

CWL version 1.0.3 added support for Starbucks IoT cloud. There were a few minor fixes that may affect OKE implementors, so they may choose to update to this version from 1.0.2 or earlier.

CWL version 1.0.4 minor fixes that may affect OKE implementors, so they may choose to update to this version from 1.0.3 or earlier.

CWL version 1.0.5 minor fixes that may affect OKE implementors, so they may choose to update to this version from 1.0.4 or earlier.

CWL version 1.0.6 fixes a Base64 encoding bug in the MJSON library, provides version and CRC fields for file directory operations, and includes other minor fixes and enhancements. Implementors should update to this version if they use Base64 encoding or support file operations. The amount of effort to update to this version from earlier versions is expected to be low.

CWL version 1.0.7 adds an OKE Linux port example, fixes a MJSON %lu formatter bug affecting only 64-bit systems, and prevents the OKE Windows port from closing a file handle more than once. Most implementors will not need to update to version 1.0.7 if already running 1.0.6.

CWL version 1.0.8 adds several new features including a throttle to OKE heartbeat generation to prevent message floods, outbound file transfer throttling, support to report total file size for inbound file transfers, support to throttle inbound file fragments without blocking. Updating to this version is only necessary if one or more of the new features is required by the implementor. Many implementors will not need to update to version 1.0.8 if already running 1.0.7.

CWL version 1.0.9 adds a compile time option to reopen USB-based serial ports at runtime. Generally only implementors using Linux and USB-based serial communication ports with the CWM would benefit from upgrading from 1.0.8.

CWL version 1.0.10 adds optional support for an OKE to receive time bias, and support to permit WiFi PSK passphrase configuration longer than 32 bytes.

Time bias is the delta between local and UTC time, this is useful for OKE implementors only if they want to display time zone information to the end user on their user interface (not required), or to time stamp internal logs with UTC time (also not required).

Some customer networks may use WiFi PSK passphrases longer than 32 bytes, in this case OKE implementors should upgrade to 1.0.10 to permit longer passphrase configuration.

CWL version 1.0.11 has improved several areas but contains no major bug fixes.

The default compiler warning levels in both Visual Studio and GCC have been increased and all latent warnings have been fixed. This will minimize the potential for compiler warnings to occur in the future.

There is improved support for the OKE to display a detailed CWM network status. The CWM now provides an enumerated value for the network status and an associated ASCII text string that can be easily displayed.

Support for the OKE to display if it is bound to an OKC location has been added. This will be very helpful for reducing the time it takes for installers to determine if the equipment is bound/configured to the correct location. Since it is very difficult to find equipment that has not been bound after installation this helps to reduce support costs.

There is improved handling of OKE heartbeats that either come close to or exceed the maximum allowable size. In previous versions of the CWL if an OKE heartbeat exceeded the maximum allowable size an assertion occurred. In this version there is no assertion, instead an empty heartbeat is generated. The CWL will now also report a warning and a heartbeat size to the OKC when the OKE heartbeat size is close to the maximum. A compile time option in cwport.h provides the ability for an OKE implementor to enable an assertion when a warning occurs during development. Ensuring that heartbeats are not near the maximum size prevents oversized heartbeats from occurring later on, especially since the size of a heartbeat can change over time. For example, as a counter increases the number of digits to represent it will also increase and will cause the heartbeat data to grow larger.

Because of the changes that will help reduce installation and support costs it is strongly recommended that OKE implementors update to this version of the CWL.

CWL version 1.0.12 is primarily a feature update. OKEs can now configure the IP settings of the WiFi CWM and display the current IP configuration settings. OKEs can now display what location it is assigned to in OpenKitchen, which can help installers confirm if the OKE if properly configured before leaving a site. There is now an OKE build script for OS X that will allow some development and debugging on OS X.

Because of the new location features that help reduce installation costs it is strongly recommended that OKE implementors update to this version of the CWL.

CWL version 1.0.13 is primarily a feature update. OKEs can now optionally negotiate a faster baud rate to speed up file transfers on TTL and 232 ports. Some additional file transfer optimizations minimize recovery time if a transfer stalls. Therefore, it is recommended to upgrade to 1.0.13 for improved file transfer performance. With these changes and the latest WiFi CWM firmware (>141) file transfers speeds will improve 2-3 times compared to older versions.

CWL version 1.0.14 has feature updates to improve file transfer behaviors. It is recommended that OKE implementors update to this version to potentially improve the speed and other behaviors related to file transfer.

CWL version 1.0.15 fixes a critical bug in the serial fragmentation layer that causes lost heartbeats when they have specific lengths. Implementors are must to update to the 1.0.15 release or patch cwnwk.c in their existing codebase.

CWL version 1.0.16 adds support for Custom Server Endpoints and RSSI reporting. Custom Server Endpoints allows a CWM to be configured to point to alternative, 3^rd party OpenKitchen compatible servers. The OKE can enable the interface to configure Custom Server Endpoints by enabling CW_PORT_IS_CUSTOM_ENDPOINT_ENABLED. Some versions of CWM will report the RSSI of scanned APs and of the network to which it is currently connected. The OKE must enable CW_PORT_IS_RSSI_ENABLED to allow decoding of the RSSI value.