Microchip Wireless (Miwi) Application Programming Interface
Total Page:16
File Type:pdf, Size:1020Kb
AN1284 Microchip Wireless (MiWi™) Application Programming Interface – MiApp The MiApp specification defines the programming Author: Yifeng Yang interfaces between the application layer and Microchip Microchip Technology Inc. proprietary wireless communication protocols. The MiApp programming interface is implemented in two INTRODUCTION ways: as configuration parameters defined in the con- figuration file, and as a set of function calls to the Micro- It is not an easy task to develop a short-range, low data chip proprietary wireless protocols. Complying with the rate and low power wireless application. Apart from MiApp specification defined in this application note, complex Radio Frequency (RF) circuit designs, the applications can use any Microchip proprietary wireless firmware development process may require the devel- protocols. With little or no modification in the applica- opers to understand the details of RF transceivers, as tion layer, software development can be easily well as the different wireless communication protocols. changed between a proprietary P2P/star topology con- Microchip has developed a way to handle the complex nection protocol to a full mesh proprietary networking and difficult RF hardware and/or communication proto- protocol for small or big networks, depending on the col stack software development, which allows wireless application needs. developers to focus on their own application develop- ment. This is achieved through a concise, yet powerful communication programming interface in the applica- tion layer which is called MiApp, and it is defined in this application note. FIGURE 1: BLOCK DIAGRAM OF MICROCHIP WIRELESS (MiWi™) STACK Application User Application Configuration MiApp MiWi™ P2P MiWi™ Mesh Protocol Configuration Future Microchip Proprietary Wireless Protocols ... Interchangeable Wireless Communication Protocols MiMAC MRF24J40 Transceiver RF Transceiver MRF49XA Transceiver Configuration Future Microchip RF Transceivers ... Interchangeable RF Transceivers 2009 Microchip Technology Inc. DS01284A-page 1 AN1284 The MiApp specification benefits wireless application CONSIDERATIONS developers in multiple ways: The MiApp specification is designed to support Micro- • Wireless application development will focus on chip proprietary wireless communication protocols. the application itself. Complex RF or protocol con- Once a wireless application is implemented by the siderations will be handled transparently by the MiApp programming interface, the Microchip RF trans- MiApp programming interface. ceivers are also supported through standardization in • The MiApp specification allows maximum flexibil- MiMAC, the module defined in the Media Access Con- ity to choose a wireless protocol at any stage of troller (MAC) layer. application software development with little effort, thus greatly lowering the risk of software develop- MiMAC standardizes the interface between Microchip ment. Application requirement changes in net- wireless protocols and Microchip RF transceivers. working capabilities have little or no impact in MiMAC makes Microchip RF transceivers interchange- application development. able with little or no change in the software application code. For details of MiMAC, please refer to application • MiApp uses the same control interface for note AN1283 “Microchip Wireless (MiWi) Media Microchip wireless proprietary protocols. Once Access Controller - MiMAC”. you are familiar with MiApp, you can apply that knowledge to the development of another applica- MiMAC regulates the lower interface of the Microchip tion even if it has a completely different network- proprietary wireless protocols, while MiApp regulates ing capability requirement. the higher interface of the Microchip proprietary wire- • By communicating to the Microchip proprietary less protocols. Working together, both MiMAC and protocols, MiApp indirectly talks to the Microchip MiApp provide wireless application developers the RF transceivers through the MiMAC interface. As maximum flexibility to choose the RF transceivers and a result, MiApp indirectly enables the wireless wireless communication protocols at any stage of soft- application developers to switch between ware development, thus further minimizing the risk of Microchip RF transceivers through MiMAC. This software development.The block diagram in Figure 1 flexibility, in turn, further reduces the development shows the Microchip Wireless (MiWi™) stack offerings. risk of the wireless application project. There are three layers of configurations for application, protocol stacks and RF transceivers. Application con- FEATURES figuration might change between devices in the same application according to their hardware design, role in The MiApp programming interface has the following the application and network. Wireless application features: developers tend to do the majority of the configuration in the application layer. Protocol configurations fine- • Easy to learn and use tune the behavior of the protocol stack. The majority of • Powerful interface to meet most requirements protocol stack configurations define the timing and from wireless applications routing mechanism for the chosen wireless protocol. • Little or no extra effort to migrate the wireless Transceiver configurations define the frequency band, application between Microchip proprietary data rate and other RF related features of the RF trans- wireless protocols ceiver. The default settings for the protocol and RF • Minimum footprint impact transceiver configurations may work with the applica- tion without any modification. The application configu- rations, however, usually need to be changed to fit the needs of different wireless applications. DS01284A-page 2 2009 Microchip Technology Inc. AN1284 MiApp OVERVIEW There are five categories of interfaces for the APIs: • The initialization interface allows wireless applica- As discussed earlier, there are two parts defined in the tion developers to properly initialize the Microchip MiApp specification: proprietary wireless protocol that has been • Configuration parameters defined in the selected in the configuration file. configuration file • The hand-shaking interface allows the wireless • Signatures of function calls to the Microchip nodes to discover and get connected with their proprietary wireless communication protocols peers, or to join the network. The configuration file contains parameters that should • Interfaces to send messages which enable appli- be set before compilation. Generally speaking, two cation developers to transmit information from the pieces of information are defined in the configuration current node to an intended audience over the air. file: • Interfaces to receive messages which enable • Hardware Definitions: Including MCU hardware application developers to receive information over resources, peripherals definition and the RF the air from other devices. transceiver control pins’ definitions. The default • Special functionalities which ensure the optimal hardware definitions have already been defined operating condition for wireless nodes through for several Microchip standard demo boards that environment noise control and power saving. support Microchip RF transceivers. In these cases, the definition of demo boards introduces MiApp CONFIGURATION FILE all hardware definitions automatically. • Software Definitions: These definitions control Of the two kinds of configurations in the MiApp config- the code sections to be compiled into the firmware uration file, the hardware definitions depend heavily on hex file. The software definitions include selec- the demo board, MCU and RF transceiver choice. tions of Microchip proprietary wireless protocol, Hardware definitions can be divided into following sub choice of Microchip RF transceiver and individual categories: functionalities. Proper definitions in this category • I/Os on the demo board – push buttons, LEDs, ensure the minimum firmware footprint with the serial ports, etc. intended protocol capabilities. • MCU system resources – timers, interrupts, etc. Application Programming Interfaces (APIs) are the • Interconnections between MCU and RF function calls between the Microchip proprietary transceiver wireless communication protocols with the wireless developer’s application. As a rule, the application inter- Hardware definitions are mainly associated with hard- face must be clean, concise, easy to understand and ware selections of the wireless application system powerful. design. They depend more on the hardware than the software and vary across different designs. As a result, MiApp does not have a set of standards for those hardware definitions. Selective compilation configurations select the features among the list of available ones. Using the selective compilation, application developers are able to config- ure Microchip proprietary wireless protocols to perform the desired functionality with the least possible system resources. Table 1 describes the possible selective compilation configurations, as well as the scope, value and functionalities of those selections. TABLE 1: SOFTWARE DEFINITIONS IN CONFIGURATION FILE Example of Definition Functionality Restriction #define PROTOCOL_MIWI Selects the Microchip wireless Only one protocol can be defined at any #define PROTOCOL_P2P protocol to be used in the wireless one time. application. #define MRF24J40 Selects the Microchip RF transceiver Only one transceiver can be defined at #define MRF49XA to be used in the wireless application. any one time.