1.2.3 How the G3 ADP module works

The G3 Adaptation Layer (ADP) module is the access point to G3 Stack.

It provides the API to an application running on top of the G3 Stack. It is also intended to be the interface to the IPv6 layer for Data transmission and reception, as ADP Data primitives expect IPv6 packets on transmission and provide IPv6 packets on reception.

The G3 ADP module offers the necessary functions to control the G3 Stack, which include:

• Module initialization

• Discover neighbouring networks (request for Beacons) and provide received Beacon information to upper layer

• Joining an existing network (PAN) if node is a PAN-Device

• Start a new network (PAN) if node is a PAN-Coordinator

• Transmitting and Receiving frames

• Accessing Parameter Information Base (PIB) to get/set configuration parameters

• State Machine maintanance

First of all, module has to be initialized at System level by calling ADP_Initialize to get an object identifier of the ADP instance. As stated, this function is called at System level, and user does not need to take care of it.

The first step a client has to take when using ADP is to set the callback functions to receive events from ADP module, this is done be means of ADP_SetManagementNotifications function, which takes a pointer to such callback handlers as parameter (see ADP_MANAGEMENT_NOTIFICATIONS for details).

There are other Callback functions generated by the ADP layer, but in a typical G3 Application, they are handled by other modules so user does not need to set and handle them. These are LBP Notifications, which are handled by the LBP Module, and the Data Notifications, which are handled by the Network Adapter and IPv6 layer.

After setting the callbacks, ADP has to be opened by calling ADP_Open, this will trigger the module internal initialization so all G3 functionalities can be used later on.

When a G3 Device wants to Join a G3 Network, the first step is to look for other nodes already in the Network, so Device can Join through one of them. This procedure is done by sending a frame to request Beacons from other nodes, to later decide which one to use in order to Join the Network. The sending of the frame requesting Beacons (Beacon Request frame) and the management of the subsequent Beacon listening window is a task performed by the G3 MAC Layer (in case PLC & RF MACs are present, each one performs the scanning independently, but this is transparent to the ADP client, thanks to the MAC abstracion provided).

To trigger the Beacon Request frame sending and start the hearing window, the ADP_DiscoveryRequest primitive is used, in which the user indicates the length of the Beacon hearing window.

During the Beacon hearing window, every time a Beacon frame is received, ADP invokes ADP_DISCOVERY_IND_CALLBACK, providing information of the received Beacon, see ADP_PAN_DESCRIPTOR for details on provided information.

Once the hearing window has finished, ADP invokes ADP_DISCOVERY_CFM_CALLBACK callback, providing the result of the Discovery process.

With the information provided by the Network Discovery process, a Device is ready to start a Network Join process.

To do so, the LBP_AdpNetworkJoinRequest primitive has to be invoked, providing the information gathered during the Discovery phase.

The result of the Joining procedure is provided through the LBP_ADP_NETWORK_JOIN_CFM_CALLBACK.

A PAN-Coordinator does not Join an existing Network, rather it creates a new Network.

To do so, the ADP_NetworkStartRequest primitive has to be invoked, providing the PAN ID for the Network to be created.

The result of the Network Start procedure is provided through the ADP_NETWORK_START_CFM_CALLBACK.

A typical G3 Application uses IPv6 protocol as Network layer to transmit data. Thus G3 Standard API for data frames, ADP_DataRequest primitive, expects an IPv6 frame, otherwise frame is discarded and not transmitted to the G3 Network.

IPv6 layer usage is beyond the G3-Hybrid specification and thus not covered by this documentation.

Microchip implementation offers an additional Data Request primitive, in case the user wants to use a protocol different to IPv6 above the G3-Hybrid Stack, the ADP_NoIPDataRequest. This way, an application with an already predefined protocol can run on top of the G3-Hybrid Stack. Please note that this is not the Standard behaviour and may lead to interoperability issues in case devices with different G3-Hybrid implementations are mixed in the same Network.

The result of requested transmission, regardless of IPv6 usage, is provided to upper layer by invoking ADP_DATA_CFM_CALLBACK. Parameters include the result of transmission, and others explained on ADP_DATA_CFM_PARAMS.

Received frames are reported to upper layer by invoking ADP_DATA_IND_CALLBACK, along with reception paramerers contained in ADP_DATA_IND_PARAMS.

These Callbacks are by default set and managed by the provided Network Adapter that links the G3-Hybrid Stack and the IPv6 layer, so they are transparent to the user and assume that the application relays on IPv6 to manage the data transmission and reception. In case there is no IPv6 layer, the application must set and manage these callbacks in order to receive frames and to capture the result of transmitted ones.

Parameter Information Base (PIB) is a set of parameters that can be accessed for reading and/or writing. They serve mainly 2 purposes: ADP layer configuration through PIB writing, and information retrieval through PIB reading.

The reading and writing of parameters are made by means of ADP_GetRequest and ADP_SetRequest primitives respectively.

The result of these operations are provided by means of ADP_GET_CFM_CALLBACK and ADP_SET_CFM_CALLBACK respectively.

A synchronous version of both Get and Set functions is provided, ADP_GetRequestSync and ADP_SetRequestSync, in which result is returned in one of the function parameters, instead of generating any callback in response.

A list of available parameters and their description is provided on ADP_PIB_ATTRIBUTE definition.

ADP State Machine is called periodically by System though the ADP_Tasks primitive. As it is called at System level, client does not need to take care of maintaining ADP State Machine.

Every ADP process is done inside this state machine (except for PIB access which may be synchronous). Request Primitives trigger State Machine changes, and then internal processes trigger in turn the callbacks to report different events to ADP client.