1.3.2.1 How the G3 MAC Wrapper module works

Description

The G3 MAC Wrapper module is the access point to G3 MAC layers: PLC MAC, RF MAC, and the Common MAC module.

In case only one of the MAC layers is present (PLC or RF), the Wrapper acts just as an access point with the only functionality of deciding where to Set/Get PIBs, whether from Common module or the corresponding MAC layer (Common moule is always present, regardless of how many MAC layers are present).

When using both PLC and RF MAC layers, Wrapper also incorporates the functionality of Hybrid Abstraction Layer. This functionality is intended to provide a unified access to both MACs.

  • In transmission, it takes the responsibility to transmit frames through one or both mediums, or even using one medium as a backup in case the primary one fails, providing information of used media on the Confirm callbacks.

  • In reception, it provides a single channel to receive frames from both MACs, indicating the medium on the Indication callbacks. Also provides a filtering capability to avoid receiving the same frame twice by upper layer, in case it came from both media.

  • When accessing IBs, it redirects the Set/Get operations to the proper MAC layer, or to the Common module.

Figure . MAC Wrapper Duties depending on included MACs
mac_wrapper_duties

The G3 MAC Wrapper module offers the necessary functions to control the G3 MAC layers, which include:

  • Module initialization

  • Scan a network (request for Beacons) and provide received Beacon information to upper layer

  • Start a new PAN assuming PAN-Coordinator role

  • Transmitting and Receiving frames

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

  • State Machine maintanance

Module Initialization

First of all, module has to be initialized at System level by calling MAC_WRP_Initialize to get an object identifier of the MAC Wrapper 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 MAC Wrapper is to open an instance of it, by calling MAC_WRP_Open, this will return a handle, which will be used in every further function call, to identify both the module instance and the client using it. Once the handle is obtained, the callback functions to receive events from MAC Wrapper module must be set, this is done be means of MAC_WRP_SetCallbacks function, which takes a pointer to such callback handlers as parameter (see MAC_WRP_HANDLERS Struct for details).

Scanning a Network

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 hearing 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 MAC Wrapper client, thanks to the MAC abstracion provided).

To trigger the Beacon Request frame sending and start the hearing window, the MAC_WRP_ScanRequest primitive is used, in which the client indicates the length of the Beacon hearing window, see MAC_WRP_SCAN_REQUEST_PARAMS for details.

During the Beacon hearing window, every time a Beacon frame is received, MAC Wrapper invokes MAC_WRP_BeaconNotifyIndication callback, providing information of the received Beacon, see MAC_WRP_BEACON_NOTIFY_INDICATION_PARAMS for details on provided information.

Once the hearing window has finished, MAC Wrapper invokes MAC_WRP_ScanConfirm callback, providing the result of the Scan process in MAC_WRP_SCAN_CONFIRM_PARAMS.

The process of Joining the Network after scanning is done by upper layers, and thus out of scope for this guide.

Starting a Network

In case a Device is intended to act as PAN-Coordinator of the Network, the first step is to auto-configure itself as Coordinator and set an own PAN Identifier which will be used throughout the Network. This is done by calling MAC_WRP_StartRequest primitive, and PAN Identifier has to be provided as a parameter, as defined in MAC_WRP_START_REQUEST_PARAMS.

Transmitting and Receiving frames

Frames are sent to the G3 Network using the MAC_WRP_DataRequest primitive. Several parameters define the transmission, as seen on MAC_WRP_DATA_REQUEST_PARAMS. In case both PLC and RF MACs are present, the field MAC_WRP_MEDIA_TYPE_REQUEST determines through which medium/media the frame is intended to be sent.

Result of requested transmission is provided by MAC Wrapper by invoking MAC_WRP_DataConfirm callback. Parameters include the result of transmission, and others explained on MAC_WRP_DATA_CONFIRM_PARAMS.

Received frames are reported by MAC Wrapper by invoking MAC_WRP_DataIndication callback, along with reception paramerers contained in MAC_WRP_DATA_INDICATION_PARAMS.

Accessing Parameter Information Base (PIB)

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

The reading and writing of parameters are made by means of MAC_WRP_GetRequestSync and MAC_WRP_SetRequestSync primitives respectively.

A list of available parameters is found on MAC_WRP_PIB_ATTRIBUTE definition.

State Machine maintanance

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

Every MAC Wrapper process is done inside this state machine (except for PIB access which is synchronous). Requests trigger State Machine changes, and internal processes and states, trigger in turn the callbacks to report different events to MAC Wrapper client.