network.h

关于zigbee厂家jennic的zigbee通信模块JN5139的一些示例程序。

 *   labelloc = "bottom";
 *   subgraph cluster_chipX {
 *     	label="JN513x";
 *     	labelloc = "bottom";
 *     	uartX [label="UART"];
 *   }
 * }
 *
 * subgraph cluster_boardY {
 *   label="Sensor Board 2";
 *   labelloc = "bottom";
 *   subgraph cluster_chipY {
 *     	label="JN513x";
 *     	labelloc = "bottom";
 *     	uartY [label="UART"];
 *   }
 * }
 * }
 * uartA -> uartX [arrowhead="normal", arrowtail="normal"];
 * uartB -> uartY [arrowhead="normal", arrowtail="normal"];
 * uartX -> uartY [arrowhead="normal", arrowtail="normal", ltail=cluster_boardX, lhead=cluster_boardY, tailport=e, headport=w, length=1.0];
 *
 *}
 *\enddot
 *
 *\page ML-AN-0004 Jenie Quickstart
 *
 *\section Introduction
 *
 * This Application Note provides a starting point for developing wireless
 * networking applications using the Jenie API available free of charge from
 * <a href="www.jennic.com">Jennic Ltd</a>.
 *
 * This Application Note adds ready made code to manage Jenie services that is
 * not included in the the standard Jenie Application Template. This code can be
 * built upon to quickly create Jenie applications or used as a learning aid
 * to understand how to implement your own applications using the Jenie API.
 *
 * The following features are implemented:
 * - Functions to specify the maximum number of bindings between source and
 *   destination services.
 * - Functions to enable and disable binding between source and destination services.
 * - Code to automatically discover and bind services that are enabled for binding
 *   and do not yet have the maximum number of bindings.
 * - Functions to transmit and receive data between bound source and destination services.
 * - Optional debugging of Jenie API calls to a UART.
 *
 *\section Application_Overview Application Overview
 *
 *\subsection Jenie_API Jenie API
 *
 * The Jenie API provides an easy-to-use interface for developing wireless
 * networking applications for the Jennic JN513x wireless microcontrollers.
 * The Jenie API comprises C functions for controlling the wireless network
 * and the on-chip hardware peripherals of the JN513x device.
 *
 * A Reference Guide, User Guide and other detailed information about Jenie
 * can be found in the
 * <a href="http://www.jennic.com//support/view_section.php?sectionID=0000000021">Jenie section</a>
 * of Jennic's website.
 *
 *\subsection Node_Types Node Types
 *
 * Jenie wireless networks are built using three types of nodes:
 *
 *\par Coordinator
 * The coordinator node is responsible for creating the network and
 * allowing other nodes to join the network as children of the coordinator node.
 * The coordinator node is able to select the the radio channel to be used by
 * the network and specify the network identification paramters. The file
 * Coordinator.c contains source code for a coordinator.
 *
 *\par Routers
 * Router nodes can join the network created by the coordinator node and
 * also extend the network by allowing other nodes to join the network as
 * children of the router node. The file Router.c contains source code for routers.
 *
 *\par End Devices
 * End devices can join the network formed by the coordinator and routers but
 * do not allow further nodes to join the network. End devices are often
 * battery powered and sleep to preserve power when not performing their
 * application functions. The file EndDevice.c contains source code for
 * end devices.
 *
 * Regardless of the node type the code used to form
 * the network, make use of services and transfer data is almost identical.
 * This Application Note takes advantage of that by placing all the common
 * networking code into the file Network.c. The node type specific files,
 * (Coordinator.c, Router.c, EndDevice.c), for the most part simply call
 * the equivalent functions in Network.c.
 *
 * If different application code is required by the different node types
 * it can be placed in or called from the node specific files.
 * If application code is common to all node types it can be placed in or
 * called from Network.c.
 *
 *\subsection Jenie_Callbacks Jenie API Callback Functions
 *
 * The Jenie API includes a number of callback functions that are called by
 * the Jenie stack. A pair of functions are used to allow the configuration and
 * initialisation of the network. Additional functions are used to manage the
 * networking stack and handle data received from other nodes.
 *
 * The Jenie API call back functions are located in the node specific files
 * but they simply call the equivalent functions provided in Network.c as
 * the functionality is almost identical for all node types.
 *
 * vNetwork_ConfigureNetwork() is called prior to the network stack being
 * initialised and provides the opportunity override the default stack
 * parameters. This function is called only on a cold start. Configuration
 * code common to all node types can be added here. Configuration code for
 * a specific node type can be added in vJenie_CbConfigureNetwork(), in the
 * appropriate node specific file.
 *
 * vNetwork_Init() is called after to the network stack is
 * initialised and provides the opportunity to perform additional initialisation
 * tasks. This function is called on both cold and warm starts. Initialisation
 * code common to all node types can be added here. Configuration code for
 * a specific node type can be added in vJenie_CbInit(), in the
 * appropriate node specific file.
 *
 * vNetwork_Main() is called regularly by the network stack
 * and provides the opportunity to perform normal application processing.
 * Code in this function should be non-blocking. Main
 * code common to all node types can be added here. Main code for
 * a specific node type can be added to vJenie_CbMain(), in the
 * appropriate node specific file.
 *
 * vNetwork_StackMgmtEvent() and vNetwork_StackDataEvent() are
 * called when stack events occurr. Network.c normally handles these
 * events internally.
 *
 * vNetwork_HwEvent() is called when hardware events occurr. Network.c
 * sets wake timer 1 to interrupt every 100ms for timing purposes. Other
 * hardware events used by the application can be picked up here or in
 * vJenie_HwEvent(), in the appropriate node specific file if required.
 *
 *\subsection Network_Up Network Up
 *
 * When a node has started or joined the network the function bNetwork_Up()
 * will return TRUE.
 *
 *\subsection Sleeping
 *
 * The function eNetwork_Sleep() should be used to put an end device to sleep
 * as wake timer 1 is used internally in Network.c and will wake a sleeping end
 * device after 100ms if not stopped.
 *
 *\subsection Direct_Data Direct Data Transmission
 *
 * The Jenie API allows the direct transmission of data between nodes as long
 * as the address of the destination node is known. When nodes join the network they learn
 * the address of their parent, and a parent learns the addresses of its children.
 * This information could be used to monitor which nodes are in the network
 * and diseminate the addresses around the network.
 *
 * The functions eNetwork_Tx() and vNetwork_Rx() can be used to send and receive data
 * directly using node addresses.
 *
 *\subsection Services
 *
 * Maintaining address lists in order to send data directly to nodes
 * can be quite onerous. Services provide a more convenient mechanism for
 * devices that have data to send to find possible destinations
 * within the network.
 *
 * Jenie allows up to 32 source and destination services to be used by
 * each node. Network.c includes functions to manage these services.
 * Some functions work on an individual service specifying the individual
 * service number, (1 to 32), others work an a set of services as specified by
 * a 32 bit mask. Calling the appropriate function allows an individual or group
 * of services to be manipulated as required.
 *
 *\subsection Destination_Services Destination Services
 *
 * Destination services are those that can receive data from other nodes.
 * Destination services are registered with the Jenie stack which then allows
 * other devices in the network to discover those services, bind to them and
 * then transmit data to them. Each node can register up to 32 destination services.
 *
 * Network.c contains a set of functions to specify which destination services
 * are to be registered with the network stack for binding. The functions
 * eNetwork_Destination_Enabled() and eNetwork_Destinations_Enabled() allow binding
 * to destination service(s) to be turned on and off. The functions
 * eNetwork_Destination_Limit() and eNetwork_Destinations_Limit() allow the
 * maximum number of bindings to a destination service to be controlled.
 *
 * Whilst binding is enabled and the maximum number of bindings to a destination
 * service has not been reached the destination service will be registered with Jenie
 * so other devices in the network can discover the service. When another device
 * binds to the destination service it sends a direct message indicating
 * which services it has bound to, the number of bindings is then updated.
 * When binding is disabled or the binding limit is reached the destination service
 * will be unregistered so it cannot be discovered by other devices. If the
 * number of bindings is about to be exceeded when a binding message is received
 * a command to unbind that service will be returned. This functionality
 * is all performed automatically by code in Network.c, the application code
 * simply needs to ensure that binding is allowed at the appropriate point by
 * enabling and setting an appropriate binding limit for a destination service.
 *
 * When data is sent to a bound destination service the function vNetwork_Destination_Rx()
 * will be called. Application data should be handled in this function. Alternativly the call to
 * vDevice_Destination_Rx() can be uncommented which will call that function in the
 * node specific file.
 *
 * The functions bNetwork_Destination_Bound(), bNetwork_Destination_Enabled(),
 * u8Network_Destination_Limit() and u8Network_Destination_Count() can be used
 * to get the bound, enabled, binding limit and current binding count for a
 * destination service.
 *
 *\subsection Source_Services Source Services
 *
 * Source services are those that can send data to other nodes. Up to
 * 32 source services can be used by each node, (this Quickstart Application
 * Note only allows use of the first four, NETWORK_MAX_SOURCE in Network.h
 * can be used to increase this). Each source service can be bound to up to
 * 32 destination services on one or more other nodes in the network.
 * Destination services that source services can bind to are discovered by
 * requesting them from the Jenie stack.
 *
 * Network.c contains a set of functions to specify which destination services
 * for each source service are to be requested from the network stack for binding.
 * The functions eNetwork_Source_Enabled() and eNetwork_Sources_Enabled() allow binding
 * from source service(s) to be turned on and off. The functions
 * eNetwork_Source_Limit() and eNetwork_Sources_Limit() allow the
 * maximum number of bindings from a source service to be controlled.
 *
 * Whilst binding is enabled and the maximum number of bindings from a source
 * service has not been reached the source service will be request the specified
 * destination services from Jenie. When a matching destination service is found
 * on another device the source service will be bound to the destination service.
 * The source node sends a direct message indicating which services it has bound
 * to, the number of bindings is then updated. If the
 * number of bindings to a destination service is about to be exceeded a command
 * to unbind that service will be received from the destination node.
 * When binding is disabled or the binding limit is reached destination services
 * will stop being requested. This functionality
 * is all performed automatically by code in Network.c, the application code
 * simply needs to ensure that binding is allowed at the appropriate point by
 * enabling and setting an appropriate binding limit for a source service.
 *
 * When data is to be sent from a bound source service the function eNetwork_Source_Tx()
 * should be called by the application. This will cause data to be sent to all the destination
 * services on all the nodes bound from the source service.
 *
 * The functions bNetwork_Source_Bound(), bNetwork_Source_Enabled(),
 * u8Network_Source_Limit() and u8Network_Source_Count() can be used
 * to get the bound, enabled, binding limit and current binding count for a
 * source service.
 *
 *\section Usage
 *
 * Basic usage is to set up the network configuration parameters in Network.h.
 * These will be used by vNetwork_ConfigureNetwork(). Application specific
 * configuration can be added here or vJenie_CbConfigureNetwork().
 *
 * Add application specific initialisation to vNetwork_Init() or vJenie_CbInit().
 *
 * Specify which source and destination services are to be used by the application
 * by setting the binding limits and enabling binding. This could be done during
 * initialisation or in repsonse to other events such as button presses.
 *
 * Add application specific code to vNetwork_Main() and/or vJenie_CbMain().
 *
 * Add application specific hardware code to vNetwork_HwEvent() and/or
 * vJenie_CbHwEvent().
 *
 * Transmit application data from source services using eNetwork_Source_Tx()
 * checking the service is bound first using bNetwork_Source_Bound().
 *
 * Process received data in vNetwork_Destination_Rx() or vDevice_Destination_Rx().
 *
 *\subsection Examples
 *
 * The following Application Notes are built upon this Quickstart Application Note:
 *
 * - ML-AN-0005 Jenie User Binding Lightswitch
 *
 * The following Application Notes are built upon an earlier version of this
 * Quickstart Application Note:
 *
 * - JN-AN-1064 Jenie Wireless UART
 * - JN-AN-1067 Jenie Wireless Sensor Network
 * - JN-AN-1071 Jenie Radio Control Application
 * - JN-AN-1072 Jenie Wireless Keyboard
 *
 * These Application Notes can be downloaded from the
 * <a href="http://www.jennic.com//support/view_section.php?sectionID=0000000021">Jenie section</a>
 * of Jennic's website.
 *
 *\section Debugging
 *
 * The define NETWORK_DEBUG in Network.h will output a large amount of debugging
 * to UART 0 when set to TRUE. This data will allow the calls to the functions in
 * Network.c to be monitored and also the calls that Network.c makes to the Jenie
 * stack.
 ***************************************************************************/

/****************************************************************************/
/***        END OF FILE                                                   ***/
/****************************************************************************/