XBee802.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_802_H_)
00014 #define __XBEE_802_H_
00015 
00016 #include "FrameHandlers/FH_AtCmdResp.h"
00017 #include "FrameHandlers/FH_RxPacket802.h"
00018 #include "FrameHandlers/FH_IoDataSample802.h"
00019 #include "RemoteXBee/RemoteXBee.h"
00020 
00021 namespace XBeeLib {
00022 
00023 /** Class for XBee ZigBee modules, derived from XBee */
00024 class XBee802 : public XBee
00025 {
00026     public:
00027 
00028         /**
00029          * IoLine for XBee802 Modules
00030          */
00031         enum IoLine {
00032             DIO0_AD0 = 0, /**< DIO0_AD0 pin */
00033             DIO1_AD1 = 1, /**< DIO1_AD1 pin */
00034             DIO2_AD2 = 2, /**< DIO2_AD2 pin */
00035             DIO3_AD3 = 3, /**< DIO3_AD3 pin */
00036             DIO4_AD4 = 4, /**< DIO4_AD4 pin */
00037             DIO5_AD5 = 5, /**< DIO5_AD5 pin */
00038             DIO6     = 6, /**< DIO6 pin */
00039             DIO7     = 7, /**< DIO7 pin */
00040             DI8      = 8, /**< DI8 pin */
00041             PWM0,         /**< PWM0 pin */
00042             PWM1           /**< PWM1 pin */
00043         };
00044 
00045         enum AssocStatus  {
00046             ErrorReading        = -1,       /**< Error occurred when reading parameter. */
00047             Joined              = 0x00,     /**< Successful Completion - Coordinator successfully started or End Device association complete. */
00048             ActiveScanTimeOut   = 0x01,     /**< Active Scan Timeout. */
00049             NoPANs              = 0x02,     /**< Active Scan found no PANs. */
00050             JoinNotAllowed      = 0x03,     /**< Active Scan found PAN, but the Coordinator's Allow Association bit is not set. */
00051             BeaconsFailed       = 0x04,     /**< Active Scan found PAN, but Coordinator and End Device are not configured to support beacons. */
00052             BadPAN              = 0x05,     /**< Active Scan found PAN, but Coordinator ID (PAN ID) value does not match the ID of the End Device. */
00053             BadChannel          = 0x06,     /**< Active Scan found PAN, but Coordinator CH (Channel) value does not match the CH of the End Device */
00054             EnergyScanTimeout   = 0x07,     /**< Energy Scan timed out. */
00055             CoordStartFailed    = 0x08,     /**< Coordinator start request failed. */
00056             CoordBadParameters  = 0x09,     /**< Coordinator could not start due to Invalid Parameter. */
00057             CoordRealignment    = 0x0A,     /**< Coordinator Realignment is in progress. */
00058             AssocReqNotSent     = 0x0B,     /**< Association Request not sent. */
00059             AssocReqTimeout     = 0x0C,     /**< Association Request timed out - no reply was received. */
00060             AssocReqInvalidPara = 0x0D,     /**< Association Request had an Invalid Parameter. */
00061             AssocReqChannelFail = 0x0E,     /**< Association Request Channel Access Failure - Request was not transmitted - CCA failure. */
00062             RemCoordNoACK       = 0x0F,     /**< Remote Coordinator did not send an ACK after Association Request was sent. */
00063             RemCoordLateACK     = 0x10,     /**< Remote Coordinator did not reply to the Association Request, but an ACK was received after sending the request. */
00064             Associating         = 0xFF      /**< RF Module is attempting to associate. */
00065         };
00066 
00067         /** Class constructor
00068          * @param tx the TX pin of the UART that will interface the XBee module
00069          * @param rx the RX pin of the UART that will interface the XBee module
00070          * @param reset the pin to which the XBee's reset line is attached to, use NC if not available
00071          * @param rts the RTS pin for the UART that will interface the XBee module, use NC if not available
00072          * @param cts the CTS pin for the UART that will interface the XBee module, use NC if not available
00073          * @param baud the baudrate for the UART that will interface the XBee module. Note that the module has to be already configured
00074          * to this baud rate (ATBD parameter). By default it is configured to 9600 bps
00075          */
00076         XBee802(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600);
00077 
00078         /** Class destructor */
00079         virtual ~XBee802();
00080 
00081         /** init -  initializes object
00082          * This function must be called just after creating the object so it initializes internal data.
00083          * @returns
00084          *         Success if the module has been properly initialized and is ready to process data.
00085          *         Failure otherwise.
00086          */
00087         RadioStatus init();
00088 
00089         /** set_panid - sets the 16 bit PAN ID.
00090          *
00091          *  @param panid the PAN 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_panid(uint16_t panid);
00097 
00098         /** get_panid - gets the configured 16 bit PAN ID
00099          *
00100          *  @param panid pointer where the read PAN ID value will be stored
00101          *  @returns
00102          *     Success if the operation was successful,
00103          *     Failure otherwise
00104          */
00105         RadioStatus get_panid(uint16_t * const panid);
00106 
00107         /** set_channel - sets the network channel number
00108          *
00109          *  @param channel the channel in which the radio operates. Range is 0x0B - 0x1A for XBee and 0x0C - 0x17 for XBee-PRO.
00110          *  The Center Frequency = 2.405 + (CH - 11) * 5 MHz
00111          *  @returns
00112          *     Success if the operation was successful,
00113          *     Failure otherwise
00114          */
00115         RadioStatus set_channel(uint8_t channel);
00116 
00117         /** get_panid - gets the network channel number
00118          *
00119          *  @param channel pointer where the channel value will be stored.
00120          *  @returns
00121          *     Success if the operation was successful,
00122          *     Failure otherwise
00123          */
00124         RadioStatus get_channel(uint8_t * const channel);
00125 
00126         /** get_network_address - gets the 16bit network address of the device
00127          *
00128          *  @param addr pointer where the device 16bit network address will be stored
00129          *  @returns
00130          *     Success if the operation was successful,
00131          *     Failure otherwise
00132          */
00133         RadioStatus get_network_address(uint16_t * const addr);
00134 
00135         /** set_network_address - sets the 16 bit network address of the device
00136          *
00137          *  @param addr the device 16bit network address (0x0 - 0xFFFF)
00138          *  @returns
00139          *     Success if the operation was successful,
00140          *     Failure otherwise
00141          */
00142         RadioStatus set_network_address(uint16_t addr);
00143 
00144         /** register_node_discovery_cb - registers the callback function that will be called
00145          * when the responses to the node discovery command arrive
00146          *
00147          *  @param function function pointer with the callback function
00148          */
00149         void register_node_discovery_cb(node_discovery_802_cb_t function);
00150 
00151         /** unregister_node_discovery_cb - removes the node discovery callback */
00152         void unregister_node_discovery_cb();
00153 
00154         /** register_receive_cb - registers the callback function that will be called
00155          * when a rx packet is received
00156          *
00157          *  @param function function pointer with the callback function
00158          */
00159         void register_receive_cb(receive_802_cb_t function);
00160 
00161         /** unregister_receive_cb - removes the rx packet callback */
00162         void unregister_receive_cb();
00163 
00164         /** register_io_sample_cb - registers the callback function that will be called
00165          * when a IO Sample Data packet is received
00166          *
00167          *  @param function function pointer with the callback function
00168          */
00169         void register_io_sample_cb(io_data_cb_802_t function);
00170 
00171         /** unregister_io_sample_cb - removes the IO Sample Data reception callback */
00172         void unregister_io_sample_cb();
00173 
00174         /*********************** send_data member methods ************************/
00175         /** send_data - sends data to a remote device
00176          *
00177          *  @param remote remote device
00178          *  @param data pointer to the data that will be sent
00179          *  @param len number of bytes that will be transmitted
00180          *  @param syncr if true, method waits for the packet answer with the result of the operation
00181          *  @returns the result of the data transfer
00182          *     TxStatusSuccess if the operation was successful,
00183          *     the error code otherwise
00184          */
00185         virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true);
00186 
00187         /** get_assoc_status - returns current network association status. This wraps AI parameter, for more information refer to moudle's Reference Manual.
00188          *
00189          *  @returns an AssocStatus with current network association status.
00190          */
00191         AssocStatus  get_assoc_status(void);
00192 
00193         /** get_remote_node_by_id - searches for a device in the network with the specified Node Identifier.
00194          *
00195          *  @param node_id node id of the device we are looking for
00196          *  @returns a RemoteXBee802 with the 16-bit and 64-bit address of the remote device whose node id matches with the parameter.
00197          *  If node is not found, the returned object will have invalid addresses (RemoteXBee802::is_valid() will return false).
00198          */
00199         RemoteXBee802 get_remote_node_by_id(const char * const node_id);
00200 
00201         /* Allow using XBee::set_param() methods for local radio from this class */
00202         using XBee::set_param;
00203 
00204         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00205          *
00206          *  @param remote remote device
00207          *  @param param parameter to be set.
00208          *  @param data the parameter value (4 bytes) to be set.
00209          *  @returns the command response status.
00210          */
00211         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data);
00212 
00213         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00214          *
00215          *  @param remote remote device
00216          *  @param param parameter to be set.
00217          *  @param the parameter value byte array (len bytes) to be set.
00218          *  @param len number of bytes of the parameter value.
00219          *  @returns the command response status.
00220          */
00221         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0);
00222 
00223         /* Allow using XBee::get_param() methods for local radio from this class */
00224         using XBee::get_param;
00225 
00226         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00227          *
00228          *  @param remote remote device
00229          *  @param param parameter to be get.
00230          *  @param data pointer where the param value (4 bytes) will be stored.
00231          *  @returns the command response status.
00232          */
00233         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data);
00234 
00235         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00236          *
00237          *  @param remote remote device
00238          *  @param param parameter to be get.
00239          *  @param data pointer where the param value (n bytes) will be stored.
00240          *  @param len pointer where the number of bytes of the param value will be stored.
00241          *  @returns the command response status.
00242          */
00243         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len);
00244 
00245         /************************* IO member methods **************************/
00246         /** set_pin_config - configures a radio IO line
00247          *
00248          *  @param remote remote device
00249          *  @param line IO line being configured
00250          *  @param mode configuration mode for the selected line
00251          *  @returns
00252          *     Success if the operation was successful,
00253          *     Failure otherwise
00254          */
00255         RadioStatus set_pin_config(const RemoteXBee& remote, IoLine line, IoMode mode);
00256 
00257         /** get_pin_config - gets the configuration of a radio IO line
00258          *
00259          *  @param remote remote device
00260          *  @param line IO line being read to get its configuration
00261          *  @param mode pointer where the configuration will be stored
00262          *  @returns
00263          *     Success if the operation was successful,
00264          *     Failure otherwise
00265          */
00266         RadioStatus get_pin_config(const RemoteXBee& remote, IoLine line, IoMode * const mode);
00267 
00268         /** set_dio - sets to low/high a DIO line
00269          *
00270          *  @param remote remote device
00271          *  @param line DIO line being set
00272          *  @param val value that will be set in the DIO line
00273          *  @returns
00274          *     Success if the operation was successful,
00275          *     Failure otherwise
00276          */
00277         RadioStatus set_dio(const RemoteXBee& remote, IoLine line, DioVal val);
00278 
00279         /** get_dio - read the value of a DIO configured as digital input
00280          *
00281          *  @param remote remote device
00282          *  @param line DIO line being read
00283          *  @param val pointer where the DIO value read will be stored
00284          *  @returns
00285          *     Success if the operation was successful,
00286          *     Failure otherwise
00287          */
00288         RadioStatus get_dio(const RemoteXBee& remote, IoLine line, DioVal * const val);
00289 
00290         /** get_adc - read the value of the espcified ADC line
00291          *
00292          *  @param remote remote device
00293          *  @param line ADC line being read
00294          *  @param val pointer where the value read from the ADC will be stored
00295          *  @returns
00296          *     Success if the operation was successful,
00297          *     Failure otherwise
00298          */
00299         RadioStatus get_adc(const RemoteXBee& remote, IoLine line, uint16_t * const val);
00300 
00301         /** get_iosample - retrieves an @ref IOSample802 from a remote node. This object can be used to get the remote node's ADC and DIO values.
00302          *
00303          *  @param remote remote device
00304          *  @returns IOSample802 object with the remote node's DIO and ADC values.
00305          */
00306         IOSample802 get_iosample(const RemoteXBee& remote);
00307 
00308         /** set_pwm - sets the duty cycle of a PWM line
00309          *
00310          *  @param remote remote device
00311          *  @param line PWM line being set
00312          *  @param duty_cycle duty cycle that will be set in the PWM line
00313          *  @returns
00314          *     Success if the operation was successful,
00315          *     Failure otherwise
00316          */
00317         RadioStatus set_pwm(const RemoteXBee& remote, IoLine line, float duty_cycle);
00318 
00319         /** set_pin_pull_up - enables or disables the internal pull-up resistor of a line
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 set_pin_pull_up(const RemoteXBee& remote, IoLine line, bool enable);
00329 
00330         /** enable_dio_change_detection - enables or disables the notification when a change is detected in a digital input line.
00331          * In other words, it will force an IO Sample transmission when the DIO state changes. Only for DIO0 to DIO7.
00332          *
00333          *  @param remote remote device
00334          *  @param line line being configured for pull-up
00335          *  @param enable whether to enable the internal pull-up resistor.
00336          *  @returns
00337          *     Success if the operation was successful,
00338          *     Failure otherwise
00339          */
00340         RadioStatus enable_dio_change_detection(const RemoteXBee& remote, IoLine line, bool enable);
00341 
00342 /* TODO: With current firmware ATM0 fails: Returns just OK and sets pwm to 0 */
00343 #ifdef GET_PWM_AVAILABLE
00344         /** get_pwm - gets the duty cycle of a PWM line
00345          *
00346          *  @param remote remote device
00347          *  @param line PWM line being read
00348          *  @param duty_cycle pointer where the value of the duty cycle read from
00349          *                    the PWM line will be stored
00350          *  @returns
00351          *     Success if the operation was successful,
00352          *     Failure otherwise
00353          */
00354         RadioStatus get_pwm(const RemoteXBee& remote, IoLine line, float * const duty_cycle);
00355 #endif
00356 
00357     protected:
00358 
00359         /** Frame handler used for the node discovery. Registered when a callback function
00360          * is registered */
00361         FH_NodeDiscovery802  *_nd_handler;
00362 
00363          /** Frame handler used for the rx 64 bit packets. Automatically registered when a callback
00364          *  function is registered */
00365         FH_RxPacket64b802  *_rx_64b_handler;
00366 
00367          /** Frame handler used for the rx 16 bit packets. Automatically registered when a callback
00368          *  function is registered */
00369         FH_RxPacket16b802  *_rx_16b_handler;
00370 
00371         /** Frame handler used for the 64 bit IO Data Samples packets. Automatically registered when a callback
00372         *  function is registered */
00373         FH_IoDataSampe64b802  *_io_data_64b_handler;
00374 
00375         /** Frame handler used for the 16 bit IO Data Samples packets. Automatically registered when a callback
00376         *  function is registered */
00377         FH_IoDataSampe16b802  *_io_data_16b_handler;
00378 
00379         /** Method called directly by the library when a modem status frame is received to
00380          * update the internal status variables */
00381         virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status);
00382 
00383         /* Allow using XBee::send_data() methods from this class */
00384         using XBee::send_data;
00385 
00386         /** get_node_discovery_timeout - gets the node discovery timeout
00387           *
00388           *  @param timeout_ms pointer where the node discovery timeout value will be stored
00389           *  @param wait_for_complete_timeout pointer where the function will store if the operator
00390           *                                   has to wait for the complete nd timeout after issuing 
00391           *                                   a directed nd request
00392           *  @returns
00393           *     Success if the operation was successful,
00394           *     Failure otherwise
00395           */
00396         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms);
00397         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms, bool * const wait_for_complete_timeout);
00398 
00399     private:
00400 
00401 };
00402 
00403 }   /* namespace XBeeLib */
00404 
00405 #endif /* __XBEE_802_H_ */