| AVR Z-LINKŪ |

# callbacks.c File Reference

## Detailed Description

This files implements all the necessary callback functions.

The IEEE 802.15.4 library that is utilized in AVR414 is based on a structure where request primitives are implemented as function calls (weak binding) into the library, and confirm and indication primitives are implemented as callback. All these callbacks are placed in this file mainly for the sake of readability.

Application note:
  AVR414: User's Guide - ATAVRRZ502 - Accessory Kit

Documentation
  For comprehensive code documentation, supported compilers, compiler settings and supported devices see readme.html

Author:
  Atmel Corporation: http://www.atmel.com
  Support email: avr@atmel.com

Name

Revision
  1.2

RCSfile
  ATInterface.c,v

Date
  2006/09/15 17:02:19

Definition in file callbacks.c.

`#include <stdbool.h>`
`#include <stdint.h>`
`#include "compiler.h"`
`#include "ieee_const.h"`
`#include "ieee_types.h"`
`#include "wpan_mac.h"`
`#include "chat.h"`
`#include "serialPortHAL.h"`
`#include "utilities.h"`

Include dependency graph for callbacks.c:

Go to the source code of this file.

## Functions
void | usr_mcps_data_conf (uint8_t msduHandle, uint8_t status)
| This is the implementation of the mcps_data.confirm callback function.
void | usr_mcps_data_ind (wpan_mcpsdata_addr_t *addrInfo, uint8_t mpduLinkQuality, uint8_t SecurityUse, uint8_t ACLEntry, uint8_t msduLength, uint8_t *msdu)
| This is the implementation of the mcps_data.indication callback function.
void | usr_mlme_associate_conf (uint16_t AssocShortAddress, uint8_t status)
| This is the implementation of the mlme_assciate.confirm callback function.
void | usr_mlme_associate_ind (uint64_t DeviceAddress, uint8_t CapabilityInformation, uint8_t SecurityUse, uint8_t ACLEntry)
| This is the implementation of the mlme_associate.indication callback function.
void | usr_mlme_comm_status_ind (wpan_commstatus_addr_t *pAddrInfo, uint8_t status)
| This is the implementation of the mlme_comm_status.indication callback function.
void | usr_mlme_reset_conf (uint8_t status)
| This is the implementation of the mlme_reset.confirm callback function.
void | usr_mlme_scan_conf (uint8_t status, uint8_t ScanType, uint32_t UnscannedChannels, uint8_t ResultListSize, uint8_t *data, uint8_t data_length)
| This is the implementation of the mlme_scan.confirm callback function.
void | usr_mlme_set_conf (uint8_t status, uint8_t PIBAttribute)
| This is the implementation of the mlme_set.confirm callback function.
void | usr_mlme_start_conf (uint8_t status)
| This is the implementation of the mlme_start.confirm callback function.
## Variables
bool | permit = true
uint16_t | shortAddress = 0x0000

## Function Documentation

void usr_mcps_data_conf | ( | uint8_t | msduHandle,
|  | uint8_t | status |
| ) |  |  |

This is the implementation of the mcps_data.confirm callback function.

This callback will be issued to convey the results after an mcps_data.request to the caller. Code flow:

1. send "OK" string if the data was sent successfully.
2. send an error message if the mcps_data.request did not terminate as it should.

Parameters:

  | msduHandle | The handle of the MSDU to be purged from the transaction queue.
  | status | The result code for the corresponding request (see 7.1.1.2.1 in 802.15.4).

Definition at line 365 of file callbacks.c.

References DATA_TRANSMISSION_FAILED, sendERROR(), and sendOK().

    00365                                                              {
    00366
    00367         //Check if the message was successfully transmitted.
    00368         if( status == MAC_SUCCESS ){
    00369
    00370                 sendOK( );
    00371         }
    00372
    00373         //Give feedback about errors to user.
    00374         else{
    00375
    00376                 sendERROR( DATA_TRANSMISSION_FAILED );
    00377         }
    00378 }

Here is the call graph for this function:

void usr_mcps_data_ind | ( | wpan_mcpsdata_addr_t * | addrInfo,
|  | uint8_t | mpduLinkQuality,
|  | uint8_t | SecurityUse,
|  | uint8_t | ACLEntry,
|  | uint8_t | msduLength,
|  | uint8_t * | msdu |
| ) |  |  |

This is the implementation of the mcps_data.indication callback function.

This callback notifies the node that new data has been received from the other peer. A notification will be sent over the serial interface if the primitive was received in the correct state of the application (CHAT_CONNECTED).

Parameters:

  | addrInfo | Pointer to a address information structure of the type wpan_mcpsdata_addr_t.
  | mpduLinkQuality | LQ value measured during reception of the MPDU. Lower values represent lower LQ (see 6.7.8 in 802.15.4-2003).
  | SecurityUse | An indication of whether the received data frame is using security. This value is set to TRUE if the security enable subfield was set to 1 or FALSE if the security enabled subfield was set to 0 .
  | ACLEntry | The macSecurityMode parameter value from the ACL entry associated with the sender of the data frame. This value is set to 0 x 08 if the sender of the data frame was not found in the ACL .
  | msduLength | Size The number of octets contained in the MSDU being indicated by the MAC sublayer entity. The maximum length of a MSDU is defined by the constant aMaxPHYPacketSize.
  | msdu | Pointer to array of uint8_t data, the length of the array is given by the parameter data_length.

Definition at line 404 of file callbacks.c.

References CHAT_CONNECTED, sendDataNotification(), and state.

    00405                                                                                   {
    00406
    00407         //Only possible to send messages from this state.
    00408         if( state != CHAT_CONNECTED ){
    00409
    00410                 return;
    00411         }
    00412
    00413         sendDataNotification( msduLength,msdu );
    00414 }

Here is the call graph for this function:

void usr_mlme_associate_conf | ( | uint16_t | AssocShortAddress,
|  | uint8_t | status |
| ) |  |  |

This is the implementation of the mlme_assciate.confirm callback function.

This callback is issued to convey the results of an mlme_associate.request to the caller (End-device). If the request was successful it is safe to change state to CHAT_CONNECTED. The two nodes are now formally connected, a link between two peers is established, and it is possible to send data between them.

Parameters:

  | AssocShortAddress | The short device address allocated by the coordinator on successful association. This parameter is set to 0xffff if the association was unsuccessful.
  | status | The result code for the corresponding request (see 7.1.1.5.1 in 802.15.4-2003).

Definition at line 337 of file callbacks.c.

References ASSOCIATION_FAILED, CHAT_ASSOCIATION_PENDING, CHAT_CONNECTED, CHAT_IDLE, sendERROR(), sendOK(), and state.

    00337                                                                           {
    00338
    00339         if( ( status == MAC_SUCCESS ) && ( state == CHAT_ASSOCIATION_PENDING ) ){
    00340
    00341                 sendOK( );
    00342                 state = CHAT_CONNECTED;
    00343         }
    00344
    00345         else{
    00346
    00347                 sendERROR( ASSOCIATION_FAILED );
    00348                 state = CHAT_IDLE;
    00349         }
    00350 }

Here is the call graph for this function:

void usr_mlme_associate_ind | ( | uint64_t | DeviceAddress,
|  | uint8_t | CapabilityInformation,
|  | uint8_t | SecurityUse,
|  | uint8_t | ACLEntry |
| ) |  |  |

This is the implementation of the mlme_associate.indication callback function.

This callback is only valid for a coordinator in the peer-to-peer link used in AVR414. After a coordinator successfully has started a new network, it is possible for an end -device to associate to it. This is done by executing the mlme_associate.request primitive. Such a request is indicated to the coordinator by issuing the callback below. If no other end-device has been associated an mlme_associate.response will be sent indicating that the operation was successful. If another device already is associated (Only possible with two nodes in the simple network of AVR414) it will be indicated that the coordinator is full (PAN_AT_CAPACITY).

Parameters:

  | DeviceAddress | IEEE 64-bit address of entity.
  | CapabilityInformation | Operating capabilities of joined device.
  | SecurityUse | An indication of whether the received data frame is using security. This value is set to TRUE if the security enable subfield was set to 1 or FALSE if the security enabled subfield was set to 0 .
  | ACLEntry | The macSecurityMode parameter value from the ACL entry associated with the sender of the data frame. This value is set to 0 x 08 if the sender of the data frame was not found in the ACL .

Definition at line 280 of file callbacks.c.

References CHAT_WAIT_FOR_ASSOCIATION, and state.

    00280                                                                                                                            {
    00281
    00282         if( state == CHAT_WAIT_FOR_ASSOCIATION ){
    00283
    00284                 //Generate response.
    00285                 wpan_mlme_associate_response( DeviceAddress, 0x0001,
    00286                                                                           ASSOCIATION_SUCCESSFUL, false );
    00287         }
    00288
    00289         else{
    00290
    00291                 //Generate response.
    00292                 wpan_mlme_associate_response( DeviceAddress, 0x0001,
    00293                                                                           PAN_AT_CAPACITY, false );
    00294         }
    00295 }

void usr_mlme_comm_status_ind | ( | wpan_commstatus_addr_t * | pAddrInfo,
|  | uint8_t | status |
| ) |  |  |

This is the implementation of the mlme_comm_status.indication callback function.

This callback is tightly connected to the mlme_associate.indication. As mentioned in the documentation for that primitive (mlme_associate.indication) an mlme_associate.response must be issued back as a part of the handshake procedure. This message must then be acknowledged by the caller (end-device). The mlme_comm_status.indication returns the status of this acknowledge. For the association process to be successful the status parameter of the primitive must equal "MAC_SUCCES". A notification will be sent over the serial interface to indicate (+N AT-Command) that an end-device has successfully been associated.

Parameters:

  | pAddrInfo | Pointer to address information structure of type wpan_commstatus_addr_t.
  | status | The result code for the corresponding request (see 7.1.12.1.12 in 802.15.4-2003).

Definition at line 314 of file callbacks.c.

References CHAT_CONNECTED, sendAssociationNotification(), and state.

    00314                                                                                   {
    00315
    00316         if( status == MAC_SUCCESS ){
    00317
    00318                 sendAssociationNotification( );
    00319                 state = CHAT_CONNECTED;
    00320         }
    00321 }

Here is the call graph for this function:

void usr_mlme_reset_conf | ( | uint8_t | status | ) |

This is the implementation of the mlme_reset.confirm callback function.

This function will be called from the IEEE 802.15.4 stack when the "internal" reset procedure assciated with the mlme_reset.request primitive is finished.

Parameters:

  | status | The result code for the corresponding request (see 7.1.9.2.1 in 802.15.4-2003).

Definition at line 59 of file callbacks.c.

References CHAT_IDLE, RESET_FAILED, sendERROR(), sendOK(), and state.

    00059                                           {
    00060
    00061         //If success, send OK to confirm.
    00062         if( status == MAC_SUCCESS ){
    00063
    00064                 sendOK( );
    00065                 state = CHAT_IDLE;
    00066         }
    00067
    00068         //Else, give error feedback.
    00069         else{
    00070
    00071                 sendERROR( RESET_FAILED );
    00072         }
    00073 }

Here is the call graph for this function:

void usr_mlme_scan_conf | ( | uint8_t | status,
|  | uint8_t | ScanType,
|  | uint32_t | UnscannedChannels,
|  | uint8_t | ResultListSize,
|  | uint8_t * | data,
|  | uint8_t | data_length |
| ) |  |  |

This is the implementation of the mlme_scan.confirm callback function.

Code flow:

1. check that the current state is valid.
2. if Coordinator:
   - verify that no becons were received. No beacons means there is a high probability that this channel is not used by someone else. Continue by setting the short address of the coordinator (mlme_set.request).
     - if beacons were received. Terminate the start of new network procedure.
3. if End-device:
   - if the scan procedure was successful, that means a beacon was received from from the coordinator. Proceed the association process by calling the mlme_associate.request primitive
     - if no beacon was received: Terminate the association process. Could not reach the coordinator.

Parameters:

  | status | The result code for the corresponding request.
  | ScanType | Indicates the type of scan performed.
  | UnscannedChannels | Indicates which channels given in the request that were not scanned (1 = not scanned, 0 = scanned or not requested). This parameter is only valid for passive or active scans.
  | ResultListSize | The number of elements returned in the appropriate result lists. This value is 0 for the result of an orphan scan.
  | data | Pointer to array of uint8_t data, the length of the array is given by the parameter data_length.
  | data_length | Number of bytes in the array, referenced by the parameter *data.

Definition at line 107 of file callbacks.c.

References ACTIVE_SCAN_FAILED, CHAT_ACTIVE_SCAN_PENDING, CHAT_ASSOCIATION_PENDING, CHAT_IDLE, CHAT_SET_ADDRESS_PENDING, chatChannel, chatPANID, COORDINATOR, INCONSISTENT_STATE, role, sendERROR(), shortAddress, and state.

    00108                                                                                                              {
    00109
    00110         uint8_t capabilityInfo;
    00111     capabilityInfo = WPAN_CAP_FFD | WPAN_CAP_PWRSOURCE |\
    00112                       WPAN_CAP_RXONWHENIDLE | WPAN_CAP_ALLOCADDRESS;
    00113
    00114         //The only valid call to this function is as a termination of the
    00115         //mlme_scan_request done in startNetworkOperation.
    00116         if( state != CHAT_ACTIVE_SCAN_PENDING ){
    00117
    00118                 sendERROR( INCONSISTENT_STATE );
    00119                 return;
    00120         }
    00121
    00122         //Coordinator.
    00123         if( role == COORDINATOR ){
    00124
    00125                 //Should not receive any beacon frames.
    00126                 //This means that none else is using the channel.
    00127                 if( status == MAC_NO_BEACON ){
    00128
    00129                         wpan_mlme_set_request( macShortAddress, &shortAddress,
    00130                                                                    sizeof( shortAddress ) );
    00131
    00132                         state = CHAT_SET_ADDRESS_PENDING;
    00133                 }
    00134
    00135                 else{
    00136
    00137                         sendERROR( ACTIVE_SCAN_FAILED );
    00138                         state = CHAT_IDLE;
    00139                 }
    00140         }
    00141
    00142         //End_device.
    00143         else{
    00144
    00145                 if( status == MAC_SUCCESS ){
    00146
    00147                         wpan_mlme_associate_request( chatChannel, WPAN_ADDRMODE_SHORT,
    00148                                                                                  chatPANID, shortAddress,
    00149                                                                                  capabilityInfo, false );
    00150
    00151                         state = CHAT_ASSOCIATION_PENDING;
    00152                 }
    00153
    00154                 else{
    00155
    00156                         sendERROR( ACTIVE_SCAN_FAILED );
    00157                         state = CHAT_IDLE;
    00158                 }
    00159
    00160         }
    00161 }

Here is the call graph for this function:

void usr_mlme_set_conf | ( | uint8_t | status,
|  | uint8_t | PIBAttribute |
| ) |  |  |

This is the implementation of the mlme_set.confirm callback function.

This function is only used by the coordinator to establish a new network. Code flow:

1. check for the valid states.
2. if the PIB attribute associated with this callback is macShortAddress it is ensured that it is safe to proceed with calling mlme_start.request. If the set operation was unsuccessful further primitive calls are terminated.
3. if the PIB attribute associated with this callback is macAssociationPermit it is ensured that it was possible to start a new network with this configuration. If the set operation was unsuccessful further primitive calls are terminated.

Parameters:

  | status | The result code for the corresponding request (see 7.1.14.2.1 in 802.15.4-2003).
  | PIBAttribute | The identifier of the PHY PIB attribute to get.

Definition at line 180 of file callbacks.c.

References CHAT_IDLE, CHAT_SET_ADDRESS_PENDING, CHAT_SET_PERMIT_ASSOCIATION_PENDING, CHAT_START_PENDING, CHAT_WAIT_FOR_ASSOCIATION, chatChannel, chatPANID, INCONSISTENT_STATE, sendERROR(), sendOK(), SET_MAC_ADDRESS_FAILED, START_NETWORK_FAILED, and state.

    00180                                                               {
    00181
    00182         //State check.
    00183         if( !( ( state == CHAT_SET_ADDRESS_PENDING ) ||
    00184              ( state == CHAT_SET_PERMIT_ASSOCIATION_PENDING ) ) ){
    00185
    00186                 sendERROR( INCONSISTENT_STATE );
    00187                 state = CHAT_IDLE;
    00188                 return;
    00189         }
    00190
    00191         //Set macShortAddress.
    00192         if( PIBAttribute == macShortAddress )
    00193     {
    00194
    00195                 if( status == MAC_SUCCESS ){
    00196
    00197                         wpan_mlme_start_request( chatPANID, chatChannel, 0x0F, 0x0F, true, false, false, false );
    00198                         state = CHAT_START_PENDING;
    00199                 }
    00200
    00201                 else{
    00202
    00203                         sendERROR( SET_MAC_ADDRESS_FAILED );
    00204                         state = CHAT_IDLE;
    00205                 }
    00206         }
    00207
    00208         //Set macAssociationPermit.
    00209         else{
    00210
    00211                 if( status == MAC_SUCCESS ){
    00212
    00213                         sendOK( );
    00214                         state = CHAT_WAIT_FOR_ASSOCIATION;
    00215                 }
    00216
    00217                 else{
    00218
    00219                         sendERROR( START_NETWORK_FAILED );
    00220                         state = CHAT_IDLE;
    00221                 }
    00222         }
    00223 }

Here is the call graph for this function:

void usr_mlme_start_conf | ( | uint8_t | status | ) |

This is the implementation of the mlme_start.confirm callback function.

This function is a part of the callbacks that a coordinator has to go through to establish a new network. The mlme_start.requests configures the MAC to do so on the chosen channel, PANID etc. The next step then is to permit the other node to associate. This is done by calling the mlme_set_request primitive. If the mlme_start.request was not successful, this will be indicated to the end-user (AT-Command AT+C fails).

Parameters:

  | status | The result code for the corresponding request (see 7.1.14.2.14 in 802.15.4-2003).

Definition at line 237 of file callbacks.c.

References CHAT_IDLE, CHAT_SET_PERMIT_ASSOCIATION_PENDING, CHAT_START_PENDING, permit, sendERROR(), START_NETWORK_FAILED, and state.

    00238 {
    00239
    00240         //Check status and that the state is correct.
    00241         if( ( status == MAC_SUCCESS ) && ( state == CHAT_START_PENDING ) ){
    00242
    00243                 wpan_mlme_set_request( macAssociationPermit, &permit,
    00244                                                                    sizeof( permit ) );
    00245
    00246                 state = CHAT_SET_PERMIT_ASSOCIATION_PENDING;
    00247         }
    00248
    00249         else{
    00250
    00251                 sendERROR( START_NETWORK_FAILED );
    00252                 state = CHAT_IDLE;
    00253         }
    00254 }

Here is the call graph for this function:

## Variable Documentation

bool permit = true

Definition at line 47 of file callbacks.c.

Referenced by usr_mlme_start_conf().

uint16_t shortAddress = 0x0000

Definition at line 46 of file callbacks.c.

Referenced by usr_mlme_scan_conf().

@DOC_TITLE@