Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Tutorial on the Examples

From Texas Instruments Wiki
Jump to: navigation, search

This tutorial will walk you through the various CC2530 Zigbee Network Processor (ZNP) examples. This tutorial assumes that you are familiar with programming in C and have all the hardware needed. For questions on the examples, please use the TI E2E forums

The examples (available [here] are written for IAR Embedded Workbench but will likely work with other compilers with a minimum of change. Use of intrinsics has been kept to a minimum.

The CC2530ZNP is the successor to the CC2480 and shares most of the same API. Whereas the CC2480 was a CC2430 preloaded with the network processor firmware, the CC2530ZNP is a firmware image that you can download onto any CC2530. The CC2530 processor on the CC2530ZNP target boards that come with the kit are preloaded with the ZNP firmware but you can also install the ZNP firmware on any CC2530. See Changing the CC2530ZNP Firmware

Introduction

The examples provided are designed to be small, easy to use building blocks of code which can be easily incorporated into your application. The examples in this document are written for ease of use first, performance second. There is most likely a faster way to do everything, but we wanted to ensure that the examples are easy to understand. That being said, please let us know if there are improvements we can make.

The examples are grouped into four main categories, organized for simple to complex:

It is recommended that you familiarize yourself with the examples in order. In other words, don't jump into the Simple Applications until you have a reasonable amount of confidence with the previous examples.

File Structure

The files follow the following file structure:

  • HAL - Hardware Access Layer, containing a file for basic interfacing to the hardware. You will want to modify the file in here when changing hardware. For more information see Changing ZNP Hardware
  • ZNP - The ZNP libraries, can be reused in multiple projects
  • ZNP Examples - The actual examples
    • IAR - contains all the IAR workspace and project files
  • Common - basic utilities reused throughout the projects

When using the ZNP in your own project I recommend adding another directory at this level containing your project-specific files. For example, if your project was named "Confabulator" then the top-level directory would contain HAL, ZNP, Common, and Confabulator. This makes it easy to share the ZNP libraries across multiple projects.

You'll also notice that each IAR project has the includes defined in Project Options. These definitions ($PROJ_DIR$/something etc) are there to make the examples portable since IAR by default uses absolute paths. Otherwise when you opened the examples you would get an error if your file structure did not exactly match mine.

Tips to make your Zigbee development easier

  • If you've created a new project and it builds & downloads fine but looks like nothing is happening, check the project options to be sure it's not running in the simulator.
  • When in doubt, go back to the basics: run hello_world example and reset_radio example to verify that the basics are working.
  • Occasionally in any compiler you might get random build errors, especially after switching between projects. Do a clean and then rebuild all.
  • It goes without saying, but use a version control system! There are many good ones out there including Subversion, Git, even the venerable CVS. There are also many hosted solutions, some less than $5 per month. These examples were developed using Subversion. A good Subversion client for Windows is TortoiseSVN (free); a good Subversion client for Mac is Cornerstone (not free).
  • Use multiple monitors. During development I have quite a few windows open, including the IDE for compiler, Version Control System client, multiple terminal windows (one for each device), TI Packet Sniffer, Interface Specification, and of course this great tutorial.
  • If you are planning on porting the ZNP libraries or examples to other hardware platforms, you'll need access to a logic analyzer and oscilloscope. We've created some utilities to make this easier. See hal_helper.c in the HAL directory for more information.
  • Buy the following:
  • Look at the example logic analyzer traces for configuring which pin connects to which signal. When debugging basic communications between two devices it is handy to monitor the radio signals (CS, MOSI, SOMI, SCLK if using SPI; Tx, Rx, RTS, CTS if using UART) on both devices. That way you can see if the other device received the message.
  • If using UART, don't neglect RTS.
  • If you are programming the flash on a CC2530 that is also connected to a microcontroller, be sure to run an application that sets the radio reset line as an Input on the microcontroller to prevent conflict with the external programming adapter. There's a function that does this in the HAL file entitled setZnpInterfaceToInputs().

Additional Resources

For more information about Zigbee or designing Zigbee networks, look at the following:

Physical Interfaces (SPI/UART)

The ZNP supports either SPI or UART interfaces. For very simple applications, the UART interface is easier, but the SPI interface is actually easier if you are building a robust application, since you immediately get the responses from the IC. In a UART application the state machine will need to wait between each message received from the ZNP.

Benefits of SPI Benefits of UART
Faster (~20x) Quicker response on SRSP messages
Fewer pins Simpler hardware/firmware interface

Using the UART interface

The most common problem encountered with getting the UART interface working is with the flow control pins. Be sure that you configure all the pins correctly. Select the UART functionality on your microcontroller for the Tx/Rx signals and verify that the pin labeled "Tx" on the microcontroller is connected to the pin labeled "Rx" on the radio, and vice versa.You will need to configure the MSP430 signal for RTS (Ready to Send). The signal RTS is an OUTPUT from the ZNP and is asserted logic high when the ZNP is busy. This will typically be asserted on longer messages. This signal needs to be connected to an input pin on the microcontroller and the microcontroller MUST pause transmitting when this signal is asserted. In our sendMessage() method, we simply check RTS prior to sending each byte, if RTS is asserted (logic high) then we just wait. For example:

//send message out to the radio
for (char i = 0; i<bufIndex; i++)
{
   while (P1IN & BIT1) ;   			//P1.1 is RTS - if HIGH then do not send, just wait!
   while (!(UC1IFG&UCA1TXIFG));                 // USCI_A1 TX buffer ready?
   UCA1TXBUF = c;                     		// TX  character
}

If using a Stellaris processor then you need to be a little careful, since these have a FIFO queue on the UART. Stopping sending bytes into the queue won't work; you need to stop the flow out of the queue. See Using the ZNP with Stellaris. For example:

if (GPIOPinRead(GPIO_PORTD_BASE, RADIO_RTS))  			       //if RTS is high (asserted)
{
   HWREG(UART1_BASE + UART_O_CTL) &= ~UART_CTL_TXE;  	//	...turn off UART TX
} else {  							       //if RTS is low
   HWREG(UART1_BASE + UART_O_CTL) |= UART_CTL_TXE;  	//	...turn UART TX back on
}

Danger: If RTS is not configured correctly then some of the messages will work but the longer commands will not; the CC2530ZNP will just ignore them and behave erratically. CTS (Clear to Send) is an optional input to the ZNP to instruct it to pause transmitting. Use this if your application cannot receive a message or has a full buffer. It is optional and most applications don't use it. Please note: the UART interface is not supported on the CC2530 battery board.

Using the SPI interface

To reduce hardware signals you can connect MRDY to Chip Select. The MRDY signal was necessary on the CC2430 based hardware but is no longer required. CS is active LOW. Check the Clock Polarity and Phase with the examples if you're using a different microcontroller than the MSP430. SRDY has multiple functionality depending on whether you're waiting for data or whether the radio has data pending. See the examples. Using SPI has a few little tricks, like the write-to-read functionality as well as the timing. Follow the examples and when in doubt, refer to the logic analyzer traces.

MRDY must be asserted when communicating with the ZNP. If CS is connected to MRDY then you must leave it asserted between sending a SREQ and receiving a SRSP. If CS is controlled independently from MRDY then you must leave MRDY asserted between sending a SREQ and receiving a SRSP but you can de-assert CS inbetween. This is useful when you have multiple peripherals on the SPI bus and you don't want to tie up the bus waiting on the ZNP.

If you are seeing RESET_IND correctly but no other commands, check MRDY.

IAR Project Configuration

The examples are all configured as IAR projects, with each group of examples in its own workspace. To see all the examples in a particular workspace, open IAR and then navigate to File:Open:Workspace... and select the workspace you want to open. In the Workspace pane (usually far left side) click on the Overview tab at the bottom of the pane. This will list all the examples in this group.

The files are organized into folders corresponding to their location in the file structure, e.g:

  • HAL - this contains all the Hardware Abstraction Library files that interface with the hardware.
  • ZNP - the Zigbee Network Processor interface files
  • Common - this contains miscellaneous utilities

Other files (not in directories) will be located in the ZNP Examples directory. IAR automatically creates an additional directory, Output, that contains any debug files or list files.

The project configurations are all fairly simple to ease the transition to other platforms. Changes to the default project configuration are the following (under project options dialog - Project : Options)

  • General Options : Target - change Device to MSP430F2274.
  • Debugger : Setup - change Driver to Automatic. Note: change this to your USB dongle - should be something like "HID0003" or so.
  • Optional: Linker : List - check "Generate Linker Listing", Under File Format, check "HTML", and check "Module summary".
  • Optional: C/C++ Compiler : Preprocessor : Under "Additional include directories" the relative paths for all files are added. Otherwise IAR will display a warning if the project directory changes, since IAR by default uses absolute paths in its project configuration.

The project uses a few compiler intrinsic functions. These will need to be changed if using a different compiler. It is recommended to surround each with #ifdef __IAR_SYSTEMS_ICC__ if using IAR, or the corresponding function to allow the compiler to automatically select which intrinsic to use during compilation.

  • hal_cc2530znp_target_board.c
* __interrupt for defining interrupt service routines.
  • hal_cc2530znp_target_board.h
* __bis_SR_register() for setting bits in the MSP430 Status Register. Only used for End-Device low power mode.
* __bic_SR_register_on_exit() for clearing bits in the MSP430 Status Register upon function return. Only used for End-Device low power mode.
* _EINT() for enabling interrupts
* _DINT() for disabling interrupts

Troubleshooting

The following are a few helpful hints if you run into trouble using the examples.

Incorrect Device Set

If you see the following error when building in IAR:

Building configuration: Secure Comms - Coordinator - AFZDO - MDB1
Updating build tree...

...omitting other stuff...

Linking
Error[e16]: Segment INTVEC (size: 0x30 align: 0x1) is too long for segment definition. At least 0x10 more bytes needed. The problem
occurred while processing the segment placement command "-Z(CODE)INTVEC=FFE0-FFFF", where at the moment of placement the
available memory ranges were "CODE:ffe0-ffff"
   Reserved ranges relevant to this placement:
   ffe0-ffff            INTVEC
Error while running Linker

Then you most likely have the processor set incorrectly. Project : Options : General Options : Device.

Function Declared Implicitly

Warning[Pe223]: function "bitBangOutput" declared implicitly \\.psf\Home\Documents\svn\hardware\fw\HAL\hal_mdb1.c 184

Then you need to add the file containing that function to the path somewhere. In other words, #include that file. In this case we would add the following line of code to hal_mdb.c:

#include "../Common/bit_bang_uart.h"

ZNP Hangs

Occasionally when playing with the ZNP you may see it hang whereby it won't respond to a reset:

Basic Communications Example - ROUTER - using AFZDO
Initializing the ZNP

In this case, power cycle the board with the ZNP and it will work fine.

Too Much Code

The free version of IAR for MSP430 is limited to 4kB of code. If you get this error:

"Fatal Error[e89]: Too much object code produced (more than 0x1000 bytes) for this package "

This means that you have exceeded the 4kB limit. The size of the CODE + CONST must be less than 4kB. You can check the size by looking at the bottom of the Linker Listing (HTML file generated by the compiler, located in the Output directory). You can either trim down your application, port your application to Code Composer (which has a 16kB limit for the free version), buy a full license of IAR, or try the 30 day evaluation edition of IAR. If changing IAR version, remember to clean your project before rebuilding.

CC Debugger Can't Connect to Target

If you have connected the CC Debugger to the Target and pressed Reset but the light on the CC Debugger is still red, then this means that the CC Debugger is unable to connect to the CC2530. If there is an application running on the MSP430 then there will be a bus conflict between the MSP430 and the Debugger. You need to tri-state the MSP430 interface signals to prevent this from happening. In the HAL Utilities workspace (HAL/IAR/HAL Utilities.eww) there is a project named "Program ZNP" that will do this. Just make "Program ZNP" the active project and then debug and run it. The red LED on the CC2530ZNP Target Board will blink quickly to show that this program is running. You should now be able to connect the CC Debugger to the Target Board and when you press Reset on the Debugger the light should turn green.