Diff: XBee/XBee.h

Revision:

4:629712865107

Parent:

3:8662ebe83570

Child:

5:da2ea7a76243

--- a/XBee/XBee.h	Mon May 18 13:16:55 2015 +0200
+++ b/XBee/XBee.h	Mon Jun 01 18:59:43 2015 +0200
@@ -47,44 +47,11 @@
  * @{
  */
 /**
- * RadioStatus 
+ * RadioStatus
  */
 enum RadioStatus {
     Success         = 0,    /**< Success */
     Failure         = -1,   /**< Failure */
-    OpNotSupported  = -2,   /**< Option Not Supported */
-};
-/**
- * @}
- */
-
-/**
- * @defgroup RadioType
- * @{
- */
-/**
- * RadioType 
- */
-enum RadioType {
-    Unknown     = 0,        /**< Not detected yet */
-    XB24_A_S1   = 0x17,     /**< S1 */
-    XBP24_A_S1  = 0x18,     /**< S1 */
-    XB24_B_S2   = 0x19,     /**< S2 */
-    XBP24_B_S2  = 0x1A,     /**< S2 */
-    XBP09_D     = 0x1B,     /**< S4 */
-    XBP09_XC    = 0x1C,     /**< S3 */
-    XBP08_D     = 0x1D,     /**< 868MHz S5 */
-    XBP24_B_S2B = 0x1E,     /**< S2B */
-    XB24_WF     = 0x1F,     /**< S6 */
-    XBP24_C_SMT = 0x21,     /**< XBee PRO SMT S2C */
-    XB24_C_SMT  = 0x22,     /**< XBee SMT S2C */
-    XBP09_XC_B  = 0x23,     /**< S3B */
-    XBP09_B     = 0x23,     /**< S3B */
-    XB8         = 0x24,     /**< S8 */
-    XB2B_WF_TH  = 0x27,     /**< S6B TH */
-    XB2B_WF_SMT = 0x28,     /**< S6B SMT */
-    XBP24_C_TH  = 0x2D,     /**< S2C TH */
-    XB24_C_TH   = 0x2E,     /**< S2C TH */
 };
 /**
  * @}
@@ -95,7 +62,7 @@
  * @{
  */
 /**
- * TxStatus 
+ * TxStatus
  */
 enum TxStatus {
     TxStatusSuccess            = 0,     /**< Success */
@@ -124,46 +91,11 @@
  */
 
 /**
- * @defgroup PmMode
- * @{
- */
-/**
- * PmMode 
- */
-enum PmMode {
-    SleepDisabled       = 0,  /**< SleepDisabled */
-    PinSleep            = 1,  /**< PinSleep */
-    PinDoze             = 2,  /**< PinDoze */
-    CyclicSeleep        = 4,  /**< CyclicSeleep */
-    CyclicSeleepPinW    = 5,  /**< CyclicSeleepPinW */
-};
-/**
- * @}
- */
- 
- /**
- * @defgroup NetworkRole
- * @{
- */
-/**
- * NetworkRole 
- */
-enum NetworkRole {
-    UnknownRole,            /**< Unknown Role */
-    Coordinator,            /**< Coordinator */
-    Router,                 /**< Router */
-    EndDevice,              /**< EndDevice */
-};
-/**
- * @}
- */
-
-/**
  * @defgroup RadioLocation
  * @{
  */
 /**
- * RadioLocation 
+ * RadioLocation
  */
 enum RadioLocation {
     RadioLocal     = 0,     /**< Local Radio */
@@ -172,7 +104,7 @@
 /**
  * @}
  */
- 
+
 /** Parent Class for XBee modules, not to be directly used */
 class XBee
 {
@@ -187,16 +119,14 @@
     RadioStatus wait_for_module_to_reset(volatile uint16_t *rst_cnt_p, uint16_t init_rst_cnt);
 
     protected:
-    /** timer used by local and remote objects */
-    static Timer        _timer;
-
     /** buffer to store the received frames */
-    static FrameBuffer _framebuf;
+    static FrameBuffer _framebuf_app;
+    static FrameBuffer _framebuf_syncr;
 
     public:
- 
+
         /**
-         * RadioMode 
+         * RadioMode
          */
         enum RadioMode {
             ModeUnknown     = 0,  /**< Unknown */
@@ -216,11 +146,11 @@
          * to this baud rate (ATBD parameter). By default it is configured to 9600 bps
          * */
         XBee(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600);
- 
+
         XBee(const XBee& other); /* Intentionally not implemented */
         /** Class destructor */
         virtual ~XBee();
-        
+
         /** init-  initializes object
          * This function must be called just after creating the object so it initializes internal data.
          * @returns
@@ -235,12 +165,6 @@
          */
         uint64_t get_addr64() const;
 
-        /** get_addr16 - returns the 16bit address of the local device
-         *
-         *  @returns the 16-bit address of the local device.
-         */
-        uint16_t get_addr16() const;
-
         /** get_network_address - gets the 16bit network address of the device
          *
          *  @param addr pointer where the device 16bit network address will be stored
@@ -266,8 +190,8 @@
          *     Failure otherwise
          */
         RadioStatus software_reset();
- 
-        /** device_reset - performs a hardware reset if there is a GPIO connected to the 
+
+        /** device_reset - performs a hardware reset if there is a GPIO connected to the
          * reset line of the device. Otherwise, performs a firmware reset.
          *
          *  @returns
@@ -279,12 +203,6 @@
 #endif
         RadioStatus device_reset();
 
-        /** get_radio_type - returns the type of radio, in most cases the hardware version
-         *
-         *  @returns the radio type
-         */
-        RadioType get_radio_type() const;
-
         /** set_tx_options - sets the transmit options byte, used with the transmit frames.
          *                   Valid flags are:
          *                       - DISABLE_RETRIES_AND_ROUTE_REPAIR
@@ -295,24 +213,11 @@
          */
         void set_tx_options(uint8_t options);
 
-        /** set_broadcast_radius - sets the max number of hops for a broadcast msg.
-         *                         When set to 0 uses the maximum possible.
-         *
-         *  @param bc_radius variable with the broadcast radious
-         */
-        void set_broadcast_radius(uint8_t bc_radius);
-
         /** get_tx_options - returns the tx options byte configured in the library.
          *
          *  @returns the tx options byte configured in the library.
          */
         uint8_t get_tx_options() const;
-        
-        /** get_bc_radius - returns the broadcast radius configured in the library.
-         *
-         *  @returns the broadcast radius configured in the library.
-         */
-        uint8_t get_bc_radius() const;
 
         /************************ Configuration member methods *************************/
         /** write_config - write settings to non volatile memory
@@ -322,7 +227,7 @@
          *     Failure otherwise
          */
         RadioStatus write_config();
-       
+
         /** config_io_sample_destination - configures to which node a remote module will send its IO Samples to.
          * @Note: this will modify 'remote' DH and DL parameters, if the remote node is configured in transparent mode this could lead to unwanted behavior.
          * Consult the module's reference manual for more information.
@@ -362,13 +267,13 @@
          *     Failure otherwise
          */
         RadioStatus get_power_level(uint8_t * const level);
-        
+
         /** get_hw_version - gets the hardware version of the radio
          *
          *  @returns the hardware version of the radio
          */
         uint16_t get_hw_version() const;
-        
+
         /** get_fw_version - gets the firmware version of the radio
          *
          *  @returns the firmware version of the radio
@@ -393,9 +298,28 @@
          */
         RadioStatus get_node_identifier(char * const node_id);
 
+        /** enable_network_encryption - Enable network encryption.
+         *
+         *  @param enable whether to enable this feature or not
+         *  @returns
+         *     Success if the operation was successful,
+         *     Failure otherwise
+         */
+        RadioStatus enable_network_encryption(bool enable);
+
+        /** set_network_encryption_key - Sets the 128-bit AES key used for encryption and decryption. Setting it to 0 will cause the coordinator to transmit the network key in the clear to joining devices, and will cause joining devices to acquire the network key in the clear when joining.
+         *  It is not recommended to set the key programmatically, because it could be read through the raw serial port bits.
+         *  @param key pointer to the 128-bit AES key
+         *  @param length size of the buffer pointed by 'key'
+         *  @returns
+         *     Success if the operation was successful,
+         *     Failure otherwise
+         */
+        RadioStatus set_network_encryption_key(const uint8_t * const key, const uint16_t length);
+
         /** start_node_discovery - starts a node discovery operation. The responses
          * have to be processes on the callback function that have to be registered
-         * for that purpose
+         * for that purpose.
          *
          *  @returns
          *     Success if the operation was successful,
@@ -403,6 +327,11 @@
          */
         RadioStatus start_node_discovery();
 
+        /** is_node_discovery_in_progress - checks if node discovery is in progress.
+         *  @returns true if node discovery is in progress, false otherwise
+         */
+        bool is_node_discovery_in_progress();
+
 #define XBEEZB_ND_OPTION_APPEND_DD          (1 << 0)
 #define XBEEZB_ND_OPTION_SELF_RESPONSE      (1 << 1)
 #define XBEE802_ND_OPTION_SELF_RESPONSE     (1 << 0)
@@ -437,7 +366,7 @@
          *  @param timeout_ms new timeout in ms
          */
         void set_timeout(uint16_t timeout_ms);
-        
+
         /** get_timeout - gets the timeout in ms configured in the library. This value
          *                is used in sync commands
          *
@@ -445,7 +374,7 @@
          */
         uint16_t get_timeout() const;
 
-        /* ... */     
+        /* ... */
 
         /*********************** send_data member methods ************************/
         /** send_data - sends data to a remote device
@@ -459,7 +388,7 @@
          *     the error code otherwise
          */
         virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true) = 0;
-        
+
         /** send_data_broadcast - sends data to all devices in the network, using the broadcast address.
          *
          *  @param data pointer to the data that will be sent
@@ -470,7 +399,7 @@
          *     the error code otherwise
          */
         TxStatus send_data_broadcast(const uint8_t *const data, uint16_t len, bool syncr = true);
-        
+
         /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response.
          *
          *  @param param parameter to be set.
@@ -478,29 +407,29 @@
          *  @returns the command response status.
          */
         AtCmdFrame::AtCmdResp set_param(const char * const param, uint32_t data);
-        
+
         /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response.
          *
          *  @param param parameter to be set.
-         *  @param data the parameter value byte array (len bytes) to be set. 
-         *  @param len number of bytes of the parameter value. 
+         *  @param data the parameter value byte array (len bytes) to be set.
+         *  @param len number of bytes of the parameter value.
          *  @returns the command response status.
          */
         AtCmdFrame::AtCmdResp set_param(const char * const param, const uint8_t * data = NULL, uint16_t len = 0);
-        
+
         /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response.
          *
          *  @param param parameter to be get.
-         *  @param data pointer where the param value (4 bytes) will be stored. 
+         *  @param data pointer where the param value (4 bytes) will be stored.
          *  @returns the command response status.
          */
         AtCmdFrame::AtCmdResp get_param(const char * const param, uint32_t * const data);
-      
+
         /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response.
          *
          *  @param param parameter to be get.
-         *  @param data pointer where the param value (n bytes) will be stored. 
-         *  @param len pointer where the number of bytes of the param value will be stored. 
+         *  @param data pointer where the param value (n bytes) will be stored.
+         *  @param len pointer where the number of bytes of the param value will be stored.
          *  @returns the command response status.
          */
         AtCmdFrame::AtCmdResp get_param(const char * const param, uint8_t * const data, uint16_t * const len);
@@ -513,110 +442,37 @@
          *  @returns the command response status.
          */
         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data) = 0;
-        
+
         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
          *
          *  @param remote remote device
          *  @param param parameter to be set.
-         *  @param data the parameter value byte array (len bytes) to be set. 
+         *  @param data the parameter value byte array (len bytes) to be set.
          *  @param len number of bytes of the parameter value.
          *  @returns the command response status.
          */
         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0) = 0;
-        
+
         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
          *
          *  @param remote remote device
          *  @param param parameter to be get.
-         *  @param data pointer where the param value (4 bytes) will be stored. 
+         *  @param data pointer where the param value (4 bytes) will be stored.
          *  @returns the command response status.
          */
         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data) = 0;
-      
+
         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
          *
          *  @param remote remote device
          *  @param param parameter to be get.
-         *  @param data pointer where the param value (n bytes) will be stored. 
-         *  @param len pointer where the number of bytes of the param value will be stored. 
+         *  @param data pointer where the param value (n bytes) will be stored.
+         *  @param len pointer where the number of bytes of the param value will be stored.
          *  @returns the command response status.
          */
         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len) = 0;
 
-#if defined(ENABLE_PM_SUPPORT)
-        /** set_pm_control - sets the operational mode of the Power Management on
-         *                   the radio and registers the GPIOs used to handle the
-         *                   Power Management
-         *
-         *  @param mode operational mode of the power management
-         *  @param on_sleep pin used to detect the on/sleep status of the module
-         *  @param sleep_rq pin used to request the module to go to sleep (when pin
-         *         sleep mode is used
-         *  @returns the result of the configuration operation
-         *     Success if the operation was successful,
-         *     Failure otherwise
-         */
-         RadioStatus set_pm_control(PmMode mode, PinName on_sleep = NC, PinName sleep_rq = NC);
-
-        /** get_pm_mode - gets the power management mode programmed in the radio.
-         *
-         *  @param mode pointer where the read mode will be stored.
-         *  @returns the result of the configuration operation
-         *     Success if the operation was successful,
-         *     Failure otherwise
-         */
-         RadioStatus get_pm_mode(PmMode *mode);
-
-        /** config_pm_timing - configures the power management timing parameters.
-         *
-         *  @param before_sleep_ms number of miliseconds of inactivity before the radio will
-         *                         automatically go to sleep again (when using cyclic sleep).
-         *  @param total_sleep_period_ms time interval in ms the radio will be sleeping. Once
-         *                               this time passes, the radio will wakeup, will check for
-         *                               packets and will wait before_sleep_ms of inactivity
-         *                               before entering again in sleep mode.
-         *  @returns the result of the configuration operation
-         *     Success if the operation was successful,
-         *     Failure otherwise
-         */
-         RadioStatus config_pm_timing(uint32_t before_sleep_ms, uint32_t total_sleep_period_ms);
-
-        /** enter_sleep_mode - sets the radio into low power mode. If the pm working mode
-         *                     is pin-sleep, then it will use the GPIO, otherwise, it will
-         *                     use the serial interface.
-         *
-         *  @note the method does not wait until the radio enters in sleep mode, it returns
-         *        without making any verification.
-         *  @returns the result of the operation
-         *     Success if the operation was successful,
-         *     Failure otherwise
-         */
-         RadioStatus enter_sleep_mode();
-
-        /** exit_sleep_mode - for the pm mode called pin-sleep, sets the radio into active power
-         *                    using the corresponding GPIO.
-         *
-         */
-         void exit_sleep_mode();
-
-        /** is_sleeping - checks if the radio is sleeping or if its active.
-         *
-         *  @returns true if the radio is sleeping, false otherwisw
-         */
-         bool is_sleeping();
-         
-        /** register_wakeup_cb - registers the callback function that will be called
-         *                       when the radio wakes up from sleep mode.
-         *
-         *  @param f function pointer with the callback function
-         */
-        void register_wakeup_cb(void (*f)(void));
-
-        /** unregister_wakeup_cb - removes the wakeup callback */
-        void unregister_wakeup_cb();
-#endif  /* defined(ENABLE_PM_SUPPORT) */
-
-        /** process_rx_frames - method that process the frames queued in the reception
+        /** process_rx_frames - method that processes the frames queued in the reception
          *                      buffer. Calls the process_frame_data method of the frame
          *                      handlers registered
          *
@@ -648,20 +504,20 @@
             ZNet,
 #endif
         };
-        /** send_byte_escaping_if - sends a byte, through the serial interface, to 
+        /** send_byte_escaping_if - sends a byte, through the serial interface, to
          * the radio, escaping the byte if the working mode of the radio is API2.
          *
          *  @param line PWM line being set
          *  @param data the byte that will be send to radio
          */
         void send_byte_escaping_if(uint8_t data);
-    
+
         /** uart_read_cb - serial interface callback, called when data is received on
          * the serial port. The function parses the incoming data and, when a good
          * frame is detected, saves it in the frame list
          */
         void uart_read_cb();
-    
+
         /** get_this_api_frame - searches in the FrameBuffer for an incoming frame
          *                       with frameid equal to id and frame type equal to type
          *                       or type2. If after timeout the frame hast not been found,
@@ -670,14 +526,14 @@
          *  @param id id of the frame we are looking for.
          *  @param type tye type we expect the frame to be.
          *  @param type2 alternative valid type, if provided.
-         *  @returns a pointer to the frame found in the FrameBuffer or a null pointer if 
+         *  @returns a pointer to the frame found in the FrameBuffer or a null pointer if
          *           the frame has not been found and the timeout expired.
          */
-        ApiFrame * get_this_api_frame(uint8_t id, ApiFrame::ApiFrameType type, 
+        ApiFrame * get_this_api_frame(uint8_t id, ApiFrame::ApiFrameType type,
                     ApiFrame::ApiFrameType type2 = ApiFrame::Invalid);
 
         /** send_api_frame - method to send, over the serial port, an API frame
-         * 
+         *
          * @param frame pointer to the frame that will be sent.
          */
 #if defined(UNIT_TEST)
@@ -687,15 +543,15 @@
 
         /** update_radio_status - method called when a modem status frame is received
          *  to update the internal status variables of the library.
-         *  @note This is not a pure virtual function because it can be called while 
+         *  @note This is not a pure virtual function because it can be called while
          *        the object is being constructed and we need the implementation of the
-         *        base class.         
+         *        base class.
          *
          *  @param status byte with the status received in the modem status frame
          */
         virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status);
-        
-        /** Method used internaly by the derived classes to transmit data to 
+
+        /** Method used internaly by the derived classes to transmit data to
          * remote nodes, waiting for the answer from the device
          *
          *  @param frame frame that will be sent to the radio (have to be a
@@ -709,25 +565,20 @@
         /** send_at_cmd - sends an AT command to the radio and waits for the response.
          *
          *  @param frame api frame with the command and command params.
-         *  @param buf pointer where the param response (n bytes) will be stored. 
-         *  @param len pointer where the number of bytes of the param response will be stored. 
-         *  @param radio_location radio location, either RadioLocal or RadioRemote. 
-         *  @param reverse reverse the byte ordering of the response saved in buf. 
+         *  @param buf pointer where the param response (n bytes) will be stored.
+         *  @param len pointer where the number of bytes of the param response will be stored.
+         *  @param radio_location radio location, either RadioLocal or RadioRemote.
+         *  @param reverse reverse the byte ordering of the response saved in buf.
          *  @returns the command response status.
          */
         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame,
                     uint8_t *const buf, uint16_t *const len, RadioLocation radio_location = RadioLocal, bool reverse = true);
-                    
+
         /* send_at_cmd - methods used internally by other methods */
         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame);
         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint8_t *data);
         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint16_t *data);
         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint32_t *data);
-        
-#if defined(ENABLE_PM_SUPPORT)
-        /** Sets the radio into low power mode. This method is used by enter_sleep_mode() */
-        RadioStatus sleep_now();
-#endif  /* defined(ENABLE_PM_SUPPORT) */
 
         /** register_frame_handler - registers an object to handle incoming frames from
          *                           the radio.
@@ -777,15 +628,20 @@
          */
         bool check_radio_flow_control();
 
+        /** get_AI - reads the AI parameter.
+         *
+         *  @returns
+         *      -1 if an error occurred when reading AI.
+         *      0-0xFF the AI value.
+         */
+        int get_AI(void);
+
         /** serial hardware flow control selected by the user (RTSCTS, RTS,CTS) */
         SerialBase::Flow _serial_flow_type;
 
         /** Operating mode of the module (API1, API2,...) */
         RadioMode   _mode;
 
-        /** Type of radio, mainly the hardware version, but may differ in some cases */
-        RadioType   _type;
-        
         /** Hardware version value of the radio */
         uint16_t    _hw_version;
 
@@ -793,28 +649,22 @@
         uint16_t    _fw_version;
 
         /** Timeout in ms for sync operations (when we wait for a response) */
-        uint16_t    _timeout_ms;     
+        uint16_t    _timeout_ms;
 
         /** Device 64 bit address (SH, SL) */
         uint64_t      _dev_addr64;
 
-        /** Device 16 bit address (MY) */        
-        uint16_t    _dev_addr16;
-       
         /** Serial Interface, use RawSerial as we dont use the streams */
         RawSerial   *_uart;
 
         /** IO connected to the radio reset line */
-        DigitalOut  *_reset;         
-        
+        DigitalOut  *_reset;
+
         /** Transmit options byte */
         uint8_t     _tx_options;
 
-        /** Broadcast radius, number of hops a broadcast transmission can occur.
-         *  When set to 0 it will use the maximum */
-        uint8_t     _bc_radius;
-        /** Array of frame handler pointers. We use an array instead of a vector or other 
-         *  data structure to save memory and avoid dynamic memory allocation, to avoid 
+        /** Array of frame handler pointers. We use an array instead of a vector or other
+         *  data structure to save memory and avoid dynamic memory allocation, to avoid
          *  memory fragmentation */
         FrameHandler *_fhandlers[MAX_FRAME_HANDLERS];
 
@@ -824,8 +674,6 @@
         /** Watchdog reset counter, automatically updated by the library */
         volatile uint16_t    _wd_reset_cnt;
 
-        uint16_t    _reset_timeout;
-
         /** Frame handler used for the Modem Status packets. Automatically registered when a callback
          *  function is registered */
         FH_ModemStatus  *_modem_status_handler;
@@ -836,14 +684,14 @@
         /** Library is initializing */
         bool _initializing;
 
-#if defined(ENABLE_PM_SUPPORT)
-        /* Power Management mode used by the radio */
-        PmMode      _pm_mode;
-        /** IO connected to the radio on_sleep line */
-        InterruptIn *_on_sleep;         
-        /** IO connected to the radio sleep_req line */
-        DigitalOut  *_sleep_req;
-#endif
+        /** Timer used for node discovery */
+        Timer _nd_timer;
+
+        /** node discovery timeout */
+        int _nd_timeout;
+
+        /** If a _get_remote_node_by_id() is in progress, this keeps the expected frame id */
+        uint8_t _node_by_ni_frame_id;
 };
 
 }   /* namespace XBeeLib */