MPLAB Harmony System and Client Driver Handle

What is System and Client Driver Handle in MPLAB Harmony and how to use them

MPLAB Harmony was designed and developed to make PIC32 family of microcontroller easy to use. Whether it has lived to the expectation depends on the users. There are no online classes or classes for this in any electronics engineering schools. As such, we, the users depend on the documentation provided by microchip.

MPLAB Harmony is fairly complicated to understand for any new user. It has large number of functions or API, and complicated header and c source files are used. There are large number of drivers and each driver has API and function related to system and clients and some of them require event handlers and call back functions.

So here we gonna tell some aspect of MPLAB Harmony code writing that might be helpful to you. The aspect we gonna tell is related to driver’s system and client handles. This is very important and basic underlying basic concept in Harmony.

The use of driver library is central in MPLAB Harmony. It is provided by microchip to access the PIC32 peripherals such as ADC, USART, Timers, USB, SPI, I2S etc. In this regard, how the driver library is accessed and used is the topic of this blog post.

MPLAB Harmony divides the overall PIC32 microcontroller and software interaction via 3 components- the system, the client and the Peripheral library(PLIB). PLIB is closes to the peripherals of the microcontroller. These 3 components interaction is managed by the driver library. This is as shown in the picture below.

This picture is from the MPLAB Harmony help documentation. In the picture you can see that the driver or the driver library interacts with the system, the client and the PLIB. As said before, PLIB consist of functions that directly access the microcontroller peripherals.

In terms of software, in order to utilize peripherals we need to create driver objects or handles for the system and client. The system initializes and monitors the driver via the system driver handle. The client is user application which also requires handle to the driver. So one also needs driver handle for the client. Once the handle for client is obtained, the client uses it for opening, closing, using other library functions.

Now we will explain how the system and client handle to the driver object is created in MPLAB Harmony.

For system driver handle, first the SYS_MODULE_OBJ object is created. Normally you can create it anywhere in your C program files but if you were to use default MPLAB Harmony file structure then you would find it in the system_defination.h file. One example is shown below.

In the above code you can see that different driver objects are created for different drivers such as timer, DMA, I2S, CODEC, USART and PMP.

The extern SYSTEM_OBJECTS sysObj; statement allows us to use the objects in other source files.

Once the drivers object are created you can then use them along with initialization data structure for that driver to initialize and obtain a system driver handle. Example of initialization and obtaining handle to USART peripheral and Timer peripheral is shown below.

Once the handle is obtained it then can be used to performing system level task routines. There are two ways the System maybe operating the peripheral via the handle. One is via polling and 2nd is via interrupt. How they are handled by the system depends upon how the driver was configured in the MPLAB Harmony via the MHC.

In our example, the USART is handled in interrupt manner and the Timer is polled.

So for example since the USART is handled in interrupt manner it tasks is executed via the interrupt routine(ISR).

And since the Timer is configured in polled task environment it is called in the SYS_Tasks() function as shown below.


Turning to Client, the driver object is usually created in the app.h file following the default MPLAB Harmony file construct. However it can be created in other files as well. The client driver handle is created using DRV_HANDLE for the most and usual drivers and for some drivers such as USB drivers USB_DEVICE_HANDLE data type is used.

For example, the USART handle object can be created in the app.h file as follows,

Once the driver handle to the client is created it can be used by the application. The example is shown below.

Similarly for special peripherals like the USB, the handle object is created and used as follows.



What do you think?

0 points
Upvote Downvote

Total votes: 0

Upvotes: 0

Upvotes percentage: 0.000000%

Downvotes: 0

Downvotes percentage: 0.000000%

Leave a Reply

Your email address will not be published. Required fields are marked *

Simple Stateflow Example

Telephone Transceiver for Microcontroller

Telephone Transceiver for Microcontroller