device.h

Go to the documentation of this file.

/*
 * Copyright (c) 2009-2013 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
 * =======================================================================
 */

#ifndef __XBEE_DEVICE
#define __XBEE_DEVICE

#include "xbee/platform.h"
#include "xbee/serial.h"
#include "wpan/types.h"
#include "wpan/aps.h"

XBEE_BEGIN_DECLS

#define XBEE_DEV_FLAG_NONE    0x0000

#ifndef XBEE_DEV_MAX_DISPATCH_PER_TICK
   #define XBEE_DEV_MAX_DISPATCH_PER_TICK 5
#endif

enum xbee_frame_type {
   XBEE_FRAME_LOCAL_AT_CMD             = 0x08,

   XBEE_FRAME_LOCAL_AT_CMD_Q           = 0x09,

   XBEE_FRAME_TRANSMIT                 = 0x10,

   XBEE_FRAME_TRANSMIT_EXPLICIT        = 0x11,

   XBEE_FRAME_REMOTE_AT_CMD            = 0x17,

   XBEE_FRAME_CREATE_SRC_ROUTE         = 0x21,

   XBEE_FRAME_REG_JOINING_DEV          = 0x24,

   XBEE_FRAME_LOCAL_AT_RESPONSE        = 0x88,

   XBEE_FRAME_MODEM_STATUS             = 0x8A,

   XBEE_FRAME_TRANSMIT_STATUS          = 0x8B,

   XBEE_FRAME_ROUTE_INFORMATION        = 0x8D,

   XBEE_FRAME_AGGREGATE_ADDRESSING     = 0x8E,

   XBEE_FRAME_RECEIVE                  = 0x90,     // ATAO == 0

   XBEE_FRAME_RECEIVE_EXPLICIT         = 0x91,     // ATAO != 0

   XBEE_FRAME_IO_RESPONSE              = 0x92,

   XBEE_FRAME_SENDOR_READ              = 0x94,

   XBEE_FRAME_NODE_ID                  = 0x95,

   XBEE_FRAME_REMOTE_AT_RESPONSE       = 0x97,

   XBEE_FRAME_FW_UPDATE_STATUS         = 0xA0,

   XBEE_FRAME_ROUTE_RECORD             = 0xA1,

   XBEE_FRAME_DEVICE_AUTHENTICATED     = 0xA2,

   XBEE_FRAME_ROUTE_REQUEST_INDICATOR  = 0xA3,

   XBEE_FRAME_REG_JOINING_DEV_STATUS   = 0xA4,

   XBEE_FRAME_JOIN_NOTIFICATION_STATUS = 0xA5,
};

#define XBEE_RX_OPT_ACKNOWLEDGED    0x01

#define XBEE_RX_OPT_BROADCAST       0x02

#define XBEE_RX_OPT_SENT_ENCRYPTED  0x10

#define XBEE_RX_OPT_APS_ENCRYPT     0x20

#define XBEE_RX_OPT_FROM_END_DEVICE 0x40     // appeared in ZB 2x7x

#define XBEE_RX_OPT_MODE_MASK                0xC0

   #define XBEE_RX_OPT_MODE_NONE                (0)

   #define XBEE_RX_OPT_MODE_POINT_MULTIPOINT    (1<<6)

   #define XBEE_RX_OPT_MODE_REPEATER            (2<<6)

   #define XBEE_RX_OPT_MODE_DIGIMESH            (3<<6)

#ifndef XBEE_MAX_RFPAYLOAD
   #if XBEE_CELLULAR_ENABLED
      #define XBEE_MAX_RFPAYLOAD 1500
   #elif XBEE_WIFI_ENABLED
      #define XBEE_MAX_RFPAYLOAD 1400
   #else
      #define XBEE_MAX_RFPAYLOAD 256
   #endif
#endif

#define XBEE_MAX_RX_FRAME_LEN    (XBEE_MAX_RFPAYLOAD + 18)

#define XBEE_MAX_TX_FRAME_LEN    (XBEE_MAX_RFPAYLOAD + 20)

#define XBEE_MAX_FRAME_LEN    XBEE_MAX_RX_FRAME_LEN

// We need to declare struct xbee_dev_t here so the compiler doesn't treat it
// as a local definition in the parameter lists for the function pointer
// typedefs that follow.
struct xbee_dev_t;



/*
               Possible errors that will need unique -Exxx return values:
               -  Invalid xbee_dev_t
               -  No wpan_if assigned to xbee_dev_t
               -  Invalid length (must be > 0)
               -  Frame pointer is NULL

   @todo       What will _xbee_frame_dispatch do with those return values?
               Does there need to be a return value equivalent to "thanks
               for that frame, but please remove me from the dispatch table"?
               Right now, the dispatcher is ignoring the return value.
               Could be useful when registering to receive status information
               on outbound frames -- once we have status, we don't need
               to receive any additional notifications.
*/
typedef int (*xbee_frame_handler_fn)(
   struct xbee_dev_t          *xbee,
   const void           FAR   *frame,
   uint16_t                   length,
   void                 FAR   *context
);

typedef int (*xbee_is_awake_fn)( struct xbee_dev_t *xbee);

typedef void (*xbee_reset_fn)( struct xbee_dev_t *xbee, bool_t asserted);

struct xbee_node_id_t;
typedef void (*xbee_disc_node_id_fn)( struct xbee_dev_t *xbee,
      const struct xbee_node_id_t *rec);

typedef struct xbee_dispatch_table_entry {
   uint8_t                 frame_type; 
   uint8_t                 frame_id;   
   xbee_frame_handler_fn   handler;
   void              FAR   *context;
} xbee_dispatch_table_entry_t;



enum xbee_dev_rx_state {
   XBEE_RX_STATE_WAITSTART = 0,  
   XBEE_RX_STATE_LENGTH_MSB,     
   XBEE_RX_STATE_LENGTH_LSB,     
   XBEE_RX_STATE_RXFRAME         
};

enum xbee_dev_flags
{
   XBEE_DEV_FLAG_CMD_INIT        = 0x0001,   
   XBEE_DEV_FLAG_QUERY_BEGIN     = 0x0002,   
   XBEE_DEV_FLAG_QUERY_DONE      = 0x0004,   
   XBEE_DEV_FLAG_QUERY_ERROR     = 0x0008,   
   XBEE_DEV_FLAG_QUERY_REFRESH   = 0x0010,   
   XBEE_DEV_FLAG_QUERY_INPROGRESS= 0x0020,   

   XBEE_DEV_FLAG_IN_TICK         = 0x0080,   

   XBEE_DEV_FLAG_COORDINATOR     = 0x0100,   
   XBEE_DEV_FLAG_ROUTER          = 0x0200,   
   XBEE_DEV_FLAG_ENDDEV          = 0x0400,   
   XBEE_DEV_FLAG_ZNET            = 0x0800,   
   XBEE_DEV_FLAG_ZIGBEE          = 0x1000,   
   XBEE_DEV_FLAG_DIGIMESH        = 0x2000,   

   // (cast to int required by Codewarrior/HCS08 platform if enum is signed)
   XBEE_DEV_FLAG_USE_FLOWCONTROL = (int)0x8000, 
};

enum xbee_dev_mode {
   XBEE_MODE_UNKNOWN = 0,  
   XBEE_MODE_BOOTLOADER,   
   // Modes used by "AT firmware" and some bootloaders:
   XBEE_MODE_API,          
   XBEE_MODE_IDLE,         
   XBEE_MODE_PRE_ESCAPE,   
   XBEE_MODE_POST_ESCAPE,  
   XBEE_MODE_COMMAND,      
   XBEE_MODE_WAIT_IDLE,    
   XBEE_MODE_WAIT_RESPONSE 
};

typedef struct xbee_dev_t
{
   wpan_dev_t     wpan_dev;

   xbee_serial_t  serport;

   xbee_reset_fn     reset;

   xbee_is_awake_fn  is_awake;

   xbee_disc_node_id_fn    node_id_handler;

   uint16_t          hardware_version;
      #define XBEE_HARDWARE_MASK          0xFF00
      #define XBEE_HARDWARE_S1            0x1700
      #define XBEE_HARDWARE_S1_PRO        0x1800
      #define XBEE_HARDWARE_S2            0x1900
      #define XBEE_HARDWARE_S2_PRO        0x1A00
      #define XBEE_HARDWARE_900_PRO       0x1B00
      #define XBEE_HARDWARE_868_PRO       0x1D00
      #define XBEE_HARDWARE_S2B_PRO       0x1E00
      #define XBEE_HARDWARE_S2C_PRO       0x2100
      #define XBEE_HARDWARE_S2C           0x2200
      #define XBEE_HARDWARE_S3B           0x2300      // XBee 900HP
      #define XBEE_HARDWARE_S8            0x2400
      #define XBEE_HARDWARE_S6B           0x2700      // XBee Wi-Fi
      #define XBEE_HARDWARE_CELL_CAT1_VZW 0x4000
      #define XBEE_HARDWARE_XB3_MICRO     0x4100
      #define XBEE_HARDWARE_XB3_TH        0x4200
      #define XBEE_HARDWARE_CELL_3G       0x4400

   uint16_t          hardware_series;
      #define XBEE_HW_SERIES_MASK         0xFF00
      #define XBEE_HW_SERIES_WIFI_S6      0x0600
      #define XBEE_HW_SERIES_CELLULAR     0x0B00
      #define XBEE_HW_SERIES_XBEE3_RF     0x0C00

   uint32_t          firmware_version;
      #define XBEE_PROTOCOL_MASK          0xF000
      // Series 2 (2.4 GHz) hardware
      #define XBEE_PROTOCOL_ZNET          0x1000
      #define XBEE_PROTOCOL_ZB            0x2000
      #define XBEE_PROTOCOL_SMARTENERGY   0x3000
      #define XBEE_PROTOCOL_ZB_S2C        0x4000
      #define XBEE_PROTOCOL_SE_S2C        0x5000
      // Series 4 (900 MHz) hardware
      #define XBEE_PROTOCOL_MESHLESS      0x1000
      #define XBEE_PROTOCOL_DIGIMESH      0x8000
      // XBee 3 hardware
      #define XBEE_PROTOCOL_XB3_ZIGBEE    0x1000
      #define XBEE_PROTOCOL_XB3_802_15_4  0x2000
      #define XBEE_PROTOCOL_XB3_DIGIMESH  0x3000

      #define XBEE_NODETYPE_MASK          0x0F00
      #define XBEE_NODETYPE_COORD         0x0100
      #define XBEE_NODETYPE_ROUTER        0x0300
      #define XBEE_NODETYPE_ENDDEV        0x0900

   enum xbee_dev_flags        flags;

   uint8_t     frame_id;            

   // Need some state variables here if AT mode is supported (necessary when
   // using modules with AT firmware instead of API firmware, or when doing
   // firmware updates on DigiMesh 900 with API firmware).  Current state:
   // idle mode, command mode, pre-escape guard-time, post-escape guard-time.
   // Current timeout: value of MS_TIMER when guard-time expired or we expect
   // to return to idle mode from command mode.
   // If we track MS_TIMER from the last byte we sent to the XBee, we can
   // potentially skip over the pre-escape guard time and send the escape chars.

   #ifdef XBEE_DEVICE_ENABLE_ATMODE
      enum xbee_dev_mode   mode;
      uint32_t       mode_timer;    
      uint16_t       guard_time;    
      uint16_t       idle_timeout;  
      char           escape_char;   
   #endif

   struct rx {
      enum xbee_dev_rx_state  state;

      uint16_t                bytes_in_frame;

      uint16_t                bytes_read;

      uint8_t  frame_data[XBEE_MAX_FRAME_LEN + 1];
   } rx;
} xbee_dev_t;

#if BYTE_ORDER == BIG_ENDIAN
   #define XBEE_DEV_STACK_VERSION_ADDR(x) ((uint8_t *)&(x).firmware_version + 3)
#else
   #define XBEE_DEV_STACK_VERSION_ADDR(x) ((uint8_t *)&(x).firmware_version)
#endif

extern const xbee_dispatch_table_entry_t xbee_frame_handlers[];

#define XBEE_FRAME_TABLE_END     { 0xFF, 0, NULL, NULL }

uint8_t xbee_next_frame_id( xbee_dev_t *xbee);

int xbee_dev_init( xbee_dev_t *xbee, const xbee_serial_t *serport,
   xbee_is_awake_fn is_awake, xbee_reset_fn reset);

void xbee_dev_dump_settings( xbee_dev_t *xbee, uint16_t flags);
   #define XBEE_DEV_DUMP_FLAG_NONE        0x0000
#ifndef XBEE_DEV_DUMP_FLAG_DEFAULT
   #define XBEE_DEV_DUMP_FLAG_DEFAULT     XBEE_DEV_DUMP_FLAG_NONE
#endif

int xbee_dev_reset( xbee_dev_t *xbee);

int xbee_dev_tick( xbee_dev_t *xbee);

int xbee_frame_write( xbee_dev_t *xbee, const void FAR *header,
   uint16_t headerlen, const void FAR *data, uint16_t datalen,
   uint16_t flags);
#define XBEE_WRITE_FLAG_NONE     0x0000

void xbee_dev_flowcontrol( xbee_dev_t *xbee, bool_t enabled);

// private functions exposed for unit testing

void _xbee_dispatch_table_dump( const xbee_dev_t *xbee);

uint8_t _xbee_checksum( const void FAR *bytes, uint16_t length,
   uint_fast8_t initial);

int _xbee_frame_load( xbee_dev_t *xbee);

int _xbee_frame_dispatch( xbee_dev_t *xbee, const void FAR *frame,
   uint16_t length);


typedef XBEE_PACKED(xbee_frame_modem_status_t, {
   uint8_t        frame_type;          
   uint8_t        status;              
}) xbee_frame_modem_status_t;

#define XBEE_MODEM_STATUS_HW_RESET              0x00
#define XBEE_MODEM_STATUS_WATCHDOG              0x01
#define XBEE_MODEM_STATUS_JOINED                0x02
#define XBEE_MODEM_STATUS_DISASSOC              0x03
#define XBEE_MODEM_STATUS_IP_CONFIG_ERROR       0x04
#define XBEE_MODEM_STATUS_COORD_START           0x06
#define XBEE_MODEM_STATUS_NETWORK_KEY_UPDATED   0x07
#define XBEE_MODEM_STATUS_WOKE_UP               0x0B
#define XBEE_MODEM_STATUS_SLEEPING              0x0C
#define XBEE_MODEM_STATUS_OVERVOLTAGE           0x0D
#define XBEE_MODEM_STATUS_CLOUD_CONNECTED       0x0E
#define XBEE_MODEM_STATUS_CLOUD_DISCONNECTED    0x0F
#define XBEE_MODEM_STATUS_KEY_ESTABLISHED       0x10
#define XBEE_MODEM_STATUS_CONFIG_CHANGE_IN_JOIN 0x11
#define XBEE_MODEM_STATUS_SS_ESTABLISHED        0x3B
#define XBEE_MODEM_STATUS_SS_ENDED              0x3C
#define XBEE_MODEM_STATUS_SS_AUTH_FAILED        0x3D
#define XBEE_MODEM_STATUS_STACK_ERROR           0x80

int xbee_frame_dump_modem_status( xbee_dev_t *xbee,
   const void FAR *frame, uint16_t length, void FAR *context);

#define XBEE_FRAME_MODEM_STATUS_DEBUG  \
   { XBEE_FRAME_MODEM_STATUS, 0, xbee_frame_dump_modem_status, NULL }

XBEE_END_DECLS

// If compiling in Dynamic C, automatically #use the appropriate C file.
#ifdef __DC__
   #use "xbee_device.c"
#endif

#endif      // #ifdef __XBEE_DEVICE