Coding Guide
- Ricky Goldfarb
Microprocessor Requirements
The microprocessor and memory requirements are modest. An 8 or 16-bit microcontroller running at a clock speed of 8MHz and having a total of 128kB of program memory and 16kB of SRAM should be able to easily accommodate the CWL.
Program Memory and RAM Estimates
To generate some useful estimates, the CWL was integrated onto a 16-bit MSP430 platform having 128KB of program memory and 16KB of SRAM. The baseline program memory and RAM usage was recorded before library integration. The following table is generally illustrative of the additional memory requirements the CWL imposes.
Configuration | Program Memory (KB) | RAM (KB) |
# 1: Full w/File Transfer and w/Standard Buffers | +20 | +3.0 0.5 of the 3.0 is only used during a file transfer and could be dynamically allocated |
#2: Full w/o File Transfer and w/Standard Buffers | +18 | +2.5 |
#3: Full w/o File Transfer and w/Small Buffers | +17 | +1.5 |
The compiler optimization level was set to high to derive these estimates.
Depending on the application complexity an additional 1-5KB of program memory may be required to complete a controller implementation.
In configuration #1 file transfer is supported and the additional RAM usage is 3.0KB. However, 0.5KB of the 3KB is only used as a temporary buffer during a file transfer from the OKC to the OKE system. This temporary buffer could be dynamically allocated from the heap by the application and freed when the transfer ends. This would put the additional fixed RAM cost of the CWL at 2.5KB.
The CWL does not directly use dynamic memory, so no additional burdens are placed on system heaps. However, some systems may need to increase the stack size of the main loop or task/thread that executes the CWL. Generally, a total stack size between 1-2KB is more than enough. Implementors must account for additional RAM usage if stack size must be increased. As always implementors should exercise their systems and verify that the system stacks have ample safety margin.
Also, the CWL requires a minimum of CW_PORT_MIN_SERIAL_RX_BUFFER_SIZE + CW_PORT_MIN_SERIAL_TX_BUFFER_SIZE bytes of software-based serial receive and transmit buffering, currently a total of 512 bytes. Many systems will already have software receive and transmit buffering that meets this requirement. If not, then implementors must account for the additional RAM usage to implement the required serial buffering.
Taking all these possible factors into account, in a sub-optimal situation the CWL may require up to +25KB of code space, +4KB RAM, and +0.5KB temporary heap usage.
While it is strongly recommended for OKE systems to implement the full CWL including file transfer, we understand that some legacy systems will have extreme memory constraints. For these systems the CWL can be configured to use as little as +17KB program memory and +1.5KB of RAM while still providing OpenKitchen compatibility.
It should be noted that in many instances implementors will be able to remove existing code that interfaces to other management systems, and easily achieve the program memory and RAM savings that completely offset the needs of the CWL.
OS Requirements
There are no minimum OS requirements. It is adaptable to any bare metal, RTOS, or Linux OS environment. The CWL does not directly use dynamic memory and does not directly rely on any OS task synchronization primitives.
Linux Port
The default port of the CWL is for Windows, which can be built and debugged using Visual Studio for implementors who want to experiment before starting their port.
A Linux port of the OKE simulator is available as well. To build the Linux port change directory to _OpenKitchenEquipment_OKE and run the _OpenKitchenEquipment_OKE.sh build script. The oke simulator will be created by the build process. Running the oke simulator is the same as running and using the Windows oke.exe simulator. See the Simulation section later in the document for information on how to run the oke and oke.exe simulators.
Linux versions of the CWM and OKC simulators are not available at this time. However, it is possible to run the CWM and OKC simulators on Windows and connect to the Linux oke simulator via a serial connection.
Endianness
To ensure interoperability between platforms the byte ordering of multi-byte integer values must be considered. Little-endian means that the least significant bytes of a multi-byte integer come before the most significant bytes as address values ascend. Big-endian, also known as network byte order, means that the most significant bytes of a multi-byte integer come before the least significant bytes as address values ascend.
When applicable the CWL internals will use network byte order. Controller specific application data is not required to use network byte order, although it is strongly recommended in cases where it is applicable; usually when using the %H formatter.
Equipment platforms must minimally provide ntohs() and htons() functions. If your platform does not already provide these functions the following C marcos can be placed in cwport.h:
#define htons(x) ((uint16_t) ((((x) >> 8) & 0xff) | (((x) & 0xff) << 8)))
#define ntohs(x) htons(x)
Recursion
During the generation of certain JSON messages some functions, in particular MJPrintf(), will be called recursively. The depth of the recursion is a function of the number of levels of object and array nesting in a generated JSON string. Implementors are encouraged to minimize nesting both to reduce stack utilization on constrained platforms and to flatten OKMs that helps minimize cloud overhead when processing OKMs.
Reset
Flush
Versions