ZBOSS v1.0
ZBOSS v1.0 release notes. Learn more about ZBOSS v1.0 and technical information.
ZBOSS v1.0 Documentation
As the first open-source Zigbee® protocol stack certified by the Zigbee® Alliance, ZBOSS v1.0 is the key to solving interoperability problems for the global manufacturing and research communities.
Compliance and Interoperability
Licensing
DSR Corporation offers the ZBOSS v1.0 open source Zigbee® protocol stack under a “dual licensing” model as follows:
ZBOSS™ v1.0 is the first open-source Zigbee® protocol stack certified by the Zigbee® Alliance.
IDSmart Zigbee® stack (name used for the ZBOSS stack during ZCP certification) running on UBEC's transceivers is certified as Zigbee® Compliant Platform.
DSR Corporation is open to collaboration in Zigbee® technologies development. Nowadays Zigbee® is growing faster – the standard is modified to improve flexibility, new profiles are added, existing ones are adopted to comply with, and market demands and provides better interoperability. Having an open source Zigbee® stack solution is the first step in getting familiar with Zigbee® technology and providing a way to share information within the community of Zigbee® adopters.
Technical Info
For a better understanding of the ZBOSS v1.0 stack's design, please refer to Architecture Key Moments document.
For the full feature list, please refer to the certification PICS document. This document describes which capabilities and options must be implemented to comply with the Zigbee® standard.
Hardware Setup
The ZBOSS v1.0 stack currently supports two Zigbee® chipsets: the Texas Instruments’ TI CC253x and UBEC’s UBEC 2400, UBEC 2410.
To utilize ZBOSS v1.0 with these chipsets, simply download the ZBOSS stack and tools, load it up on your TI or UBEC-silicon based development boards, and begin your development efforts.
The complete ZBOSS v1.0 package for TI SoC CC253x is available here: ZBOSS v1.0 for TI SoC CC253x
To build Zigbee® based applications for the listed platforms follow the instructions specified in the following guide: Build Instructions.
To simplify the first attempt, please use the ready-to-execute packages for TI SoC CC253x
To use TI hardware, please contact TI and order the appropriate development kit.
DSR Corporation can assist in your company’s Zigbee® product development efforts with:
To inquire about additional services and details, please send an email to contact@dsr-corporation.com.
This version of ZBOSS v1.0 is an important release for both stack development and customers as well. The new release contains many significant changes, including new platforms support, IAR compiler support, completely refactored MAC layer, and many other improvements and changes.
TI CC253x – added support for a Texas Instruments SoC. The stack is tested with CC2530, but it could be running on other chips of TI cc253x family with minor tweaks. In addition, usage of hardware AES encryption/decryption was added to maximize stack performance.
IAR EW8051 – added support for IAR compiler. Compiling using IAR can help save up to 30% of code memory due to very efficient optimization routines provided by IAR for 8051 core. However, Keil can still be used in addition to GCC for Network Simulator.
Mac layer of ZBOSS v1.0 got streamlined with added flexibility for further porting. In addition, this change improves the overall performance, code size, and stability. Initially designed state machine is completely removed and replaced by a callback-driven mechanism.
Many of less significant changes were made during refactoring, porting and adding an IAR support.
New version of manual acknowledgments and retransmission were added. It can be used with Network Simulator, TI SoC's, and any other chips that do not support autoacks.
Transmitting collision detecting has been slightly improved.
Some global code refactoring was performed to reduce code size and RAM usage.
Minor changes for reducing call nesting were also added.
ZBOSS v1.0 Build Instructions
This section describes ZBOSS v1.0 build process.
Summary of features
This section describes the following:
API reference and SW modules internal documentation is generated automatically in Linux using Doxygen utility.
Before building ensure that Doxygen is installed, and then run
cd stack
make docs
Results are in doxydoc_api/ and doxydoc_int/ directories, in html format.
Most stack features are configured at compile time using C preprocessor (conditional compilation).
Configuration parameters are numbers, such as timeout constants and table sizes, and conditions that switch on or off some source code parts.
All configuration parameters are located in zb_config.h. Some configuration parameters are combined into groups. There are the following main groups:
See stack/include/zb_config.h for details.
To switch some branch on/off in zb_config.h, specific macro definitions must be defined in the compiler's command line. These definitions are put into build system files.
Compile-time definitionsCompile-time definitions are more actual for Keil build than for a Linux build: they are changed more often. By convention, instead of removing a definition, add 'x' letter to its beginning.
DEBUG – some additional run-time checks. Do not use it for 8051
ZB_PLATFORM_8051_SIM - must be always defined for 8051
KEIL - must be always defined for 8051
C8051F120 – must be defined for UZ2400, must be undefined for UZ2410
ZB_UZ2410 – must be defined for UZ2410, must be undefined for UZ2400
ZB_UZ2410_256 – must be defined for UZ2410 with 256k ROM, must be undefined for UZ2410 with 64k ROM
ZB_TRACE_LEVEL=2 – must be defined to switch on trace, must be undefined to exclude trace
ZB_NS_BUILD – must defined for simulator build without adapter, must be undefined for HW build
ZB_DBG_NO_IDLE – do not go sleep when idle. Must be defined for UZ2410, do not care for UZ2400
ZB_TRAFFIC_DUMP_ON – define it to enable internal traffic dump, undefine to disable traffic dump
ZB_TEXT_ONLY_TRACE – if defined, use text-only trace, no traffic dump or win_
com_dump utility usage possible. Depreciated.
ZB_ED_ROLE – define it to build ZED, undefine to build ZR or ZC
ZB_SECURITY – define it to include security feature. Usually defined.
ZB_USE_NVRAM – define it to read some parameters from NVRAM. Usually undefined.
ZB_NVRAM_WRITE_CFG – define it to write into NVRAM. Usually undefined.
Example of definition set for UZ2410/256 build for ZC/ZR, with traffic dump and security, without debug trace:
xDEBUG ZB_PLATFORM_8051_SIM KEIL xC8051F120 ZB_UZ2410 ZB_UZ2410_256 xZB_TRACE_LEVEL=2 xZB_NS_BUILD ZB_DBG_NO_IDLE
ZB_TRAFFIC_DUMP_ON xZB_TEXT_ONLY_TRACE xZB_ED_ROLE ZB_SECURITY xZB_USE_NVRAM xZB_NVRAM_WRITE_CFG
Also, need additional configuration to switch between UZ2400 and UZ2410 builds in Keil.
For UZ2410/256:
For UZ2410/64:
For UZ2400:
See also file zb_config.h
ln -s build-configurations/Platform-linux Platform
ln -s build-configurations/Options-linux-debug Options
make rebuild
make tags
ln -s build-configurations/Platform-8051 Platform
ln -s build-configurations/Options-8051-sim-debug Options
make rebuild
make tags
Detailed explanations
Build scripts in Linux uses the 'make' utility.
The files used by the build subsystem include:
Before compiling the build subsystem must be configured by creating symbolic links for Options-xxx-xxx-xxx and Platform-xxx into the stack directory as follows:
ln -s build-configurations/Platform-linux Platform
ln -s build-configurations/Options-linux-debug Options
The idea here is that leaf makefiles first set its place related to the sources root using assignment like BUILD_HOME=.., and then includes Options file using string include $(BUILD_HOME)/Options.
Now all definitions from Options file are available for the leaf makefiles and all that is needed is to define a list of targets. As a result, leaf makefiles are very simple, usually containing only files lists and frequently can be used in environments other than Linux/PC.
Here is an example of the leaf makefile:
BUILD_HOME=..
include $(BUILD_HOME)/Options
SRCS = secur_ccm.c apsme_secur.c zdo_secur.c nwk_secur.c aps_secur.c
all: $(SECUR_LIB) $(SECUR_LIB_ED)
$(SECUR_LIB) : $(OBJS)
$(MAKE_LIB)
$(SECUR_LIB_ED) : $(OBJS_ED)
$(MAKE_LIB)
In this example there is only one file list and one target list. Note that XXX_ED (SECUR_LIB_ED, OBJS_ED) are used for ZED build and will be described later.
Sometimes leaf makefiles must be different for different platforms: for example, some OS-specific files must be compiled for Linux/ARM and do not have to be compiled for Linux/PC. To resolve this issue every leaf directory does not include a Makefile, but instead has mk/{platform}/Makefile. When 'make rebuild' is issued from the root directory, the build script creates a link to the proper Makefile.
If mk/{platform} directory does not exist (meaning, no special logic is necessary for this platform), the build script links mk/unix/Makefile generic file.
stack/Options file contains all definitions including C compiler options, command line used to translate .c to .o, libraries list, command-line to link executable files from the dependencies list, etc.
When Options files are functionally similar (for example, for debug and release builds for Linux), one file is used as a base while another includes it and redefines a few variables.
Build scripts automatically create dependencies file – it is a global stack/deps file.
Another problem stack/dups file causes is a necessity to include it in the Options file.
Root Makefile can't include Options file because at the time of the first build the stack/depth file does not exist and the make utility will fail.
The solution is to use the Platform file, which is included by every file (directly by root Makefile and indirectly from others – via Options file). That file contains the definition of the PLATFORM variable, so the root Makefile can correctly set up links at the leaf directories.
Root Makefile does common actions, such as links setup or cleanup, and runs make on its subdirectories.
One more problem which Linux build system also resolves is the existence of two stack builds: full, for ZC/ZR, and limited, for ZED. Both builds are necessary at the same time for testing ZC – ZE work.
This is the reason why the two versions of libraries are compiled with different definitions. The root makefiles have simple declaration of which library needs to be used
Here is an example of leaf makefile for both ed and zc:
BUILD_HOME=../../..
include $(BUILD_HOME)/Options
SRCS1 = tp_pro_bv_27_gZC.c
OBJS1 = ${SRCS1:.c=.o}
SRCS2 = tp_pro_bv_27_DUTZED1.c
OBJS2 = ${SRCS2:.c=.ed.o}
SRCS3 = tp_pro_bv_27_DUTZED2.c
OBJS3 = ${SRCS3:.c=.ed.o}
$(BIN)tp_pro_bv_27_gZC$(EXE) : $(OBJS1) $(LIBS)
$(LINK_BINARY)
$(BIN)tp_pro_bv_27_DUTZED1$(EXE) : $(OBJS2) $(LIBS_ED)
$(LINK_BINARY_ED)
$(BIN)tp_pro_bv_27_DUTZED2$(EXE) : $(OBJS3) $(LIBS_ED)
$(LINK_BINARY_ED)
BINS = $(BIN)tp_pro_bv_27_gZC$(EXE) $(BIN)tp_pro_bv_27_DUTZED1$(EXE) $(BIN)tp_pro_bv_27_DUTZED2$(EXE)
all: $(BINS)
The function of Makefiles in intermediate, non-leaf folders, such as stack/tests/, is to call the make procedure for every directory listed in it.
cd stack
ln -s build-configurations/Platform-linux Platform
ln -s build-configurations/Options-linux-debug Options
make rebuild
cd stack
ln -s build-configurations/Platform-linux Platform
ln -s build-configurations/Options-linux-release Options
make rebuild
This build uses gcc compiler.
Compile for Linux ARM
Compilation runs on the development host PC running Linux. The main difference with a PC build is a usage of another compiler name, such as /opt/toolchain/arm-none-linux-gnueabi/bin/arm-none-linux-gnueabi-gcc. Build scripts are nearly the same for Linux and PC.
To run the stack on Linux/ARM platform, build the stack itself and compile Linux kernel with two additional drivers.
Currently, only Debug build is available.
Stack buildEdit build-configurations/Options-linux-arm-debug to setup path to the Linux kernel include dir: change LINUX_HDRS (by default it set to be LINUX_HDRS=/home/zheka/zbarm/linux-2.6.31/include).
cd stack
ln -s build-configurations/Platform-linux-arm Platform
ln -s build-configurations/Options-linux-arm-debug Options
make rebuild
Configure Linux kernel:
make ARCH=arm menuconfig
Build Linux kernel:
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi-
The following utilities are compiled during the build process for Linux/PC:
No special care is necessary to build it – just build Linux/PC build.
devtools/win_com_dump/trace_cvt utility was used only once, during trace macros conversion, so no build scripts for it. It can be compiled in Linux by typing
gcc -o trace_cvt trace_cvt.c
devtools/win_com_dump/win_com_dump utility is a decoder of trace and traffic dump received from the hardware. It is compiled in Windows OS using MSVC with the following commands:
cd stack/devtools/win_com_dump
nmake
A host for development is Linux PC.
The compiler used is sdcc.
The build scripts used for compiling for 8051 are similar to the Linux build scripts. The main difference is that the names of intermediate files: sdcc create a number of files. One of the problem that is not yet resolved, is that sdcc debugger does not work if the binary is linked from libraries.
Instructions:
ln -s build-configurations/Platform-8051 Platform
ln -s build-configurations/Options-8051-sim-debug Options
make rebuild
Compile for 8051 using Keil
ZBOSS build procedure uses Keil’s build system
Quick instruction for buildif necessary, edit preprocessor definitions for zigbee/ folder. Definitions to change are:
ZB_NS_BUILD – if defined, this is NS simulator build, else hardware build
ZB_TRACE_LEVEL=4 – if defined, trace is on, level defines trace details level
DEBUG – if defined, run-time assertions are on
ZB_SECURITY – if defined, security is compiled, else excluded
ZB_ED_ROLE – if defined, code compiles for ZED, else for ZC/ZR
To switch preprocessor definition off, add x before it, so definitions are still visible in the Keil dialog and it is easy to switch it on.
Test name is always zig_test.
Keil build results are placed in stack/build and the build log is stored in stack/build/zig_test.m51.
Build and test run procedure for two UZ2400 devices Requirements:
1. Connect all devices described above, except one usb debugger (will be explained later).
2. Start uVision4, and load tests source code.
3. You need to prepare two firmware files (for coordinator and router)
4. For coordinator:
4.1 Select zdo_start_zc from project tree.
4.2 Mark it to be built in the project.
4.3 Make sure, that no other tests are selected (there's main function in nwk_formation, nwk_discovery, mac_test, zdo_start_zc, zdo_start_zr, zdo_start_zr, pcon_test, crypto_test)
4.4 Build project.
4.5 Go to the project options->debug. Then, set up Silicon Labs Debugger, press settings and remember which device name is specified in the adapter selection menu.
4.6 Flash device, by pressing flash->download.
5. Second device can be Router or End device.
For router:
5.1 Select zdo_start_zr from project tree.
5.2 Same as for coordinator.
5.3 Same as for coordinator.
5.4 Same as for coordinator.
5.5 Same, but select a device that is different from the one you remembered.
5.6 Same as for coordinator.
For end device:
5.1 Select zdo_start_ze from project tree.
5.2-5.3 Are the same as for coordinator or router.
5.4 Go to the Project->Options for zigbee - Target "Zigbee", then select C51 tab and append a define ZB_ED_ROLE (but do not forget to undefine it before building coordinator or router tests).
5.4.1 Build project.
5.5 Same as for coordinator, but select a device that is different from the one you remembered.
5.6 Same as for coordinator.
6. You have two flashed devices. Now, you can, if needed, set up serial and 802.15 sniffer.
7. Start ZC, and wait several seconds, while it performs Energy and Active scans. If you have any sniffer, you can see the beacon request.
8. Now start router (or end device), it will send another beacon request and join to our network and send test data packet.
Keil build internals
Build files for Keil are stored in the stack/ directory. They are: zigbee.uvmpw, zigbee.uvopt, zigbee.uvproj, zigbee.lin, rfd_zigbee.lin files.
Initially we designed Keil workspace as a project that generates a library and a project for a test that uses that library.
The problem is that Keil puts all library files into the same code bank while we need to put near all the stack code into library and only some of the routine-specific top of the test program into the main source file.
So, the tests must be included into the project that contains other files.
However, it is still needed to compile more than one test.
One of the only ways to resolve this problem: create folders in the project (one folder per subsystem) that are always compiled. Also, create individual subfolder per test, with main().
Only one test can be compiled. All other tests compilation must be switched off in the Options dialog: uncheck "Include in Target Build".
File zigbee.lin and its alternatives rfd_zigbee.lin and ffd_zigbee.lin are linker definitions for Keil. There are two main things:
To debug NS stack build, tune Keil to direct some UART to the COM port. debug_1.ini and debug_2.ini files used for it.