RF24Network
Diff: RF24Network.h
- Revision:
- 0:c3db0798d9aa
- Child:
- 2:a5f8e04bd02b
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/RF24Network.h Mon Jul 06 05:11:06 2015 +0000 @@ -0,0 +1,344 @@ +/* + Copyright (C) 2011 James Coliz, Jr. <maniacbug@ymail.com> + + This program is free software; you can redistribute it and/or + modify it under the terms of the GNU General Public License + version 2 as published by the Free Software Foundation. + */ + +#ifndef __RF24NETWORK_H__ +#define __RF24NETWORK_H__ + +/** + * @file RF24Network.h + * + * Class declaration for RF24Network + */ + +#include <stddef.h> +#include <stdint.h> + +class RF24; + +/** + * Header which is sent with each message + * + * The frame put over the air consists of this header and a message + */ +struct RF24NetworkHeader +{ + uint16_t from_node; /**< Logical address where the message was generated */ + uint16_t to_node; /**< Logical address where the message is going */ + uint16_t id; /**< Sequential message ID, incremented every message */ + unsigned char type; /**< Type of the packet. 0-127 are user-defined types, 128-255 are reserved for system */ + unsigned char reserved; /**< Reserved for future use */ + + static uint16_t next_id; /**< The message ID of the next message to be sent */ + + /** + * Default constructor + * + * Simply constructs a blank header + */ + RF24NetworkHeader() {} + + /** + * Send constructor + * + * Use this constructor to create a header and then send a message + * + * @code + * RF24NetworkHeader header(recipient_address,'t'); + * network.write(header,&message,sizeof(message)); + * @endcode + * + * @param _to The logical node address where the message is going + * @param _type The type of message which follows. Only 0-127 are allowed for + * user messages. + */ + RF24NetworkHeader(uint16_t _to, unsigned char _type = 0): to_node(_to), id(next_id++), type(_type&0x7f) {} + + /** + * Create debugging string + * + * Useful for debugging. Dumps all members into a single string, using + * internal static memory. This memory will get overridden next time + * you call the method. + * + * @return String representation of this object + */ + const char* toString(void) const; +}; + +/** + * Network Layer for RF24 Radios + * + * This class implements an OSI Network Layer using nRF24L01(+) radios driven + * by RF24 library. + */ + +class RF24Network +{ +public: + /** + * Construct the network + * + * @param _radio The underlying radio driver instance + * + */ + RF24Network( RF24& _radio ); + + /** + * Bring up the network + * + * @warning Be sure to 'begin' the radio first. + * + * @param _channel The RF channel to operate on + * @param _node_address The logical address of this node + */ + void begin(uint8_t _channel, uint16_t _node_address ); + + /** + * Main layer loop + * + * This function must be called regularly to keep the layer going. This is where all + * the action happens! + */ + void update(void); + + /** + * Test whether there is a message available for this node + * + * @return Whether there is a message available for this node + */ + bool available(void); + + /** + * Read the next available header + * + * Reads the next available header without advancing to the next + * incoming message. Useful for doing a switch on the message type + * + * If there is no message available, the header is not touched + * + * @param[out] header The header (envelope) of the next message + */ + void peek(RF24NetworkHeader& header); + + /** + * Read a message + * + * @param[out] header The header (envelope) of this message + * @param[out] message Pointer to memory where the message should be placed + * @param maxlen The largest message size which can be held in @p message + * @return The total number of bytes copied into @p message + */ + size_t read(RF24NetworkHeader& header, void* message, size_t maxlen); + + /** + * Send a message + * + * @param[in,out] header The header (envelope) of this message. The critical + * thing to fill in is the @p to_node field so we know where to send the + * message. It is then updated with the details of the actual header sent. + * @param message Pointer to memory where the message is located + * @param len The size of the message + * @return Whether the message was successfully received + */ + bool write(RF24NetworkHeader& header,const void* message, size_t len); + +protected: + void open_pipes(void); + uint16_t find_node( uint16_t current_node, uint16_t target_node ); + bool write(uint16_t); + bool write_to_pipe( uint16_t node, uint8_t pipe ); + bool enqueue(void); + + bool is_direct_child( uint16_t node ); + bool is_descendant( uint16_t node ); + uint16_t direct_child_route_to( uint16_t node ); + uint8_t pipe_to_descendant( uint16_t node ); + void setup_address(void); + +private: + RF24& radio; /**< Underlying radio driver, provides link/physical layers */ + uint16_t node_address; /**< Logical node address of this unit, 1 .. UINT_MAX */ + const static int frame_size = 32; /**< How large is each frame over the air */ + uint8_t frame_buffer[frame_size]; /**< Space to put the frame that will be sent/received over the air */ + uint8_t frame_queue[5*frame_size]; /**< Space for a small set of frames that need to be delivered to the app layer */ + uint8_t* next_frame; /**< Pointer into the @p frame_queue where we should place the next received frame */ + + uint16_t parent_node; /**< Our parent's node address */ + uint8_t parent_pipe; /**< The pipe our parent uses to listen to us */ + uint16_t node_mask; /**< The bits which contain signfificant node address information */ + uint8_t min(uint8_t, uint8_t); +}; + +/** + * @example helloworld_tx.pde + * + * Simplest possible example of using RF24Network. Put this sketch + * on one node, and helloworld_rx.pde on the other. Tx will send + * Rx a nice message every 2 seconds which rx will print out for us. + */ + +/** + * @example helloworld_rx.pde + * + * Simplest possible example of using RF24Network. Put this sketch + * on one node, and helloworld_tx.pde on the other. Tx will send + * Rx a nice message every 2 seconds which rx will print out for us. + */ + +/** + * @example meshping.pde + * + * Example of pinging across a mesh network + * Using this sketch, each node will send a ping to the base every + * few seconds. The RF24Network library will route the message across + * the mesh to the correct node. + */ + +/** + * @example sensornet.pde + * + * Example of a sensor network. + * This sketch demonstrates how to use the RF24Network library to + * manage a set of low-power sensor nodes which mostly sleep but + * awake regularly to send readings to the base. + */ +/** + * @mainpage Network Layer for RF24 Radios + * + * This class implements an <a href="http://en.wikipedia.org/wiki/Network_layer">OSI Network Layer</a> using nRF24L01(+) radios driven + * by the <a href="http://maniacbug.github.com/RF24/">RF24</a> library. + * + * @section Purpose Purpose/Goal + * + * Create an alternative to ZigBee radios for Arduino communication. + * + * Xbees are excellent little radios, backed up by a mature and robust standard + * protocol stack. They are also expensive. + * + * For many Arduino uses, they seem like overkill. So I am working to build + * an alternative using nRF24L01 radios. Modules are available for less than + * $6 from many sources. With the RF24Network layer, I hope to cover many + * common communication scenarios. + * + * Please see the @ref Zigbee page for a comparison against the ZigBee protocols + * + * @section Features Features + * + * The layer provides: + * @li Host Addressing. Each node has a logical address on the local network. + * @li Message Forwarding. Messages can be sent from one node to any other, and + * this layer will get them there no matter how many hops it takes. + * @li Ad-hoc Joining. A node can join a network without any changes to any + * existing nodes. + * + * The layer does not (yet) provide: + * @li Fragmentation/reassembly. Ability to send longer messages and put them + * all back together before exposing them up to the app. + * @li Power-efficient listening. It would be useful for nodes who are listening + * to sleep for extended periods of time if they could know that they would miss + * no traffic. + * @li Dynamic address assignment. + * + * @section More How to learn more + * + * @li <a href="http://maniacbug.github.com/RF24/">RF24: Underlying radio driver</a> + * @li <a href="classRF24Network.html">RF24Network Class Documentation</a> + * @li <a href="https://github.com/maniacbug/RF24Network/">Source Code</a> + * @li <a href="https://github.com/maniacbug/RF24Network/archives/master">Downloads Page</a> + * @li <a href="examples.html">Examples Page</a>. Start with <a href="helloworld_rx_8pde-example.html">helloworld_rx</a> and <a href="helloworld_tx_8pde-example.html">helloworld_tx</a>. + * + * @section Topology Topology for Mesh Networks using nRF24L01(+) + * + * This network layer takes advantage of the fundamental capability of the nRF24L01(+) radio to + * listen actively to up to 6 other radios at once. The network is arranged in a + * <a href="http://en.wikipedia.org/wiki/Network_Topology#Tree">Tree Topology</a>, where + * one node is the base, and all other nodes are children either of that node, or of another. + * Unlike a true mesh network, multiple nodes are not connected together, so there is only one + * path to any given node. + * + * @section Octal Octal Addressing + * + * Each node must be assigned an 15-bit address by the administrator. This address exactly + * describes the position of the node within the tree. The address is an octal number. Each + * digit in the address represents a position in the tree further from the base. + * + * @li Node 00 is the base node. + * @li Nodes 01-05 are nodes whose parent is the base. + * @li Node 021 is the second child of node 01. + * @li Node 0321 is the third child of node 021, an so on. + * @li The largest node address is 05555, so 3,125 nodes are allowed on a single channel. + * + * @section Routing How routing is handled + * + * When sending a message using RF24Network::write(), you fill in the header with the logical + * node address. The network layer figures out the right path to find that node, and sends + * it through the system until it gets to the right place. This works even if the two nodes + * are far separated, as it will send the message down to the base node, and then back out + * to the final destination. + * + * All of this work is handled by the RF24Network::update() method, so be sure to call it + * regularly or your network will miss packets. + * + * @section Startup Starting up a node + * + * When a node starts up, it only has to contact its parent to establish communication. + * No direct connection to the Base node is needed. This is useful in situations where + * relay nodes are being used to bridge the distance to the base, so leaf nodes are out + * of range of the base. + * + * @section Directionality Directionality + * + * By default all nodes are always listening, so messages will quickly reach + * their destination. + * + * You may choose to sleep any nodes which do not have any active children on the network + * (i.e. leaf nodes). This is useful in a case where + * the leaf nodes are operating on batteries and need to sleep. + * This is useful for a sensor network. The leaf nodes can sleep most of the time, and wake + * every few minutes to send in a reading. However, messages cannot be sent to these + * sleeping nodes. + * + * In the future, I plan to write a system where messages can still be passed upward from + * the base, and get delivered when a sleeping node is ready to receive them. The radio + * and underlying driver support 'ack payloads', which will be a handy mechanism for this. + * + * @page Zigbee Comparison to ZigBee + * + * This network layer is influenced by the design of ZigBee, but does not implement it + * directly. + * + * @section Advantage Which is better? + * + * ZigBee is a much more robust, feature-rich set of protocols, with many different vendors + * providing compatible chips. + * + * RF24Network is cheap. While ZigBee radios are well over $20, nRF24L01 modules can be found + * for under $6. My personal favorite is + * <a href="http://www.mdfly.com/index.php?main_page=product_info&products_id=82">MDFly RF-IS2401</a>. + * + * @section Contrast Similiarities & Differences + * + * Here are some comparisons between RF24Network and ZigBee. + * + * @li Both networks support Star and Tree topologies. Only Zigbee supports a true mesh. + * @li In both networks, only leaf nodes can sleep (see @ref NodeNames). + * @li ZigBee nodes are configured using AT commands, or a separate Windows application. + * RF24 nodes are configured by recompiliing the firmware or writing to EEPROM. + * + * @section NodeNames Node Naming + * + * @li Leaf node: A node at the outer edge of the network with no children. ZigBee calls it + * an End Device node. + * @li Relay node: A node which has both parents and children, and relays messages from one + * to the other. ZigBee calls it a Router. + * @li Base node. The top of the tree node with no parents, only children. Typically this node + * will bridge to another kind of network like Ethernet. ZigBee calls it a Co-ordinator node. + */ + +#endif // __RF24NETWORK_H__ +// vim:ai:cin:sts=2 sw=2 ft=cpp