Porting to MSP430 Example

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.

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.

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.

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)

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.

The porting layer requires access to read a system tick count and optional access to read and write a real time clock.

System Tick

Most systems will already have and use a system tick count. It is usually an integer value that is incremented at a constant periodic rate, typically inside a timer interrupt.

Unlike a real-time clock that usually has a resolution of 1 second, the system tick counter allows application code to time intervals down to the millisecond resolution. And unlike a real-time clock that has discontinuities when time is changed, the system tick counter always, predictably increases until the system is reset.

The CWL library requires access to a system tick count. First, the constant CW_PORT_TICKS_PER_SECOND must be defined to indicate the number of system tick counts per second. Second the CWPortTick_t type must be defined to match the data type of the system tick counter. Third, the CWPortGetTick64() function must be implemented to return the current tick counter value in a synchronized manner.

A system tick resolution of 10ms is acceptable, although a resolution of 1ms makes timing more precise and is especially beneficial for half-duplex serial communication to the CWM. By these guidelines, CW_PORT_TICKS_PER_SECOND should be roughly in the range of 100 to 1000. This constant should include a type qualifier such as ull for 64-bit system tick counters to ensure that arithmetic operations use the correct type.

As implied by the name, CWPortGetTick64() function expects to return a 64-bit tick counter value, and this is the preferred implementation. When using a 64-bit tick counter, code can safely ignore the case when the timer wraps back to zero, since this would take a very, very long time to occur. Because integer overflow is not relevant, tick comparisons are straightforward and simplify the code logic. Most modern toolchains support the uint64_t type even on 8 and 16-bit microcontrollers.

For platforms that support 64-bit integer types, but that currently use a 32-bit tick counter there are the following options: One, convert the system to a single 64-bit tick counter. Two, add a parallel 64-bit tick counter so that existing code using the 32-bit counter does not need to be updated. Three, use the 32-bit tick counter anyhow.

For platforms that do not support 64-bit integer types or that decide not to use them the implementor may simply define CWPortTick_t to be a 32-bit integer type and CWPortGetTick64() will return a 32-bit value. The drawback is that tick counter integer overflow will occur regularly on the human time scale. For example, a 32-bit 10ms timer tick will wrap every 1.3 years, and a 1ms ticker tick will wrap every 49 days. When wrap occurs, there is the possibility that active timeout intervals within the CWL will malfunction. To avoid these potential malfunctions the system controller could reset itself before the timer tick count wraps. For example, the system controller could reset itself at 3AM if the timer tick count has been running for more than 45 days. Rebooting the system controller during off hours minimizes any impact to normal operation.

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.

The tick counter is a uint64_t type. CWPortTick_t is defined to be a uint64_t type. The system tick fires 1024 times per second to increment the counter, so CW_PORT_TICKS_PER_SECOND is defined accordingly. The CWPortGetTick64() function makes a copy of the system tick counter while interrupts are disabled. This synchronizes it with the timer interrupt and prevents corrupted tick values from being read and returned to the CWL.

Volatile uint64_t gTimerTickCnt;
#pragma vector=TIMER1_A1_VECTOR
__interrupt void TimerTickIsr(void) 
{
    if (TA1IV == 2) gTimerTickCnt++;
}

#define CW_PORT_TICKS_PER_SECOND (1024ull)
typedef uint64_t CWPortTick_t ;
CWPortTick_t CWPortGetTick64(void) 
{
    CWPortTick_t temp;
    CS_ENTER() ; /* Disable global interrupts */
    temp = gTimerTickCnt;
    CS_EXIT(); /* Enable global interrupts */
    return temp;
}

Clock Minute

The CWL library aligns heartbeat reports to the top of every clock minute. The clock epoch, whether Jan 1, 1970, 2000, or some other date will not affect the proper operation of the library. The CWPortGetClockMinute() function must be implemented to return the current clock minute, a value from 0 to 59, and must properly synchronize access to the clock data source so that data corruption does not occur.

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.

Int8_t CWPortGetClockMinute(void)
{
    int8_t minute;
    CW_ASSERT(RTCIsRunning()); /* Only valid to call if RTC is inited */
    while((RTCCTL01 & RTCRDY) == 0); /* Wait for RTC to be ready to read */
    minute = _RTCBCD2Bin(RTCMIN); /* Read minute value */
    CW_ENSURE((minute >= 0) && (minute <= 59)); /* Must be in range */
    return minute; /* Return the clock minute */
}

ISO 8601 Time

ISO 8601 defines a standard way to unambiguously convey dates and times as structured ASCII strings. The CWL only requires a small subset of the standard to be implemented so that current time can be read and written as an ISO 8601 string. A platform will typically not maintain time as an ISO 8601 string. Rather a platform will convert an ISO 8601 string into its local time representation or will convert its local time representation into an ISO 8601 string on an as needed basis.

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.

UTC aligned time is not written to connected devices since this would require connected devices to also be properly configured for time zone and daylight savings to perform local time calculations competently. Only setting local time to the connected devices greatly simplifies ensuring correct time is displayed and used by the OKE.

The CWM periodically writes local time as an ISO 8601 string to the OKE. The CWM gets current local time either directly from the OCK or indirectly via the IoT Gateway which gets time from the OKC.

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);

The CWPortGetISOTimeStr() function must return a pointer to a persistent, valid, NULL terminated ISO 8601 time string. The time string must not include time zone information and should report local time. Implementors may include sub-second precision only if application specific requirements warrant it. For example, a typical time string value would be: "2019-02-03T16:59:01". The string may not allocated from the stack of the CWPortGetISOTimeStr() function because the time string must persist after the function returns. Therefore, the time string should be allocated as a global variable or statically within the scope of the function. The function must also synchronize access to the RTC so that data read from it is not corrupted.

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.

If there is a use case for sub-second resolution time stamps, the OKE implementor will need to perform additional implementation specific steps to queue and forward the messages via the CWPortGenHeartbeatCB() callback and override the CWL's default timestamp.

Another possible solution to high resolution timestamping is to curate the data into a log file containing the desired timestamp resolution and use the CLW's file transfer to write the log to the cloud for processing.

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) ;

The CWPortSetISOTime() function takes a valid ISO 8601 time string and updates its internal clock time. Implementors only need to handle and process the most basic of ISO 8601 time strings, ones of the form "yyyy-mm-ddThh:mm:ss", and must ignore any unhandled time string formats. For example, time string formats including time zone information must be ignored if the implementation only handles the basic format. When processing a basic time string without any time zone information, the function must interpret it as the current local time of the OKE. The function must also synchronize access to the RTC so that data written to it is not corrupted.

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.

In the CWPortGetISOTimeStr() function the buffer into which the current local time is formatted is declared as static. This ensures the buffer persists after the function returns. The ReadCurrentTimeAndDate() function is a platform specific function that reads the current time and date into easy to use structure. Because this platform operates as a single main execution loop and the RTC is never accessed from an interrupt context it is not necessary to explicitly synchronize access to the RTC using critical sections or a semaphore. A snprintf() call is used to generate the current local time as a valid ISO 8601 string. Because snprintf() does not guarantee NULL termination, a NULL terminator is explicitly set. The pointer to the newly formatted, NULL terminated buffer is returned.

The CWPortSetISOTime() function is passed what should be an ISO 8601 time string. Since this implementation only support the basic form of ISO 8601 strings the size of the input string must be exactly 20 bytes, and the field separators must be in the correct positions. If the length and field separators are valid then the code attempts to convert the fields into integer values written to a TimeAndDate structure. The TimeAndDate structure is platform specific and is not a standard time structure. After the string to integer conversions are complete the code sanity checks the ranges of the date and time fields. Only if the sanity check passes will the code write the time to the RTC. Although this code deliberately ignores other forms of ISO 8601 time strings which may include time zone information or additional precision it meets CWL requirements.

#define ISO_STRING_SIZE 20 /* "yyyy-mm-ddThh:mm:ss" including NULL */

int8_t* CWPortGetISOTime(void)
{
    TimeAndDate td;
    static int8_t isoTime[ISO_STRING_SIZE];
    ReadCurrentTimeAndDate(&td);
    snprintf((char *)isoTime, sizeof(isoTime), "%04d-%02d-%02dT%02d:%02d:%02d", td.Year, td.Month, td.Date, td.Hour, td.Minute, td.Second);
    isoTime[sizeof(isoTime) – 1] = 0; /* Ensure NULL termination */
    return isoTime;
}

void CWPortSetISOTime(int8_t *isoTimeStr, uint16_t isoTimeStrSize)
{
    TimeAndDate td;
    CW_REQUIRE(isoTimeStr != NULL);
    /* Only process time strings of basic format, ignore anything else */
    if ((isoTimeStrSize == ISO_STRING_SIZE) && (isoTimeStr[4] == '-') &&
        (isoTimeStr[7] == '-') && (isoTimeStr[10] == 'T') &&
        (isoTimeStr[13] == ':') && (isoTimeStr[16] == ':')) 
      {
        td.Year = atoi(&time[0]);
        td.Month = atoi(&time[5]);
        td.Date = atoi(&time[8]);
        td.Hour = atoi(&time[11]);        
        td.Minute = atoi(&time[14]);
        td.Second = atoi(&time[17]);
        if ((td.Year > 2018) && (td.Month >= 1) && (td.Month <= 12) &&
            (td.Date >= 1) && (td.Date <= 31) && (td.Hour <= 23) &&
            (td.Minute <= 59) && (td.Second <= 59)) 
          {
            WriteCurrentTimeAndDate(&td);
          }
      }
}

void CWPortExeReset(void);

The CWPortExeReset() function must force a full warm start of the OKE controller. The function must ensure that the serial transmit software and hardware buffers are empty before resetting. This function should not return to the caller.

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.

Void CWPortExeReset(void)
{
    while (TxDataQueueIsEmpty() == false);
    DelayMs(10);
    CW_ERROR();
}

void CWPortExeFlush(void);

The CWPortExeFlush() function is intended to permit the OKC to clear out persistent/non-volatile data such as accumulated logs or other data that could backlog or inhibit the desired operation of the equipment.

Primarily this function applies to the CWM that has very deep non-volatile queues, that in some cases the OKC needs to empty.

For many OKE implementations this function may not take any action.

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.

Pseudocode Example

In this example code the CWPortGetVersion() function returns two sets of version information. The first time the CWL calls the function with an index of 0, *typeStr is set to point to "TCHEF", *fwverStr is set to point to "1.3.42", and hwrevStr is set to point to "A1", and true is returned. The second time the CWL calls the function with an index of 1, *typeStr is set to point to "TCAB", *fwverStr is set to point to "4.2.c1", and hwrevStr is set to point to "REV3", and true is returned. The last time the CWL calls the function it returns false.

Bool CWPortGetVersion(uint8_t index, int8_t** typeStr, int8_t** fwverStr, int8_t** hwrevStr) 
{
    static const int8_t *type[] = {"TCHEF","TCAB"} ;
    static const int8_t *fwver[] = {"1.3.42","4.2.c1"} ;
    static const int8_t *hwrev[] = {"A1","REV3"} ;

    CW_REQUIRE(typeStr != NULL);
    CW_REQUIRE(fwverStr != NULL);
    CW_REQUIRE(hwrevStr != NULL);

    /* There are only 2 versions to report */
    if (index >= 2) return false;

    *typeStr = (int8_t *) type[index];
    *fwverStr = (int8_t *) fwver[index];
    *hwrevStr = (int8_t *) hwrev[index];

    CW_ENSURE(*typeStr != NULL);
    CW_ENSURE(*fwverStr != NULL);
    CW_ENSURE(*hwrevStr != NULL);

    return true;
}

OKE systems must send periodic OKMs that contain the operational status of the system. The CWL will automatically invoke CWPortGenHeartbeatCB() once every minute to allow the application code to generate its application specific heartbeat message. The heartbeat message must be valid JSON.

CWPortGenHeartbeatCB() is an MJSON printer function invoked under the context of a MJPrintf() call triggered by the library. Implementors must use MJPrintf() calls within the context of CWPortGenHeartbeatCB()to generate the heartbeat message. The function must return the total number of new bytes written to the message. Implementors will have either 300 or 800 (default) bytes of buffer space for generating each heartbeat message depending on the CWL configuration.

Implementors can cause the callback to be invoked additional times when more than one heartbeat OKM must be generated each minute or when a critical state change occurs. This is done by calling CWCmdScheduleHeartbeat().

The last heartbeat message per minute interval should not invoke CWCmdScheduleHeartbeat() because that will cause continuous heartbeat generation.

Heartbeat Throttling

The CWL has added a throttling mechanism for heartbeats that prevents the generation of more than CW_PORT_MAX_HEARTBEATS_PER_MIN per minute. Continuous generation of heartbeat messages clogs up the outbound store and forward queues and the bandwidth to the OKC with highly redundant information. Additionally, it can starve out other CWL message generation.

CW_PORT_MAX_HEARTBEATS_PER_MIN is defined in cwport.h and the default is 15 which should be more than enough for most applications such that they are never throttled.

If a throttling event occurs the CWL will report additional diagnostics to the OKC so that the condition is recorded. When the next one-minute period begins, the application will be allowed to send another set of heartbeats.

Common causes of excessive heartbeat generation includes calling CWCmdScheduleHeartbeat() every time CWPortGenHeartbeatCB() is invoked and calling CWCmdScheduleHeartbeat()continuously while the equipment is in a fault state when the desired behavior is to send a single set of heartbeats after entering the fault state.

Partitioning Heartbeats

There is a 1000 total byte limit for each OKM including required overhead added by the CWL and NULL terminator. Implementors must target a maximum heartbeat payload size of either 300 or 800 bytes. This will adequately account for overhead and some margin for future protocol changes. Many systems will be able to encode all the required heartbeat data in 800 bytes.

However, some systems may have more than 800 bytes of heartbeat data, and/or may be organized in such a way that logically organizing data in distinct heartbeats is convenient. For example, a modular oven system, may send a separate heartbeat for each cabinet.

From an efficiency perspective it is better to have fewer, larger heartbeats, rather than many, smaller heartbeats, since the overhead of each message is constant.

OKM Formatting

It is valid for JSON strings to include whitespace and line breaks. This formatting does not alter the meaning of a JSON message. However, it does unnecessarily consume additional memory and network bandwidth. Therefore, implementors should not include whitespace or line breaks in their generated messages.

Rate Limiting

Heartbeats should only be generated once per minute. It is best to report faults and other events that occur between heartbeats as ascending counters. These counters can be reset to 0 on a restart. The OKC can determine the type and number of faults that occurred between two heartbeats. The OKE may generate additional heartbeats when certain events occur, but this is not encouraged. However, if a requirement exists to do so then the OKE must implement a rate limiting mechanism to prevent the CWM store and forward queue from being filled with OKMs that consume storage and network resources and limit the ability to diagnose problems by delaying delivery of newer OKMs to the OKC.

Every OKE must be a good OpenKitchen citizen and try to use the minimum resources necessary when sending heartbeats. By doing so the entire OpenKitchen system will work better for our customers.

Pseudocode Example

This example is from the Window port. It shows a simple scenario where the application code generates two heartbeat message each minute. This is a contrived example since all the data could have fit into a single heartbeat. When hbState is zero the callback prints the door count data, requests an additional heartbeat by calling CWCmdScheduleHeartbeat() and changes hbState to 1. The CWL will invoke the callback a second time after the first one is sent. Since hbState is one the temp data is reported, and the state is set back to 0. It does not call CWMsgTxHeartbeat() again since all the heartbeats have been sent for this cycle.

Int32_t CWPortGenHeartbeatCB(MJBuffer_t* mb, va_list* ap) 
{
    int total = 0;
    static uint8_t hbState;
    static uint32_t appcount;
    switch (hbState) 
    {
        case 0:
            total += MJPrintf(mb, "%Q:%u", "door", appcount);
            appcount++;
            CWCmdScheduleHeartbeat();
            hbState = 1;
            break;
        default:
            total += MJPrintf(mb, "%Q:%u", "temp", 350 + appcount % 10);
            hbState = 0;
            break;
    }
    return total;
}

The following are messages generated by the example code.

{"_dst":["OKC"],"_src":["0011223344556677"],"_cmd":"wr","_id":24,"_ts":"2019-12-06T12:06:00","_crc":"48D7","_pld":{"_hbt":{"door":8}}}

{"_dst":["OKC"],"_src":["0011223344556677"],"_cmd":"wr","_id":25,"_ts":"2019-12-06T12:06:00","_crc":"6949","_pld":{"_hbt":{"temp":359}}}

The CWPortGenHeartbeatCB() function only is responsible for the "door":8 and "temp":359 portions of the messages. The rest of the JSON is automatically generated by the library.

The CWL allows OKE systems to read and write files containing arbitrary data via the file transfer interface. Individual file transfers of up to 2^31-1 bytes (2GB) in size are allowed. The primary use of file transfer is for firmware updates since it is highly likely that all OKE controllers will support in-system updates. Other possible uses for file transfer include sending recipes to equipment, or for equipment to offload diagnostic logs to the OKC.

File transfer is an optional service of the CWL and may be disabled by setting CW_PORT_IS_FILE_SUPPORT_ENABLED to 0. This will save code space and also permit implementors to significantly reduce the CWL RAM requirements by also setting CW_PORT_IS_SMALL_MSG_ENABLED to 1.

The OKC can write a file to an OKE system and read a file from an OKE system.

Likewise, an OKE system can write a file to the OKC and read a file from the OKC.

When a file read request is made, regardless if sent by the OKC to an OKE system or vice versa, it will simply cause the target of the request to begin writing the file back to the requestor. This means that files are only transferred in the context of a file write operation.

The CWL makes no assumptions about the filesystem on the implementor's platform, or even if a traditional file system exists. For example, many deeply embedded platforms simply have interfaces that read and write to a non-volatile memory that is partitioned statically. Other platforms, such as Linux, will have full desktop compatible, wear leveling flash file systems. The CWL can easily work with either setup. Implementors should consider the file names used in OKMs to be logical and not necessarily have or demand a direct manifestation as a "real" file.

CWM Buffering

File transfers may need to move large quantities of data. Many embedded systems will have limited amounts of high-speed RAM buffers, and there can be significant latency and throughput bottlenecks when writing data out to a non-volatile memory. So how can a small embedded system handle the onslaught of file data sent to it from the cloud computers with 10 Gigabit network connections?

The answer is that the ConnectWare file transfer mechanism ensures that when the OKC is writing a file to OKE, an OKE system needs to only handle small amounts of file data, no more than 512 bytes, at any time and can easily throttle the rate at which it receives file data.

The CWM will only send these file fragment messages to OKE at the rate allowed by the OKE system.

Likewise, when an OKE system is writing a file to the OKC, the CWM buffers the file fragment messages from the OKE before sending them to the OKC.

By decoupling file transfer between an OKE system from the OKC, the CWM allows an OKE system to easily manage having large files written to it and write large files to the OKC.

OKE Inbound File Transfer Throttling

As an OKE receives inbound file write fragments it may easily throttle the CWM from sending the next fragment for up to 4 seconds without triggering serial communication layer timeouts. Implementors should add code to the CWPortIsAppBusy() function that will return true when the application is not ready to handle the next file fragment, and false otherwise. The CWPortIsAppBusy() function must not return true for more than 4 consecutive seconds otherwise serial communication timeouts may occur. Serial communication is always gracefully recovered after a timeout but nevertheless should be avoided.

Generally, 4 seconds should be enough time for an application to completely write 512 bytes to modern non-volatile memory.

Should the non-volatile memory need to be erased before a write is initiated then implementors should erase the smallest partition necessary to complete the next write to minimize the erase time. For example, it is better to make 16 4KB erase requests that each take 250ms than a single 64KB erase request that takes 4 seconds.

Aborting an OKE Inbound File Transfer

An OKE may abort an inbound file transfer at any time by returning false when CWPortExeFileWrite() is invoked by the library. For example, an OKE may abort or prevent a file transfer if the user enters a technician diagnostic mode. Generally, implementors should minimize or eliminate modes during which file transfers are not permitted.

Transferring Large Files

Files larger than the CWM ISFQ can be transferred from the OKC to an OKE. This is possible by the OKC actively monitoring the progress of the file transfer to ensure that it does not overrun the CWM ISFQ. Using this technique files up to 2GB can be transferred.

Faster Baud Rate Negotiation

When CW_PORT_DYNAMIC_BAUD_ENABLED is set to 1 in cwport.h the CWL will automatically attempt to negotiate the baud rate defined by CW_PORT_BAUD_RATE_FAST with the CWM. The OKE starts at default baud rate defined by CW_PORT_BAUD_RATE_DEFAULT and the library will try to increase the rate to the desired speed. If the CWM supports running at the higher speed, then both the OKE and CWM will switch. If any communication failures occur or the baud rates get out of sync both the OKE and CWM will drop back to the default baud rate and resynchronize. The OKE will request the baud rate to increase again. Typically, this option will only be used by OKEs using the TTL or 232 bus and that regularly transfer large files >10MB. Other OKEs can simply ignore this option and run at the default baud rate. The allowed values for faster baud rate are 230400, 250000, 500000, and 1000000.

Fastest Interface

The USB interface can support the highest transfer speeds. Although the 232 and USB transfers rates are similar with the current WiFi CWM hardware, in the future newer CWM hardware will allow the USB interface to go much faster than 1000000 baud.

File Transfer Throughput

The amount of time it takes to transfer a file is a function of many variables including file size, processing latencies, and link bandwidths. The following table shows the estimated throughput between the MiWi and WiFi CWM versus the OKE connection type:

OKE implementors should use these throughput estimates along with their product requirements to help determine the CWM communication port type (USB, serial, etc.) and settings (baud rate, full/half duplex, etc.) and the recommended CWM network type (WiFi, MiWi, etc.) for their application. Poor wireless connectivity or OKE file transfer throttling will reduce throughput so OKE implementors should verify that file transfers are meeting their requirements during the development and integration phase.

For the MiWi CWM the MiWi wireless network interface is the primary bottleneck for file transfers. The MiWi radio network has a 250,000bps raw bit rate and the maximum payload size is 127 bytes. This requires fragmentation of OKMs resulting in increased overhead and much lower throughput efficiency. Additionally, the MiWi network bandwidth may be shared with up to 2 dozen other devices further reducing file transfer throughput to a specific device.

MiWi CWM transfer time examples:

1. A MiWi CWM connected to an OKE via any communication interface can transfer a 1MB file in about 1 hour.

For the WiFi CWM the OKE connection to the CWM will be the primary bottleneck for file transfers. Generally, the WiFi CWM should be able to transfer files to the OKE at a significant fraction of the OKE connection's baud rate.

WiFi CWM transfer time examples:

1. A WiFi CWM connected to an OKE via USB can transfer a 1MB file in about 46 seconds.

1. A WiFi CWM connected to an OKE via TTL full duplex serial at 115200 can transfer a 1MB file in about 3 minutes.

1. A WiFi CWM connected to an OKE via 232 full duplex serial at 1000000 can transfer a 1MB file in about 50 seconds.

1. A MiWi CWM connected to an OKE via TTL full duplex serial at 115200 can transfer a 1MB file in about 1 hour.

1. At comparable baud rates a half-duplex serial connection will be slightly slower than a full duplex connection for OKC to OKE file transfers.

OKE implementors should consider the file transfer use cases for their equipment and ask the following questions:

1. For each type of file, does the equipment need to perform the file transfer without affecting normal operation?

1. For each type of file, what is the typical and maximum acceptable amount of time to transfer the file.

OKE implementors should consider the following when specifying the encoding of their files:

1. Can the file be encoded more efficiently? For example, a firmware file could be encoded as binary instead of Intel Hex (printable ASCII), more than halving the file size. This would also halve the file transfer time.

1. Can the file be broken up into smaller independent portions? For example, instead of transferring all the recipes, just transfer the modified recipes. This could reduce the file transfer time by a factor of 10 or more.

OKE implementors should consider embedding the following information in their file's header to check before processing the file after download:

1. A file integrity check, such as a CRC. This helps to ensure that the file has not been corrupted before processing. Corrupted files can be safely ignored by the OKE.

1. A file version to differentiate between different file encodings. This ensures files with incompatible encodings are safely ignored by the OKE.

File Status

Independent of reporting the current status of a file being written to the OKE, the names of important individual files maintained by the OKE are also reported automatically by the CWL.

An OKE system must be targeted in its list of reported files, for example it should NOT try to report every single file in a Linux root file system. Besides being too large to fit into a single OKM it would consume tremendous bandwidth to report on files that are of little direct management value.

Some examples of files that might make sense to report are the name of recipe configurations, or the name of diagnostic logs. It is not necessary to list the names of firmware files since they are enumerated in the version data. The idea is to enable the equipment to be effectively managed by the OKC. Implementors should think about the capabilities of the product and the use cases for its utilization. Based on this knowledge, provide file information to the OKC that can enhance it manageability.

Firmware

Many systems that implement file transfer will also implement in-system firmware updates. The OKC will transfer firmware images to an OKE system via a file write. An OKE system will be able to write the new firmware image to secondary storage. If the file transfer is successfully and the firmware passes platform specific integrity checks then it should be automatically installed.

Writing from the OKC to an OKE System

bool CWPortGetInboundFileWriteBuf(uint8_t** buf, uint16_t* bufSize);

bool CWPortExeFileWrite(int8_t* fileStr, uint32_t offset, uint8_t* data, uint16_t dataLen, int32_t fileSize) ;

The CWPortGetInboundFileWriteBuf() function returns the buffer into which file fragment data being written to an OKE system is temporarily stored by the CWL. The function must allocate a buffer of at least CWCMD_FILE_FRAG_SIZE bytes. It will pass a pointer and the allocated size back to the CWL via the buf and bufSize pointers then return true. The function must return false if the buffer could not be allocated. Because only one fragment buffer is used by the CWL at a time the buffer may simply be a global or statically defined buffer. The buffer is only used by the CWL from the time the CWPortGetInboundFileWriteBuf() function returns until the CWPortExeFileWrite() function finishes writing the data buffer to non-volatile memory. Therefore, implementors may also allocate the buffer once, dynamically from heap memory, and then free it when the file transfer completes.

The CWPortExeFileWrite() function is called every time a new, in sequence, file fragment being written to an OKE system is received. The fileStr parameter is a NULL terminated string containing the name of the file being written. The file name will remain constant for the duration of the file transfer. The offset parameter indicates the byte offset from the start of the file where the new file fragment should be written. When offset is zero this means a new file transfer is being started, any previous open or incomplete file transfer must first be aborted and then the new file transfer opened. The data parameter points to the binary data that should be written to the file, and it is the buffer returned by CWPortGetInboundFileWriteBuf(). The dataLen parameter is the number of bytes of data to be written. If dataLen is equal to CWCMD_FILE_FRAG_SIZE, then the file transfer is not yet complete. If dataLen is less than CWCMD_FILE_FRAG_SIZE bytes then it is the last fragment of file data, and the file can be closed after writing the last fragment. If the file is an even multiple of CWCMD_FILE_FRAG_SIZE bytes then the last fragment will have a dataLen of zero and the file can be closed without writing any additional data. When known fileSize indicates the total size of the file in bytes, otherwise it will be -1. fileSize must only be used by implementors to indicate file download progress, it must not be used to detect the end of the file transfer.

The CWL simplifies the logic required in CWPortExeFileWrite(). First the CWL only permits one file to be written to an OKE system at a time. Therefore CWPortExeFileWrite()  must only manage one open file at a time. Second, CWPortExeFileWrite()  will only be called with the next logical file fragment offset, or with an offset of zero if a new file transfer if requested. Therefore, the CWPortExeFileWrite()  function does not need to be concerned with out of sequence file fragments.

The CWPortExeFileWrite()  must return true if it successfully processed the file fragment. If an unexpected error occurs, then the function must return false.

Throttling File Fragments

As previously discussed, the CWM buffers all file fragments from the OKC. The OKE can determine the pace at which the file fragments are received in case its local non-volatile memory cannot be written to fast enough. This section describes two strategies for the OKE to implement throttling.

1. Simply block in the CWPortExeFileWrite()  function until the file fragment data can be written. Implementations can block for up to 5 seconds before any serial bus timeouts with the CWM will occur. Typically, most platforms would not need to block for more than 10-100ms. The drawback to this approach is most apparent in bare metal systems that run from a single main loop. Blocking in CWPortExeFileWrite()  will block the main loop from being serviced. Implementors will need to determine if the additional latency will adversely affect the system operation or not. For RTOS, or Linux implementations that have a dedicated CWL task/thread, blocking in CWPortExeFileWrite()  should not pose any problems.

1. Modify the bare metal main loop, or the CWPortTask() so that it does not call CWMsgTask() if the non-volatile memory is not ready to write data to it. Functionally this is like #1, except that in the case of a bare metal system other functions of the main loop can still be serviced.

Implementors may also consider lazy blocking. For example, after writing data to a non-volatile memory the memory usually goes into a busy state for a period during which it cannot accept new writes. Instead of writing and immediately blocking waiting for the write to complete the CWPortExeFileWrite()  function should return without blocking. The next time the CWPortExeFileWrite()  function is called it can block conditionally only if the write operation is still in progress. Deferring the memory busy check can increase file throughput considerably.

Pseudocode Example

This example code is from the Windows port of the CWL.

The CWPortGetInboundFileWriteBuf() function simply returns a static buffer pointer of the required minimum size. The CWL uses this buffer to pass the file fragment data to the CWPortExeFileWrite() function as the data pointer.

The CWPortExeFileWrite() function first checks to see of the offset is zero. If zero it means a new file transfer is being started. If a previous file was opened it is first closed, then the new file is opened. The data is then written to the file. You will notice that the offset is not used in the fwrite() function call. This is because the standard C file functions keep track of the current file pointer. Since the CWL only calls the CWPortExeFileWrite() function with sequential file fragments the code can simply write the fragment out to the file without being concerned that the file will get mangled. Finally, the file is closed if the dataLen is less than CWCMD_FILE_FRAG_SIZE  since that indicates the end of the file transfer.

A real implementation may need to look at fileStr to determine the type of file, where and how to store it, and what if any actions to take after the file is successfully written.

Bool CWPortGetInboundFileWriteBuf (uint8_t** buf, uint16_t *bufSize) {

static uint8_t ftBuf[CWMSGCMD_FT_MAX_SIZE];
{
    CW_REQUIRE(buf != NULL);
    CW_REQUIRE(bufSize != NULL);
    *buf = ftBuf;
    *bufSize = sizeof(ftBuf);
    CW_ENSURE(*buf != NULL);
    CW_ENSURE(*bufSize >= CWMSGCMD_FT_MAX_SIZE);
    return true;
}

bool CWPortExeFileWrite (int8_t* fileStr, uint32_t offset, uint8_t* data, uint16_t dataLen)
{
    CW_REQUIRE(fileStr != NULL);
    CW_REQUIRE(data != NULL);
    CW_REQUIRE(dataLen <= CWMSGCMD_FT_MAX_SIZE);
    if (offset == 0)
    {
        if (fpWrite != NULL) fclose(fpWrite); /* Close open files */
        CW_ASSERT((fpWrite = _fsopen(fileStr, "wb+", _SH_DENYNO)) != NULL);
    }

    CW_ASSERT(fwrite(data, 1, dataLen, fpWrite) == dataLen);

    if ((dataLen < CWMSGCMD_FT_MAX_SIZE) && (fpWrite != NULL))
      { fclose(fpWrite);}
    
    return true;
}

Writing to the OKC from an OKE System

OKE systems may write files to the OKC either by explicit request of the OKC or triggered by the OKE application logic. Regardless, the OKC is always ready to have a file written to it from the OKE. The OKE should only write one file at a time to the OKC since the CWL will not handle simultaneous writes. The OKE application logic will serialize file transmissions to the cloud when more than one file is ready to the sent to the OKC. An OKE system must be able to write a file to the OKC simultaneously with having a file written to it by the OKC.

void CWCmdStartFileWrite(int8_t* fileStr);

To start writing a file to the OKC an OKE system will call the CWCmdStartFileWrite() function. It will pass the name of the file to start writing to the cloud as a NULL terminated C string. This function should not be called again by the application code until the file write completes, otherwise the ongoing one must be aborted and a new file write will be started.

The CWL will begin the file writing process at the next available opportunity.

The CWL will call the CWPortGenFileWriteCB() function repeatedly until the entire file is written to the OKC.

The CWPortGenFileWriteCB() function must pop three variable arguments off the stack:

static int32_t CWPortFileWriteCB(MJBuffer_t* mb, va_list* ap)
{
    int8_t* fileStr = va_arg(*ap, int8_t*) ;
    int32_t offset = va_arg(*ap, int32_t) ;
    bool* areMoreFrags = va_arg(*ap, bool*);
}

fileStr is the name of the logical file that was passed in the CWCmdStartFileWrite ()call. Offset will start at zero and advance 512 bytes, CWMSGCMD_FT_MAX_SIZE, every time the function is called. areMoreFrags is a pointer to a Boolean. The function must set the value to false when the last fragment is written. The function always returns the number of new bytes written to the JSON buffer.

Implementors must simply read up to 512 bytes of data from the file starting at offset and print it to the mb buffer as a Base64 encode string. For example, if bufLen of data is read from the file into buf the implementor must call MJPrintf(mb, "%V", bufLen, buf); If the file is a multiple of 512 bytes, then the last MJPrintf() call will output an empty string "" since bufLen is zero. This is required so that the OKC knows the file write is complete.

1.1.1.9         Pseudocode Example

The following example code is from the CWL Windows port. The Windows port is setup to call CWCmdStartFileWrite() when a menu selection is made. This call sets up the CWL to repeatedly invoke CWPortFileWriteCB().

CWCmdStartFileWrite(SOURCE_FILE);

The CWPortFileWriteCB() function first pops the three variable arguments off the stack. If this is not done or done in a different order, then the system is likely to crash. Next it allocates a temporary buffer on the stack that can hold up to 512 bytes of data. Implementors, may use a global buffer or dynamic memory for the buffer instead. The code then checks to see if this is the start of the file by checking if offset is zero. If it is then any previous file is closed, and the requested file is opened. Note: Implementors must map the logical filename (fileStr) to an actual system filename or reference. The code then reads up to 512 bytes of data from the file. Since the CWL will only request sequential data, the offset is not used for the fread() since the byte offset of the read is tracked by the file pointer. If less than 512 bytes are read, then the Boolean pointed to by areMoreFrags must be set false. The return statement causes the data in buf to be printed to the OKM as a Base64 encoded string, and the function returns the number of bytes written to the JSON buffer. If any unexpected error occurs the function should set areMoreFrags false. This will cause the CWL to stop calling the function.

int32_t CWPortFileWriteCB(MJBuffer_t* mb, va_list* ap) 
{
    int8_t* fileStr = va_arg(*ap, int8_t*) ;
    int32_t offset = va_arg(*ap, int32_t) ;
    bool* areMoreFrags = va_arg(*ap, bool*);
    uint8_t buf[CWMSGCMD_FT_MAX_SIZE];
    uint32_t bufLen;

    if (offset == 0)
    {
        if (fp != NULL) fclose(fp); /* Close file if already open */
        fp = _fsopen(fileStr, "ab+", _SH_DENYNO); /* Open file */
        if (fp == NULL) 
        {
            *areMoreFrags = false;
            return 0;
        }
    }

    bufLen = fread(buf, 1, sizeof(buf), fp);
    if (bufLen < CWMSGCMD_FT_MAX_SIZE)
    {
        *areMoreFrags = false;
        fclose(fp);
    }
    return MJPrintf(mb, "%V", bufLen, buf);
}

Reading from the OKC to an OKE System

The OKE may send a request to the OKC to read a file stored on the OKC. This will cause the OKC to write the file to the OKE.

void CWCmdRequestFileRead(int8_t* fileStr);

The CWCmdRequestFileRead() function is passed the name of the file as a NULL terminated C string. The CWL will generate and send the file read request to the OKC.

Reading to the OKC from an OKE System

The OKC may send a request to an OKE system to read a file stored on the OKE. This will cause the OKE system to write the file to the OKC.

void CWPortExeFileRead(int8_t* fileStr);

The CWPortExeFileRead() function is called by the CWL when a file read request is received from the OKC. If the request is valid then the OKE system should call CWCmdStartFileWrite() to start sending the requested file to the OKC.

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.