From b24866225a6301d3a663f874725e83c012dc25d3 Mon Sep 17 00:00:00 2001 From: Florent Duchon Date: Wed, 26 Dec 2012 17:36:00 +0100 Subject: digital/beacon: add bitcloud stack into common directory digital/zigbit --- .../stack/Components/APS/include/apsdeData.h | 319 +++++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 digital/zigbit/bitcloud/stack/Components/APS/include/apsdeData.h (limited to 'digital/zigbit/bitcloud/stack/Components/APS/include/apsdeData.h') diff --git a/digital/zigbit/bitcloud/stack/Components/APS/include/apsdeData.h b/digital/zigbit/bitcloud/stack/Components/APS/include/apsdeData.h new file mode 100644 index 00000000..50f202ba --- /dev/null +++ b/digital/zigbit/bitcloud/stack/Components/APS/include/apsdeData.h @@ -0,0 +1,319 @@ +/**************************************************************************//** + \file apsdeData.h + + \brief The interface for sending data through the APS component + + \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-18 Max Gekk - Created. + Last change: + $Id: apsdeData.h 18132 2011-08-02 15:58:18Z ataradov $ + ******************************************************************************/ +#if !defined _APSDE_DATA_H +#define _APSDE_DATA_H + +/****************************************************************************** + Includes section + ******************************************************************************/ +#include +#include + +/****************************************************************************** + Types section + ******************************************************************************/ +/**//** + * \struct APS_DataConf_t apsdeData.h "aps.h" + * + * \brief The structure for reporting the result of APS_DataReq() function + * + * A pointer to an instance of this type is received as an argument in a confirmation callback for APS_DataReq() + * request reporting the result of data transmission. + * The structure definition follows APSDE-DATA confirm primitive described in + * ZigBee Specification r18, 2.2.4.1.2 APSDE-DATA.confirm, page 27. + **/ +typedef struct +{ + /** The status of the corresponding request. */ + APS_Status_t status; + /** Timestamp for the transmitted packet based on the local clock, + * as provided by the NWK layer. */ + uint32_t txTime; +} APS_DataConf_t; + +/**//** + * \struct APS_TxOptions_t apsdeData.h "aps.h" + * + * \brief Describes additional options of data transmission. + * + * The structure is used to set additional parameters for a data request such as + * \li to request for acknowledgement assign acknowledgedTransmission to 1 + * \li to enable fragmentation assign fragmentationPermitted to 1 + * \li to enable security assign securityEnabledTransmission to 1 + * \li to use network key in the request assign useNwkKey to 1 + * \li to include extended nonce to the auxiliary header assign includeExtendedNonce to 1 + * + * This fields conform to the primitive defined in ZigBee Specification r20, Table 2.2, page 25. + * + * Few extensions to the specification are defined: + * \li to disable decryption of sent data (clobbers data pointed by the asdu field) assign doNotDecrypt to 1 + * \li to enable indications from broadcast transmissions assign indicateBroadcasts to 1 + * + */ +BEGIN_PACK +typedef struct PACK +{ + uint8_t securityEnabledTransmission :1; + uint8_t useNwkKey :1; + uint8_t acknowledgedTransmission :1; + uint8_t fragmentationPermitted :1; + uint8_t includeExtendedNonce :1; + uint8_t doNotDecrypt :1; + uint8_t indicateBroadcasts :1; + /** Reserved. Should always be zero. */ + uint8_t reserved :1; +} APS_TxOptions_t; +END_PACK + +/**//** + * \struct APS_DataReq_t apsdeData.h "aps.h" + * + * \brief The structure for request parameters of APS_DataReq() function + * + * The structure represents parameters of data request, i.e. the request for sending data across the network. A pointer + * to an instance of the structure should to be passed as an argument to APS_DataReq() function. + * The structure definition follows APSDE-DATA request primitive described in + * Zigbee Specification r18, 2.2.4.1.1 APSDE-DATA.request, page 23. + */ +typedef struct +{ + /** \cond SERVICE_FIELDS **/ + struct + { + void *next; /*!< Used for queue support */ + } service; + /** \endcond **/ + + /** The addressing mode for identifying the destination of a data request. + * May take any non-reserved value from the following list: + * \li APS_NO_ADDRESS (0x00) - used for binding; set dstAddress and dstEndpoint + * \li APS_GROUP_ADDRESS (0x01) - used for group transmission; 16-bit group address should be specified in dstAddress; dstEndpoint is not set + * \li APS_SHORT_ADDRESS (0x02) - identifying the destination (unicast or broadcast) with a 16-bit short address specified + * in dstAddress and the endpoint set in dstEndpoint + * \li APS_EXT_ADDRESS (0x03) - identifying the destination with a 64-bit extended address specified in dstAddress and the endpoint set in dstEndpoint + * \li 0x04..0xff - reserved values, must not be used by the application*/ + APS_AddrMode_t dstAddrMode; + /** + * \ref Endian "[LE]" The address of the individual device or group address + * of the entity to which the ASDU is being transferred. + **/ + APS_Address_t dstAddress; + /** This parameter shall be present if and only if the DstAddrMode parameter + * value is 0x02 or 0x03 and, if present, shall contain either the number of + * individual endpoints of the entity to which the ASDU is being transferred, + * or the broadcast endpoint (0xff). */ + Endpoint_t dstEndpoint; + /** \ref Endian "[LE]" The identifier of the profile for which + * this frame is intended. */ + ProfileId_t profileId; + /** \ref Endian "[LE]" The identifier of the cluster for which + * this frame is intended. */ + ClusterId_t clusterId; + /** The endpoint on the request originator node from + * which the data frame is being transferred. */ + Endpoint_t srcEndpoint; + /** The number of octets comprising the ASDU to be transferred. + * The maximum length of an individual APS frame payload is given + * as NsduLength-apscMinHeaderOverhead. Assuming the possibility + * of fragmentation, a maximum-sized single ASDU consists of 256 such blocks. + **/ + uint16_t asduLength; + /** The set of octets comprising the ASDU to be transferred. */ + uint8_t *asdu; + /** The transmission options for the ASDU to be transferred. + * See structure definition for details. + */ + APS_TxOptions_t txOptions; + /** The distance, in hops, that a transmitted frame will be allowed to + * travel via the network*/ + uint8_t radius; + /** A pointer to a callback function called upon request + * completion.*/ + void (*APS_DataConf)(APS_DataConf_t *conf); + /** Confirm primitive passed to the callback and containing the results of request execution*/ + APS_DataConf_t confirm; +} APS_DataReq_t; + +/**//** + * \struct APS_DataInd_t apsdeData.h "aps.h" + * + * \brief The structure for indication of data reception + * + * A pointer to an instance of this type is passed to a data indication callback registered for a given + * endpoint when the data is received destined to the endpoint. + * The structure definition follows APSDE-DATA indication primitive described in + * Zigbee Specification r18, 2.2.4.1.3 APSDE-DATA.indication, page 29. + */ +typedef struct +{ + /** \cond SERVICE_FIELDS **/ + struct + { + void *next; /*!< Service field for queue support */ + } service; + /** \endcond **/ + + /** The addressing mode used to identify the destination + * in the data frame that has been received. + * May take any non-reserved value from the following list: + * \li APS_NO_ADDRESS (0x00) - used for binding; set dstAddress and dstEndpoint + * \li APS_GROUP_ADDRESS (0x01) - used for group transmission; 16-bit group address should be specified in dstAddress; dstEndpoint is not set + * \li APS_SHORT_ADDRESS (0x02) - identifying the destination (unicast or broadcast) with a 16-bit short address specified + * in dstAddress and the endpoint set in dstEndpoint + * \li APS_EXT_ADDRESS (0x03) - identifying the destination with a 64-bit extended address specified in dstAddress and the endpoint set in dstEndpoint + * \li 0x04..0xff - reserved values, must not be used by the application*/ + APS_AddrMode_t dstAddrMode; + /** \ref Endian "[LE]" The individual device address or group addressto which + * the ASDU is directed. Value size depends on the dstAddrMode parameter. */ + APS_Address_t dstAddress; + /** The target endpoint on the local entity to which the ASDU is directed. */ + Endpoint_t dstEndpoint; + /** The addressing mode for the source address used in this primitive + * and of the APDU that has been received. May possess any non-reserved value + * from the following list: + * \li APS_SHORT_ADDRESS (0x02) - short address is used in srcAddress and srcEndpoint is specified + * \li APS_EXT_ADDRESS (0x03) - extended address is used in srcAddress and srcEndpoint is specified + * */ + APS_AddrMode_t srcAddrMode; + /** \ref Endian "[LE]" The individual device address of the entity from which + * the ASDU has been received. + * Value type and size is depend of the srcAddrMode parameter. */ + APS_Address_t srcAddress; + /** \ref Endian "[LE]" Network address of previous hop from which the packet + * received. */ + ShortAddr_t prevHopAddr; + /** The number of the individual endpoint of the entity from + * which the ASDU has been received. */ + Endpoint_t srcEndpoint; + /** \ref Endian "[LE]" The identifier of the profile from + * which this frame originates. */ + ProfileId_t profileId; + /** \ref Endian "[LE]" The identifier of the received object. */ + ClusterId_t clusterId; + /** The number of octets comprising the ASDU being indicated by the APSDE. */ + uint16_t asduLength; + /** The set of octets comprising the ASDU being indicated by the APSDE. */ + uint8_t *asdu; + /** The status of the incoming frame processing. */ + APS_Status_t status; + /** + * \li APS_UNSECURED_STATUS=0xaf if the ASDU was received without any security. + * \li APS_SECURED_NWK_KEY_STATUS=0xac if the received ASDU was secured + * with the NWK key, + * \li APS_SECURED_LINK_KEY_STATUS=0xab if the ASDU was secured with a link key, + * \li APS_SECURED_TRUST_CENTER_LINK_KEY_STATUS=0xb1 if the ASDU was secured + * with the trust center link key, + * \li APS_SECURED_HASH_OF_TRUST_CENTER_LINK_KEY_STATUS=0xb2 if secured + * with hash of the trust center link key. + **/ + APS_Status_t securityStatus; + /** The status of whether the NSDU is using security: TRUE = use, + * FALSE = doesn't use. */ + bool nwkSecurityStatus; + /** The link quality indication delivered by the NLDE. */ + uint8_t linkQuality; + /** Timestamp for the received packet based on the local clock, + * as provided by the NWK layer. */ + uint32_t rxTime; + int8_t rssi; +} APS_DataInd_t; + +/****************************************************************************** + Prototypes section + ******************************************************************************/ +/**************************************************************************//** + \brief Sends data to a node in the network. + +The function is used to transmit data across the network. The function is able to send a data frame to a single +node (unicast), an arbitrary group of nodes (multicast), or to all nodes in the network (broadcast). Sending data to devices +that support a specific cluster and to which the node has already bound is also possible. Specific actions performed by the +request depend on parameters configuration. A destination type is identified according the value +of APS_DataReq_t::dstAddrMode. + +To send a unicast message to a node with a known short address set ::APS_SHORT_ADDRESS as addressing mode, specify +the destination address, destination and source endpoints, profile and cluster IDs.Specified cluster should be supported +by both the destination and the originator enpoints. Both endpoints should also have the same profile ID. If the short address +is unknown ::APS_EXT_ADDRESS mode can be used to identify the destination with a help of extended address +(\c dstAddress.extAddress field). For broadcasting +exactly the same parameters should be set, but the destination address (\c dstAddress.shortAddress) should be assigned to +::BROADCAST_ADDRESS_ALL to send a message to all nodes in the network, ::BROADCAST_ADDR_RX_ON_WHEN_IDLE +to send a message to all nodes with \c rxOnWhenIdle parameter equal to 1, or ::BROADCAST_ADDR_ROUTERS to send data to +all routers. + +To send data to all members of a group set ::APS_GROUP_ADDRESS as addressing mode, and specify 16bit group address +(via \c dstAddress.groupAddress). Destination endpoint should be assigned to 0xFF value. The data will be delivered to all endpoints +associated to a given group address on each group member. To apply binding use ::APS_NO_ADDRESS mode and specify +source endpoint and cluster ID. Other parameters such as profile, destination address and endpoint are ignored. + +Actual data to be sent with a request is provided through APS_DataReq_t::asdu. The parameter takes as an argument a pointer +to a segment of memory within a specially defined structure. Consider the example: + +\code +// Application message buffer +BEGIN_PACK +typedef struct +{ + uint8_t header[APS_ASDU_OFFSET]; // Header + uint8_t data[APP_ASDU_SIZE]; // Application data + uint8_t footer[APS_AFFIX_LENGTH - APS_ASDU_OFFSET]; //Footer +} PACK AppMessageBuffer_t; END_PACK +static AppMessageBuffer_t appMessageBuffer; // A global variable for the message buffer +static APS_DataReq_t dataReq; // A global variable for the data request +... +dataReq.asdu = appMessageBuffer.data; +dataReq.asduLength = sizeof(appMessageBuffer.data); +\endcode + +Additional options are switched on and off with a help of APS_DataReq_t::txOptions parameter. For unicast messages the application can request +for acknowledgement and apply fragmentation if it needs to sends greater amounts of data within a single request. Security is also +may be turned and off. + +The result of the operation is reported via callback call with confirm (APS_DataConf_t) primitive pointer as an argument. In case +of acknowledged transmission the callback is called after the response from the destination node is received. When one of +destination nodes receives data, it fires data indication callback on the destination endpoint. + + + \param[in] req - The APSDE-DATA.request primitive pointer. + \sa APS_DataReq_t + + \return None. + ******************************************************************************/ +void APS_DataReq(APS_DataReq_t *const req); + +/**************************************************************************//** + \brief ZDO APSDE-DATA.indication handler. + + \param[in] ind - pointer to APSDE_DATA.indication parameters. + \return None. + ******************************************************************************/ +extern void APS_ZdoDataInd(APS_DataInd_t *ind); + +/**************************************************************************//** + \brief Recalculates transmission timeouts and duplicate rejection time. + Reads maximum frame transmission time, + indirect poll rate and other parameters from the config server and + updates ack time. + \param none + \return none + ******************************************************************************/ +void APS_CalculateTimes(void); + +#endif /* _APSDE_DATA_H */ +/** eof apsdeData.h */ + -- cgit v1.2.3