Error Conditions#

The error conditions encountered by the host are exactly that: errors. These errors are not meant to be encountered in a mature product and are primarily used as development and debugging aids. If the host experiences an error condition, chances are the host and the NCP are out of sync, and the code needed to recover would be exceptionally error prone. Therefore, it is reasonable for the host to treat all error conditions or timeouts in the same way as asserts, and simply reset both the host and the NCP.

There is one common exception to this rule: When the host intentionally resets the NCP (for example, as described in Powering On, Power Cycling, and Rebooting), the host must expect the NCP Reset error condition to occur on the next transaction. This error condition should be observed and discarded as expected and normal.

Note: The application must be careful not to interfere with any operation that loads firmware onto the NCP (for example, bootloading). The recommended practice is for the host to have access to and control of the NCP’s nRESET signal, and to toggle nRESET if an error condition occurs. When the NCP is being loaded with new firmware, it will not be capable of responding to the host; the host may think the NCP is unresponsive and attempt to reset it, which will disrupt the loading of new firmware. You should consider the best method to avoid resetting the NCP in this situation. Some options include:

  • Putting the application in some mode where it leaves the NCP alone.

  • Holding the host in reset, bootloader, or some other innocuous mode.

  • Disabling the host’s access to the nRESET line on the NCP.

  • Physically disconnecting nRESET.

If two or more different error conditions occur back to back, only the first error condition will be reported to the Host (if it is possible to report the error). The following are error conditions that might occur with the NCP.

Unsupported SPI Command: If the SPI Byte of the command is unsupported, the NCP will drop the incoming command and respond with the Unsupported SPI Command Error Response. This error means the SPI Byte is unsupported by the NCP’s current Mode. Bootloader Frames can only be used with the bootloader, and EZSP Frames can only be used with the EZSP.

Oversized Payload Frame: If the transaction includes a Payload Frame, the Length Byte cannot be a value greater than 133. If the NCP detects a length byte greater than 133, it will drop the incoming Command and abort the entire transaction. The NCP will then assert nHOST_INT after Slave Select returns to Idle to inform the Host through an error code in the Response section what has happened. The NCP not only drops the Command in the problematic transaction, but the next Command is also dropped because it is responded to with the Oversized Payload Frame Error Response.

Aborted Transaction: An aborted transaction is any transaction where Slave Select returns to Idle prematurely and the SPI Protocol dropped the transaction. The most common reason for Slave Select returning to Idle prematurely is the Host unexpectedly resetting. If a transaction is aborted, the NCP will assert nHOST_INT to inform the Host through an error code in the Response section what has happened. When a transaction is aborted, the NCP not only drops the Command in the problematic transaction, but the next Command also gets dropped because it is responded to with the Aborted Transaction Error Response.

Missing Frame Terminator: Every Command and Response must be terminated with the Frame Terminator byte. The NCP will drop any Command that is missing the Frame Terminator. The NCP will then immediately provide the Missing Frame Terminator Error Response.

Long Transaction: A Long Transaction error occurs when the Host clocks too many bytes. As long as the inter-command spacing requirement is met, this error condition should not cause a problem because the NCP will send only 0xFF outside of the Response section and ignore incoming bytes outside of the Command section.

Unresponsive: Unresponsive can mean the NCP is not powered, not fully booted yet, incorrectly connected to the Host, or busy performing other tasks. The Host must wait the maximum length of the Wait section before it can consider the NCP unresponsive to the Command section. This maximum length is 350 ms, measured from the end of the last byte sent in the Command section. If the NCP ever fails to respond during the Wait section, it is valid for the Host to consider the NCP unresponsive and to reset the NCP. Additionally, if nHOST_INT does not assert within 300 ms of nWAKE asserting during the wake handshake, the Host can consider the NCP unresponsive and reset the NCP.

Error Bytes#

As described in section SPI Bytes, five SPI Bytes indicate error conditions. When implementing the code to receive a Response from the NCP, the host must be capable of parsing the SPI Byte as soon as possible for any of these error conditions. The host must continue to receive the entire error before deasserting Slave Select and processing the error. With the exception of an intentional NCP Reset error condition, the host should report, through a printf or other simple method, these four errors to the developer for debugging purposes, but should ultimately result in an assert or similar reset mechanism.

Timeouts#

The host can experience only two timeouts: Wait Section and Wake Handshake. Just like the Error Bytes, if either of these timeouts occurs, the application should report them to the developer for debugging purposes, but should ultimately result in an assert or similar reset mechanism.

The timeouts are best measured using a timer, but if necessary, the host can simply burn a known amount of CPU cycles while waiting for either normal operation to resume or the limit of allowable CPU cycles. For the Wait Section Timeout, the time is measured from the end of the last byte transmitted in the Command to the start of the first byte received that is not 0xFF. For the Wake Handshake Timeout, the time is measured from the falling edge of nWAKE to the falling edge of nHOST_INT.