XBeeDM.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(__XBEE_DM_H_)
00014 #define __XBEE_DM_H_
00015 
00016 #include "XBee/XBee.h"
00017 #include "FrameHandlers/FH_AtCmdResp.h"
00018 #include "FrameHandlers/FH_RxPacketDM.h"
00019 #include "FrameHandlers/FH_IoDataSampleDM.h"
00020 #include "RemoteXBee/RemoteXBee.h"
00021 
00022 namespace XBeeLib {
00023 
00024 /** Class for XBee ZigBee modules, derived from XBee */
00025 class XBeeDM : public XBee
00026 {
00027     public:
00028 
00029         /**
00030          * IoLine for XBeeDM Modules
00031          */
00032         enum IoLine {
00033             DIO0_AD0   = 0,  /**< DIO0_AD0 pin */
00034             DIO1_AD1   = 1,  /**< DIO1_AD1 pin */
00035             DIO2_AD2   = 2,  /**< DIO2_AD2 pin */
00036             DIO3_AD3   = 3,  /**< DIO3_AD3 pin */
00037             DIO4       = 4,  /**< DIO4 pin */
00038             DIO5       = 5,  /**< DIO5 pin */
00039             DIO6       = 6,  /**< DIO6 pin */
00040             DIO7       = 7,  /**< DIO7 pin */
00041             DIO8       = 8,  /**< DIO8 pin */
00042             DIO9       = 9,  /**< DIO9 pin */
00043             DIO10_PWM0 = 10, /**< DIO10_PWM0 pin */
00044             DIO11_PWM1 = 11, /**< DIO11_PWM1 pin */
00045             DIO12      = 12  /**< DIO12 pin */
00046         };
00047 
00048         /** Class constructor
00049          * @param tx the TX pin of the UART that will interface the XBee module
00050          * @param rx the RX pin of the UART that will interface the XBee module
00051          * @param reset the pin to which the XBee's reset line is attached to, use NC if not available
00052          * @param rts the RTS pin for the UART that will interface the XBee module, use NC if not available
00053          * @param cts the CTS pin for the UART that will interface the XBee module, use NC if not available
00054          * @param baud the baudrate for the UART that will interface the XBee module. Note that the module has to be already configured
00055          * to this baud rate (ATBD parameter). By default it is configured to 9600 bps
00056          */
00057         XBeeDM(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600);
00058 
00059         /** Class destructor */
00060         virtual ~XBeeDM();
00061 
00062         /** init-  initializes object
00063          * This function must be called just after creating the object so it initializes internal data.
00064          * @returns
00065          *         Success if the module has been properly initialized and is ready to process data.
00066          *         Failure otherwise.
00067          */
00068         RadioStatus init();
00069 
00070         /** set_channel - sets the channel number
00071          *
00072          *  @param channel the channel in which the radio operates. Range is 0x0B - 0x1A for XBee and 0x0C - 0x17 for XBee-PRO.
00073          *  The Center Frequency = 2.405 + (CH - 11) * 5 MHz
00074          *  @returns
00075          *     Success if the operation was successful,
00076          *     Failure otherwise
00077          */
00078         RadioStatus set_channel(uint8_t channel);
00079 
00080         /** get_channel - gets the channel number
00081          *
00082          *  @param channel pointer where the channel value will be stored.
00083          *  @returns
00084          *     Success if the operation was successful,
00085          *     Failure otherwise
00086          */
00087         RadioStatus get_channel(uint8_t * const channel);
00088 
00089         /** set_network_id - sets the Network ID.
00090          *
00091          *  @param network_id the Network ID value that will be set on the radio
00092          *  @returns
00093          *     Success if the operation was successful,
00094          *     Failure otherwise
00095          */
00096          RadioStatus set_network_id(uint16_t network_id);
00097 
00098         /** get_network_id - gets the Network ID, as it was set by @ref set_network_id().
00099          *
00100          *  @param network_id pointer where the Network ID will be stored
00101          *  @returns
00102          *     Success if the operation was successful,
00103          *     Failure otherwise
00104          */
00105         RadioStatus get_network_id(uint16_t * const network_id);
00106 
00107         /** register_node_discovery_cb - registers the callback function that will be called
00108          * when the responses to the node discovery command arrive
00109          *
00110          *  @param function function pointer with the callback function
00111          */
00112         void register_node_discovery_cb(node_discovery_dm_cb_t function);
00113 
00114         /** unregister_node_discovery_cb - removes the node discovery callback */
00115         void unregister_node_discovery_cb();
00116 
00117         /** register_receive_cb - registers the callback function that will be called
00118          * when a data packet is received
00119          *
00120          *  @param function function pointer with the callback function
00121          */
00122         void register_receive_cb(receive_dm_cb_t function);
00123 
00124         /** unregister_receive_cb - removes the rx packet callback */
00125         void unregister_receive_cb();
00126 
00127         /** register_io_sample_cb - registers the callback function that will be called
00128          * when a IO Sample Data packet is received
00129          *
00130          *  @param function function pointer with the callback function
00131          */
00132         void register_io_sample_cb(io_data_cb_dm_t function);
00133 
00134         /** unregister_io_sample_cb - removes the IO Sample Data reception callback */
00135         void unregister_io_sample_cb();
00136 
00137         /*********************** send_data member methods ************************/
00138         /** send_data - sends data to a remote device
00139          *
00140          *  @param remote remote device
00141          *  @param data pointer to the data that will be sent
00142          *  @param len number of bytes that will be transmitted
00143          *  @param syncr if true, method waits for the packet answer with the result of the operation
00144          *  @returns the result of the data transfer
00145          *     TxStatusSuccess if the operation was successful,
00146          *     the error code otherwise
00147          */
00148         virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true);
00149 
00150         /** send_data - sends data to a remote device. This method uses
00151          *                   the explicit addressing frame, allowing to use source and
00152          *                   destination end points and cluster and profile IDs
00153          *
00154          *  @param remote remote device
00155          *  @param source_ep source end point
00156          *  @param dest_ep destination end point
00157          *  @param cluster_id cluster ID
00158          *  @param profile_id profile ID
00159          *  @param data pointer to the data that will be sent
00160          *  @param len number of bytes that will be transmitted
00161          *  @param syncr if true, method waits for the packet answer with the result of the operation
00162          *  @returns the result of the data transfer
00163          *     TxStatusSuccess if the operation was successful,
00164          *     the error code otherwise
00165          */
00166         TxStatus send_data(const RemoteXBee& remote, uint8_t source_ep,
00167                                 uint8_t dest_ep, uint16_t cluster_id, uint16_t profile_id,
00168                                 const uint8_t *const data, uint16_t len, bool syncr = true);
00169 
00170         /** send_data_to_coordinator - sends data to the ZigBee coordinator
00171          *
00172          *  @param data pointer to the data that will be sent
00173          *  @param len number of bytes that will be transmitted
00174          *  @param syncr if true, method waits for the packet answer with the result of the operation
00175          *  @returns the result of the data transfer
00176          *     TxStatusSuccess if the operation was successful,
00177          *     the error code otherwise
00178          */
00179         TxStatus send_data_to_coordinator(const uint8_t *const data, uint16_t len, bool syncr = true);
00180 
00181         /** get_remote_node_by_id - searches for a device in the network with the specified Node Identifier.
00182          *
00183          *  @param node_id node id of the device we are looking for
00184          *  @returns a RemoteXBeeDM with the 16-bit and 64-bit address of the remote device whose node id matches with the parameter.
00185          *  If node is not found, the returned object will have invalid addresses (RemoteXBeeDM::is_valid() will return false).
00186          */
00187         RemoteXBeeDM get_remote_node_by_id(const char * const node_id);
00188 
00189         /* Allow using XBee::set_param() methods for local radio from this class */
00190         using XBee::set_param;
00191 
00192         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00193          *
00194          *  @param remote remote device
00195          *  @param param parameter to be set.
00196          *  @param data the parameter value (4 bytes) to be set.
00197          *  @returns the command response status.
00198          */
00199         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data);
00200 
00201         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00202          *
00203          *  @param remote remote device
00204          *  @param param parameter to be set.
00205          *  @param data the parameter value byte array (len bytes) to be set.
00206          *  @param len number of bytes of the parameter value.
00207          *  @returns the command response status.
00208          */
00209         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0);
00210 
00211         /* Allow using XBee::get_param() methods for local radio from this class */
00212         using XBee::get_param;
00213 
00214         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00215          *
00216          *  @param remote remote device
00217          *  @param param parameter to be get.
00218          *  @param data pointer where the param value (4 bytes) will be stored.
00219          *  @returns the command response status.
00220          */
00221         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data);
00222 
00223         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00224          *
00225          *  @param remote remote device
00226          *  @param param parameter to be get.
00227          *  @param data pointer where the param value (n bytes) will be stored.
00228          *  @param len pointer where the number of bytes of the param value will be stored.
00229          *  @returns the command response status.
00230          */
00231         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len);
00232 
00233         /************************* IO member methods **************************/
00234         /** set_pin_config - configures a radio IO line
00235          *
00236          *  @param remote remote device
00237          *  @param line IO line being configured
00238          *  @param mode configuration mode for the selected line
00239          *  @returns
00240          *     Success if the operation was successful,
00241          *     Failure otherwise
00242          */
00243         RadioStatus set_pin_config(const RemoteXBee& remote, IoLine line, IoMode mode);
00244 
00245         /** get_pin_config - gets the configuration of a radio IO line
00246          *
00247          *  @param remote remote device
00248          *  @param line IO line being read to get its configuration
00249          *  @param mode pointer where the configuration will be stored
00250          *  @returns
00251          *     Success if the operation was successful,
00252          *     Failure otherwise
00253          */
00254         RadioStatus get_pin_config(const RemoteXBee& remote, IoLine line, IoMode * const mode);
00255 
00256         /** set_dio - sets to low/high a DIO line
00257          *
00258          *  @param remote remote device
00259          *  @param line DIO line being set
00260          *  @param val value that will be set in the DIO line
00261          *  @returns
00262          *     Success if the operation was successful,
00263          *     Failure otherwise
00264          */
00265         RadioStatus set_dio(const RemoteXBee& remote, IoLine line, DioVal val);
00266 
00267         /** get_dio - read the value of a DIO configured as digital input
00268          *
00269          *  @param remote remote device
00270          *  @param line DIO line being read
00271          *  @param val pointer where the DIO value read will be stored
00272          *  @returns
00273          *     Success if the operation was successful,
00274          *     Failure otherwise
00275          */
00276         RadioStatus get_dio(const RemoteXBee& remote, IoLine line, DioVal * const val);
00277 
00278         /** get_adc - read the value of the espcified ADC line
00279          *
00280          *  @param remote remote device
00281          *  @param line ADC line being read
00282          *  @param val pointer where the value read from hte ADC will be stored
00283          *  @returns
00284          *     Success if the operation was successful,
00285          *     Failure otherwise
00286          */
00287         RadioStatus get_adc(const RemoteXBee& remote, IoLine line, uint16_t * const val);
00288 
00289         /** get_iosample - retrieves an @ref IOSampleDM from a remote node. This object can be used to get the remote node's ADC and DIO values.
00290          *
00291          *  @param remote remote device
00292          *  @returns IOSampleDM object with the remote node's DIO and ADC values.
00293          */
00294         IOSampleDM get_iosample(const RemoteXBee& remote);
00295 
00296         /** set_pwm - sets the duty cycle of a PWM line
00297          *
00298          *  @param remote remote device
00299          *  @param line PWM line being set
00300          *  @param duty_cycle duty cycle that will be set in the PWM line
00301          *  @returns
00302          *     Success if the operation was successful,
00303          *     Failure otherwise
00304          */
00305         RadioStatus set_pwm(const RemoteXBee& remote, IoLine line, float duty_cycle);
00306 
00307         /** set_pin_pull_up - enables or disables the internal pull-up resistor of a line
00308          *
00309          *  @param remote remote device
00310          *  @param line line being configured for pull-up
00311          *  @param enable whether to enable the internal pull-up resistor.
00312          *  @returns
00313          *     Success if the operation was successful,
00314          *     Failure otherwise
00315          */
00316         RadioStatus set_pin_pull_up(const RemoteXBee& remote, IoLine line, bool enable);
00317 
00318         /** enable_dio_change_detection - enables or disables the notification when a change is detected in a digital input line.
00319          * In other words, it will force an IO Sample transmission when the DIO state changes. Only for DIO0 to DIO11.
00320          *
00321          *  @param remote remote device
00322          *  @param line line being configured for pull-up
00323          *  @param enable whether to enable the internal pull-up resistor.
00324          *  @returns
00325          *     Success if the operation was successful,
00326          *     Failure otherwise
00327          */
00328         RadioStatus enable_dio_change_detection(const RemoteXBee& remote, IoLine line, bool enable);
00329 
00330         /** config_poll_destination - configures to which node poll messages will be sent once module awakes if configured as
00331          *                            an Indirect Msg Poller (CE==0x4).
00332          * Consult the module's reference manual for more information.
00333          *
00334          *  @param destination remote device where the poll messages will be sent
00335          *  @returns the result of the data transfer
00336          *     Success if the operation was successful,
00337          *     Failure otherwise
00338          */
00339         RadioStatus config_poll_destination(const RemoteXBee& destination);
00340 
00341     protected:
00342 
00343         /** Frame handler used for the node discovery. Registered when a callback function
00344          * is registered */
00345         FH_NodeDiscoveryDM  *_nd_handler;
00346 
00347         /** Frame handler used for the rx packets. Automatically registered when a callback
00348          *  function is registered */
00349         FH_RxPacketDM  *_rx_pkt_handler;
00350 
00351         /** Frame handler used for the IO Data Sample packets. Automatically registered when a callback
00352          *  function is registered */
00353         FH_IoDataSampeDM  *_io_data_handler;
00354 
00355         /** Method called directly by the library when a modem status frame is received to
00356          * update the internal status variables */
00357         virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status);
00358 
00359         /* Allow using XBee::send_data() methods from this class */
00360         using XBee::send_data;
00361 
00362         /** get_node_discovery_timeout - gets the node discovery timeout
00363           *
00364           *  @param timeout_ms pointer where the node discovery timeout value will be stored
00365           *  @param wait_for_complete_timeout pointer where the function will store if the operator
00366           *                                   has to wait for the complete nd timeout after issuing 
00367           *                                   a directed nd request
00368           *  @returns
00369           *     Success if the operation was successful,
00370           *     Failure otherwise
00371           */
00372         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms);
00373         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms, bool * const wait_for_complete_timeout);
00374 };
00375 
00376 }   /* namespace XBeeLib */
00377 
00378 #endif /* __XBEE_DM_H_ */