1.1.2.1 How the Library Works
The G3 MAC RT driver library is a single-client, single-instance based driver interface.
Abstraction Model
The G3 MAC RT firmware communicates with a PLC transceiver using an SPI port, Direct Memory Access and the GPIO controller.
The PLC transceiver performs PHY and MAC RT (Real Time) duties of the G3-PLC communication protocol, thus allowing a high latency attendance from the host MCU.
MAC duties performed by the library are:
Frame filtering so only frames to be processed are sent to upper layers.
Acknowledgement generation and reception, including frame retries when an expected ACK is not received.
Segmentation and reassembly of MAC frames.
Neighbour maintenance and link parameters negotiation (modulation scheme and used tones) on both forward and reverse direction.
POS (Personal Operating Space) maintenance by storing information of every heard node before filtering.
Beacon generation upon Beacon Request frames reception.
The G3 MAC RT library offers the necessary functions to control the transceiver, which include:
Library initialization.
Transmitting and Receiving PLC frames.
Accessing PLC Information Base to get/set configuration parameters.
Enabling/Disabling transceiver Sleep Mode.
Check warnings due to Thermal Monitor control.
The client can be:
Application: Directly access the external PLC device (PL360/PL460) using the APIs provided by the G3 MAC RT Driver library.
G3-PLC PAL layer: Application can run the G3 communication stack by connecting it to the Platform Abstraction Layer (PAL) which can further be connected to the G3 MAC RT driver.
Driver Initialization and instance opening
First of all, driver has to be initialized by calling DRV_G3_MACRT_Initialize to get a valid handle.
Then, when an instance is opened by calling DRV_G3_MACRT_Open, the library loads a binary file onto the PLC transceiver. This is done using an iternal transfer protocol through SPI port. After binary loading, the library manages the reset and startup of the transceiver. This task is transparent to the user, and the library is not available until binary file is transferred and thus PLC transceiver is ready to operate. At this point, driver is ready to be configured and used. The status can be checked be calling DRV_G3_MACRT_Status.
PLC Transceiver Interrupt mapping
PLC transceiver events have to be notified to MCU in which MAC RT Driver is running. This is done using a physical connection between the transceiver and an interrupt-capable PIO in MCU.
The library implements DRV_G3_MACRT_ExternalInterruptHandler function, which is set as callback to be invoked when the interrupt is triggered on PIO. This function then reads information from the transceiver and performs the required operations.
Data Service Functions
PLC communication capabilities are provided by the following functions:
Frame Transmission. Frames are trasnmitted to PLC using DRV_G3_MACRT_TxRequest function. This function expects a valid standard IEEE 802.15.4 frame (including its MAC Header) as parameter, otherwise frame will not be correctly transmitted.
Transmission result is reported by library through the configured callback function set on DRV_G3_MACRT_TxCfmCallbackRegister.
Frame reception is reported by library in 2 steps:
First, reception parameters are received in the configured callback function set on DRV_G3_MACRT_RxParamsIndCallbackRegister.
Second, frame itself is received through the configured callback function set on DRV_G3_MACRT_DataIndCallbackRegister. Reception buffer will contain a valid standard IEEE 802.15.4 frame (including its MAC Header) for further processing.
The following figures ilustrate transmission request and following callback generation for both acknowledged and non-acknowledged transmissions.
Apart from receiving frames to be processed, the G3 MAC RT driver can act as a sniffer (if configured to) at 2 levels:
MAC: Where every valid MAC frame will be reported before performing any filtering. As in Data Indication callback, a valid standard IEEE 802.15.4 frame (including its MAC Header) is received. The sniffed frames are reported on the configured callback function set on DRV_G3_MACRT_MacSnifferCallbackRegister.
PHY: Where every PHY frame will be reported, before filtering and reassembling, even before CRC checking so invalid MAC frames are also received. The content of the sniffer data is compliant with Microchip Hybrid Sniffer tool. The sniffed frames are reported on the configured callback function set on DRV_G3_MACRT_PhySnifferCallbackRegister respectively.
Management Functions
The G3 MAC RT library includes management functions to configure it and to retrieve information about the library, transceiver, and PLC medium status. Management functions include:
Information Base Access. There are several parameters at both MAC RT and PHY levels that can be written/read to change behaviour and get information to/from the library. In order to get/set these parameters, DRV_G3_MACRT_PIBGet and DRV_G3_MACRT_PIBSet functions are used. Available parameters are listed on MAC_RT_PIB Enum and MAC_RT_PHY_PIB Enum.
PLC Transceiver Timer Referece. Every PLC transmission and reception timestamp is referenced to an interal 32-bit microseconds counter. The current value of such counter can be retrieved using DRV_G3_MACRT_GetTimerReference.
PLC Transceiver Error handling. Errors in the PLC transceiver (here called "exceptions") are reported by the library invoking the callback function set in DRV_G3_MACRT_ExceptionCallbackRegister. Exceptions are described in DRV_G3_MACRT_EXCEPTION Enum.
PLC Transmission Enabling/Disabling. Sometimes it is required to inhibit the G3 MAC RT driver to transmit frames to the PLC medium, but keeping everything else on the driver running and maintaining the Information Base. DRV_G3_MACRT_EnableTX function allow to enable/disable PLC transmissions using the TX Enable pin (PL460 only), keeping other driver mechanisms active, as well as its state machine. An application of this mechanism is the PLC PVDD monitor service, which monitores the PVDD voltage and when it is not in the expected range, PLC transmission is disabled to avoid PL460 damage; when the PVDD voltage is in the expected range, PLC transmission can be enabled again.
Sleep Mode. DRV_G3_MACRT_Sleep function allows entering/exitting PLC transceiver Sleep mode. In sleep mode, the PLC transceiver consumes as little power as possible. To exit from sleep mode it is not needed to load the PLC binary again. In case Sleep mode is exited, it is reported by the library by invoking the callback function set in DRV_G3_MACRT_SleepIndCallbackRegister.
Working flow
The library's state machine is driven from the interrupt context and the tasks function (DRV_G3_MACRT_Tasks). Once an event is detected, a callback (if registered by the application) is given to the application from the tasks function.
The library does not support queuing of more than one transmission requests. The application must check and ensure that any previous request is completed before submitting a new one. This can be done by registering a Transmission Confirm callback function.