changes to communication
Fork of XBeeLib by
Diff: XBee/XBee.h
- Revision:
- 4:629712865107
- Parent:
- 3:8662ebe83570
- Child:
- 5:da2ea7a76243
--- a/XBee/XBee.h Mon May 18 13:16:55 2015 +0200 +++ b/XBee/XBee.h Mon Jun 01 18:59:43 2015 +0200 @@ -47,44 +47,11 @@ * @{ */ /** - * RadioStatus + * RadioStatus */ enum RadioStatus { Success = 0, /**< Success */ Failure = -1, /**< Failure */ - OpNotSupported = -2, /**< Option Not Supported */ -}; -/** - * @} - */ - -/** - * @defgroup RadioType - * @{ - */ -/** - * RadioType - */ -enum RadioType { - Unknown = 0, /**< Not detected yet */ - XB24_A_S1 = 0x17, /**< S1 */ - XBP24_A_S1 = 0x18, /**< S1 */ - XB24_B_S2 = 0x19, /**< S2 */ - XBP24_B_S2 = 0x1A, /**< S2 */ - XBP09_D = 0x1B, /**< S4 */ - XBP09_XC = 0x1C, /**< S3 */ - XBP08_D = 0x1D, /**< 868MHz S5 */ - XBP24_B_S2B = 0x1E, /**< S2B */ - XB24_WF = 0x1F, /**< S6 */ - XBP24_C_SMT = 0x21, /**< XBee PRO SMT S2C */ - XB24_C_SMT = 0x22, /**< XBee SMT S2C */ - XBP09_XC_B = 0x23, /**< S3B */ - XBP09_B = 0x23, /**< S3B */ - XB8 = 0x24, /**< S8 */ - XB2B_WF_TH = 0x27, /**< S6B TH */ - XB2B_WF_SMT = 0x28, /**< S6B SMT */ - XBP24_C_TH = 0x2D, /**< S2C TH */ - XB24_C_TH = 0x2E, /**< S2C TH */ }; /** * @} @@ -95,7 +62,7 @@ * @{ */ /** - * TxStatus + * TxStatus */ enum TxStatus { TxStatusSuccess = 0, /**< Success */ @@ -124,46 +91,11 @@ */ /** - * @defgroup PmMode - * @{ - */ -/** - * PmMode - */ -enum PmMode { - SleepDisabled = 0, /**< SleepDisabled */ - PinSleep = 1, /**< PinSleep */ - PinDoze = 2, /**< PinDoze */ - CyclicSeleep = 4, /**< CyclicSeleep */ - CyclicSeleepPinW = 5, /**< CyclicSeleepPinW */ -}; -/** - * @} - */ - - /** - * @defgroup NetworkRole - * @{ - */ -/** - * NetworkRole - */ -enum NetworkRole { - UnknownRole, /**< Unknown Role */ - Coordinator, /**< Coordinator */ - Router, /**< Router */ - EndDevice, /**< EndDevice */ -}; -/** - * @} - */ - -/** * @defgroup RadioLocation * @{ */ /** - * RadioLocation + * RadioLocation */ enum RadioLocation { RadioLocal = 0, /**< Local Radio */ @@ -172,7 +104,7 @@ /** * @} */ - + /** Parent Class for XBee modules, not to be directly used */ class XBee { @@ -187,16 +119,14 @@ RadioStatus wait_for_module_to_reset(volatile uint16_t *rst_cnt_p, uint16_t init_rst_cnt); protected: - /** timer used by local and remote objects */ - static Timer _timer; - /** buffer to store the received frames */ - static FrameBuffer _framebuf; + static FrameBuffer _framebuf_app; + static FrameBuffer _framebuf_syncr; public: - + /** - * RadioMode + * RadioMode */ enum RadioMode { ModeUnknown = 0, /**< Unknown */ @@ -216,11 +146,11 @@ * to this baud rate (ATBD parameter). By default it is configured to 9600 bps * */ XBee(PinName tx, PinName rx, PinName reset = NC, PinName rts = NC, PinName cts = NC, int baud = 9600); - + XBee(const XBee& other); /* Intentionally not implemented */ /** Class destructor */ virtual ~XBee(); - + /** init- initializes object * This function must be called just after creating the object so it initializes internal data. * @returns @@ -235,12 +165,6 @@ */ uint64_t get_addr64() const; - /** get_addr16 - returns the 16bit address of the local device - * - * @returns the 16-bit address of the local device. - */ - uint16_t get_addr16() const; - /** get_network_address - gets the 16bit network address of the device * * @param addr pointer where the device 16bit network address will be stored @@ -266,8 +190,8 @@ * Failure otherwise */ RadioStatus software_reset(); - - /** device_reset - performs a hardware reset if there is a GPIO connected to the + + /** device_reset - performs a hardware reset if there is a GPIO connected to the * reset line of the device. Otherwise, performs a firmware reset. * * @returns @@ -279,12 +203,6 @@ #endif RadioStatus device_reset(); - /** get_radio_type - returns the type of radio, in most cases the hardware version - * - * @returns the radio type - */ - RadioType get_radio_type() const; - /** set_tx_options - sets the transmit options byte, used with the transmit frames. * Valid flags are: * - DISABLE_RETRIES_AND_ROUTE_REPAIR @@ -295,24 +213,11 @@ */ void set_tx_options(uint8_t options); - /** set_broadcast_radius - sets the max number of hops for a broadcast msg. - * When set to 0 uses the maximum possible. - * - * @param bc_radius variable with the broadcast radious - */ - void set_broadcast_radius(uint8_t bc_radius); - /** get_tx_options - returns the tx options byte configured in the library. * * @returns the tx options byte configured in the library. */ uint8_t get_tx_options() const; - - /** get_bc_radius - returns the broadcast radius configured in the library. - * - * @returns the broadcast radius configured in the library. - */ - uint8_t get_bc_radius() const; /************************ Configuration member methods *************************/ /** write_config - write settings to non volatile memory @@ -322,7 +227,7 @@ * Failure otherwise */ RadioStatus write_config(); - + /** config_io_sample_destination - configures to which node a remote module will send its IO Samples to. * @Note: this will modify 'remote' DH and DL parameters, if the remote node is configured in transparent mode this could lead to unwanted behavior. * Consult the module's reference manual for more information. @@ -362,13 +267,13 @@ * Failure otherwise */ RadioStatus get_power_level(uint8_t * const level); - + /** get_hw_version - gets the hardware version of the radio * * @returns the hardware version of the radio */ uint16_t get_hw_version() const; - + /** get_fw_version - gets the firmware version of the radio * * @returns the firmware version of the radio @@ -393,9 +298,28 @@ */ RadioStatus get_node_identifier(char * const node_id); + /** enable_network_encryption - Enable network encryption. + * + * @param enable whether to enable this feature or not + * @returns + * Success if the operation was successful, + * Failure otherwise + */ + RadioStatus enable_network_encryption(bool enable); + + /** set_network_encryption_key - Sets the 128-bit AES key used for encryption and decryption. Setting it to 0 will cause the coordinator to transmit the network key in the clear to joining devices, and will cause joining devices to acquire the network key in the clear when joining. + * 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_encryption_key(const uint8_t * const key, const uint16_t length); + /** start_node_discovery - starts a node discovery operation. The responses * have to be processes on the callback function that have to be registered - * for that purpose + * for that purpose. * * @returns * Success if the operation was successful, @@ -403,6 +327,11 @@ */ RadioStatus start_node_discovery(); + /** is_node_discovery_in_progress - checks if node discovery is in progress. + * @returns true if node discovery is in progress, false otherwise + */ + bool is_node_discovery_in_progress(); + #define XBEEZB_ND_OPTION_APPEND_DD (1 << 0) #define XBEEZB_ND_OPTION_SELF_RESPONSE (1 << 1) #define XBEE802_ND_OPTION_SELF_RESPONSE (1 << 0) @@ -437,7 +366,7 @@ * @param timeout_ms new timeout in ms */ void set_timeout(uint16_t timeout_ms); - + /** get_timeout - gets the timeout in ms configured in the library. This value * is used in sync commands * @@ -445,7 +374,7 @@ */ uint16_t get_timeout() const; - /* ... */ + /* ... */ /*********************** send_data member methods ************************/ /** send_data - sends data to a remote device @@ -459,7 +388,7 @@ * the error code otherwise */ virtual TxStatus send_data(const RemoteXBee& remote, const uint8_t *const data, uint16_t len, bool syncr = true) = 0; - + /** send_data_broadcast - sends data to all devices in the network, using the broadcast address. * * @param data pointer to the data that will be sent @@ -470,7 +399,7 @@ * the error code otherwise */ TxStatus send_data_broadcast(const uint8_t *const data, uint16_t len, bool syncr = true); - + /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response. * * @param param parameter to be set. @@ -478,29 +407,29 @@ * @returns the command response status. */ AtCmdFrame::AtCmdResp set_param(const char * const param, uint32_t data); - + /** set_param - sets a parameter in the local radio by sending an AT command and waiting for the response. * * @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. + * @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. */ AtCmdFrame::AtCmdResp set_param(const char * const param, const uint8_t * data = NULL, uint16_t len = 0); - + /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response. * * @param param parameter to be get. - * @param data pointer where the param value (4 bytes) will be stored. + * @param data pointer where the param value (4 bytes) will be stored. * @returns the command response status. */ AtCmdFrame::AtCmdResp get_param(const char * const param, uint32_t * const data); - + /** get_param - gets a parameter from the local radio by sending an AT command and waiting for the response. * * @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. + * @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. */ AtCmdFrame::AtCmdResp get_param(const char * const param, uint8_t * const data, uint16_t * const len); @@ -513,110 +442,37 @@ * @returns the command response status. */ virtual AtCmdFrame::AtCmdResp set_param(const RemoteXBee& remote, const char * const param, uint32_t data) = 0; - + /** 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 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) = 0; - + /** 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. + * @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) = 0; - + /** 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. + * @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) = 0; -#if defined(ENABLE_PM_SUPPORT) - /** set_pm_control - sets the operational mode of the Power Management on - * the radio and registers the GPIOs used to handle the - * Power Management - * - * @param mode operational mode of the power management - * @param on_sleep pin used to detect the on/sleep status of the module - * @param sleep_rq pin used to request the module to go to sleep (when pin - * sleep mode is used - * @returns the result of the configuration operation - * Success if the operation was successful, - * Failure otherwise - */ - RadioStatus set_pm_control(PmMode mode, PinName on_sleep = NC, PinName sleep_rq = NC); - - /** get_pm_mode - gets the power management mode programmed in the radio. - * - * @param mode pointer where the read mode will be stored. - * @returns the result of the configuration operation - * Success if the operation was successful, - * Failure otherwise - */ - RadioStatus get_pm_mode(PmMode *mode); - - /** config_pm_timing - configures the power management timing parameters. - * - * @param before_sleep_ms number of miliseconds of inactivity before the radio will - * automatically go to sleep again (when using cyclic sleep). - * @param total_sleep_period_ms time interval in ms the radio will be sleeping. Once - * this time passes, the radio will wakeup, will check for - * packets and will wait before_sleep_ms of inactivity - * before entering again in sleep mode. - * @returns the result of the configuration operation - * Success if the operation was successful, - * Failure otherwise - */ - RadioStatus config_pm_timing(uint32_t before_sleep_ms, uint32_t total_sleep_period_ms); - - /** enter_sleep_mode - sets the radio into low power mode. If the pm working mode - * is pin-sleep, then it will use the GPIO, otherwise, it will - * use the serial interface. - * - * @note the method does not wait until the radio enters in sleep mode, it returns - * without making any verification. - * @returns the result of the operation - * Success if the operation was successful, - * Failure otherwise - */ - RadioStatus enter_sleep_mode(); - - /** exit_sleep_mode - for the pm mode called pin-sleep, sets the radio into active power - * using the corresponding GPIO. - * - */ - void exit_sleep_mode(); - - /** is_sleeping - checks if the radio is sleeping or if its active. - * - * @returns true if the radio is sleeping, false otherwisw - */ - bool is_sleeping(); - - /** register_wakeup_cb - registers the callback function that will be called - * when the radio wakes up from sleep mode. - * - * @param f function pointer with the callback function - */ - void register_wakeup_cb(void (*f)(void)); - - /** unregister_wakeup_cb - removes the wakeup callback */ - void unregister_wakeup_cb(); -#endif /* defined(ENABLE_PM_SUPPORT) */ - - /** process_rx_frames - method that process the frames queued in the reception + /** process_rx_frames - method that processes the frames queued in the reception * buffer. Calls the process_frame_data method of the frame * handlers registered * @@ -648,20 +504,20 @@ ZNet, #endif }; - /** send_byte_escaping_if - sends a byte, through the serial interface, to + /** send_byte_escaping_if - sends a byte, through the serial interface, to * the radio, escaping the byte if the working mode of the radio is API2. * * @param line PWM line being set * @param data the byte that will be send to radio */ void send_byte_escaping_if(uint8_t data); - + /** uart_read_cb - serial interface callback, called when data is received on * the serial port. The function parses the incoming data and, when a good * frame is detected, saves it in the frame list */ void uart_read_cb(); - + /** get_this_api_frame - searches in the FrameBuffer for an incoming frame * with frameid equal to id and frame type equal to type * or type2. If after timeout the frame hast not been found, @@ -670,14 +526,14 @@ * @param id id of the frame we are looking for. * @param type tye type we expect the frame to be. * @param type2 alternative valid type, if provided. - * @returns a pointer to the frame found in the FrameBuffer or a null pointer if + * @returns a pointer to the frame found in the FrameBuffer or a null pointer if * the frame has not been found and the timeout expired. */ - ApiFrame * get_this_api_frame(uint8_t id, ApiFrame::ApiFrameType type, + ApiFrame * get_this_api_frame(uint8_t id, ApiFrame::ApiFrameType type, ApiFrame::ApiFrameType type2 = ApiFrame::Invalid); /** send_api_frame - method to send, over the serial port, an API frame - * + * * @param frame pointer to the frame that will be sent. */ #if defined(UNIT_TEST) @@ -687,15 +543,15 @@ /** update_radio_status - method called when a modem status frame is received * to update the internal status variables of the library. - * @note This is not a pure virtual function because it can be called while + * @note This is not a pure virtual function because it can be called while * the object is being constructed and we need the implementation of the - * base class. + * base class. * * @param status byte with the status received in the modem status frame */ virtual void radio_status_update(AtCmdFrame::ModemStatus modem_status); - - /** Method used internaly by the derived classes to transmit data to + + /** Method used internaly by the derived classes to transmit data to * remote nodes, waiting for the answer from the device * * @param frame frame that will be sent to the radio (have to be a @@ -709,25 +565,20 @@ /** send_at_cmd - sends an AT command to the radio and waits for the response. * * @param frame api frame with the command and command params. - * @param buf pointer where the param response (n bytes) will be stored. - * @param len pointer where the number of bytes of the param response will be stored. - * @param radio_location radio location, either RadioLocal or RadioRemote. - * @param reverse reverse the byte ordering of the response saved in buf. + * @param buf pointer where the param response (n bytes) will be stored. + * @param len pointer where the number of bytes of the param response will be stored. + * @param radio_location radio location, either RadioLocal or RadioRemote. + * @param reverse reverse the byte ordering of the response saved in buf. * @returns the command response status. */ AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint8_t *const buf, uint16_t *const len, RadioLocation radio_location = RadioLocal, bool reverse = true); - + /* send_at_cmd - methods used internally by other methods */ AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame); AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint8_t *data); AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint16_t *data); AtCmdFrame::AtCmdResp send_at_cmd(AtCmdFrame *frame, uint32_t *data); - -#if defined(ENABLE_PM_SUPPORT) - /** Sets the radio into low power mode. This method is used by enter_sleep_mode() */ - RadioStatus sleep_now(); -#endif /* defined(ENABLE_PM_SUPPORT) */ /** register_frame_handler - registers an object to handle incoming frames from * the radio. @@ -777,15 +628,20 @@ */ bool check_radio_flow_control(); + /** get_AI - reads the AI parameter. + * + * @returns + * -1 if an error occurred when reading AI. + * 0-0xFF the AI value. + */ + int get_AI(void); + /** serial hardware flow control selected by the user (RTSCTS, RTS,CTS) */ SerialBase::Flow _serial_flow_type; /** Operating mode of the module (API1, API2,...) */ RadioMode _mode; - /** Type of radio, mainly the hardware version, but may differ in some cases */ - RadioType _type; - /** Hardware version value of the radio */ uint16_t _hw_version; @@ -793,28 +649,22 @@ uint16_t _fw_version; /** Timeout in ms for sync operations (when we wait for a response) */ - uint16_t _timeout_ms; + uint16_t _timeout_ms; /** Device 64 bit address (SH, SL) */ uint64_t _dev_addr64; - /** Device 16 bit address (MY) */ - uint16_t _dev_addr16; - /** Serial Interface, use RawSerial as we dont use the streams */ RawSerial *_uart; /** IO connected to the radio reset line */ - DigitalOut *_reset; - + DigitalOut *_reset; + /** Transmit options byte */ uint8_t _tx_options; - /** Broadcast radius, number of hops a broadcast transmission can occur. - * When set to 0 it will use the maximum */ - uint8_t _bc_radius; - /** Array of frame handler pointers. We use an array instead of a vector or other - * data structure to save memory and avoid dynamic memory allocation, to avoid + /** Array of frame handler pointers. We use an array instead of a vector or other + * data structure to save memory and avoid dynamic memory allocation, to avoid * memory fragmentation */ FrameHandler *_fhandlers[MAX_FRAME_HANDLERS]; @@ -824,8 +674,6 @@ /** Watchdog reset counter, automatically updated by the library */ volatile uint16_t _wd_reset_cnt; - uint16_t _reset_timeout; - /** Frame handler used for the Modem Status packets. Automatically registered when a callback * function is registered */ FH_ModemStatus *_modem_status_handler; @@ -836,14 +684,14 @@ /** Library is initializing */ bool _initializing; -#if defined(ENABLE_PM_SUPPORT) - /* Power Management mode used by the radio */ - PmMode _pm_mode; - /** IO connected to the radio on_sleep line */ - InterruptIn *_on_sleep; - /** IO connected to the radio sleep_req line */ - DigitalOut *_sleep_req; -#endif + /** Timer used for node discovery */ + Timer _nd_timer; + + /** node discovery timeout */ + int _nd_timeout; + + /** If a _get_remote_node_by_id() is in progress, this keeps the expected frame id */ + uint8_t _node_by_ni_frame_id; }; } /* namespace XBeeLib */