zdo.h

Go to the documentation of this file.

/*
 * Copyright (c) 2010-2012 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
 * =======================================================================
 */

/*
   ZigBee Protocol Overview, Section 1.2.1.3:

   Fields that are longer than a single octet are sent to the PHY in order from
   the octet containing the lowest numbered bits to the octet containing the
   highest numbered bits.
*/

#ifndef __XBEE_ZDO_H
#define __XBEE_ZDO_H

#include "wpan/types.h"
#include "wpan/aps.h"

XBEE_BEGIN_DECLS

#define ZDO_CONVERSATION_TIMEOUT 15

// endpoint, profile, handler, context, device, version, cluster list
#define ZDO_ENDPOINT(state)                                    \
   { WPAN_ENDPOINT_ZDO, WPAN_PROFILE_ZDO, zdo_handler,         \
      &state, 0x0000, 0x00, NULL }

// These functions are documented in zigbee_zdo.c.

wpan_ep_state_t FAR *zdo_endpoint_state( wpan_dev_t *dev);

int zdo_handler(
      const wpan_envelope_t   FAR *envelope, // endpoint/profile/cluster/etc.
      wpan_ep_state_t         FAR *ep_state  // track transactions
   );

int zdo_send_response( const wpan_envelope_t FAR *request,
   const void FAR *response, uint16_t length);
int zdo_match_desc_request(void *buffer, int16_t buflen,
   uint16_t addr_of_interest, uint16_t profile_id,
   const uint16_t *inClust, const uint16_t *outClust);

#define ZDO_REQUEST_TYPE_SINGLE     0x00
#define ZDO_REQUEST_TYPE_EXTENDED   0x01

#define ZDO_CAPABILITY_ALTERNATE_PAN   0x01
#define ZDO_CAPABILITY_FULL_FUNCTION   0x02
#define ZDO_CAPABILITY_MAINS_POWER     0x04
#define ZDO_CAPABILITY_RX_ON_IDLE      0x08
#define ZDO_CAPABILITY_RESERVED_1      0x10
#define ZDO_CAPABILITY_RESERVED_2      0x20
#define ZDO_CAPABILITY_SECURITY        0x40
#define ZDO_CAPABILITY_ALLOCATE_ADDR   0x80

// Status values
#define ZDO_STATUS_SUCCESS             0x00
// 0x01 to 0x7F are reserved
#define ZDO_STATUS_INV_REQUESTTYPE     0x80
#define ZDO_STATUS_DEVICE_NOT_FOUND    0x81
#define ZDO_STATUS_INVALID_EP          0x82
#define ZDO_STATUS_NOT_ACTIVE          0x83
#define ZDO_STATUS_NOT_SUPPORTED       0x84
#define ZDO_STATUS_TIMEOUT             0x85
#define ZDO_STATUS_NO_MATCH            0x86
// 0x87 is reserved
#define ZDO_STATUS_NO_ENTRY            0x88
#define ZDO_STATUS_NO_DESCRIPTOR       0x89
#define ZDO_STATUS_INSUFFICIENT_SPACE  0x8A
#define ZDO_STATUS_NOT_PERMITTED       0x8B
#define ZDO_STATUS_TABLE_FULL          0x8C
#define ZDO_STATUS_NOT_AUTHORIZED      0x8D

#define ZDO_CLUST_RESPONSE_MASK        0x8000

#define ZDO_CLUST_IS_RESPONSE(c)    (c & ZDO_CLUST_RESPONSE_MASK)

/*********************************************************
               NWK_addr Descriptor
**********************************************************/
#define ZDO_NWK_ADDR_REQ      0x0000
#define ZDO_NWK_ADDR_RSP      0x8000
typedef XBEE_PACKED(, zdo_nwk_addr_req_t {
   uint8_t     transaction;
   addr64      ieee_address_le;
   uint8_t     request_type;     
   uint8_t     start_index;
}) zdo_nwk_addr_req_t;

typedef XBEE_PACKED(zdo_nwk_addr_rsp_header_t, {
   uint8_t     status;
   addr64      ieee_remote_le;
   uint16_t    net_remote_le;
   uint8_t     num_assoc_dev;
   uint8_t     start_index;
   // followed by variable-length list of 16-bit associated device addresses
}) zdo_nwk_addr_rsp_header_t;

#define ZDO_NET_ADDR_PENDING        0xFFFE
#define ZDO_NET_ADDR_TIMEOUT        0xFFFF
#define ZDO_NET_ADDR_ERROR          0xFFFD

int zdo_send_nwk_addr_req( wpan_dev_t *dev, const addr64 FAR *ieee_be,
   uint16_t FAR *net);

/*********************************************************
               IEEE_addr Descriptor
**********************************************************/
#define ZDO_IEEE_ADDR_REQ     0x0001
#define ZDO_IEEE_ADDR_RSP     0x8001
typedef XBEE_PACKED(zdo_ieee_addr_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
   uint8_t     request_type;     
   uint8_t     start_index;
}) zdo_ieee_addr_req_t;

typedef zdo_nwk_addr_rsp_header_t zdo_ieee_addr_rsp_header_t;

#define ZDO_IEEE_ADDR_PENDING       WPAN_IEEE_ADDR_UNDEFINED
#define ZDO_IEEE_ADDR_TIMEOUT       WPAN_IEEE_ADDR_BROADCAST
#define ZDO_IEEE_ADDR_ERROR         WPAN_IEEE_ADDR_ALL_ZEROS

int zdo_send_ieee_addr_req( wpan_dev_t *dev, uint16_t net_addr,
   addr64 FAR *ieee_be);

/*********************************************************
               Node Descriptor
**********************************************************/
#define ZDO_NODE_DESC_REQ     0x0002
#define ZDO_NODE_DESC_RSP     0x8002
typedef XBEE_PACKED(zdo_node_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
}) zdo_node_desc_req_t;

typedef XBEE_PACKED(zdo_node_desc_t, {
   uint8_t     flags0;
   uint8_t     flags1;
   uint8_t     mac_capability;
   uint16_t    manufacturer_le;
   uint8_t     max_buffer;
   uint16_t    max_incoming_le;
   uint16_t    server_mask_le;
   uint16_t    max_outgoing_le;
   uint8_t     desc_capability;
}) zdo_node_desc_t;

#define ZDO_NODE_DESC_FLAGS0_TYPE_MASK                0x07
#define ZDO_NODE_DESC_FLAGS0_TYPE_COORD               0x00
#define ZDO_NODE_DESC_FLAGS0_TYPE_ROUTER              0x01
#define ZDO_NODE_DESC_FLAGS0_TYPE_ENDDEV              0x02

#define ZDO_NODE_DESC_FLAGS0_COMPLEX_DESC_AVAIL       0x08
#define ZDO_NODE_DESC_FLAGS0_USER_DESC_AVAIL          0x10

#define ZDO_NODE_DESC_FLAGS0_RESERVED                 0xE0

#define ZDO_NODE_DESC_FLAGS1_APS_FIELD                0x07
#define ZDO_NODE_DESC_FLAGS1_FREQUENCY_MASK           0xF8

#define ZDO_NODE_DESC_FLAGS1_FREQ_868                 (1<<0)
#define ZDO_NODE_DESC_FLAGS1_FREQ_RESERVED_1          (1<<1)
#define ZDO_NODE_DESC_FLAGS1_FREQ_900                 (1<<2)
#define ZDO_NODE_DESC_FLAGS1_FREQ_2400                (1<<3)
#define ZDO_NODE_DESC_FLAGS1_FREQ_RESERVED_4          (1<<4)

#define ZDO_NODE_DESC_MAC_CAPABILITY_ALT_PAN_COORD    (1<<0)
#define ZDO_NODE_DESC_MAC_CAPABILITY_DEVICE_TYPE      (1<<1)
#define ZDO_NODE_DESC_MAC_CAPABILITY_POWER_SOURCE     (1<<2)
#define ZDO_NODE_DESC_MAC_CAPABILITY_RX_ON_IDLE       (1<<3)
#define ZDO_NODE_DESC_MAC_CAPABILITY_RESERVED_4       (1<<4)
#define ZDO_NODE_DESC_MAC_CAPABILITY_RESERVED_5       (1<<5)
#define ZDO_NODE_DESC_MAC_CAPABILITY_SECURITY         (1<<6)
#define ZDO_NODE_DESC_MAC_CAPABILITY_ALLOCATE_ADDR    (1<<7)

#define ZDO_NODE_DESC_SERVER_MASK_PRIMARY_TRUST       (1<<0)
#define ZDO_NODE_DESC_SERVER_MASK_BACKUP_TRUST        (1<<1)
#define ZDO_NODE_DESC_SERVER_MASK_PRIMARY_BINDING     (1<<2)
#define ZDO_NODE_DESC_SERVER_MASK_BACKUP_BINDING      (1<<3)
#define ZDO_NODE_DESC_SERVER_MASK_PRIMARY_DISCOVERY   (1<<4)
#define ZDO_NODE_DESC_SERVER_MASK_BACKUP_DISCOVERY    (1<<5)
#define ZDO_NODE_DESC_SERVER_MASK_NETWORK_MANAGER     (1<<6)
// bits 7 through 15 are reserved

typedef XBEE_PACKED(zdo_node_desc_resp_t, {
   uint8_t              status;              
   uint16_t             network_addr_le;
   zdo_node_desc_t      node_desc;
}) zdo_node_desc_resp_t;

/*********************************************************
               Power Descriptor
**********************************************************/
#define ZDO_POWER_DESC_REQ    0x0003
#define ZDO_POWER_DESC_RSP    0x8003
typedef XBEE_PACKED(zdo_power_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
}) zdo_power_desc_req_t;

#define ZDO_POWER_SOURCE_MAINS         0x01
#define ZDO_POWER_SOURCE_RECHARGABLE   0x02
#define ZDO_POWER_SOURCE_DISPOSABLE    0x04
#define ZDO_POWER_SOURCE_RESERVED      0x08

// for .power0, choose one of the following...
#define ZDO_POWER0_SYNC                0x00
#define ZDO_POWER0_PERIODIC            0x01
#define ZDO_POWER0_STIMULATED          0x02

// ... and choose one or more of the following
#define ZDO_POWER0_AVAIL_MAINS         (ZDO_POWER_SOURCE_MAINS << 4)
#define ZDO_POWER0_AVAIL_RECHARGABLE   (ZDO_POWER_SOURCE_RECHARGABLE << 4)
#define ZDO_POWER0_AVAIL_DISPOSABLE    (ZDO_POWER_SOURCE_DISPOSABLE << 4)
#define ZDO_POWER0_AVAIL_RESERVED      (ZDO_POWER_SOURCE_RESERVED << 4)

// for .power 1, choose one of the following...
#define ZDO_POWER1_LEVEL_CRITICAL      0x00
#define ZDO_POWER1_LEVEL_33            0x40
#define ZDO_POWER1_LEVEL_66            0x80
#define ZDO_POWER1_LEVEL_FULL          0xC0

// ... and choose one or more of the following
#define ZDO_POWER1_CURRENT_MAINS       ZDO_POWER_SOURCE_MAINS
#define ZDO_POWER1_CURRENT_RECHARGABLE ZDO_POWER_SOURCE_RECHARGABLE
#define ZDO_POWER1_CURRENT_DISPOSABLE  ZDO_POWER_SOURCE_DISPOSABLE
#define ZDO_POWER1_CURRENT_RESERVED    ZDO_POWER_SOURCE_RESERVED

typedef XBEE_PACKED(zdo_power_desc_t, {
   uint8_t     power0;     
   uint8_t     power1;     
}) zdo_power_desc_t;

typedef XBEE_PACKED(zdo_power_desc_rsp_t, {
   uint8_t              status;              
   uint16_t             network_addr_le;
   zdo_power_desc_t     power_desc;
}) zdo_power_desc_rsp_t;


/*********************************************************
               Simple Descriptor
**********************************************************/
#define ZDO_SIMPLE_DESC_REQ   0x0004
#define ZDO_SIMPLE_DESC_RSP   0x8004
typedef XBEE_PACKED(zdo_simple_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
   uint8_t     endpoint;         
}) zdo_simple_desc_req_t;

typedef XBEE_PACKED(zdo_simple_desc_resp_header_t, {
   uint8_t     status;           
   uint16_t    network_addr_le;  
   uint8_t     length;           
   // variable-length simple descriptor follows
}) zdo_simple_desc_resp_header_t;

typedef XBEE_PACKED(zdo_simple_desc_header_t, {
   uint8_t     endpoint;         
   uint16_t    profile_id_le;    
   uint16_t    device_id_le;     
   uint8_t     device_version;   
   // variable-length cluster counts and ids follow
}) zdo_simple_desc_header_t;

int zdo_simple_desc_request( wpan_envelope_t *envelope,
   uint16_t addr_of_interest, uint_fast8_t endpoint,
   wpan_response_fn callback, const void FAR *context);

/*********************************************************
               Active EP Descriptor
**********************************************************/
#define ZDO_ACTIVE_EP_REQ     0x0005
#define ZDO_ACTIVE_EP_RSP     0x8005
typedef XBEE_PACKED(zdo_active_ep_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
}) zdo_active_ep_req_t;

typedef XBEE_PACKED(zdo_active_ep_rsp_header_t, {
   uint8_t     status;              
   uint16_t    network_addr_le;
   uint8_t     ep_count;
}) zdo_active_ep_rsp_header_t;


/*********************************************************
               Match Descriptor
**********************************************************/
#define ZDO_MATCH_DESC_REQ    0x0006
#define ZDO_MATCH_DESC_RSP    0x8006
typedef XBEE_PACKED(zdo_match_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
   uint16_t    profile_id_le;
   uint8_t     num_in_clusters;
   uint16_t    in_cluster_list[1];     
}) zdo_match_desc_req_t;

typedef XBEE_PACKED(zdo_match_desc_out_clust_t, {
   uint8_t     num_out_clusters;
   uint16_t    out_cluster_list[1];    
}) zdo_match_desc_out_clust_t;

typedef XBEE_PACKED(zdo_match_desc_rsp_header_t, {
   uint8_t     status;              
   uint16_t    network_addr_le;
   uint8_t     match_length;
}) zdo_match_desc_rsp_header_t;     // followed by <match_length> bytes


/*********************************************************
               Complex Descriptor
**********************************************************/
#define ZDO_COMPLEX_DESC_REQ     0x0007
#define ZDO_COMPLEX_DESC_RSP     0x8007
typedef XBEE_PACKED(zdo_complex_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
}) zdo_complex_desc_req_t;


/*********************************************************
               User Descriptor
**********************************************************/
#define ZDO_USER_DESC_REQ        0x0011
#define ZDO_USER_DESC_RSP        0x8011
typedef XBEE_PACKED(zdo_user_desc_req_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
}) zdo_user_desc_req_t;


/*********************************************************
               Device Announce
**********************************************************/
#define ZDO_DEVICE_ANNCE         0x0013
// Device_annce does not have a response (0x8013 is not used)
typedef XBEE_PACKED(zdo_device_annce_t, {
   uint8_t     transaction;
   uint16_t    network_addr_le;
   addr64      ieee_address_le;
   uint8_t     capability;    
}) zdo_device_annce_t;

#define ZDO_DEVICE_ANNCE_CLUSTER( handler, context) \
   { ZDO_DEVICE_ANNCE, handler, context, \
                     WPAN_CLUST_FLAG_OUTPUT | WPAN_CLUST_FLAG_NOT_ZCL }

/*********************************************************
               Bind/Unbind Request
**********************************************************/
#define ZDO_BIND_REQ             0x0021
#define ZDO_BIND_RSP             0x8021
#define ZDO_UNBIND_REQ           0x0022
#define ZDO_UNBIND_RSP           0x8022

typedef XBEE_PACKED(zdo_bind_req_header_t, {
   addr64      src_address_le;
   uint8_t     src_endpoint;
   uint16_t    cluster_id_le;
   uint8_t     dst_addr_mode;
}) zdo_bind_req_header_t;

typedef XBEE_PACKED(zdo_bind_group_req_t, {
   zdo_bind_req_header_t   header;
   uint16_t                group_addr_le;
}) zdo_bind_group_req_t;

typedef XBEE_PACKED(zdo_bind_address_req_t, {
   zdo_bind_req_header_t   header;
   addr64                  dst_address_le;
   uint8_t                 dst_endpoint;
}) zdo_bind_address_req_t;

typedef union zdo_bind_req_t {
   zdo_bind_req_header_t   header;
   zdo_bind_group_req_t    group;
   zdo_bind_address_req_t  address;
} zdo_bind_req_t;

#define ZDO_BIND_DST_MODE_GROUP        0x01
#define ZDO_BIND_DST_MODE_ADDR         0x03

int zdo_send_bind_req( wpan_envelope_t *envelope, uint16_t type,
   wpan_response_fn callback, void FAR *context);


/*********************************************************
               Management Leave Request
**********************************************************/
#define ZDO_MGMT_LEAVE_REQ       0x0034
#define ZDO_MGMT_LEAVE_RSP       0x8034

typedef XBEE_PACKED(zdo_mgmt_leave_req_t, {
   addr64      device_address;
   uint8_t     flags;
      #define ZDO_MGMT_LEAVE_REQ_FLAG_NONE               0x00
      #define ZDO_MGMT_LEAVE_REQ_FLAG_REJOIN             0x01
      #define ZDO_MGMT_LEAVE_REQ_FLAG_REMOVE_CHILDREN    0x02
}) zdo_mgmt_leave_req_t;

typedef XBEE_PACKED(zdo_mgmt_leave_rsp_t, {
   uint8_t     status;
}) zdo_mgmt_leave_rsp_t;

#define ZDO_MGMT_LEAVE_REQ_ENCRYPTED      0x0100

int zdo_mgmt_leave_req( wpan_dev_t *dev, const addr64 *address, uint16_t flags);


int zdo_send_descriptor_req( wpan_envelope_t *envelope, uint16_t cluster,
   uint16_t addr_of_interest, wpan_response_fn callback,
   const void FAR *context);

XBEE_END_DECLS

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

#endif      // __XBEE_ZDO_H