atcmd.h

Go to the documentation of this file.

/*
 * Copyright (c) 2008-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_COMMAND
#define __XBEE_COMMAND

#include "xbee/device.h"

XBEE_BEGIN_DECLS

#ifndef XBEE_CMD_REQUEST_TABLESIZE
   #define XBEE_CMD_REQUEST_TABLESIZE  2
#endif

#ifndef XBEE_CMD_MAX_PARAM_LENGTH
   #if XBEE_CELLULAR_ENABLED
      #define XBEE_CMD_MAX_PARAM_LENGTH 128
   #else
      #define XBEE_CMD_MAX_PARAM_LENGTH 64
   #endif
#endif

#define XBEE_CMD_REMOTE_TIMEOUT     180

#define XBEE_CMD_LOCAL_TIMEOUT      2

typedef union xbee_at_cmd {
   char     str[2];
   uint16_t    w;
} xbee_at_cmd_t;

// Values for ATEO command
#define XBEE_CMD_ATEO_INSECURE_JOIN       (1<<0)
#define XBEE_CMD_ATEO_USE_TRUST_CENTER    (1<<1)
#define XBEE_CMD_ATEO_USE_HASH_LINK_KEY   (1<<2)
#define XBEE_CMD_ATEO_USE_AUTHENTICATION  (1<<3)

// We need to declare struct _xbee_cmd_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_cmd_t;

typedef struct xbee_cmd_response {
   xbee_dev_t              *device;

   void              FAR   *context;

   int16_t                 handle;

   xbee_at_cmd_t           command;

   uint16_t                flags;
      #define XBEE_CMD_RESP_MASK_STATUS         0x000F
      #define XBEE_CMD_RESP_ATND_RSSI_INVALID   XBEE_AT_RESP_ATND_RSSI_INVALID
      #define XBEE_CMD_RESP_FLAG_TIMEOUT        0x8000

   uint_fast8_t            value_length;

   const uint8_t     FAR   *value_bytes;

   uint32_t                value;

   const wpan_address_t FAR   *source;
} xbee_cmd_response_t;

#define XBEE_ATCMD_DONE    0
#define XBEE_ATCMD_REUSE   1

typedef int (*xbee_cmd_callback_fn)(
   const xbee_cmd_response_t     FAR   *response
);

typedef struct xbee_cmd_request {
   uint8_t        sequence;

   xbee_dev_t     *device;

   uint16_t       timeout;

   uint16_t       flags;
      #define XBEE_CMD_FLAG_REMOTE        0x0001

      #define XBEE_CMD_FLAG_QUEUE_CHANGE  0x0002

      #define XBEE_CMD_FLAG_REUSE_HANDLE  0x0004

      #define XBEE_CMD_FLAG_USER_MASK  (XBEE_CMD_FLAG_QUEUE_CHANGE   \
                                       |XBEE_CMD_FLAG_REUSE_HANDLE)

/*
   we probably don't need this member

   uint8_t        status;        // status byte from AT response
      #define XBEE_CMD_STATUS_PENDING        254
      #define XBEE_CMD_STATUS_TIMEOUT         255
*/

   uint8_t                 param[XBEE_CMD_MAX_PARAM_LENGTH];

   uint8_t                 param_length;

   xbee_cmd_callback_fn    callback;

   void              FAR   *context;

   uint8_t                 frame_id;

#ifndef XBEE_CMD_DISABLE_REMOTE
   wpan_address_t          address;
#endif

   xbee_at_cmd_t           command;
} xbee_cmd_request_t;

typedef XBEE_PACKED(xbee_header_local_at_req, {
   uint8_t           frame_type;

   uint8_t           frame_id;

   xbee_at_cmd_t     command;
}) xbee_header_local_at_req_t;

typedef XBEE_PACKED(xbee_header_remote_at_req, {
   uint8_t           frame_type;

   uint8_t           frame_id;

   addr64            ieee_address;

   uint16_t          network_address_be;

   uint8_t           options;

   xbee_at_cmd_t     command;
}) xbee_header_remote_at_req_t;

#define XBEE_REMOTE_AT_OPT_QUEUE        (0)

#define XBEE_REMOTE_AT_OPT_IMMEDIATE    (1<<1)

#define XBEE_REMOTE_AT_OPT_SECURE       (1<<4)

typedef union xbee_header_at_request {
   uint8_t                       frame_type;

   xbee_header_local_at_req_t    local;

   xbee_header_remote_at_req_t   remote;
} xbee_header_at_request_t;

enum xbee_at_resp_status {
   XBEE_AT_RESP_STATUS_MASK             = 0x0F,

   XBEE_AT_RESP_SUCCESS                 = 0x00, 
   XBEE_AT_RESP_ERROR                   = 0x01, 
   XBEE_AT_RESP_BAD_COMMAND             = 0x02, 
   XBEE_AT_RESP_BAD_PARAMETER           = 0x03, 
   XBEE_AT_RESP_TX_FAIL                 = 0x04, 
   XBEE_AT_RESP_NO_SESSION              = 0x0B, 
   XBEE_AT_RESP_ENCRYPTION_ERR          = 0x0C, 
   XBEE_AT_RESP_TO_BIT_NOT_SET          = 0x0D, 

   XBEE_AT_RESP_ATND_RSSI_INVALID       = 0x40,
};

#ifdef XBEE_DISABLE_DIGIMESH
   #define XBEE_AT_RESP_STATUS(var)          (var)
#else
   #define XBEE_AT_RESP_STATUS(var)          ((var) & XBEE_AT_RESP_STATUS_MASK)
#endif


typedef XBEE_PACKED(xbee_header_local_at_resp, {
   uint8_t           frame_type;

   uint8_t           frame_id;
   xbee_at_cmd_t     command;

   uint8_t           status;

}) xbee_header_local_at_resp_t;

typedef XBEE_PACKED(xbee_header_remote_at_resp, {
   uint8_t           frame_type;

   uint8_t           frame_id;

   addr64            ieee_address;

   uint16_t          network_address_be;

   xbee_at_cmd_t     command;

   uint8_t           status;
}) xbee_header_remote_at_resp_t;


typedef XBEE_PACKED(xbee_frame_local_at_resp, {

   xbee_header_local_at_resp_t header;
   uint8_t           value[1];
}) xbee_frame_local_at_resp_t;

typedef XBEE_PACKED(xbee_frame_remote_at_resp, {
   xbee_header_remote_at_resp_t header;

   uint8_t           value[1];
}) xbee_frame_remote_at_resp_t;

typedef union xbee_frame_at_response {
   uint8_t                       frame_type;

   xbee_frame_local_at_resp_t    local;

   xbee_frame_remote_at_resp_t   remote;
} xbee_frame_at_response_t;


// ---- API for command lists ----

struct xbee_atcmd_reg_t;   // forward

typedef void (*xbee_command_list_fn)(
   const xbee_cmd_response_t FAR       *response,
   const struct xbee_atcmd_reg_t FAR   *reg,
   void FAR                            *base
);

enum xbee_command_list_status {
   XBEE_COMMAND_LIST_RUNNING = -EBUSY,
   XBEE_COMMAND_LIST_DONE = 0,
   XBEE_COMMAND_LIST_TIMEOUT = -ETIMEDOUT,
   XBEE_COMMAND_LIST_ERROR = -EIO,
};


typedef struct xbee_command_list_context_t {
   const struct xbee_atcmd_reg_t FAR   *list;
   void FAR                            *base;
   enum xbee_command_list_status       status;
   uint16_t                            index;
} xbee_command_list_context_t;


enum xbee_command_list_type {
   XBEE_CLT_NONE,    
   XBEE_CLT_COPY,    
   XBEE_CLT_COPY_PAD_LEFT, 
   XBEE_CLT_COPY_BE, 
   XBEE_CLT_SET,     
   XBEE_CLT_SET_STR, 
   XBEE_CLT_SET_BE,  
   XBEE_CLT_SET_8,   
   XBEE_CLT_LAST,    
};

typedef struct xbee_atcmd_reg_t {
   xbee_at_cmd_t  command;          
   uint8_t        flags;            
   enum xbee_command_list_type type;

   xbee_command_list_fn callback;
   uint8_t        bytes;            
   uint16_t       offset;           
} xbee_atcmd_reg_t;

#define XBEE_ATCMD_REG(c1,c2,type,obj,field) \
   { { { c1, c2 } }, 0, type, NULL, \
      (uint8_t) sizeof((*(obj *)NULL).field), \
      (uint8_t) offsetof( obj, field) }

#define XBEE_ATCMD_REG_CB(c1,c2,cb,flags) \
   { { { c1, c2 } }, flags, XBEE_CLT_NONE, cb, 0, 0 }


#define XBEE_ATCMD_REG_MOVE_THEN_CB(c1,c2,type,obj,field,cb,flags) \
   { { { c1, c2 } }, flags, type, cb,     \
      (uint8_t) sizeof((*(obj *)NULL).field), \
      (uint8_t) offsetof( obj, field) }


#define XBEE_ATCMD_REG_SET_8(c1,c2,value) \
   { { { c1, c2 } }, 0, XBEE_CLT_SET_8, NULL, value, 0 }

#define XBEE_ATCMD_REG_END \
   { { { '\0', '\0' } } }

#define XBEE_ATCMD_REG_END_CMD(c1,c2) \
   { { { c1, c2 } }, 0, XBEE_CLT_LAST, NULL, 0, 0 }

#define XBEE_ATCMD_REG_END_CB(cb, flags) \
   { { { '\0', '\0' } }, flags, XBEE_CLT_NONE, cb, 0, 0 }

#define XBEE_ATCMD_REG_VALID(ptr)   (ptr->command.w != 0)


int xbee_cmd_list_execute(
         xbee_dev_t *xbee,
         xbee_command_list_context_t FAR *clc,
         const xbee_atcmd_reg_t FAR *list,
         void FAR *base,
         const wpan_address_t FAR *address
         );

enum xbee_command_list_status (xbee_cmd_list_status)(
         xbee_command_list_context_t FAR *clc);
#define xbee_cmd_list_status(clc)      ((clc)->status)
// ---- End of API for command lists ----


#define XBEE_CMD_REQUEST_EMPTY(index)  \
                              (xbee_cmd_request_table[index].device == NULL)

#define XBEE_CMD_REQUEST_HANDLE(index) \
   ((index << 8) || xbee_cmd_request_table[index].sequence)

// documented in xbee_atcmd.c
extern FAR xbee_cmd_request_t
                           xbee_cmd_request_table[XBEE_CMD_REQUEST_TABLESIZE];

// all functions are documented in xbee_atcmd.c
int xbee_cmd_tick( void);
xbee_cmd_request_t FAR *_xbee_cmd_handle_to_address( int16_t handle);
int xbee_cmd_init_device( xbee_dev_t *xbee);
int xbee_cmd_query_device( xbee_dev_t *xbee, uint_fast8_t refresh);
int xbee_cmd_query_status( xbee_dev_t *xbee);

int16_t xbee_cmd_create( xbee_dev_t *xbee, const char FAR command[3]);
int _xbee_cmd_release_request( xbee_cmd_request_t FAR *request);
int xbee_cmd_release_handle( int16_t handle);
int xbee_cmd_set_command( int16_t handle, const char FAR command[3]);
int xbee_cmd_set_callback( int16_t handle, xbee_cmd_callback_fn callback,
   void FAR *context);
int xbee_cmd_set_target( int16_t handle, const addr64 FAR *ieee,
   uint16_t network_address);
int xbee_cmd_set_flags( int16_t handle, uint16_t flags);
int xbee_cmd_clear_flags( int16_t handle, uint16_t flags);
int xbee_cmd_set_param( int16_t handle, uint32_t value);
int xbee_cmd_set_param_bytes( int16_t handle, const void FAR *data,
   uint8_t length);
int xbee_cmd_set_param_str( int16_t handle, const char FAR *str);
int xbee_cmd_send( int16_t handle);
int xbee_cmd_simple( xbee_dev_t *xbee, const char FAR command[3],
   uint32_t value);
int xbee_cmd_execute( xbee_dev_t *xbee, const char FAR command[3],
   const void FAR *data, uint8_t length);

#define XBEE_FRAME_HANDLE_LOCAL_AT     \
   { XBEE_FRAME_LOCAL_AT_RESPONSE, 0, _xbee_cmd_handle_response, NULL },   \
   { XBEE_FRAME_MODEM_STATUS, 0, _xbee_cmd_modem_status, NULL }
#define XBEE_FRAME_HANDLE_REMOTE_AT    \
   { XBEE_FRAME_REMOTE_AT_RESPONSE, 0, _xbee_cmd_handle_response, NULL }

int _xbee_cmd_handle_response( xbee_dev_t *xbee, const void FAR *rawframe,
   uint16_t length, void FAR *context);

int _xbee_cmd_modem_status( xbee_dev_t *xbee,
   const void FAR *payload, uint16_t length, void FAR *context);


#define xbee_zcl_identify( xbee) \
   xbee_identify( xbee, zcl_identify_isactive() > 0)

void xbee_identify( xbee_dev_t *xbee, bool_t identify);

XBEE_END_DECLS

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

#endif