Page Comparison

...

...

Reset

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

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 */
}

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

Reset

void CWPortExeReset(void);

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

Flush

void CWPortExeFlush(void);

Versions

bool CWPortGetVersion(uint8_t index, int8_t **typeStr, int8_t **fwverStr, int8_t **hwrevStr) ;

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

Heartbeats

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

{"_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}}}

File Transfer

Sections:

1. CWM Buffering

2. OKE Inbound File Transfer Throttling

3. Aborting an OKE Inbound File Transfer

4. Transferring Large Files

5. Faster Baud Rate Negotiation

6. Fastest Interface

7. File Transfer Throughput

8. File Transfer Status

9. File Status

10. Firmware

11. Writing from the OKC to an OKE System

12. Throttling File Fragments

13. Pseudocode Example

14. Common Problems

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.

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

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

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

5. 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?

2. 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.

2. 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.

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

File Transfer Status

When the OKC is writing a file, an OKE system will report on the status of the write operation. This allows the OKC to determine if the file transfer is ongoing, stalled, or completed. If the file transfer appears stalled, for example only half the file was downloaded due to a network connectivity problem. Then the OKC can restart the file transfer from where it left off without starting from the beginning. This can be very helpful when attempting to transfer large files in challenging network conditions. The CWL automatically sends File Transfer Status updates to the OKC.

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.

2. 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;

}

Common Problems

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

Flush

void CWPortExeFlush(void);

Versions

bool CWPortGetVersion(uint8_t index, int8_t **typeStr, int8_t **fwverStr, int8_t **hwrevStr) ;

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

...

Heartbeats

File Transfer