aps.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 __WPAN_APS_H
#define __WPAN_APS_H

#include "wpan/types.h"

XBEE_BEGIN_DECLS

typedef struct wpan_envelope_t {
   // first group of members are common when creating reply envelope
   struct wpan_dev_t    *dev;             
   addr64               ieee_address;     
   uint16_t             network_address;  
   uint16_t             profile_id;       
   uint16_t             cluster_id;       

   // second group of members are modified when creating reply envelope
   uint8_t              source_endpoint;  
   uint8_t              dest_endpoint;    
   uint16_t             options;
      #define WPAN_ENVELOPE_CLUSTER_FLAGS    0x00FF
      #define WPAN_ENVELOPE_BROADCAST_ADDR   0x0100
      #define WPAN_ENVELOPE_BROADCAST_EP     0x0200
      #define WPAN_ENVELOPE_RX_APS_ENCRYPT   0x0400

   const void     FAR   *payload;         
   uint16_t             length;           
} wpan_envelope_t;

#define WPAN_STACK_PROFILE_PROPRIETARY          0x0
#define WPAN_STACK_PROFILE_ZIGBEE               0x1
#define WPAN_STACK_PROFILE_ZIGBEE_PRO           0x2

#define WPAN_PROFILE_ZDO            0x0000

#define WPAN_PROFILE_SMART_ENERGY   0x0109

#define WPAN_PROFILE_DIGI           0xC105

#define WPAN_MANUFACTURER_DIGI      0x101E
#define WPAN_MANUFACTURER_DIGI2     0x1087

#define WPAN_MANUFACTURER_TEST1     0xFFF1
#define WPAN_MANUFACTURER_TEST2     0xFFF2
#define WPAN_MANUFACTURER_TEST3     0xFFF3

#define WPAN_ENDPOINT_ZDO           0x00
#define WPAN_ENDPOINT_DIGI_SE       0x5E
#define WPAN_ENDPOINT_DDO           0xE6
#define WPAN_ENDPOINT_DIGI_DEVICE   WPAN_ENDPOINT_DDO
#define WPAN_ENDPOINT_DIGI_DATA     0xE8
#define WPAN_ENDPOINT_BROADCAST     0xFF

// (cast to int required by Codewarrior/HCS08 platform if enum is signed)
enum wpan_clust_digi
{
   DIGI_CLUST_SLEEP_SYNC         = 0x0009,   
   DIGI_CLUST_SERIAL             = 0x0011,   
   DIGI_CLUST_LOOPBACK           = 0x0012,   
   DIGI_CLUST_ND_COMMAND         = 0x0015,   
   DIGI_CLUST_DN_COMMAND         = 0x0016,   
   DIGI_CLUST_REMOTE_COMMAND     = 0x0021,   
   DIGI_CLUST_NR_COMMAND         = 0x0022,   
   DIGI_CLUST_IODATA             = 0x0092,   
   DIGI_CLUST_WATCHPORT          = 0x0094,   
   DIGI_CLUST_NODEID_MESSAGE     = 0x0095,   
   DIGI_CLUST_DN_RESPONSE        = 0x0096,   
   DIGI_CLUST_REMOTE_RESPONSE    = 0x00A1,   
   DIGI_CLUST_NR_RESPONSE        = 0x00A2,   
   DIGI_CLUST_INDIRECT_ROUTE_ERR = 0x00B0,
   DIGI_CLUST_PROG_XBEE_OTA_UPD  = 0x1000,   

   // Unsure of how these clusters are used.
   DIGI_CLUST_NBRFWUPDATE        = 0x71FE,   
   DIGI_CLUST_REMFWUPDATE        = 0x71FF,   
   DIGI_CLUST_FWUPDATERESP       = (int)0xF1FF, 
};

typedef int (*wpan_aps_handler_fn)(
   const wpan_envelope_t   FAR   *envelope,
   void                    FAR   *context
);

// Actual definition comes later, declare here so we can use it in
// function pointer typedefs.
struct wpan_ep_state_t;

typedef int (*wpan_ep_handler_fn)(
   const wpan_envelope_t   FAR   *envelope,
   struct wpan_ep_state_t  FAR   *ep_state
);

typedef struct wpan_cluster_table_entry_t {
   uint16_t                      cluster_id;

   wpan_aps_handler_fn           handler;

   const void              FAR *context;

   uint8_t                       flags;
} wpan_cluster_table_entry_t;

#define WPAN_CLUST_FLAG_NONE              0x00
#define WPAN_CLUST_FLAG_INPUT             0x01
#define WPAN_CLUST_FLAG_OUTPUT            0x02
#define WPAN_CLUST_FLAG_INOUT             0x03
#define WPAN_CLUST_FLAG_SERVER            WPAN_CLUST_FLAG_INPUT
#define WPAN_CLUST_FLAG_CLIENT            WPAN_CLUST_FLAG_OUTPUT
#define WPAN_CLUST_FLAG_ENCRYPT           0x10
#define WPAN_CLUST_FLAG_ENCRYPT_UNICAST   0x20
#define WPAN_CLUST_FLAG_NOT_ZCL           0x80

typedef struct wpan_endpoint_table_entry_t
{
   uint8_t                    endpoint;

   uint16_t                   profile_id;

   wpan_ep_handler_fn         handler;

   struct wpan_ep_state_t  FAR   *ep_state;

   uint16_t                   device_id;

   uint8_t                    device_version;

   const wpan_cluster_table_entry_t *cluster_table;
} wpan_endpoint_table_entry_t;

#define WPAN_CLUSTER_END_OF_LIST    0xFFFF

#define WPAN_CLUST_ENTRY_LIST_END   { WPAN_CLUSTER_END_OF_LIST }

// All wpan-capable devices need to start with the wpan_dev_t struct so that the
// wpan layer can share some elements (ieee_address, network_address, payload)
// and have access to the function pointers.
// Set function pointers to NULL if not implemented on a particular device.

typedef int (*wpan_endpoint_send_fn)( const wpan_envelope_t FAR *envelope,
   uint16_t flags);

#define WPAN_SEND_FLAG_NONE         0x0000      

#define WPAN_SEND_FLAG_ENCRYPTED    0x0001      


typedef int (*_wpan_config_fn)( struct wpan_dev_t *dev, ...);

typedef int (*wpan_tick_fn)( struct wpan_dev_t *dev);

typedef const wpan_endpoint_table_entry_t *(*wpan_endpoint_get_next_fn)(
   struct wpan_dev_t *dev, const wpan_endpoint_table_entry_t *ep);

typedef struct wpan_dev_t {
// _wpan_config_fn            config;        ///< change device's cfg
   wpan_tick_fn               tick;          
   wpan_endpoint_send_fn      endpoint_send; 
   wpan_endpoint_get_next_fn  endpoint_get_next;   

   wpan_address_t address;                

   uint16_t       payload;

   uint16_t       flags;
      #define WPAN_FLAG_NONE                    0x0000
      #define WPAN_FLAG_JOINED                  0x0001
      #define WPAN_FLAG_AUTHENTICATED           0x0002
      #define WPAN_FLAG_AUTHENTICATION_ENABLED  0x0004

   const wpan_endpoint_table_entry_t   *endpoint_table;

} wpan_dev_t;

#define WPAN_DEV_IS_JOINED(dev)        ((dev)->flags & WPAN_FLAG_JOINED)

#define WPAN_DEV_IS_AUTHENTICATED(dev) ((dev)->flags & WPAN_FLAG_AUTHENTICATED)

#define WPAN_ENDPOINT_END_OF_LIST   0xFF

#define WPAN_ENDPOINT_TABLE_END     { WPAN_ENDPOINT_END_OF_LIST }


int wpan_tick( wpan_dev_t *dev);

const wpan_cluster_table_entry_t *wpan_cluster_match( uint16_t match,
   uint8_t mask, const wpan_cluster_table_entry_t *entry);

const wpan_endpoint_table_entry_t *wpan_endpoint_get_next( wpan_dev_t *dev,
   const wpan_endpoint_table_entry_t *ep);

const wpan_endpoint_table_entry_t *wpan_endpoint_match( wpan_dev_t *dev,
   uint8_t endpoint, uint16_t profile_id);

const wpan_endpoint_table_entry_t
   *wpan_endpoint_of_envelope( const wpan_envelope_t *env);

const wpan_endpoint_table_entry_t *wpan_endpoint_of_cluster( wpan_dev_t *dev,
   uint16_t profile_id, uint16_t cluster_id, uint8_t mask);

// DEVNOTE: Do we need to use the platform-independent casting macros
//          to cast this value to uint16_t?
#define WPAN_APS_PROFILE_ANY     0xFFFF

void wpan_envelope_create( wpan_envelope_t *envelope, wpan_dev_t *dev,
   const addr64 FAR *ieee, uint16_t network_addr);

int wpan_envelope_reply( wpan_envelope_t FAR *reply,
   const wpan_envelope_t FAR *original);

int wpan_envelope_send( const wpan_envelope_t FAR *envelope);

void wpan_envelope_dump( const wpan_envelope_t FAR *envelope);

// Forward declaration of struct for use in function pointer declaration.
struct wpan_conversation_t;
typedef int (*wpan_response_fn)(
   struct wpan_conversation_t FAR   *conversation,
   const wpan_envelope_t      FAR   *envelope);

// WPAN_CONVERSATION_*: Return values for wpan_response_fn() function handlers.
// Reserve 0 for invalid response and negative for error responses.
#define WPAN_CONVERSATION_END       1
#define WPAN_CONVERSATION_CONTINUE  2

typedef struct wpan_conversation_t {
   uint8_t           transaction_id;
   void        FAR *context;
   uint16_t          timeout;          // time to expire converstation
   wpan_response_fn  handler;          // if NULL, record is unused
} wpan_conversation_t;

#ifndef WPAN_MAX_CONVERSATIONS
   #define WPAN_MAX_CONVERSATIONS 3
#endif

#ifndef WPAN_CONVERSATION_TIMEOUT
   #define WPAN_CONVERSATION_TIMEOUT 30
#endif

typedef struct wpan_ep_state_t {
   uint8_t              last_transaction;
   wpan_conversation_t  conversations[WPAN_MAX_CONVERSATIONS];
} wpan_ep_state_t;

int wpan_conversation_register( wpan_ep_state_t FAR *state,
   wpan_response_fn handler, const void FAR *context, uint16_t timeout);
int wpan_conversation_response( wpan_ep_state_t FAR *state,
   uint8_t transaction_id, const wpan_envelope_t FAR *envelope);
uint8_t wpan_endpoint_next_trans( const wpan_endpoint_table_entry_t *ep);

int wpan_envelope_dispatch( wpan_envelope_t *envelope);

void wpan_conversation_delete( wpan_conversation_t FAR *conversation);

XBEE_END_DECLS

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

#endif      // __WPAN_APS_H