XBeeZB.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_ZB_H_)
00014 #define __XBEE_ZB_H_
00015 
00016 #include "XBee/XBee.h"
00017 #include "FrameHandlers/FH_AtCmdResp.h"
00018 #include "FrameHandlers/FH_RxPacketZB.h"
00019 #include "FrameHandlers/FH_IoDataSampleZB.h"
00020 #include "RemoteXBee/RemoteXBee.h"
00021 
00022 namespace XBeeLib {
00023 
00024 /** Class for XBee ZigBee modules, derived from XBee */
00025 class XBeeZB : public XBee
00026 {
00027     public:
00028 
00029         /**
00030          * IoLine for XBeeZB 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             DIO10    = 10, /**< DIO10 pin */
00042             DIO11    = 11, /**< DIO11 pin */
00043             DIO12    = 12, /**< DIO12 pin */
00044             SUPPLY_VOLTAGE = 7, /**< SUPPLY_VOLTAGE is not a real pin */
00045         };
00046 
00047         enum AssocStatus  {
00048             ErrorReading    = -1,       /**< Error occurred when reading parameter. */
00049             Joined          = 0x00,     /**< Successfully formed or joined a network. (Coordinators form a network, routers and end devices join a network.) */
00050             NoPANs          = 0x21,     /**< Scan found no PANs */
00051             NoValidPAN      = 0x22,     /**< Scan found no valid PANs based on current SC and ID settings */
00052             JoinNotAllowed  = 0x23,     /**< Valid Coordinator or Routers found, but they are not allowing joining (NJ expired). */
00053             NoBeacons       = 0x24,     /**< No joinable beacons were found. */
00054             Unexpected      = 0x25,     /**< Unexpected state, node should not be attempting to join at this time. */
00055             JoinFailed      = 0x27,     /**< Node Joining attempt failed (typically due to incompatible security settings). */
00056             CoordStartFail  = 0x2A,     /**< Coordinator start attempt failed */
00057             CheckingCoord   = 0x2B,     /**< Checking for an existing coordinator. */
00058             LeaveFail       = 0x2C,     /**< Attempt to leave the network failed. */
00059             JoinNoResponse  = 0xAB,     /**< Attempted to join a device that did not respond. */
00060             SecKeyUnsec     = 0xAC,     /**< Secure join error - network security key received unsecured. */
00061             SecKeyNotRec    = 0xAD,     /**< Secure join error - network security key not received. */
00062             SecBadKey       = 0xAF,     /**< Secure join error - joining device does not have the right preconfigured link key. */
00063             Scanning        = 0xFF      /**< Scanning for a ZigBee network (routers and end devices). */
00064         };
00065 
00066         /** Class constructor
00067          * @param tx the TX pin of the UART that will interface the XBee module
00068          * @param rx the RX pin of the UART that will interface the XBee module
00069          * @param reset the pin to which the XBee's reset line is attached to, use NC if not available
00070          * @param rts the RTS pin for the UART that will interface the XBee module, use NC if not available
00071          * @param cts the CTS pin for the UART that will interface the XBee module, use NC if not available
00072          * @param baud the baudrate for the UART that will interface the XBee module. Note that the module has to be already configured
00073          * to this baud rate (ATBD parameter). By default it is configured to 9600 bps
00074          */
00075         XBeeZB(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600);
00076 
00077         /** Class destructor */
00078         virtual ~XBeeZB();
00079 
00080         /** init-  initializes object
00081          * This function must be called just after creating the object so it initializes internal data.
00082          * @returns
00083          *         Success if the module has been properly initialized and is ready to process data.
00084          *         Failure otherwise.
00085          */
00086         RadioStatus init();
00087 
00088         /** set_panid - sets the 64bit extended PAN ID.
00089          *
00090          *  @note on ZigBee devices, if set to 0, the coordinator will select a random PAN ID
00091          *           and the routers will join any extended PAN ID
00092          *  @param panid the PAN ID value that will be set on the radio
00093          *  @returns
00094          *     Success if the operation was successful,
00095          *     Failure otherwise
00096          */
00097         RadioStatus set_panid(uint64_t panid);
00098 
00099         /** get_configured_panid - gets the configured PAN ID, as it was set by @ref set_panid().
00100          *
00101          *  @note on ZigBee devices, if set to 0, the coordinator will select a random PAN ID
00102          *           and the routers will join any extended PAN ID
00103          *  @param panid pointer where the configured PAN ID will be stored
00104          *  @returns
00105          *     Success if the operation was successful,
00106          *     Failure otherwise
00107          */
00108         RadioStatus get_configured_panid(uint64_t * const panid);
00109 
00110         /** get_operating_panid - gets the operating 64bit extended PAN ID the module is running on. This is useful to determine the PAN ID when the ID parameter (@ref set_panid) is set to 0x00.
00111          *
00112          *  @param panid pointer where the operating PAN ID will be stored
00113          *  @returns
00114          *     Success if the operation was successful,
00115          *     Failure otherwise
00116          */
00117         RadioStatus get_operating_panid(uint64_t * const panid);
00118 
00119         /** set_panid - sets the 64bit extended PAN ID.
00120          *
00121          *  @note on ZigBee devices, if set to 0, the coordinator will select a random PAN ID
00122          *           and the routers will join any extended PAN ID
00123          *  @param remote remote device
00124          *  @param panid the PAN ID value that will be set on the radio
00125          *  @returns
00126          *     Success if the operation was successful,
00127          *     Failure otherwise
00128          */
00129         RadioStatus set_panid(const RemoteXBee& remote, uint64_t panid);
00130 
00131         /** get_configured_panid - gets the configured PAN ID in a remote node, as it was set by @ref set_panid()
00132          *
00133          *  @note on ZigBee devices, if set to 0, the coordinator will select a random PAN ID
00134          *           and the routers will join any extended PAN ID
00135          *
00136          *  @param remote remote device
00137          *  @param panid pointer where the configured PAN ID will be stored
00138          *  @returns
00139          *     Success if the operation was successful,
00140          *     Failure otherwise
00141          */
00142         RadioStatus get_configured_panid(const RemoteXBee& remote, uint64_t * const panid);
00143 
00144         /** get_operating_panid - gets the operating 64bit extended PAN ID in which a remote node is running on. This is useful to determine the PAN ID when the ID parameter (@ref set_panid) is set to 0x00.
00145          *
00146          *  @param remote remote device
00147          *  @param panid pointer where the operating PAN ID will be stored
00148          *  @returns
00149          *     Success if the operation was successful,
00150          *     Failure otherwise
00151          */
00152         RadioStatus get_operating_panid(const RemoteXBee& remote, uint64_t * const panid);
00153 
00154         /** set_channel_mask - sets the channel mask in which the module will scan for the PAN ID (if it is a router or end-device) or start the network (if it is a coordinator).
00155          * It should be set to the minimum available set of channels of all nodes in the network. Refer to "SC" parameter in the product manual for more information.
00156          *
00157          *  @param chmask bit field list of channels to scan (router/end-devices) or to choose when starting a network (coordinator). Bit 0 is for channel 0x0B and bit 15 for channel 0x1A.
00158          *  @returns
00159          *     Success if the operation was successful,
00160          *     Failure otherwise
00161          */
00162         RadioStatus set_channel_mask(uint16_t const chmask);
00163 
00164         /** get_channel_mask - gets the channel mask in which the module will scan for the PAN ID (if it is a router or end-device) or start the network (if it is a coordinator).
00165          *
00166          *  @param chmask pointer to where the configured channel mask will be stored
00167          *  @returns
00168          *     Success if the operation was successful,
00169          *     Failure otherwise
00170          */
00171         RadioStatus get_channel_mask(uint16_t * const chmask);
00172 
00173         /** get_network_address - gets the 16bit network address of the device
00174          *
00175          *  @param addr pointer where the device 16bit network address will be stored
00176          *  @returns
00177          *     Success if the operation was successful,
00178          *     Failure otherwise
00179          */
00180         RadioStatus get_network_address(uint16_t * const addr);
00181 
00182         /** check_for_coordinator_at_start - (Routers only) If enabled, a router will verify the coordinator is on its operating channel when joining or coming up from a power cycle.
00183          * If a coordinator is not detected, the router will leave its current channel and attempt to join a new PAN. If JV=0, the router will continue operating on its current channel even if a coordinator is not detected.
00184          *
00185          *  @param enable whether to enable this feature or not
00186          *  @returns
00187          *     Success if the operation was successful,
00188          *     Failure otherwise
00189          */
00190         RadioStatus check_for_coordinator_at_start(bool enable);
00191 
00192         /** set_network_security_key - (Coordinator only) Set the 128-bit AES network encryption key. If set to 0 (default), the module will select a random network key.
00193          *  It is not recommended to set the key programmatically, because it could be read through the raw serial port bits.
00194          *  @param key pointer to the 128-bit AES key
00195          *  @param length size of the buffer pointed by 'key'
00196          *  @returns
00197          *     Success if the operation was successful,
00198          *     Failure otherwise
00199          */
00200         RadioStatus set_network_security_key(const uint8_t * const key, const uint16_t length);
00201 
00202 #define XBEE_ZB_ENC_OPT_SEND_KEY_ON_JOIN    0x01
00203 #define XBEE_ZB_ENC_OPT_USE_TRUST_CENTER    0x02
00204         /** set_encryption_options - Configure options for encryption. Unused option bits should be set to 0. Options include:
00205          *  - XBEE_ZB_ENC_OPT_SEND_KEY_ON_JOIN - Send the security key unsecured over-the-air during joins
00206          *  - XBEE_ZB_ENC_OPT_USE_TRUST_CENTER - Use trust center (coordinator only)
00207          *  @param options bit mask with the encryption options
00208          *  @returns
00209          *     Success if the operation was successful,
00210          *     Failure otherwise
00211          */
00212         RadioStatus set_encryption_options(const uint8_t options);
00213 
00214         /** register_node_discovery_cb - registers the callback function that will be called
00215          * when the responses to the node discovery command arrive
00216          *
00217          *  @param function function pointer with the callback function
00218          */
00219         void register_node_discovery_cb(node_discovery_zb_cb_t function);
00220 
00221         /** unregister_node_discovery_cb - removes the node discovery callback */
00222         void unregister_node_discovery_cb();
00223 
00224         /** register_receive_cb - registers the callback function that will be called
00225          * when a data packet is received
00226          *
00227          *  @param function function pointer with the callback function
00228          */
00229         void register_receive_cb(receive_zb_cb_t function);
00230 
00231         /** unregister_receive_cb - removes the rx packet callback */
00232         void unregister_receive_cb();
00233 
00234         /** register_io_sample_cb - registers the callback function that will be called
00235          * when a IO Sample Data packet is received
00236          *
00237          *  @param function function pointer with the callback function
00238          */
00239         void register_io_sample_cb(io_data_cb_zb_t function);
00240 
00241         /** unregister_io_sample_cb - removes the IO Sample Data reception callback */
00242         void unregister_io_sample_cb();
00243 
00244         /*********************** send_data member methods ************************/
00245         /** send_data - sends data to a remote device
00246          *
00247          *  @param remote remote device
00248          *  @param data pointer to the data that will be sent
00249          *  @param len number of bytes that will be transmitted
00250          *  @param syncr if true, method waits for the packet answer with the result of the operation
00251          *  @returns the result of the data transfer
00252          *     TxStatusSuccess if the operation was successful,
00253          *     the error code otherwise
00254          */
00255         virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true);
00256 
00257         /** send_data - sends data to a remote device. This method uses
00258          *                   the explicit addressing frame, allowing to use source and
00259          *                   destination end points and cluster and profile IDs
00260          *
00261          *  @param remote remote device
00262          *  @param source_ep source end point
00263          *  @param dest_ep destination end point
00264          *  @param cluster_id cluster ID
00265          *  @param profile_id profile ID
00266          *  @param data pointer to the data that will be sent
00267          *  @param len number of bytes that will be transmitted
00268          *  @param syncr if true, method waits for the packet answer with the result of the operation
00269          *  @returns the result of the data transfer
00270          *     TxStatusSuccess if the operation was successful,
00271          *     the error code otherwise
00272          */
00273         TxStatus send_data(const RemoteXBee& remote, uint8_t source_ep,
00274                                 uint8_t dest_ep, uint16_t cluster_id, uint16_t profile_id,
00275                                 const uint8_t *const data, uint16_t len, bool syncr = true);
00276 
00277         /** send_data_to_coordinator - sends data to the ZigBee coordinator
00278          *
00279          *  @param data pointer to the data that will be sent
00280          *  @param len number of bytes that will be transmitted
00281          *  @param syncr if true, method waits for the packet answer with the result of the operation
00282          *  @returns the result of the data transfer
00283          *     TxStatusSuccess if the operation was successful,
00284          *     the error code otherwise
00285          */
00286         TxStatus send_data_to_coordinator(const uint8_t *const data, uint16_t len, bool syncr = true);
00287 
00288         /** get_assoc_status - returns current network association status. This wraps AI parameter, for more information refer to moudle's Reference Manual.
00289          *
00290          *  @returns an AssocStatus with current network association status.
00291          */
00292         AssocStatus  get_assoc_status(void);
00293 
00294         /** is_joined - checks if the device is joined to ZigBee network
00295          *  @returns true if joined, false otherwise
00296          */
00297         bool is_joined();
00298 
00299         /** get_remote_node_by_id - searches for a device in the network with the specified Node Identifier.
00300          *
00301          *  @param node_id node id of the device we are looking for
00302          *  @returns a RemoteXBeeZB with the 16-bit and 64-bit address of the remote device whose node id matches with the parameter.
00303          *  If node is not found, the returned object will have invalid addresses (RemoteXBeeZB::is_valid() will return false).
00304          */
00305         RemoteXBeeZB get_remote_node_by_id(const char * const node_id);
00306 
00307         /* Allow using XBee::set_param() methods for local radio from this class */
00308         using XBee::set_param;
00309 
00310         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00311          *
00312          *  @param remote remote device
00313          *  @param param parameter to be set.
00314          *  @param data the parameter value (4 bytes) to be set.
00315          *  @returns the command response status.
00316          */
00317         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data);
00318 
00319         /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response.
00320          *
00321          *  @param remote remote device
00322          *  @param param parameter to be set.
00323          *  @param data the parameter value byte array (len bytes) to be set.
00324          *  @param len number of bytes of the parameter value.
00325          *  @returns the command response status.
00326          */
00327         virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0);
00328 
00329         /* Allow using XBee::get_param() methods for local radio from this class */
00330         using XBee::get_param;
00331 
00332         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00333          *
00334          *  @param remote remote device
00335          *  @param param parameter to be get.
00336          *  @param data pointer where the param value (4 bytes) will be stored.
00337          *  @returns the command response status.
00338          */
00339         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data);
00340 
00341         /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response.
00342          *
00343          *  @param remote remote device
00344          *  @param param parameter to be get.
00345          *  @param data pointer where the param value (n bytes) will be stored.
00346          *  @param len pointer where the number of bytes of the param value will be stored.
00347          *  @returns the command response status.
00348          */
00349         virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len);
00350 
00351         /************************* IO member methods **************************/
00352         /** set_pin_config - configures a radio IO line
00353          *
00354          *  @param remote remote device
00355          *  @param line IO line being configured
00356          *  @param mode configuration mode for the selected line
00357          *  @returns
00358          *     Success if the operation was successful,
00359          *     Failure otherwise
00360          */
00361         RadioStatus set_pin_config(const RemoteXBee& remote, IoLine line, IoMode mode);
00362 
00363         /** get_pin_config - gets the configuration of a radio IO line
00364          *
00365          *  @param remote remote device
00366          *  @param line IO line being read to get its configuration
00367          *  @param mode pointer where the configuration will be stored
00368          *  @returns
00369          *     Success if the operation was successful,
00370          *     Failure otherwise
00371          */
00372         RadioStatus get_pin_config(const RemoteXBee& remote, IoLine line, IoMode * const mode);
00373 
00374         /** set_dio - sets to low/high a DIO line
00375          *
00376          *  @param remote remote device
00377          *  @param line DIO line being set
00378          *  @param val value that will be set in the DIO line
00379          *  @returns
00380          *     Success if the operation was successful,
00381          *     Failure otherwise
00382          */
00383         RadioStatus set_dio(const RemoteXBee& remote, IoLine line, DioVal val);
00384 
00385         /** get_dio - read the value of a DIO configured as digital input
00386          *
00387          *  @param remote remote device
00388          *  @param line DIO line being read
00389          *  @param val pointer where the DIO value read will be stored
00390          *  @returns
00391          *     Success if the operation was successful,
00392          *     Failure otherwise
00393          */
00394         RadioStatus get_dio(const RemoteXBee& remote, IoLine line, DioVal * const val);
00395 
00396         /** get_adc - read the value of the espcified ADC line
00397          *
00398          *  @param remote remote device
00399          *  @param line ADC line being read
00400          *  @param val pointer where the value read from hte ADC will be stored
00401          *  @returns
00402          *     Success if the operation was successful,
00403          *     Failure otherwise
00404          */
00405         RadioStatus get_adc(const RemoteXBee& remote, IoLine line, uint16_t * const val);
00406 
00407         /** get_iosample - retrieves an @ref IOSampleZB from a remote node. This object can be used to get the remote node's ADC and DIO values.
00408          *
00409          *  @param remote remote device
00410          *  @returns IOSampleZB object with the remote node's DIO and ADC values.
00411          */
00412         IOSampleZB get_iosample(const RemoteXBee& remote);
00413 
00414         /** set_pin_pull_up - enables or disables the internal pull-up resistor of a line
00415          *
00416          *  @param remote remote device
00417          *  @param line line being configured for pull-up
00418          *  @param enable whether to enable the internal pull-up resistor.
00419          *  @returns
00420          *     Success if the operation was successful,
00421          *     Failure otherwise
00422          */
00423         RadioStatus set_pin_pull_up(const RemoteXBee& remote, IoLine line, bool enable);
00424 
00425         /** enable_dio_change_detection - enables or disables the notification when a change is detected in a digital input line.
00426          * In other words, it will force an IO Sample transmission when the DIO state changes. Only for DIO0 to DIO11.
00427          *
00428          *  @param remote remote device
00429          *  @param line line being configured for pull-up
00430          *  @param enable whether to enable the internal pull-up resistor.
00431          *  @returns
00432          *     Success if the operation was successful,
00433          *     Failure otherwise
00434          */
00435         RadioStatus enable_dio_change_detection(const RemoteXBee& remote, IoLine line, bool enable);
00436 
00437     protected:
00438 
00439         /** Frame handler used for the node discovery. Registered when a callback function
00440          * is registered */
00441         FH_NodeDiscoveryZB  *_nd_handler;
00442 
00443         /** Frame handler used for the rx packets. Automatically registered when a callback
00444          *  function is registered */
00445         FH_RxPacketZB  *_rx_pkt_handler;
00446 
00447         /** Frame handler used for the IO Data Sample packets. Automatically registered when a callback
00448          *  function is registered */
00449         FH_IoDataSampeZB  *_io_data_handler;
00450 
00451         /** Method called directly by the library when a modem status frame is received to
00452          * update the internal status variables */
00453         virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status);
00454 
00455         /* Allow using XBee::send_data() methods from this class */
00456         using XBee::send_data;
00457 
00458         /** get_node_discovery_timeout - gets the node discovery timeout
00459           *
00460           *  @param timeout_ms pointer where the node discovery timeout value will be stored
00461           *  @param wait_for_complete_timeout pointer where the function will store if the operator
00462           *                                   has to wait for the complete nd timeout after issuing 
00463           *                                   a directed nd request
00464           *  @returns
00465           *     Success if the operation was successful,
00466           *     Failure otherwise
00467           */
00468         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms);
00469         virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms, bool * const wait_for_complete_timeout);
00470 };
00471 
00472 }   /* namespace XBeeLib */
00473 
00474 #endif /* __XBEE_ZB_H_ */