...
| Expand | ||
|---|---|---|
| ||
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 PortThe 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
| Expand | |||||
|---|---|---|---|---|---|
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:
|
Recursion
| Expand |
|---|
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. |
Clocks
The porting layer requires access to read a system tick count and optional access to read and write a real time clock.
...
CWPortGetTick64() must safely make a copy of the current tick counter and return it. For example, if the system tick counter is updated in a timer interrupt, then CWPortGetTick64() must turn off interrupts, make a copy of the system tick counter, turn on interrupts, and finally return the copy of the system tick counter. Not providing proper synchronization when accessing the system tick counter will invariably cause the CWL to malfunction in unexpected ways.
...
MSP430 Pseudocode Example
This section has pseudocode taken from a working MSP430-based embedded platform that properly implements synchronized retrieval of a 64-bit system tick count.
...
If an OKE system does not have an RTC then the system must use the system tick counter to simulate a clock minute.
...
MSP430 Pseudocode Example
This section has pseudocode taken from a working MSP430-based embedded platform that properly implements synchronized retrieval of the current clock minute. For context, this MSP430 platform uses a bare metal, single threaded, main execution loop. The RTC peripheral is only accessed in the context of the main loop, therefore no other conflicting access can occur simultaneously. Therefore, using an explicit synchronization primitive such as a critical section or semaphore is not required. The while loop waiting for the RTC to be ready is an access requirement of this specific RTC and will not be applicable to all RTCs. The _RTCBCD2Bin() function converts the BCD representation of the RTCMIN register into a 2's complement integer value. Accessing hardware RTC peripheral registers will vary between platforms.
...
The minimum requirement for implementors is to be able to parse and generate an ISO 8601 string such as "2019-12-03T16:17:00". The string contains a date and time field separated by a capitol T. The date field is a 4-digit year, a minus sign, a 2-digit month (01-12), a minus sign, and a 2-digit day (01-31). The time field is a 2-digit hour (00-23), a colon, a 2-digit minute (00-59), a colon, and a 2-digit second (00-59). When no time zone information is explicitly indicated, the default, the OKE will treat it as local time.
...
Local Time
The OKC knows the correct local time, accounting for both time zone and daylight savings, of a connected OKE. When time is written to the OKE, local time will be set, and time-zone context will not be provided by default. This means that OKE can display the correct local time, but without time zone context.
...
If a platform currently displays or allows manual configuration of current time, time zone and/or daylight savings then some adjustments must occur. First, when using the OKC manual time configuration should not be permitted since OKC expects to and will automatically set and maintain the proper clock time through the CWM. Second, when using the OKC, displayed time must not also report a time zone or daylight savings context since that information is not conveyed to the OKE.
...
Reading ISO Time
int8_t* CWPortGetISOTimeStr(void);
...
If an OKE system does not have an RTC, then it must return the string "0000-00-00T00:00:00". When the CWM receives a message from an OKE system with a "0000-00-00T00:00:00" timestamp it will update the timestamp with its current time before sending the message to the OKC.
...
Millisecond or Microsecond ISO Time Resolution
Nearly all OKE implementations DO NOT require sub-second time stamping. The CWM automatically ensures that the exact sequence of messages generated by the OKE is preserved and no data will be overwritten when it is transferred to and stored by the OKC even when some of those messages have the same timestamp and the same data fields.
...
In either case, please consult with the OKC team before designing and implementing high resolution timestamps since it will require additional OKC development to appropriately process the application specific data.
...
Writing ISO Time
void CWPortSetISOTime(int8_t *isoTimeStr) ;
...
If an OKE system does not have an RTC, then it may ignore the set time request.
...
ISO 8601 Platform Support
Some platforms may natively support ISO 8601 time strings. Those platforms may utilize the native interfaces to implement the CWL requirements.
For platforms that do not natively support ISO 8601 time strings the example MSP430 pseudocode in the next section shows how to implement the CWL requirements using standard C library functions.
...
MSP430 Pseudocode Examples
This section has pseudocode taken from a working MSP430-based embedded platform that properly implements synchronized reading and writing of ISO 8601 time using only standard C library functions. This platform only supports the basic form of the ISO 8601 time string, which is always 20 bytes in length including the NULL terminator.
...
It is strongly recommended that the reset function call the CW_ERROR() macro to force the reset. If the assertion handler is implemented to log the assertion, then the cause of the reset will be traceable to a deliberately commanded action rather than a spurious problem.
MSP430 Pseudocode Example
In this example port to an MSP430 platform, the CWPortExeReset() function first waits for the transmit software queue to empty, then waits 10ms for the hardware buffers to finish transmitting on the wire. Finally, an assertion is forced. The assertion handler ensures the file and line number is logged and then performs a warm reset.
...