Microchip Wireless (Miwi) Application Programming Interface

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 configuration 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 development. This is achieved through a concise, yet powerful communication programming interface in the application 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 application without any modification. The application configurations, 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. #define TX_BUFFER_SIZE 40 Defines the maximum size of the There may be RF transceiver hardware application payload to be transmitted, restrictions on the size of buffer that can excluding all protocol headers. be transmitted. The hardware restriction includes all protocol headers.

 2009 Microchip Technology Inc. DS01284A-page 3 AN1284

TABLE 1: SOFTWARE DEFINITIONS IN CONFIGURATION FILE (CONTINUED) Example of Definition Functionality Restriction #define RX_BUFFER_SIZE 40 The maximum size of application pay- There may be RF transceiver hardware load to be received, excluding all restrictions on the size of buffer that can protocol headers. be received. The hardware restriction includes all protocol headers. #define CONNECTION_SIZE The size of connection table. Deter- Depends upon available MCU RAM. 10 mines the maximum number of devices that the node can connect to. #define Defines the size of additional informa- The additional node identifier plays no ADDITIONAL_NODE_ID_SIZE 0 tion attached to the packets in the role in Microchip’s proprietary protocols. hand-shake process. Primarily used to However, it may play an important role in identify the node in the application the application. In a simple case of light layer. and switch, two lights may not be inter- ested in connecting to each other, and the same applies to two switches. Using the additional node identifier enables the application to identify the role of the node in the application so that switches only connect with lights. #define ENABLE_PA_LNA Enables the RF transceiver to use an For RF transceivers that can control an external power amplifier and/or a low external PA and/or LNA. noise amplifier #define ENABLE_HAND_SHAKE Enables Microchip’s proprietary wire- Hand-shake process enables two wireless protocol to establish connections less nodes to know each other. In other with peers automatically. protocols, this process is also called “Pairing”. Applications without hand- shake only use broadcast to exchange messages. #define ENABLE_SLEEP Enables the RF transceiver to go to Sleep mode depends on the capability of sleep when idle to save power. the RF transceiver. #define ENABLE_ED_SCAN Enables the Microchip proprietary The energy scan depends on the wireless protocol and RF transceiver capability of the RF transceiver. to perform an energy detection scan. #define Enables the Microchip proprietary Active Scan is used to search for exist- ENABLE_ACTIVE_SCAN wireless protocol to perform an active ing wireless devices of the same kind in scan to discover nodes and networks the neighborhood. Active Scan can be in the neighborhood. used to decide which device to connect to. #define ENABLE_SECURITY Enables Microchip’s proprietary proto- The security engine, security mode and col to secure packets that are keys are defined in a configuration file transferred. for the RF transceiver, as security is defined as part of MiMAC. #define Enables the wireless node to cache Only wireless nodes that do not go to ENABLE_INDIRECT_MESSAGE messages for sleeping devices and to sleep can cache message for sleeping deliver them once the sleeping device nodes. The number of messages which wakes up and asks for the messages. can be cached depends on the available MCU RAM. #define Defines, in seconds, the RFD devices' Only effective when indirect message is RFD_WAKEUP_INTERVAL 5 wake-up time interval. enabled. This definition is used for devices that are always awake to keep track of timeouts for indirect messages. The sleeping time of sleeping devices depends on the WDT setting of the host MCU.

DS01284A-page 4  2009 Microchip Technology Inc. AN1284

TABLE 1: SOFTWARE DEFINITIONS IN CONFIGURATION FILE (CONTINUED) Example of Definition Functionality Restriction #define ENABLE_BROADCAST Enables the wireless node to handle Only wireless nodes that do not go to broadcast messages for sleeping sleep can cache messages for sleeping devices. nodes. #define Enables Microchip’s proprietary wire- N/A ENABLE_FREQUENCY_AGILITY less protocol to perform frequency agility procedures. #define HARDWARE_SPI Enables the MCU to use the hardware Defining of HARDWARE_SPI enables SPI to communicate with the the MCU to use the hardware SPI to transceiver. communicate with the transceiver. Oth- erwise, the MCU can use bit-bang to simulate SPI communication with transceiver. #define Defines the current device’s role in the This configuration is only used for net- NWK_ROLE_COORDINATOR network. work protocol. P2P protocol, like MiWi™ #define P2P, does not use this configuration. NWK_ROLE_END_DEVICE #define TARGET_SMALL Minimizes the footprint of Microchip’s Some features of the Microchip proprie- proprietary wireless protocols. tary wireless protocol may not be supported when minimizing the footprint of the protocol. #define Enables the Microchip proprietary Requires nonvolatile memory of either ENABLE_NETWORK_FREEZER wireless protocol to store critical net- MCU data EEPROM, external EEPROM work parameters and to recover from or programming space. Network size power loss to the original network and chosen wireless protocol decides setting. the total amount of nonvolatile memory required.

MiApp FUNCTION INTERFACES There is only one parameter for the initialization. The input boolean decides if the network freezer feature is Other than the options in the configuration file, the performed during the initialization. When the network application layer also uses function calls to communi- freezer feature is performed, the old network settings cate with the Microchip proprietary wireless protocol that are stored in nonvolatile memory will be restored. layer, thus controlling the transceiver indirectly to per- The return value is a boolean to indicate if the operation form wireless communication. There are five catego- is successful. ries of function calls to the protocol layers from the Other than the normal initialization process, wireless application layer: applications may need to change the transmit or • Initialization receive frequency during operation. MiApp defines the • Hand-shaking following function to change the operating frequency of • Sending Messages the RF transceiver according to the predefined chan- • Receiving Messages nel. Each channel defines the frequency either according to the specification, or the RF transceiver settings • Special Functionality under different operating frequency bands. The The following sections describe the function interfaces function signature is: in detail, as well as associated structure definitions. BOOL MiApp_SetChannel(BYTE Channel);

Initialization The only input parameter is the channel to be set. The return value indicates if the operation is successful. To initialize the RF transceiver and protocol stack, the The possible channel numbers are from 0 to 31. application layer only needs to trigger the initialization Depending on the RF transceiver, frequency band and process by calling the function ProtocolInit. The full data rate, not all channels from 0 to 31 may be valid function signature is: under all conditions. If the input channel is invalid under BOOL MiApp_ProtocolInit(BOOL bNetworkFreezer); current conditions, the operating channel is not changed and the return value will be FALSE to indicate failure.

 2009 Microchip Technology Inc. DS01284A-page 5 AN1284

Hand Shaking The input parameter ScanDuration specifies the maximum time to perform the channel assessment. The Unless hard coded in manufacturing, in most applica- max-and-hold method should be applied for the scan tions, the two communication endpoints need an intro- period, if multiple scans can be performed. In case the duction before they can unicast messages between a starting mode specifies no channel assessment, this pair of wireless nodes. The introduction for a network- input parameter will be discarded. The value of the ing protocol is sometimes called joining the network. input parameter ScanDuration complies with the defini- For the P2P protocol, this process can also be called tion in the IEEE 802.15.4™ specification. Its range is pairing. Since this strategy does not focus on any par- from 1 to 14. Equation 1 is the formula to calculate the ticular topology or protocol, this process can generally scan duration time. be called the hand-shaking phase. Without a hand- shaking process, wireless nodes can only use broad- EQUATION 1: SCAN DURATION cast, which treats every wireless node in the source CALCULATION radio range as the audience, to communicate with each other. ScanTime(us) = 960 * (2ScanDuration + 1) The following function calls for hand-shaking are available to the application layer: As the formula shows, a ScanDuration of 10 is roughly • MiApp_StartConnection one second. An increase by one roughly doubles the • MiApp_SearchConnection time, while a decrease by one roughly cuts the time in half. • MiApp_RemoveConnection • MiApp_ConnectionMode The input parameter ChannelMap specifies the channels to be scanned in the process. ChannelMap is MiApp_StartConnection defined as a 4-byte double word. It uses bit-map to rep- resent channel 0 to channel 31. When a bit is set in the The function call MiApp_StartConnection will enable a double word, it means that the corresponding channel wireless node to start operating in different ways. There will perform the channel assessment. For instance, if are three ways to start a PAN: start a PAN directly on a bit 0 of the input parameter ChannelMap is set, channel particular channel, or start a PAN after either of the two 0 will perform channel assessment. To perform channel channel assessments. The full function signature is: assessment on all available channels, the input param- BOOL StartConnection(BYTE Mode, BYTE eter ChannelMap will be 0xFFFFFFFF. ScanDuration, DWORD ChannelMap, BYTE *DestAddr); MiApp_SearchConnection The return value of the function call indicates if the The function call MiApp_SearchConnection searches operation is successful. for and discovers the existing peer wireless nodes in the neighborhood. This procedure is also known as The input parameter mode specifies the mode of start- active scan. In some applications, this step informs the ing the PAN. The possible modes are: device whether it should start a PAN or choose a PAN • START_CONN_DIRECT: Start the connection at to join. If a PAN is started, this procedure can be used the current channel without an