summaryrefslogtreecommitdiff
path: root/digital/beacon/src/Bitcloud_stack/Components/APS/include/apsdeEndpoint.h
blob: 02bd43b2b5e4c5d0b604affaef42a5fdb49496e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
/**************************************************************************//**
  \file apsdeEndpoint.h

  \brief Interface of APS Endpoint SAP.

  \author
    Atmel Corporation: http://www.atmel.com \n
    Support email: avr@atmel.com

  Copyright (c) 2008-2011, Atmel Corporation. All rights reserved.
  Licensed under Atmel's Limited License Agreement (BitCloudTM).

  \internal
   History:
    2010-10-20 Max Gekk - Created.
   Last change:
    $Id: apsdeEndpoint.h 17448 2011-06-09 13:53:59Z ataradov $
 ******************************************************************************/
/**//**
 *
 *  The application framework in ZigBee is the environment in which application
 * objects are hosted on ZigBee devices. Up to 254 distinct application objects
 * can be defined, each identified by an endpoint address from 1 to 254.
 *
 *  Two additional endpoints are defined for APSDE-SAP usage: endpoint 0 is
 * reserved for the data interface to the ZDO, and endpoint 255 is reserved for
 * the data interface function to broadcast data to all application objects.
 * See ZigBee Specification r19, 2.1.2, page 18.
 *
 **/
#if !defined _APSDE_ENDPOINT_H
#define _APSDE_ENDPOINT_H

/******************************************************************************
                               Includes section
 ******************************************************************************/
#include <appFramework.h>
#include <apsdeData.h>

/******************************************************************************
                                Types section
 ******************************************************************************/
/**//**
 * \struct APS_RegisterEndpointReq_t apsdeEndpoint.h "aps.h"
 *
 * \brief Parameters of the APS_RegisterEndpointReq() function
 *
 * A pointer to an instance of this type shall be passed to APS_RegisterEndpointReq() function
 * as an argument to register a new endpoint. The structure contains simple descriptor
 * configuration, data indication callback pointer, and the status field.
 **/
typedef struct
{
  /** \cond SERVICE_FIELDS **/
  struct
  {
    void *next;  /*!< Used for queue support. */
    bool noIndication; /*!< Disable indication to upper-layer. */
  } service;
  /** \endcond **/

  /** A pointer to a simple descriptor */
  SimpleDescriptor_t *simpleDescriptor;
  /** A pointer to an indication callback function, which is called when data is received addressed to
   * the endpoint; conforms to APSDE-DATA.indication handler defined in ZigBee spec r19, 2.2.4.1.3.1, page 30. */
  void (*APS_DataInd)(APS_DataInd_t *ind);
  /** The status of endpoint registration; is written by the stack to report the result of the operation */
  APS_Status_t status;
} APS_RegisterEndpointReq_t;

typedef APS_RegisterEndpointReq_t APS_EndpointReg_t;

/**//**
 * \struct APS_UnregisterEndpointReq_t apsdeEndpoint.h "aps.h"
 *
 * \brief Parameters of the APS_UnregisterEndpointReq() function
 **/
typedef struct
{
  /*! The endpoint which is to be unregistered. */
  Endpoint_t endpoint;
  /*! The status of endpoint unregistration; is written by the stack to report the result
      * of the operation execution. */
  APS_Status_t status;
} APS_UnregisterEndpointReq_t;

typedef APS_UnregisterEndpointReq_t APS_EndpointUnreg_t;

/******************************************************************************
                              Prototypes section
 ******************************************************************************/
/**************************************************************************//**
  \brief Registers a new endpoint in the APS layer

  The function is used to register an application endpoint. In order to take part in network
  communication the application on the device must register at least one endpoint, since
  data exchange on the application level occurs between two endpoints registered on
  two nodes, which in fact can be a single node as well.
  
  The function call is done synchronously. The function simply writes an entry containing 
  endpoint information to a dedicated internal structure. The request parameters for 
  the funciton include simple descriptor configuration, a pointer to the indication callback 
  function, which is to be called upon data reception addressed to the endpoint, and a status 
  field, which is written by the stack.
  
  See the example of request parameters configuration and function usage:
\code
//Global definitions
static ClusterId_t clustersTable[] = {0}; //The list of clusters that the endpoint will support

//Configure the simple descriptor of the endpoint
static SimpleDescriptor_t simpleDescriptor =
{
  .endpoint = APP_ENDPOINT, //Endpoint ID, an arbitrary number between 1 and 240
  .AppDeviceVersion = 1,
  .AppInClustersCount = 1, //The number of suppoted input clusters
  .AppInClustersList = clustersTable,  //The list of supported input clusters
  .AppOutClustersCount = 0,
  .AppOutClustersList = NULL, //Suppose out clusters are not supported
};

//Configure parameters for endpoint registration request
static APS_RegisterEndpointReq_t endpointDesc =
{
  .simpleDescriptor = &simpleDescriptor,
  .APS_DataInd = APS_DataInd,
};

//Data indication callback definition
static void APS_DataInd(APS_DataInd_t *ind)
{
  //Perform appropriate actions, for example, switch on the value of 
  //cluster specified in the received frame
  switch (ind->clusterId)
  {
    case CPU_TO_LE16(APP_CLUSTER_ONE):
	...
    case CPU_TO_LE16(APP_CLUSTER_TWO):
	...
  }
}
...
simpleDescriptor.AppProfileId = CPU_TO_LE16(APP_PROFILE_ID);
simpleDescriptor.AppDeviceId = CPU_TO_LE16(1);

APS_RegisterEndpointReq(&endpointDesc);
\endcode
Although it is not required that a variable for the simple descriptor is static or simply defined
in the global scope, it may be convenient to do so to keep track of the endpoint. Note the use
of the CPU_TO_LE16 macro which converts a 16-bit value to a 16-bit little-endian value. Backward
convertion is performed with the LE16_TO_CPU macro.
  
  \param[in] req - pointer to the endpoint registration request parameters

  \return APS_SUCCESS_STATUS in req->status if registration is a success,
          otherwise, APS_INVALID_PARAMETER_STATUS. \sa APS_Status_t
 ******************************************************************************/
void APS_RegisterEndpointReq(APS_RegisterEndpointReq_t *const req);

/**************************************************************************//**
  \brief Unregisters an endpoint from the APS layer

  \param[in] req - pointer to the endpoint unregistering request parameters

  \return APS_SUCCESS_STATUS in req->status if unregistration is a success,
          otherwise, APS_INVALID_PARAMETER_STATUS. \sa APS_Status_t
 ******************************************************************************/
void APS_UnregisterEndpointReq(APS_UnregisterEndpointReq_t *const req);

/**************************************************************************//**
  \brief Get next registered endpoint descriptor by previous.

  \param[in] prev - previous endpoint descriptor pointer.It is must be non NULL
                    sequential access required if. And it is must be NULL the
                    first descriptor as registered endpoints queue head element
                    access required if.

  \return Valid endpoint descriptor pointer descriptor found if,
           NULL - other case.
 ******************************************************************************/
APS_RegisterEndpointReq_t* APS_NextEndpoint(const APS_RegisterEndpointReq_t *const prev);

/**************************************************************************//**
  \brief Stops APS Data indications of specific endpoint number.

  \param[in] endpoint - the registered endpoint number. The 0xff special value
                        means all registered endpoints.
  \return None.
 ******************************************************************************/
void APS_StopEndpointIndication(const Endpoint_t endpoint);

/**************************************************************************//**
  \brief Resumes APS Data indications of specific endpoint number.

  \param[in] endpoint - the registered endpoint number. The 0xff special value
                        means all registered endpoints.
  \return None.
 ******************************************************************************/
void APS_ResumeEndpointIndication(const Endpoint_t endpoint);

#endif /* _APSDE_ENDPOINT_H */
/** eof apsdeEndpoint.h */