changes to communication
Fork of XBeeLib by
Diff: XBeeDM/XBeeDM.h
- Revision:
- 6:06522f3a6642
- Child:
- 7:3ac2a461ce76
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/XBeeDM/XBeeDM.h Thu Jul 28 10:17:20 2016 +0200 @@ -0,0 +1,414 @@ +/** + * Copyright (c) 2015 Digi International Inc., + * All rights not expressly granted are reserved. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this file, + * You can obtain one at http://mozilla.org/MPL/2.0/. + * + * Digi International Inc. 11001 Bren Road East, Minnetonka, MN 55343 + * ======================================================================= + */ + +#if !defined(__XBEE_DM_H_) +#define __XBEE_DM_H_ + +#include "XBee/XBee.h" +#include "FrameHandlers/FH_AtCmdResp.h" +#include "FrameHandlers/FH_RxPacketDM.h" +#include "FrameHandlers/FH_IoDataSampleDM.h" +#include "RemoteXBee/RemoteXBee.h" + +namespace XBeeLib { + +/** Class for XBee ZigBee modules, derived from XBee */ +class XBeeDM : public XBee +{ + public: + + /** + * IoLine for XBeeDM Modules + */ + enum IoLine { + DIO0_AD0 = 0, /**< DIO0_AD0 pin */ + DIO1_AD1 = 1, /**< DIO1_AD1 pin */ + DIO2_AD2 = 2, /**< DIO2_AD2 pin */ + DIO3_AD3 = 3, /**< DIO3_AD3 pin */ + DIO4 = 4, /**< DIO4 pin */ + DIO5 = 5, /**< DIO5 pin */ + DIO6 = 6, /**< DIO6 pin */ + DIO7 = 7, /**< DIO7 pin */ + DIO8 = 8, /**< DIO8 pin */ + DIO9 = 9, /**< DIO9 pin */ + DIO10_PWM0 = 10, /**< DIO10_PWM0 pin */ + DIO11_PWM1 = 11, /**< DIO11_PWM1 pin */ + DIO12 = 12 /**< DIO12 pin */ + }; + + enum AssocStatus { + ErrorReading = -1, /**< Error occurred when reading parameter. */ + Joined = 0x00, /**< Successfully formed or joined a network. (Coordinators form a network, routers and end devices join a network.) */ + NoPANs = 0x21, /**< Scan found no PANs */ + NoValidPAN = 0x22, /**< Scan found no valid PANs based on current SC and ID settings */ + JoinNotAllowed = 0x23, /**< Valid Coordinator or Routers found, but they are not allowing joining (NJ expired). */ + NoBeacons = 0x24, /**< No joinable beacons were found. */ + Unexpected = 0x25, /**< Unexpected state, node should not be attempting to join at this time. */ + JoinFailed = 0x27, /**< Node Joining attempt failed (typically due to incompatible security settings). */ + CoordStartFail = 0x2A, /**< Coordinator start attempt failed */ + CheckingCoord = 0x2B, /**< Checking for an existing coordinator. */ + LeaveFail = 0x2C, /**< Attempt to leave the network failed. */ + JoinNoResponse = 0xAB, /**< Attempted to join a device that did not respond. */ + SecKeyUnsec = 0xAC, /**< Secure join error - network security key received unsecured. */ + SecKeyNotRec = 0xAD, /**< Secure join error - network security key not received. */ + SecBadKey = 0xAF, /**< Secure join error - joining device does not have the right preconfigured link key. */ + Scanning = 0xFF /**< Scanning for a ZigBee network (routers and end devices). */ + }; + + /** Class constructor + * @param tx the TX pin of the UART that will interface the XBee module + * @param rx the RX pin of the UART that will interface the XBee module + * @param reset the pin to which the XBee's reset line is attached to, use NC if not available + * @param rts the RTS pin for the UART that will interface the XBee module, use NC if not available + * @param cts the CTS pin for the UART that will interface the XBee module, use NC if not available + * @param baud the baudrate for the UART that will interface the XBee module. Note that the module has to be already configured + * to this baud rate (ATBD parameter). By default it is configured to 9600 bps + */ + XBeeDM(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600); + + /** Class destructor */ + virtual ~XBeeDM(); + + /** init- initializes object + * This function must be called just after creating the object so it initializes internal data. + * @returns + * Success if the module has been properly initialized and is ready to process data. + * Failure otherwise. + */ + RadioStatus init(); + + /** set_channel - sets the channel number + * + * @param channel the channel in which the radio operates. Range is 0x0B - 0x1A for XBee and 0x0C - 0x17 for XBee-PRO. + * The Center Frequency = 2.405 + (CH - 11) * 5 MHz + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_channel(uint8_t channel); + + /** get_channel - gets the channel number + * + * @param channel pointer where the channel value will be stored. + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus get_channel(uint8_t * const channel); + + /** set_network_id - sets the Network ID. + * + * @param network_id the Network ID value that will be set on the radio + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_network_id(uint16_t network_id); + + /** get_network_id - gets the Network ID, as it was set by @ref set_network_id(). + * + * @param network_id pointer where the Network ID will be stored + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus get_network_id(uint16_t * const network_id); + + /** 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. + * It is not recommended to set the key programmatically, because it could be read through the raw serial port bits. + * @param key pointer to the 128-bit AES key + * @param length size of the buffer pointed by 'key' + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_network_security_key(const uint8_t * const key, const uint16_t length); + +#define XBEE_DM_ENC_OPT_SEND_KEY_ON_JOIN 0x01 +#define XBEE_DM_ENC_OPT_USE_TRUST_CENTER 0x02 + /** set_encryption_options - Configure options for encryption. Unused option bits should be set to 0. Options include: + * - XBEE_DM_ENC_OPT_SEND_KEY_ON_JOIN - Send the security key unsecured over-the-air during joins + * - XBEE_DM_ENC_OPT_USE_TRUST_CENTER - Use trust center (coordinator only) + * @param options bit mask with the encryption options + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_encryption_options(const uint8_t options); + + /** register_node_discovery_cb - registers the callback function that will be called + * when the responses to the node discovery command arrive + * + * @param function function pointer with the callback function + */ + void register_node_discovery_cb(node_discovery_dm_cb_t function); + + /** unregister_node_discovery_cb - removes the node discovery callback */ + void unregister_node_discovery_cb(); + + /** register_receive_cb - registers the callback function that will be called + * when a data packet is received + * + * @param function function pointer with the callback function + */ + void register_receive_cb(receive_dm_cb_t function); + + /** unregister_receive_cb - removes the rx packet callback */ + void unregister_receive_cb(); + + /** register_io_sample_cb - registers the callback function that will be called + * when a IO Sample Data packet is received + * + * @param function function pointer with the callback function + */ + void register_io_sample_cb(io_data_cb_dm_t function); + + /** unregister_io_sample_cb - removes the IO Sample Data reception callback */ + void unregister_io_sample_cb(); + + /*********************** send_data member methods ************************/ + /** send_data - sends data to a remote device + * + * @param remote remote device + * @param data pointer to the data that will be sent + * @param len number of bytes that will be transmitted + * @param syncr if true, method waits for the packet answer with the result of the operation + * @returns the result of the data transfer + * TxStatusSuccess if the operation was successful, + * the error code otherwise + */ + virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true); + + /** send_data - sends data to a remote device. This method uses + * the explicit addressing frame, allowing to use source and + * destination end points and cluster and profile IDs + * + * @param remote remote device + * @param source_ep source end point + * @param dest_ep destination end point + * @param cluster_id cluster ID + * @param profile_id profile ID + * @param data pointer to the data that will be sent + * @param len number of bytes that will be transmitted + * @param syncr if true, method waits for the packet answer with the result of the operation + * @returns the result of the data transfer + * TxStatusSuccess if the operation was successful, + * the error code otherwise + */ + TxStatus send_data(const RemoteXBee& remote, uint8_t source_ep, + uint8_t dest_ep, uint16_t cluster_id, uint16_t profile_id, + const uint8_t *const data, uint16_t len, bool syncr = true); + + /** send_data_to_coordinator - sends data to the ZigBee coordinator + * + * @param data pointer to the data that will be sent + * @param len number of bytes that will be transmitted + * @param syncr if true, method waits for the packet answer with the result of the operation + * @returns the result of the data transfer + * TxStatusSuccess if the operation was successful, + * the error code otherwise + */ + TxStatus send_data_to_coordinator(const uint8_t *const data, uint16_t len, bool syncr = true); + + /** get_assoc_status - returns current network association status. This wraps AI parameter, for more information refer to moudle's Reference Manual. + * + * @returns an AssocStatus with current network association status. + */ + AssocStatus get_assoc_status(void); + + /** get_remote_node_by_id - searches for a device in the network with the specified Node Identifier. + * + * @param node_id node id of the device we are looking for + * @returns a RemoteXBeeDM with the 16-bit and 64-bit address of the remote device whose node id matches with the parameter. + * If node is not found, the returned object will have invalid addresses (RemoteXBeeDM::is_valid() will return false). + */ + RemoteXBeeDM get_remote_node_by_id(const char * const node_id); + + /* Allow using XBee::set_param() methods for local radio from this class */ + using XBee::set_param; + + /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response. + * + * @param remote remote device + * @param param parameter to be set. + * @param data the parameter value (4 bytes) to be set. + * @returns the command response status. + */ + virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data); + + /** set_param - sets a parameter in a remote radio by sending an AT command and waiting for the response. + * + * @param remote remote device + * @param param parameter to be set. + * @param data the parameter value byte array (len bytes) to be set. + * @param len number of bytes of the parameter value. + * @returns the command response status. + */ + virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, const uint8_t * data = NULL, uint16_t len = 0); + + /* Allow using XBee::get_param() methods for local radio from this class */ + using XBee::get_param; + + /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response. + * + * @param remote remote device + * @param param parameter to be get. + * @param data pointer where the param value (4 bytes) will be stored. + * @returns the command response status. + */ + virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint32_t * const data); + + /** get_param - gets a parameter from a remote radio by sending an AT command and waiting for the response. + * + * @param remote remote device + * @param param parameter to be get. + * @param data pointer where the param value (n bytes) will be stored. + * @param len pointer where the number of bytes of the param value will be stored. + * @returns the command response status. + */ + virtual AtCmdFrame::AtCmdResp get_param(const RemoteXBee& remote, const char * const param, uint8_t * const data, uint16_t * const len); + + /************************* IO member methods **************************/ + /** set_pin_config - configures a radio IO line + * + * @param remote remote device + * @param line IO line being configured + * @param mode configuration mode for the selected line + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_pin_config(const RemoteXBee& remote, IoLine line, IoMode mode); + + /** get_pin_config - gets the configuration of a radio IO line + * + * @param remote remote device + * @param line IO line being read to get its configuration + * @param mode pointer where the configuration will be stored + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus get_pin_config(const RemoteXBee& remote, IoLine line, IoMode * const mode); + + /** set_dio - sets to low/high a DIO line + * + * @param remote remote device + * @param line DIO line being set + * @param val value that will be set in the DIO line + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_dio(const RemoteXBee& remote, IoLine line, DioVal val); + + /** get_dio - read the value of a DIO configured as digital input + * + * @param remote remote device + * @param line DIO line being read + * @param val pointer where the DIO value read will be stored + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus get_dio(const RemoteXBee& remote, IoLine line, DioVal * const val); + + /** get_adc - read the value of the espcified ADC line + * + * @param remote remote device + * @param line ADC line being read + * @param val pointer where the value read from hte ADC will be stored + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus get_adc(const RemoteXBee& remote, IoLine line, uint16_t * const val); + + /** 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. + * + * @param remote remote device + * @returns IOSampleDM object with the remote node's DIO and ADC values. + */ + IOSampleDM get_iosample(const RemoteXBee& remote); + + /** set_pwm - sets the duty cycle of a PWM line + * + * @param remote remote device + * @param line PWM line being set + * @param duty_cycle duty cycle that will be set in the PWM line + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_pwm(const RemoteXBee& remote, IoLine line, float duty_cycle); + + /** set_pin_pull_up - enables or disables the internal pull-up resistor of a line + * + * @param remote remote device + * @param line line being configured for pull-up + * @param enable whether to enable the internal pull-up resistor. + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus set_pin_pull_up(const RemoteXBee& remote, IoLine line, bool enable); + + /** enable_dio_change_detection - enables or disables the notification when a change is detected in a digital input line. + * In other words, it will force an IO Sample transmission when the DIO state changes. Only for DIO0 to DIO11. + * + * @param remote remote device + * @param line line being configured for pull-up + * @param enable whether to enable the internal pull-up resistor. + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus enable_dio_change_detection(const RemoteXBee& remote, IoLine line, bool enable); + + protected: + + /** Frame handler used for the node discovery. Registered when a callback function + * is registered */ + FH_NodeDiscoveryDM *_nd_handler; + + /** Frame handler used for the rx packets. Automatically registered when a callback + * function is registered */ + FH_RxPacketDM *_rx_pkt_handler; + + /** Frame handler used for the IO Data Sample packets. Automatically registered when a callback + * function is registered */ + FH_IoDataSampeDM *_io_data_handler; + + /** Method called directly by the library when a modem status frame is received to + * update the internal status variables */ + virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status); + + /* Allow using XBee::send_data() methods from this class */ + using XBee::send_data; + + /** get_node_discovery_timeout - gets the node discovery timeout + * + * @param timeout_ms pointer where the node discovery timeout value will be stored + * @param wait_for_complete_timeout pointer where the function will store if the operator + * has to wait for the complete nd timeout after issuing + * a directed nd request + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms); + virtual RadioStatus get_node_discovery_timeout(uint16_t * const timeout_ms, bool * const wait_for_complete_timeout); +}; + +} /* namespace XBeeLib */ + +#endif /* __XBEE_DM_H_ */