changes to communication
Fork of XBeeLib by
Embed:
(wiki syntax)
Show/hide line numbers
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_ */
Generated on Tue Jul 12 2022 17:33:34 by 1.7.2