XBee.h

00001 /**
00002  * Copyright (c) 2015 Digi International Inc.,
00003  * All rights not expressly granted are reserved.
00004  *
00005  * This Source Code Form is subject to the terms of the Mozilla Public
00006  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
00007  * You can obtain one at http://mozilla.org/MPL/2.0/.
00008  *
00009  * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343
00010  * =======================================================================
00011  */
00012 
00013 #if !defined(__DIGI_RADIO_H_)
00014 #define __DIGI_RADIO_H_
00015 
00016 #include <stdint.h>
00017 #include "config.h"
00018 #include "Utils/Debug.h"
00019 #include "Frames/AtCmdFrame.h"
00020 #include "FrameHandlers/FrameHandler.h"
00021 #include "FrameHandlers/FH_ModemStatus.h"
00022 #include "FrameBuffer/FrameBuffer.h"
00023 #include "Addresses.h"
00024 #include "RemoteXBee/RemoteXBee.h"
00025 #include "IO/IO.h"
00026 
00027 #define MAX_FRAME_HANDLERS      4
00028 #define RESET_TIMEOUT_MS        5000
00029 
00030 #define DR_API_FRAME_OVERHEAD   4       /* Start of frame + frame len + checksum */
00031 #define DR_MIN_API_FRAME_LEN    4
00032 #define DR_START_OF_FRAME       0x7E
00033 #define DR_ESCAPE_BYTE          0x7D
00034 #define DR_XON_BYTE             0x11
00035 #define DR_XOFF_BYTE            0x13
00036 #define DR_ESCAPE_XOR_BYTE      0x20
00037 
00038 /* TODO, verify these flags work in all modules */
00039 #define DISABLE_RETRIES_AND_ROUTE_REPAIR    0x01
00040 #define ENABLE_APS_ENCRYPTION               0x20
00041 #define USE_EXTENDED_TX_TIMEOUT             0x40
00042 
00043 /* XbeeLib Configurations *** CHANGE HERE *** */
00044 #define FRAME_BUFFER_SIZE 16         
00045 #define MAX_FRAME_PAYLOAD_LEN 256   // MAX 256 (type uint8_t)
00046 #define SYNC_OPS_TIMEOUT_MS 2000
00047 
00048 namespace XBeeLib {
00049 
00050 /**
00051  * @defgroup RadioStatus
00052  * @{
00053  */
00054 /**
00055  * RadioStatus
00056  */
00057 enum RadioStatus {
00058     Success         = 0,    /**< Success */
00059     Failure         = -1,   /**< Failure */
00060 };
00061 /**
00062  * @}
00063  */
00064 
00065 /**
00066  * @defgroup TxStatus
00067  * @{
00068  */
00069 /**
00070  * TxStatus
00071  */
00072 enum TxStatus {
00073     TxStatusSuccess            = 0,     /**< Success */
00074     TxStatusAckFail            = 1,     /**< MAC ACK Failure */
00075     TxStatusCCAFail            = 2,     /**< CCA Failure */
00076     TxStatusInvDestEP          = 0x15,  /**< Invalid destination endpoint */
00077     TxStatusNwAckFail          = 0x21,  /**< Network ACK Failure */
00078     TxStatusNotJoinNw          = 0x22,  /**< Not Joined to Network */
00079     TxStatusSelfAddr           = 0x23,  /**< Self-addressed */
00080     TxStatusAddrNotFound       = 0x24,  /**< Address Not Found */
00081     TxStatusRouteNotFound      = 0x25,  /**< Route Not Found */
00082     TxStatusBroadSrcFail2Heard = 0x26,  /**< Broadcast source failed to hear a neighbor relay the message */
00083     TxStatusInvBindTableIdx    = 0x2B,  /**< Invalid binding table index */
00084     TxStatusResourceError      = 0x2C,  /**< Resource error lack of free buffers, timers, etc. */
00085     TxStatusAttBroadcWithAPS   = 0x2D,  /**< Attempted broadcast with APS transmission */
00086     TxStatusAttUnicWithAPSEE0  = 0x2E,  /**< Attempted unicast with APS transmission, but EE=0 */
00087     TxStatusResourceError2     = 0x31,  /**< TxStatusResourceError2 */
00088     TxStatusInternalError      = 0x32,  /**< Resource error lack of free buffers, timers, etc. */
00089     TxStatusPayloadTooLarge    = 0x74,  /**< Data payload too large */
00090     TxStatusIndirectMsgUnReq   = 0x75,  /**< Indirect message unrequested */
00091     TxStatusInvalidAddr        = 0xfe,  /**< Invalid Address (Error generated by the library) */
00092     TxStatusTimeout            = 0xff,  /**< Timeout (Error generated by the library) */
00093 };
00094 /**
00095  * @}
00096  */
00097 
00098 /**
00099  * @defgroup RadioLocation
00100  * @{
00101  */
00102 /**
00103  * RadioLocation
00104  */
00105 enum RadioLocation {
00106     RadioLocal     = 0,     /**< Local Radio */
00107     RadioRemote    = 1,     /**< Remote Radio */
00108 };
00109 /**
00110  * @}
00111  */
00112 
00113 /** Parent Class for XBee modules, not to be directly used */
00114 class XBee
00115 {
00116     private:
00117     /** wait_for_module_to_reset - waits until a Modem Status packet with a reset status
00118      * is received, or the timeout expires.
00119      *
00120      *  @returns
00121      *     Success if a Modem Status was received,
00122      *     Failure otherwise
00123      */
00124     RadioStatus wait_for_module_to_reset(volatile uint16_t *rst_cnt_p, uint16_t init_rst_cnt);
00125 
00126     protected:
00127     /** buffer to store the received frames */
00128     static FrameBuffer _framebuf_app;
00129     static FrameBuffer _framebuf_syncr;
00130 
00131     public:
00132 
00133         /**
00134          * RadioMode
00135          */
00136         enum RadioMode {
00137             ModeUnknown     = 0,  /**< Unknown */
00138             ModeAPI1        = 1,  /**< API1 */
00139             ModeAPI2        = 2,  /**< API2 */
00140             ModeTransparent = 3,  /**< Transparent */
00141             ModeBootloader  = 4,  /**< Bootloader */
00142         };
00143 
00144         /** Class constructor
00145          * @param tx the TX pin of the UART that will interface the XBee module
00146          * @param rx the RX pin of the UART that will interface the XBee module
00147          * @param reset the pin to which the XBee's reset line is attached to, use NC if not available
00148          * @param rts the RTS pin for the UART that will interface the XBee module, use NC if not available
00149          * @param cts the CTS pin for the UART that will interface the XBee module, use NC if not available
00150          * @param baud the baudrate for the UART that will interface the XBee module. Note that the module has to be already configured
00151          * to this baud rate (ATBD parameter). By default it is configured to 9600 bps
00152          * */
00153         XBee(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600);
00154 
00155         XBee(const XBee& other); /* Intentionally not implemented */
00156         /** Class destructor */
00157         virtual ~XBee();
00158 
00159         /** init-  initializes object
00160          * This function must be called just after creating the object so it initializes internal data.
00161          * @returns
00162          *         Success if the module has been properly initialized and is ready to process data.
00163          *         Failure otherwise.
00164          */
00165         RadioStatus init();
00166 
00167         /** get_addr64 - returns the 64bit address of the local device
00168          *
00169          *  @returns the 64bit address of the local device
00170          */
00171         uint64_t get_addr64() const;
00172 
00173         /** hardware_reset - performs a hardware reset. The reset GPIO must have
00174          * been provided to the constructor
00175          *
00176          *  @returns
00177          *     Success if the operation was successful,
00178          *     Failure otherwise
00179          */
00180         RadioStatus hardware_reset();
00181 
00182         /** software_reset - performs a firmware reset
00183          *
00184          *  @returns
00185          *     Success if the operation was successful,
00186          *     Failure otherwise
00187          */
00188         RadioStatus software_reset();
00189 
00190         /** device_reset - performs a hardware reset if there is a GPIO connected to the
00191          * reset line of the device. Otherwise, performs a firmware reset.
00192          *
00193          *  @returns
00194          *     Success if the operation was successful,
00195          *     Failure otherwise
00196          */
00197 #if defined(UNIT_TEST)
00198         virtual
00199 #endif
00200         RadioStatus device_reset();
00201 
00202         /** set_tx_options - sets the transmit options byte, used with the transmit frames.
00203          *                   Valid flags are:
00204          *                       - DISABLE_RETRIES_AND_ROUTE_REPAIR
00205          *                       - ENABLE_APS_ENCRYPTION
00206          *                       - USE_EXTENDED_TX_TIMEOUT
00207          *
00208          *  @param options variable with the option flags
00209          */
00210         void set_tx_options(uint8_t options);
00211 
00212         /** get_tx_options - returns the tx options byte configured in the library.
00213          *
00214          *  @returns the tx options byte configured in the library.
00215          */
00216         uint8_t get_tx_options() const;
00217 
00218         /************************ Configuration member methods *************************/
00219         /** write_config - write settings to non volatile memory
00220          *
00221          *  @returns
00222          *     Success if the operation was successful,
00223          *     Failure otherwise
00224          */
00225         RadioStatus write_config();
00226 
00227         /** config_io_sample_destination - configures to which node a remote module will send its IO Samples to.
00228          * @Note: this will modify 'remote' DH and DL parameters, if the remote node is configured in transparent mode this could lead to unwanted behavior.
00229          * Consult the module's reference manual for more information.
00230          *
00231          *  @param remote remote device that will be sending the IO Samples
00232          *  @param destination remote device that will be receiving the IO Samples sent by 'remote'
00233          *  @returns the result of the data transfer
00234          *     Success if the operation was successful,
00235          *     Failure otherwise
00236          */
00237         RadioStatus config_io_sample_destination(const RemoteXBee& remote, const RemoteXBee& destination);
00238 
00239         /** set_io_sample_rate - configures how often the IO Samples should be sent to the destination (see @ref send_io_sample_to).
00240          *
00241          *  @param remote remote device that will be sending the IO Samples
00242          *  @param seconds the IO Sample sending rate in seconds (granularity is of 1 millisecond). Maximum is 65.535 seconds.
00243          *  @returns the result of the data transfer
00244          *     Success if the operation was successful,
00245          *     Failure otherwise
00246          */
00247         RadioStatus set_io_sample_rate(const RemoteXBee& remote, float seconds);
00248 
00249         /** set_power_level - sets the power level at which the radio will transmit
00250          *
00251          *  @param level power level at which the radio will transmit
00252          *  @returns
00253          *     Success if the operation was successful,
00254          *     Failure otherwise
00255          */
00256         RadioStatus set_power_level(uint8_t level);
00257 
00258         /** get_power_level - reads the power level configured in the radio
00259          *
00260          *  @param level pointer where the read power level will be stored
00261          *  @returns
00262          *     Success if the operation was successful,
00263          *     Failure otherwise
00264          */
00265         RadioStatus get_power_level(uint8_t * const level);
00266 
00267         /** get_hw_version - gets the hardware version of the radio
00268          *
00269          *  @returns the hardware version of the radio
00270          */
00271         uint16_t get_hw_version() const;
00272 
00273         /** get_fw_version - gets the firmware version of the radio
00274          *
00275          *  @returns the firmware version of the radio
00276          */
00277         uint16_t get_fw_version() const;
00278 
00279         /** set_node_identifier - configures the Node Identifier string
00280          *
00281          *  @param node_id NULL-terminated string with the Node Identifier that will be set on the module. Up to 20 characters length (21 with NULL-terminator).
00282          *  @returns
00283          *     Success if the operation was successful,
00284          *     Failure otherwise
00285          */
00286         RadioStatus set_node_identifier(const char * const node_id);
00287 
00288         /** get_node_identifier - reads the configured Node Identifier string
00289          *
00290          *  @param node_id Pointer to where to store the read Node Identifier, it must point to a buffer with at least 21-bytes length.
00291          *  @returns
00292          *     Success if the operation was successful,
00293          *     Failure otherwise
00294          */
00295         RadioStatus get_node_identifier(char * const node_id);
00296 
00297         /** enable_network_encryption - Enable network encryption.
00298          *
00299          *  @param enable whether to enable this feature or not
00300          *  @returns
00301          *     Success if the operation was successful,
00302          *     Failure otherwise
00303          */
00304         RadioStatus enable_network_encryption(bool enable);
00305 
00306         /** 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.
00307          *  It is not recommended to set the key programmatically, because it could be read through the raw serial port bits.
00308          *  @param key pointer to the 128-bit AES key
00309          *  @param length size of the buffer pointed by 'key'
00310          *  @returns
00311          *     Success if the operation was successful,
00312          *     Failure otherwise
00313          */
00314         RadioStatus set_network_encryption_key(const uint8_t * const key, const uint16_t length);
00315 
00316         /** start_node_discovery - starts a node discovery operation. The responses
00317          * have to be processes on the callback function that have to be registered
00318          * for that purpose.
00319          *
00320          *  @returns
00321          *     Success if the operation was successful,
00322          *     Failure otherwise
00323          */
00324         RadioStatus start_node_discovery();
00325 
00326         /** is_node_discovery_in_progress - checks if node discovery is in progress.
00327          *  @returns true if node discovery is in progress, false otherwise
00328          */
00329         bool is_node_discovery_in_progress();
00330 
00331 #define XBEEZB_ND_OPTION_APPEND_DD          (1 << 0)
00332 #define XBEEZB_ND_OPTION_SELF_RESPONSE      (1 << 1)
00333 #define XBEE802_ND_OPTION_SELF_RESPONSE     (1 << 0)
00334 #define XBEEDM_ND_OPTION_APPEND_DD          (1 << 0)
00335 #define XBEEDM_ND_OPTION_SELF_RESPONSE      (1 << 1)
00336 #define XBEEDM_ND_OPTION_INCLUDE_RSSI       (1 << 2)
00337 
00338         /** config_node_discovery - configures the node discovery operation
00339          *
00340          *  @param backoff_ms max allowed time for devices in the network to answer
00341          *                    to the Node Discovery request
00342          *  @param  options node discovery options (flags)
00343          *              XBEE802_ND_OPTION_SELF_RESPONSE - to allow the module self responding (802.15.4 only)
00344          *              XBEEZB_ND_OPTION_SELF_RESPONSE - to allow the module self responding (ZigBee only)
00345          *              XBEEZB_ND_OPTION_APPEND_DD - to append the DD value to the response (ZigBee only)
00346          *              XBEEDM_ND_OPTION_INCLUDE_RSSI - to include RSSI information in response (DigiMesh only)
00347          *              XBEEDM_ND_OPTION_SELF_RESPONSE - to allow the module self responding (DigiMesh only)
00348          *              XBEEDM_ND_OPTION_APPEND_DD - to append the DD value to the response (DigiMesh only)
00349          *  @returns
00350          *     Success if the operation was successful,
00351          *     Failure otherwise
00352          */
00353          RadioStatus config_node_discovery(uint16_t backoff_ms, uint8_t options = 0);
00354 
00355          /** get_config_node_discovery - reads the configuration of the node discovery
00356           * settings
00357           *
00358           *  @param backoff_ms pointer where the configured node discovery back-off time value will be stored
00359           *  @param  options pointer whre the node discovery options (flags) will be saved
00360           *  @returns
00361           *     Success if the operation was successful,
00362           *     Failure otherwise
00363           */
00364          RadioStatus get_config_node_discovery(uint16_t * const backoff_ms, uint8_t * const options);
00365 
00366         /** set_timeout - sets the timeout in ms, used by sync methods
00367          *
00368          *  @param timeout_ms new timeout in ms
00369          */
00370         void set_timeout(uint16_t timeout_ms);
00371 
00372         /** get_timeout - gets the timeout in ms configured in the library. This value
00373          *                is used in sync commands
00374          *
00375          *  @returns the configured timeout value in ms
00376          */
00377         uint16_t get_timeout() const;
00378 
00379         /* ... */
00380 
00381         /*********************** send_data member methods ************************/
00382         /** send_data - sends data to a remote device
00383          *
00384          *  @param remote remote device
00385          *  @param data pointer to the data that will be sent
00386          *  @param len number of bytes that will be transmitted
00387          *  @param syncr if true, method waits for the packet answer with the result of the operation
00388          *  @returns the result of the data transfer
00389          *     TxStatusSuccess if the operation was successful,
00390          *     the error code otherwise
00391          */
00392         virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true) = 0;
00393 
00394         /** send_data_broadcast - sends data to all devices in the network, using the broadcast address.
00395          *
00396          *  @param data pointer to the data that will be sent
00397          *  @param len number of bytes that will be transmitted
00398          *  @param syncr if true, method waits for the packet answer with the result of the operation
00399          *  @returns the result of the data transfer
00400          *     TxStatusSuccess if the operation was successful,
00401          *     the error code otherwise
00402          */
00403         TxStatus send_data_broadcast(const uint8_t *const data, uint16_t len, bool syncr = true);
00404 
00405         /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response.
00406          *
00407          *  @param param parameter to be set.
00408          *  @param data the parameter value (4 bytes) to be set.
00409          *  @returns the command response status.
00410          */
00411         AtCmdFrame::AtCmdResp set_param(const char * const param, uint32_t data);
00412 
00413         /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response.
00414          *
00415          *  @param param parameter to be set.
00416          *  @param data the parameter value byte array (len bytes) to be set.
00417          *  @param len number of bytes of the parameter value.
00418          *  @returns the command response status.
00419          */
00420         AtCmdFrame::AtCmdResp set_param(const char * const param, const uint8_t * data = NULL, uint16_t len = 0);
00421 
00422         /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response.
00423          *
00424          *  @param param parameter to be get.
00425          *  @param data pointer where the param value (4 bytes) will be stored.
00426          *  @returns the command response status.
00427          */
00428         AtCmdFrame::AtCmdResp get_param(const char * const param, uint32_t * const data);
00429 
00430         /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response.
00431          *
00432          *  @param param parameter to be get.
00433          *  @param data pointer where the param value (n bytes) will be stored.
00434          *  @param len pointer where the number of bytes of the param value will be stored.
00435          *  @returns the command response status.
00436          */
00437         AtCmdFrame::AtCmdResp get_param(const char * const param, uint8_t * const data, uint16_t * const len);
00438 
00439         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00440          *
00441          *  @param remote remote device
00442          *  @param param parameter to be set.
00443          *  @param data the parameter value (4 bytes) to be set.
00444          *  @returns the command response status.
00445          */
00446         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data) = 0;
00447 
00448         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00449          *
00450          *  @param remote remote device
00451          *  @param param parameter to be set.
00452          *  @param data the parameter value byte array (len bytes) to be set.
00453          *  @param len number of bytes of the parameter value.
00454          *  @returns the command response status.
00455          */
00456         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0) = 0;
00457 
00458         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00459          *
00460          *  @param remote remote device
00461          *  @param param parameter to be get.
00462          *  @param data pointer where the param value (4 bytes) will be stored.
00463          *  @returns the command response status.
00464          */
00465         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data) = 0;
00466 
00467         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00468          *
00469          *  @param remote remote device
00470          *  @param param parameter to be get.
00471          *  @param data pointer where the param value (n bytes) will be stored.
00472          *  @param len pointer where the number of bytes of the param value will be stored.
00473          *  @returns the command response status.
00474          */
00475         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len) = 0;
00476 
00477         /** process_rx_frames - method that processes the frames queued in the reception
00478          *                      buffer. Calls the process_frame_data method of the frame
00479          *                      handlers registered
00480          *
00481          *  @returns Number of dropped frames since latest call to this method.
00482          */
00483         uint32_t process_rx_frames();
00484 
00485         /** register_modem_status_cb - registers the callback function that will be called
00486          * when a Modem Status packet is received
00487          *
00488          *  @param function function pointer with the callback function
00489          */
00490         void register_modem_status_cb(modem_status_cb_t function);
00491 
00492         /** unregister_modem_status_cb - removes the Modem Status reception callback */
00493         void unregister_modem_status_cb();
00494 
00495     protected:
00496 
00497 #define EXTRA_XBEE_PROTOCOLS
00498 
00499         enum RadioProtocol {
00500             None,
00501             ZigBee,
00502             Raw_802_15_4,
00503 #ifdef EXTRA_XBEE_PROTOCOLS
00504             XBeeWiFi,
00505             DigiMesh,
00506             SmartEnergy,
00507             DigiPoint,
00508             ZNet,
00509 #endif
00510         };
00511         /** send_byte_escaping_if - sends a byte, through the serial interface, to
00512          * the radio, escaping the byte if the working mode of the radio is API2.
00513          *
00514          *  @param line PWM line being set
00515          *  @param data the byte that will be send to radio
00516          */
00517         void send_byte_escaping_if(uint8_t data);
00518 
00519         /** uart_read_cb - serial interface callback, called when data is received on
00520          * the serial port. The function parses the incoming data and, when a good
00521          * frame is detected, saves it in the frame list
00522          */
00523         void uart_read_cb();
00524 
00525         /** get_this_api_frame - searches in the FrameBuffer for an incoming frame
00526          *                       with frameid equal to id and frame type equal to type
00527          *                       or type2. If after timeout the frame hast not been found,
00528          *                       returns.
00529          *
00530          *  @param id id of the frame we are looking for.
00531          *  @param type tye type we expect the frame to be.
00532          *  @param type2 alternative valid type, if provided.
00533          *  @returns a pointer to the frame found in the FrameBuffer or a null pointer if
00534          *           the frame has not been found and the timeout expired.
00535          */
00536         ApiFrame * get_this_api_frame(uint8_t id, ApiFrame::ApiFrameType type,
00537                     ApiFrame::ApiFrameType type2 = ApiFrame::Invalid);
00538 
00539         /** send_api_frame - method to send, over the serial port, an API frame
00540          *
00541          * @param frame pointer to the frame that will be sent.
00542          */
00543 #if defined(UNIT_TEST)
00544         virtual
00545 #endif
00546         void send_api_frame(ApiFrame *frame);
00547 
00548         /** update_radio_status - method called when a modem status frame is received
00549          *  to update the internal status variables of the library.
00550          *  @note This is not a pure virtual function because it can be called while
00551          *        the object is being constructed and we need the implementation of the
00552          *        base class.
00553          *
00554          *  @param status byte with the status received in the modem status frame
00555          */
00556         virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status);
00557 
00558         /** Method used internaly by the derived classes to transmit data to
00559          * remote nodes, waiting for the answer from the device
00560          *
00561          *  @param frame frame that will be sent to the radio (have to be a
00562          *         proper transmit frame
00563          *  @returns the result of the data transfer
00564          *     TxStatusSuccess if the operation was successful,
00565          *     the error code otherwise
00566          */
00567         TxStatus send_data(ApiFrame *frame);
00568 
00569         /** send_at_cmd - sends an AT command to the radio and waits for the response.
00570          *
00571          *  @param frame api frame with the command and command params.
00572          *  @param buf pointer where the param response (n bytes) will be stored.
00573          *  @param len pointer where the number of bytes of the param response will be stored.
00574          *  @param radio_location radio location, either RadioLocal or RadioRemote.
00575          *  @param reverse reverse the byte ordering of the response saved in buf.
00576          *  @returns the command response status.
00577          */
00578         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame,
00579                     uint8_t *const buf, uint16_t *const len, RadioLocation radio_location = RadioLocal, bool reverse = true);
00580 
00581         /* send_at_cmd - methods used internally by other methods */
00582         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame);
00583         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint8_t *data);
00584         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint16_t *data);
00585         AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint32_t *data);
00586 
00587         /** register_frame_handler - registers an object to handle incoming frames from
00588          *                           the radio.
00589          *  @note For any type of frame more than one handler can be registered and all
00590          *        of them are called, sequentially, when a frame of that type arrives.
00591          *
00592          *  @param handler pointer to the frame handler object
00593          *  @returns the result of the registration
00594          *     Success if the operation was successful,
00595          *     Failure otherwise
00596          */
00597         RadioStatus register_frame_handler(FrameHandler *const handler);
00598 
00599         /** unregister_frame_handler - removes a previously registered frame handler
00600          *
00601          *  @param handler pointer to the frame handler object
00602          *  @returns the result of the unregister operation
00603          *     Success if the operation was successful,
00604          *     Failure otherwise
00605          */
00606         RadioStatus unregister_frame_handler(FrameHandler *const handler);
00607 
00608         /** get_radio_protocol - returns the RF protocol that the connected module uses
00609          *                       based on its firmware and hardware versions
00610          *
00611          *  @returns a RadioProtocol enum.
00612          */
00613         RadioProtocol get_radio_protocol(void) const;
00614 
00615         /** _get_iosample - forces an io_sample read (reads all digital and analog inputs)
00616          *
00617          *  @param remote remote device
00618          *  @param io_sample buffer where the io_sample response is copied
00619          *  @param len pointer where the length of the io_sample response is stored
00620          *  @returns
00621          *     Success if the operation was successful,
00622          *     Failure otherwise
00623          */
00624         RadioStatus _get_iosample(const RemoteXBee& remote, uint8_t * const io_sample, uint16_t * const len);
00625 
00626         void _get_remote_node_by_id(const char * const node_id, uint64_t * addr64, uint16_t * addr16);
00627 
00628         /** check_radio_flow_control - checks that the radio has the CTS "D7" and RTS "D6" pins configured
00629          *                       according to the serial hardware flow control selected by the user
00630          *
00631          *  @returns true if check success.
00632          */
00633         bool check_radio_flow_control();
00634 
00635         /** get_AI - reads the AI parameter.
00636          *
00637          *  @returns
00638          *      -1 if an error occurred when reading AI.
00639          *      0-0xFF the AI value.
00640          */
00641         int get_AI(void);
00642 
00643         /** get_node_discovery_timeout - gets the node discovery timeout
00644           *
00645           *  @param timeout_ms pointer where the node discovery timeout value will be stored
00646           *  @param wait_for_complete_timeout pointer where the function will store if the operator
00647           *                                   has to wait for the complete nd timeout after issuing 
00648           *                                   a directed nd request
00649           *  @returns
00650           *     Success if the operation was successful,
00651           *     Failure otherwise
00652           */
00653         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms) = 0;
00654         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms, bool * const wait_for_complete_timeout) = 0;
00655 
00656         /** serial hardware flow control selected by the user (RTSCTS, RTS,CTS) */
00657         SerialBase::Flow _serial_flow_type;
00658 
00659         /** Operating mode of the module (API1, API2,...) */
00660         RadioMode   _mode;
00661 
00662         /** Hardware version value of the radio */
00663         uint16_t    _hw_version;
00664 
00665         /** Firmware version value of the radio */
00666         uint16_t    _fw_version;
00667 
00668         /** Timeout in ms for sync operations (when we wait for a response) */
00669         uint16_t    _timeout_ms;
00670 
00671         /** Device 64 bit address (SH, SL) */
00672         uint64_t      _dev_addr64;
00673 
00674         /** Serial Interface, use RawSerial as we dont use the streams */
00675         RawSerial   *_uart;
00676 
00677         /** IO connected to the radio reset line */
00678         DigitalOut  *_reset;
00679 
00680         /** Transmit options byte */
00681         uint8_t     _tx_options;
00682 
00683         /** Array of frame handler pointers. We use an array instead of a vector or other
00684          *  data structure to save memory and avoid dynamic memory allocation, to avoid
00685          *  memory fragmentation */
00686         FrameHandler *_fhandlers[MAX_FRAME_HANDLERS];
00687 
00688         /** Hardware reset counter, automatically updated by the library */
00689         volatile uint16_t    _hw_reset_cnt;
00690 
00691         /** Watchdog reset counter, automatically updated by the library */
00692         volatile uint16_t    _wd_reset_cnt;
00693 
00694         /** Frame handler used for the Modem Status packets. Automatically registered when a callback
00695          *  function is registered */
00696         FH_ModemStatus  *_modem_status_handler;
00697 
00698         /** Latest modem status received */
00699         AtCmdFrame::ModemStatus _modem_status;
00700 
00701         /** Library is initializing */
00702         bool _initializing;
00703 
00704         /** Timer used for node discovery */
00705         Timer _nd_timer;
00706 
00707         /** node discovery timeout */
00708         int _nd_timeout;
00709 
00710         /** If a _get_remote_node_by_id() is in progress, this keeps the expected frame id */
00711         uint8_t _node_by_ni_frame_id;
00712 };
00713 
00714 }   /* namespace XBeeLib */
00715 
00716 #endif /* defined(__DIGI_RADIO_H_) */
00717 
00718 
00719