Before you proceed with EZSP-UART, it's important to understand that the EZSP-UART platform has several layers to it, so let's first review how each layer fits into the puzzle, where the code for that layer can be found, and where more information about that layer can be found...
How it fits in: Your application is going to sit on top of the ZCL (ZigBee Cluster Library), which is a set of application framework code that handles each cluster (set of application/device functionality) required by that device implementation.
Where it lives: Silicon Labs currently provides the ZCL application framework for you in the app/framework folder, which includes support for all of the official ZCL clusters supported by the Zigbee profiles as well as a callback interface for you to add application-level behavior on top of this. Note that this framework is tied into AppBuilder within Simplicity Studio, such that AppBuilder can be used as a front-end to quickly configure the framework to include appropriate cluster support for whichever ZigBee device type you're implementing.
Where it's described: See Application Framework Developer's Guide (UG391) for a comprehensive description of Silicon Labs's ZCL application framework.
How it fits in: The top-level app code (including the ZCL app framework) is making calls into the EZSP driver, which is utilizing the EZSP command/response format to provide a serial abstraction of the EmberZNet stack interface (running inside the network coprocessor [NCP], such as an EFR32 chip loaded with NCP firmware).
Where it lives: The basic EZSP driver itself (that handles encoding and decoding the EZSP frames between the driver and the app framework) lives in app/util/ezsp. Note the serial-interface-spi.c and serial-interface-uart.c files in that directory, which handle interfacing down to the next lower layer.
Where it's described: See EZSP Reference Guide (UG100) for explanation of the EZSP frame format and general EZSP concepts.
How it fits in: The Asynchronous Serial Host ('ASH', is a sort of middle layer between the generic EZSP driver (which is abstracted across SPI and UART interfaces) and the low-level UART. It's there mostly as a quality-of-service [QoS] protocol to manage things like error-checking, CRC, ACK/NAK timing, flow control, et cetera, which is necessary because UART is much more error-prone (and more difficult to manage due to its asynchronous nature) than SPI. The ASH framework handles the encapsulation of EZSP frames into a more robust UART protocol and occasionally does some of its own serial transactions for QoS purposes.
Where it lives: This code is mostly contained in app/ezsp-uart-host, along with some uart-test programs that can be built to run on your host for the purposes of testing the low-level UART/ASH connectivity without involving the EZSP driver. There are also a couple of supporting files for ASH in the hal/micro/generic folder, and these files are shared between the host-side code and the NCP firmware that Ember builds for each release.
Where it's described: See UART-EZSP Gateway Protocol Reference (UG101) for description of ASH framework.
How it fits in: The ezsp-host-io.c file in the aforementioned layer is using POSIX termios library calls to interface with your host's UART. If you happen to be on a host architecture where no POSIX libraries of this sort exist (like if there's no OS), you'll have to do some hacking of the ezsp-host-io module to interface to some kind of more customized driver for your microcontroller's UART peripheral. This driver is supposed to take care of getting the actual bytes in/out of the serial queues and handling hardware flow control if applicable. If your target serial port is utilizing a USB-to-serial driver, the ASH framework doesn't know the difference; your low-level UART driver should handle that automatically.
Where it lives: The actual UART driver is generally part of your operating system, so unless you've written a custom driver, this is most likely in a kernel module or DLL or some other piece of pre-compiled code that you [hopefully] aren't responsible for.
Where it's described: While your actual UART driver is going to be system-specific and is therefore outside of Silicon Labs's realm, you can refer to the EZSP-UART Host Interfacing Guide (AN706) for information about how to tie the ASH framework into your particular low-level UART driver and unit test that piece before moving up to EZSP-level testing.
So that's the host side of things, and the NCP side is basically the reverse of all that, with the 'app framework' for the NCP just being a simple EZSP interpreter that translates EZSP frames into EmberZNet stack library calls to accomplish the necessary stack tasks.
Hopefully, this explanation helps to put things into perspective, but if you want more information, make sure to consult the HTML/PDF references discussed above, all of which are linked from the documentation/index.html page in your EmberZNet software installation.
Now that you know a bit about how the EZSP-UART platform is organized, let's discuss how you can start using it right away.
In order to use the EZSP-UART functionality on a particular node, the node must be loaded with appropriate firmware, namely the EZSP-UART Network CoProcessor (NCP) firmware. This firmware will need to be generated and built within Simplicity Studio. Your NCP applications will also require a suitable bootloader, such as a UART XMODEM or EZSP SPI bootloader. Refer to AN1010: Building a Customized NCP Application for information for building an NCP application. If you are using a WSTK and standard Silicon Labs radio board, like the BRD4161, you can use the default settings to generate you NCP, using the NCP-SPI or NCP-UART plugin, depending on your particular interface.
If you load the EZSP-UART NCP firmware onto your chip, you can then use an EZSP-UART host application (such as the executables built from the Makefiles provided in your EmberZNet release or those generated by AppBuilder when Host is set to 'UNIX UART Host') to communicate with the NCP via EZSP-UART.
Sample code for implementing the host side of the protocol (which is based on a serial library called ASH [Asynchronous Serial Host]) can be found in /app/ezsp-uart-host in the NCP-based EmberZNet stack installations.
The default baud rate of the EZSP UART NCP application is as follows:
Changing baud rate (or other NCP settings): Modify that NCP-UART plugin with the appropriate settings for your NCP.
NOTE: Please be aware that hardware flow control is strongly recommended for the use of EZSP-UART, so if your hardware doesn't implement this, then you should use the Xon/Xoff (software flow control) version of the EZSP-UART firmware, or else make sure to keep the baud rate quite low (38400 or lower) to reduce the chances of communication errors.
Additional ASH configuration tokens exist for setting other ASH parameters on the NCP. The following table lists the parameters by their manufacturing word-addressed offset in the manufacturing token space. Note that any addresses containing 0xFFFF data will cause that ASHConfig parameter to assume the default value per the protocol definition.
ASH configuration manufacturing token storage locations:
|AshConfigValue||Manufacturing word offset||CIB bytes||Description|
|baudRate||0x80||0x08040856/7||SerialBaudRate enum value (e.g: 6=9600, 8=19200, A=38400, C=57600, F=115200)|
|traceFlags||0x81||0x08040858/9||trace output control bit flags|
|txK||0x83||0x0804085C/D||max frames that can be sent w/o being ACKed (1-7)|
|randomize||0x84||0x0804085E/F||enables randomizing DATA frame payloads|
|ackTimeInit||0x85||0x08040860/1||adaptive RX'ed ACK timeout initial value|
|ackTimeMin||0x86||0x08040862/3||adaptive RX'ed ACK timeout minimum value|
|ackTimeMax||0x87||0x08040864/5||adaptive RX'ed ACK timeout maximum value|
|maxTimeouts||0x88||0x08040866/7||ACK timeouts needed to enter the ERROR state|
|rebootDelay||0x8A||0x0804086A/B||reboot delay before sending RstACK|
|nrTime||0x8E||0x08040872/3||time after which a RX'ed nFlag expires|