Xbee s2b for lpc11u24

Dependencies:   DigiLogger

Dependents:  

Fork of XBeeLib by Digi International Inc.

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers XBee.h Source File

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