RF24Network.h

Go to the documentation of this file.

/*
 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__
 
#include <stddef.h>
#include <stdint.h>
#include "RF24Network_config.h"
 
#if (defined(__linux) || defined(linux)) && !defined(__ARDUINO_X86__)
    #include <stdint.h>
    #include <stdio.h>
    #include <time.h>
    #include <string.h>
    #include <sys/time.h>
    #include <stddef.h>
    #include <assert.h>
    #include <map>
    #include <utility> // std::pair
    #include <queue>
 
//ATXMega
#elif defined(XMEGA_D3)
    #include "../../rf24lib/rf24lib/RF24.h"
#endif
 
/* Header types range */
#define MIN_USER_DEFINED_HEADER_TYPE 0
#define MAX_USER_DEFINED_HEADER_TYPE 127
 
// ACK Response Types
#define NETWORK_ADDR_RESPONSE 128
 
#define NETWORK_PING 130
 
#define EXTERNAL_DATA_TYPE 131
 
#define NETWORK_FIRST_FRAGMENT 148
 
#define NETWORK_MORE_FRAGMENTS 149
 
#define NETWORK_LAST_FRAGMENT 150
//#define NETWORK_LAST_FRAGMENT 201
 
// NO ACK Response Types
//#define NETWORK_ACK_REQUEST 192
 
#define NETWORK_ACK 193
 
#define NETWORK_POLL 194
 
#define NETWORK_REQ_ADDRESS 195
 
// The following 2 atrifacts now exist in RF24Mesh as their significance was specific to RF24Mesh.
//#define NETWORK_ADDR_LOOKUP 196
//#define NETWORK_ADDR_RELEASE 197
/* This isn't actually used anywhere. */
#define NETWORK_MORE_FRAGMENTS_NACK 200
 
/* Internal defines for handling written payloads */
#define TX_NORMAL                   0
#define TX_ROUTED                   1
#define USER_TX_TO_PHYSICAL_ADDRESS 2 // no network ACK
#define USER_TX_TO_LOGICAL_ADDRESS  3 // network ACK
#define USER_TX_MULTICAST           4
 
#if defined NRF52_RADIO_LIBRARY
    #define MAX_FRAME_SIZE 123 // Size of individual radio frames is larger with NRF52
#else
    #define MAX_FRAME_SIZE 32 // Size of individual radio frames
#endif
 
#define FRAME_HEADER_SIZE 10 // Size of RF24Network frames - data
 
#define USE_CURRENT_CHANNEL 255
 
#define FLAG_FAST_FRAG 4
#define FLAG_NO_POLL 8
 
class RF24;
#if defined(ARDUINO_ARCH_NRF52) || defined(ARDUINO_ARCH_NRF52840) || defined(ARDUINO_ARCH_NRF52833)
class nrf_to_nrf;
#endif
 
struct RF24NetworkHeader
{
    uint16_t from_node;
 
    uint16_t to_node;
 
    uint16_t id;
 
    unsigned char type;
 
    unsigned char reserved;
 
    static uint16_t next_id;
 
    RF24NetworkHeader() {}
 
    RF24NetworkHeader(uint16_t _to, unsigned char _type = 0) : to_node(_to), id(next_id++), type(_type) {}
 
    const char* toString(void) const;
};
 
struct RF24NetworkFrame
{
    RF24NetworkHeader header;
 
    uint16_t message_size;
 
#if defined(RF24_LINUX)
    uint8_t message_buffer[MAX_PAYLOAD_SIZE]; // Array to store the message
#else
    uint8_t* message_buffer; // Pointer to the buffer storing the actual message
#endif
 
    RF24NetworkFrame() {}
 
#if defined(RF24_LINUX) || defined(DOXYGEN_FORCED)
    RF24NetworkFrame(RF24NetworkHeader& _header, const void* _message = NULL, uint16_t _len = 0) : header(_header), message_size(_len)
    {
        if (_message && _len) {
            memcpy(message_buffer, _message, _len);
        }
    }
#endif
#if defined(DOXYGEN_FORCED) || !defined(RF24_LINUX)
    RF24NetworkFrame(RF24NetworkHeader& _header, uint16_t _message_size) : header(_header), message_size(_message_size)
    {
    }
#endif
};
 
template<class radio_t = RF24>
class ESBNetwork
{
 
public:
    ESBNetwork(radio_t& _radio);
 
    inline void begin(uint16_t _node_address)
    {
        begin(USE_CURRENT_CHANNEL, _node_address);
    }
 
    uint8_t update(void);
 
    bool available(void);
 
    uint16_t peek(RF24NetworkHeader& header);
 
    void peek(RF24NetworkHeader& header, void* message, uint16_t maxlen = MAX_PAYLOAD_SIZE);
 
    uint16_t read(RF24NetworkHeader& header, void* message, uint16_t maxlen = MAX_PAYLOAD_SIZE);
 
    bool write(RF24NetworkHeader& header, const void* message, uint16_t len);
 
    void multicastLevel(uint8_t level);
 
    bool multicastRelay;
 
    void setup_watchdog(uint8_t prescalar);
 
    uint32_t txTimeout;
 
    uint16_t routeTimeout;
 
#if defined(ENABLE_NETWORK_STATS) || defined(DOXYGEN_FORCED)
 
    void failures(uint32_t* _fails, uint32_t* _ok);
 
#endif // defined (ENABLE_NETWORK_STATS)
#if defined(RF24NetworkMulticast)
 
    bool multicast(RF24NetworkHeader& header, const void* message, uint16_t len, uint8_t level = 7);
 
#endif
 
    bool write(RF24NetworkHeader& header, const void* message, uint16_t len, uint16_t writeDirect);
 
    bool sleepNode(unsigned int cycles, int interruptPin, uint8_t INTERRUPT_MODE = 0); //added interrupt mode support (default 0=LOW)
 
    uint16_t parent() const;
 
    uint16_t addressOfPipe(uint16_t node, uint8_t pipeNo);
 
    bool is_valid_address(uint16_t node);
 
    void begin(uint8_t _channel, uint16_t _node_address);
 
    uint8_t frame_buffer[MAX_FRAME_SIZE];
 
#if defined(RF24_LINUX) || defined(DOXYGEN_FORCED)
    std::queue<RF24NetworkFrame> external_queue;
#endif
 
#if (!defined(DISABLE_FRAGMENTATION) && !defined(RF24_LINUX)) || defined(DOXYGEN_FORCED)
    RF24NetworkFrame* frag_ptr;
#endif
 
    bool returnSysMsgs;
 
    uint8_t networkFlags;
 
protected:
#if defined(RF24NetworkMulticast)
    uint8_t _multicast_level;
#endif
    uint16_t node_address;
 
private:
    bool write(uint16_t to_node, uint8_t sendType);
 
    bool write_to_pipe(uint16_t node, uint8_t pipe, bool multicast);
 
    uint8_t enqueue(RF24NetworkHeader* header);
 
    /*
     * Called from begin(), this sets up the radio to act accordingly per the
     * logical `_node_address` parameter passed to `begin()`.
     *
     * Based on the value of the private member `node_address`, the resulting confiuration affects
     * private members `node_mask`, `parent_node`, `parent_pipe`, and `_multicast_level`.
     */
    void setup_address(void);
 
    /*
     * This (non-overloaded) function copies the outgoing frame into the `frame_buffer` and detirmines
     * the initial values passed into `logicalToPhysicalAddress()` (based on the value passed
     * to the `writeDirect` parameter). This is always called from either of the overloaded public
     * `write()` functions.
     */
    bool _write(RF24NetworkHeader& header, const void* message, uint16_t len, uint16_t writeDirect);
 
    /*
     * The main write function where fragmentation and processing of the payload is initiated
     */
    inline bool main_write(RF24NetworkHeader& header, const void* message, uint16_t len, uint16_t writeDirect);
 
    struct logicalToPhysicalStruct
    {
        uint16_t send_node;
        uint8_t send_pipe;
        bool multicast;
    };
 
    /*
     * Translates an outgoing frame's header information into the current node's
     * required information (`logicalToPhysicalStruct`) for making the transmission.
     *
     * This returns void because the translated results are stored in the
     * `logicalToPhysicalStruct` passed by reference.
     */
    void logicalToPhysicalAddress(logicalToPhysicalStruct* conversionInfo);
 
    /********* only called from `logicalToPhysicalAddress()` ***************/
 
    /* Returns true if the given logical address (`node` parameter) is a direct child of the current node; otherwise returns false. */
    bool is_direct_child(uint16_t node);
    /* Returns true if the given logical address (`node` parameter) is a descendent of the current node; otherwise returns false. */
    bool is_descendant(uint16_t node);
    /* Returns a logical address for the first child en route to a child node */
    uint16_t direct_child_route_to(uint16_t node);
 
    /***********************************************************************/
 
    radio_t& radio; 
    uint8_t frame_size; /* The outgoing frame's total size including the header info. Ranges [8, MAX_PAYLOAD_SIZE] */
 
    unsigned int max_frame_payload_size = MAX_FRAME_SIZE - sizeof(RF24NetworkHeader); /* always 24 bytes to compensate for the frame's header */
 
#if defined(RF24_LINUX)
    std::queue<RF24NetworkFrame> frame_queue;
    std::map<uint16_t, RF24NetworkFrame> frameFragmentsCache;
    bool appendFragmentToFrame(RF24NetworkFrame frame);
#else // Not Linux:
 
    #if defined(DISABLE_USER_PAYLOADS)
    uint8_t frame_queue[1];  
    #else
    uint8_t frame_queue[MAIN_BUFFER_SIZE]; 
    #endif
 
    uint8_t* next_frame;                                 
    #if !defined(DISABLE_FRAGMENTATION)
    RF24NetworkFrame frag_queue;                         /* a cache for re-assembling incoming message fragments */
    uint8_t frag_queue_message_buffer[MAX_PAYLOAD_SIZE]; //frame size + 1
    #endif
 
#endif // Linux/Not Linux
 
    uint16_t parent_node; 
    uint8_t parent_pipe;  
    uint16_t node_mask;   
    /* Given the Logical node address & a pipe number, this returns the Physical address assigned to the radio's pipes. */
    uint64_t pipe_address(uint16_t node, uint8_t pipe);
 
#if defined ENABLE_NETWORK_STATS
    uint32_t nFails;
    uint32_t nOK;
#endif
 
#if defined(RF24NetworkMulticast)
    /* translates network level number (0-3) to a Logical address (used for TX multicasting) */
    uint16_t levelToAddress(uint8_t level);
#endif
 
};
 
typedef ESBNetwork<RF24> RF24Network;
#if defined(ARDUINO_ARCH_NRF52) || defined(ARDUINO_ARCH_NRF52840) || defined(ARDUINO_ARCH_NRF52833)
typedef ESBNetwork<nrf_to_nrf> RF52Network;
#endif
 
#endif // __RF24NETWORK_H__