Development of a General Purpose XBee Series-2 APIMode Communication Library for LabVIEWMichael Schell1 Mustafa G. Guvench2 Abstract – The design project detailed in this paper focuses on the development of a modular toolset for working with the XBee RF module from within the LabVIEW programming environment. The lack of generic LabVIEW libraries for working with the popular XBee series-2 RF radio module makes wireless network software development using this technology cumbersome and time-consuming. The outcome of this project is an efficient, easy-to-use general purpose XBee communication library that allows LabVIEW developers to incorporate the feature-rich API-mode operation of XBee RF modules into any network project with only a minimal amount of code overhead. Keywords: XBee, LabVIEW, API, Wireless, VISA INTRODUCTION At present, LabVIEW[1] provides no general purpose library of tools for working with one of the most popular commercially available hardware solutions for building small-scale, low-power wireless networks – Digi International’s XBee series-2 RF radio module[2]. This discovery was made by the author while working to redesign wireless network hardware for a LabVIEW-based MEMS accelerometer test system developed by Dr. Mustafa Guvench and his students at the University of Southern Maine[3]. One goal of this system redesign was replacement of the existing wireless-USB network hardware with low-cost XBee Series 2B RF modules. A search of the available LabVIEW XBee resources on the National Instruments Developer Zone website[4] (using “XBee” and “API” search terms) returned only a handful of Virtual Instruments (VIs) created for working with XBee RF modules. All of the available VIs were either too application specific to make code reuse feasible, and/or designed to work only with the feature-limited XBee AT-mode. The creation of control and measurement software designed to work with hardware-specific wireless networks is a task well-suited to the hardware-oriented development environment of National Instrument’s (NI) LabVIEW programming suite. Thus, failure to find suitable libraries for this test system redesign prompted the author to develop a library of LabVIEW VIs to facilitate working with XBee RF modules. Although the development of these VIs was undertaken with a specific project application in mind, the intent from the outset was to design for maximum code reuse and generality. This paper outlines the design and development of this library. TECHNOLOGY OVERVIEW The following sections provide a brief background of the relevant aspects of Digi International’s XBee wireless RF module technology and National Instrument’s LabVIEW development suite. XBee API Mode Operation [5] Every XBee Series-2 radio module can operate in one of two interfacing modes – AT mode or API mode. These modes determine how the XBee RF module communicates with local hardware through the on-board UART. AT mode (also called transparent mode) is a feature-limited mode that simplifies the interface between the XBee radio and the hardware device at the expense of some local level control. In this mode, the XBee UART transmits and receives all traffic as a simple serial byte stream. Escape characters can be used to issue basic commands, but support for additional functionality such as multiple-radio addressing, I/O-pin sampling and remote configuration is 1 University of Southern Maine, Gorham, Maine 04038,
[email protected] 2 University of Southern Maine, Gorham, Maine 04038,
[email protected] 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28, 2012 Each XBee API frame follows a basic format and contains. serial. managing all radio nodes and network traffic. The rapid application development nature of the LabVIEW IDE was another significant factor. I/Opin sample frames. These VIs are designed to run in parallel. local & remote command request frames. To enable these features an XBee module must be operating in API mode. the XBee Connection Manager VI. Among the tools available in LabVIEW for working with hardware devices is the Virtual Instrument Software Architecture (VISA) library. The NI-VISA standard facilitates communication with a large variety of hardware devices through high-level abstraction. This radio is typically connected to a PC via a serial or USB port. GPIB. 2012 . where various interface elements are positioned on a front panel and then connected to functional blocks on the programming diagram. a frame size. etc. This hardware interface flexibility was a motivating factor in the selection of the LabVIEW design environment for this project. A graphical-user-interface for each application can be created using a WYSIWYG editor. Every XBee network must contain one radio designated as a coordinator. The LabVIEW environment provides developers with a data-flow oriented graphical programming language designed specifically for hardware control and measurement applications. Since the XBee RF module’s UART can be connected to the PC via a variety of hardware interfaces. Two VI’s. DEVELOPMENT OF THE XBEE COMMUNICATION LIBRARY The XBee Communication Library developed in this project is comprised of a set of 22 Virtual Instruments. a 1-byte checksum and the frame payload (data). a start delimiter. both with one another and with the top-level user application. This basic frame format is shown in Figure 1. the block diagram code and the front panel GUI form a Virtual Instrument – the code unit in LabVIEW (similar to a function in traditional languages like C). Applications are built using a diagrammatic approach. all data and commands transmitted and received through the XBee UART are packaged as API frames. In API mode. A final VI. National Instrument’s LabVIEW software suite is a popular choice for developers. Because API mode enables full control and configuration of the wireless network from a single XBee module. This standard presents application developers with a common hardware programming interface regardless of the underlying hardware interface (USB. with functional blocks interconnected by software “wires”. The LabVIEW VISA Standard[6] When working with PC-connected hardware. general purpose LabVIEW XBee communication library obvious. This VI can be used to simplify setup of generic XBee networks. Common frame types are serial transmit and receive frames. a frame type. The design and function of each of these VIs is detailed in the following sections. and command acknowledgement frames.). The coordinator radio acts as the network hub. Figure 1: Basic XBee API frame structure[1] The XBee API frame specification currently supports 19 distinct frame types. Taken together.disabled. A basic diagram of the data flow for these VIs is shown in Figure 2. These frame types identify the specific data contained within a frame’s payload section. is provided as an optional application. provide the bulk of the library’s functionality.specific VIs are provided as supplementary libraries to aid top-level LabVIEW applications in the construction and processing of frame-specific data. The Serial TX/RX Frame Processor VIs The core functionality of the XBee API library is contained within only two of the library’s VIs: the Serial Receive (RX) Frame Processor and the Serial Transmit (TX) Frame Processor. the NI-VISA standard is wellsuited to the development of XBee-based network applications. at a minimum. Nineteen XBee API-frame. the Serial TX and Serial RX Frame Processor VIs. this mode is typically used with an XBee coordinator radio. 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28. Such factors make the utility of an easy-to-use. Figure 2: XBee Communication Library – structure and data-flow The Serial TX/RX Frame Processors handle all frame traffic between the user application and the XBee coordinator radio. The consumer loop (bottom of Figure 3) executes in parallel. This cluster variable is defined using a structure matching that of the basic XBee API frame 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28. the Serial RX Frame Processor VI intercepts all incoming serial traffic from the XBee coordinator radio (via a PC hardware port). waiting for data to be placed into the receive data queue by the producer loop. These two VIs are designed to be used conjunction with one or more of the frame-specific reader and builder VIs provided for use within the top-level user applications – these VIs simplify the process of building and reading the specific API frames used by the XBee standard (see next section). the frame data is transferred into a LabVIEW cluster variable (similar to the struct custom data type in C). As receive data becomes available to the consumer loop. processing these frames as they are found and then adding them to the RX Frame Queue. As shown in the diagram of Figure 2. 2012 . the producer loop (top of Figure 3) handles all incoming serial traffic by polling the serial port and spooling all available data into a receive data queue. Figure 3:Block-diagram for the Serial RX Frame Processor VI For the RX Processor VI. The purpose of this VI is to scan the serial input data stream for API frame structures. Once a frame start delimiter is found and verified. Both the TX and RX Serial Frame Processor VIs are designed around a producer/consumer parallel loop architecture. the data is scanned for XBee API frames start delimiters (0x7E). The LabVIEW block diagram code for the Serial RX Frame Processor is shown in Figure 3. unprocessed form. a field for the frame type. Other than error-flow outputs. As with the receive processor.). Only the RX and TX Frame Queues are exposed to the top-level user application. If more (or less) buffering is required. the TX Frame Processor VI assumes that all frames in the TX Frame Queue are formatted as generic frame clusters – i. and a boolean field indicating the checksum pass/fail condition. In most XBee applications. Detailed processing of specific API frame types is not handled by the TX and RX Frame Processor VIs. By using the producer loop to spool incoming serial data into a simple byte queue. These VIs are used in conjunction with the TX/RX Frame Queues exposed to the top-level application by the Serial TX/RX Frame Processor VIs. however. however. As with the Serial RX Frame Processor. while Frame Reader VIs are used to extract data from the various receive frame types (e. length. timely processing of the available serial data is necessary to ensure that no overflow occurs at the hardware port buffer. After the user has supplied the frame processor VI’s with a valid hardware port reference (i.g. For similar reasons. type and checksum – and leaving frame payload data in its raw. Ideally. combined with the typical buffering that already exists at the OS-hardware level. the RX Frame Processor VI can remain small. etc. This buffering. the serial port data processing and frame assembly routines are fully encapsulated. that each frame has been packed prior to being added to the queue. etc.e. and a byte array of raw frame data. This allows the VI to handle each frame identically with no case-specific processing. this parallel architecture allows a mismatch of frame processing and hardware transmission rates to occur. In such a situation. As detailed earlier. To transmit a frame the user application simply adds the frame cluster to the TX Frame Queue. This can be an important in large networks where it is possible for many API frames to arrive at the hardware port nearly simultaneously. a port connected to the coordinator radio). command acknowledgements. In many XBee applications network activity will occur in bursts. only a handful of the 19 currently defined frame types are regularly used. all frames placed into the TX and RX Frame Queues are LabVIEW clusters based on the generic XBee API frame structures – containing only fields for frame type. serial TX data. The consumer loop then streams these bytes to the hardware port as they become available. containing a field for the frame size. this should allow the consumer loop to eventually empty the receive data queue during periods of low network activity. As frame clusters to be transmitted to the XBee coordinator radio are placed into the TX Frame Queue by the user application they are flattened into byte arrays and spooled into a transmit data queue by the producer loop.e. transmit and receive data frames. With both the TX and RX Frame Processors. When a user application finds a frame of interest in the RX Frame Queue the frame cluster can be removed from the queue and passed to a Frame Reader VI. By processing only the essential elements of every incoming XBee API frame – i. except the data flow is reversed (from application to serial port – refer to the flow diagram of Figure 2).). to read a frame from the network the user simply monitors the RX Frame Queue for new frame clusters. this situation is less common on the transmit side as only one device is sending frames through the XBee coordinator radio’s UART. the Frame Processor VIs will manage all traffic to and from that port. These reader VIs 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28. fast and efficient. I/O-pin samples. users can adjust the default size of the Serial RX Frame Processor VI’s internal receive data queue to suit the needs of the specific application. 2012 . remote command requests. a producer-consumer loop structure is employed to decouple processing of basic frame data from serial data transmission.g. Frame Builder VIs & Frame Reader VIs To assist users in working with specific frame types. After each of these frame clusters has been built by the consumer loop it is added to the RX Frame Queue. The next section details how top-level applications can use the XBee Communication Library’s supplementary VIs to handle processing of specific frame payloads. the RX Frame Queue is the only output exposed to the top-level user application. the consumer loop can process the frame data from this queue using more time-intensive code (e. Here. a TX Frame Queue is exposed to the top-level user application. frame size.g.e. The Serial TX Frame Processor VI is functionally similar to the receive processor VI. a byte array containing the frame payload. The primary benefit of this producer-consumer parallel loop structure is that it allows the processing of frame data to occur at a rate slower than the serial receive rate for a short period of time. When the user application queries the frame type field of a frame cluster present in the RX Frame Queue a decision can then be made whether to discard the frame or process its data payload (to extract frame specific data of interest to the particular application). Frame Builder VIs are used to generate the various transmission frame types (e. checksum calculation). a set of supplementary Frame Builders VIs and Frame Reader VIs were also developed as part of the XBee Communication Library. should suffice for most XBee network applications. serial RX data. local and remote command frames. checksum status. I/O-pin sample frames and command response frames are the most commonly used XBee API frame types.layout shown in Figure 1. Likewise. in the appropriate data format. This VI is an optional component designed to aid user applications in establishing an XBee network from within LabVIEW. The VI will then pack the elements into the payload format for the specific frame type. Figure 5: XBee Serial Connection Manager – Front Panel 2012 ASEE Northeast Section Conference Reviewed Paper Figure 6: Flow Diagram for XBee Connection Manager University of Massachusetts Lowell April 27-28. This specific Frame Builder VI builds Local Command Request frames (API frame type 0x08). generate the frame header and checksum and make the generic frame cluster available at the VI’s output terminal. The Frame Builder VI packages these inputs into a frame cluster according to the XBee API Frame specification for this frame type and calculates the checksum for this generated frame. at the output terminals of the VI.will unpack the payload data for a given frame type and make each element available. The GUI for this VI is shown in Figure 5. and a parameter value for the AT command. Frame Builder VIs function in the opposite fashion – here the user application supplies the VI’s input terminals with all individual data elements required for a particular frame type. 2012 . The output terminal of this VI (right side of diagram) will provide the assembled frame cluster to the top-level application. This VI is also the only component in the library to utilize a front-panel graphical-user-interface (GUI). Figure 4: Block-diagram for a Frame Builder VI (0x08 – Local Command Frame) XBee Serial Connection Manager VI The final portion of XBee Communication Library is the XBee Serial Connection Manager VI. The top-level user application supplies the input terminals of this VI (left side of diagram) with a frame ID. The LabVIEW block diagram code of a simple Frame Builder VI is shown in Figure 4. This frame cluster can then be added to the TX Frame Queue for automatic transmission to the XBee coordinator radio. This frame cluster can then be added directly to the TX Frame Queue (for transmission). an AT command string (two character op-code). The connection manager handles five network connection tasks. This command requests an identifier response from every radio on the XBee network including the coordinator. Along with execution control the connection manager passes a VISA reference to the hardware port connection and references to the TX/RX Frame Queues. Hand-off Control to User Application – When the user presses the “Start Application” button the connection manager passes control to the user specified VI. The second example gives a typical structure for transmitting XBee API frames.g. Hardware Port Initialization – Using the serial connection information provided by the user (on the front panel) the VI attempts to open a VISA serial connection to the specified hardware port using the provided serial connection settings. Start TX and RX Frame Processors – With a hardware port connection established. 2. radio information is added to a network list array. 5. Once the Node Discovery command has been issued. two simplified LabVIEW block diagram code examples are provided to illustrate ways in which the XBee Communication Library can be integrated into a top-level user application. 2012 . This allows users to invoke the connection manager from a top-level application without displaying the GUI – instead using the input terminals to pass in front-panel control values (e. the VI sends a Local Command frame (0x08) containing the XBee Software Reset command (“FR”) to the serial port and waits for reset acknowledgement from the XBee coordinator radio. EXAMPLE APPLICATION OF THE XBEE COMMUNICATION LIBRARY In this section. Figure 7: Example 1 – simplified block-diagram for a typical receive frame structure 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28. The application continues to monitor the input serial stream for radio identifier frames (frame type 0x88). the connection manager passes the VISA hardware reference to the TX and RX Frame Processor VIs to enable the XBee TX/RX Frame Queues and start hardware port traffic monitoring and processing. Example 1 – Working with Received XBee API Frames Figure 7 shows a simplified LabVIEW structure for working with received API frames using the XBee Communication Library. for automated network setup). the connection manager will idle. 3. a second AT Local Command frame is sent containing the Node Discovery command (“ND”). type and address of all radios found on the network. As each identifier frame is received. 1. all necessary front-panel controls and indicators for this VI are also connected to input and output terminals for the VI’s function block. Ping Network Radios – After the coordinator has successfully reset. Also passed is an array of network radio information. Coordinator Radio Reset and Verification – After successfully opening the serial port and starting the Serial TX/RX Frame Processors. Although the XBee Serial Connection Manager VI contains a GUI that can be used as the starting point for any user application. containing the name. illustrated in Figure 6 and detailed below. 4. The first example gives a typical structure for working with received XBee API frames. If no frame is present in the RX Frame Queue the Dequeue function block will timeout after 500 milliseconds and the loop will repeat. Once the Serial TX Processor has been started it will monitor the TX Frame Queue for frame clusters and transmit them to the hardware port (i. This is all that is required from the user application to begin receiving frames from the XBee network. When a matching frame type is found in the RX Frame Queue the code for this case will execute. For this example. CONCLUSION The XBee Communication Library developed in this design project provides an easy to use. In this loop the RX Frame Queue is polled. The modular approach of breaking-out frame specific processing code into a set of targeted VIs also keeps the core functionality of this library simple and efficient making it suitable for applications where speed and reliability are a concern. In the example code above. Additional cases for other frame types can be added to the case structure as well. This is all that is required from the user application to begin transmitting frames to the XBee coordinator. As with the RX processor. Example 2 – Working with XBee Transmit API Frames Figure 8 shows a simplified LabVIEW structure for working with transmit API frames using the XBee Communication Library. every part of the XBee Communication Library is easy to access and fully customizable by the user for integration into any application specific XBee-based LabVIEW project. By employing the simple TX/RX queue-based approach used in this library. etc. This frees designers to focus on the particulars of their XBee-based application without getting bogged down in the details of the underlying XBee network and software/hardware interfacing. the Serial RX Frame Processor VI has been provided with two inputs – a reference to the RX Frame Queue and a valid reference to the XBee coordinator radio’s hardware port. Note that the Serial RX Frame Processor is not placed in-line with the XBee RX Frame Queue data line.e. Finally. by building these tools within the LabVIEW environment itself. network) as they are added to the queue. a Local Command Request frame (0x08) has been built with supplied user data and the appropriate Frame Builder VI. This output frame cluster is then added to the TX Frame Queue for transmission.) In a practical example these frame elements would be further processed according to the specific function of the application. Figure 8: Example 2 – simplified block-diagram for a typical transmit frame structure In this example. general purpose set of tools for building XBee API-based network applications using NI’s LabVIEW development software. setup for the Serial TX Frame Processor VI is identical to the setup of the Serial RX Frame Processor – Inputs to the Serial TX Processor VI are a reference to the TX Frame Queue and a valid reference to the XBee coordinator radio’s hardware port. The while-loop structure is used to create a simple frame listener. If a frame cluster is successfully Dequeued from the RX Frame Queue the cluster’s Frame Type field is checked by a case structure. the code for case 0x88 is shown – this frame type corresponds to a Command Response Frame. Here. 2012 . allowing the case structure to individually process any and all receive frame types of importance to the given application. a Frame Reader VI (for frame type 0x88) is used to break the command response frame into its constituent parts (Frame ID. LabVIEW developers can add XBee wireless network functionality to their hardware control and measurement projects without incurring the significant overhead previously required to integrate this technology into the LabVIEW design environment. 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28.To the left of the while-loop structure in the diagram. AT Command. the Serial TX Frame Processor is not placed in-line with the XBee TX Frame Queue data line. This ensures that the frame processor VI will execute in parallel with the user application (preventing blocking due to LabVIEW’s dataflow execution format). http://zone.maine. NI Developer Zone. with a focus on embedded systems and algorithm design. Upgrades to this hardware platform. “PC Controlled Testing Platform for MEMS Capacitance and Acceleration Sensing” Abstracts of ASEE New England Conference. National Instruments. These upgrades made accurate and timely testing of this project’s communication library possible. REFERENCES [1] [2] [3] [4] [5] [6] What Is NI LabVIEW. Ankara. Greg Mitchell and M.C. 2012 ASEE Northeast Section Conference Reviewed Paper University of Massachusetts Lowell April 27-28. He is currently a full professor of Electrical Engineering at the University of Southern Maine. 2011. http://www. 2012.com/labview/whatis/. Guvench with his research into the testing and development of high-frequency.G. and electronic instrumentation and measurement. degrees in Electrical Engineering and Applied Physics from Case Western Reserve University. Guvench.E.. Coleman.S. His research interests and publications span the field of microelectronics including I. Testing and development of the communication library for this project were made possible by University of Southern Maine alumni Greg Mitchell and Steve Coleman. design. 2011. In the fall of 2012 Michael will be continuing his academic coursework as a graduate student at the University of Maine studying under Dr. finite element and analytical modeling of semiconductor devices and sensors. 2012 . were completed by current engineering student David Carlson. Michael’s undergraduate concentration is in the area of computer engineering. Turkey.com/dzhp/app/main.edu.ni. Guvench Dr. 2008. Steve.com/pdf/ds_xbeezbmodules.ni.U. Conn.S. National Instruments.. He can be reached at guvench@usm. and Ph. Dr. Michael Schell Michael Schell is an undergraduate student majoring in Electrical Engineering at the University of Southern Maine. MEMS and semiconductor technology and its application in sensor development. who developed the original accelerometer hardware test platform that formed the basis for this redesign project [4].com. XBee & XBee PRO ZB. Bridgeport. 99. Guvench received M. Michael can be reached at
[email protected]. Digi International.M. “API Operation. http://www.digi.” XBee/XBee-PRO ZB RF Modules. including a PC-based rotational control system.T. Mustafa G. he served on the faculties of the University of Pittsburgh and M. 2010. While at the University of Southern Maine he has worked as an independent research assistant aiding Professor Mustafa G.rr. 2012. National Instruments.ACKNOWLEDGEMENTS Funding for this project was generously provided in part by NASA and the Maine Space Grant Consortium.pdf. Digi International. Ali Abedi of the Electrical and Computer Engineering department. NI VISA Help. Prior to joining U. MEMS-based vibration sensors for ultrasonic leak-detection on NASA inflatable lunar structures.