2.4 Software Details

MPLAB® Harmony 3

The PIC32MZW1 Solution is supported with a leading Integrated Development Environment: MPLAB® X IDE, the XC32 Compiler and a fully integrated embedded software development framework: MPLAB® Harmony 3.

MPLAB® Harmony 3 is an extension of the MPLAB® ecosystem for creating embedded firmware solutions for 32-bit Microchip devices. For better installation and configuration management the software is available through GitHub.

MPLAB Harmony has a layered architecture that consists of several software modules. These modules are portable, compatible to each other and they communicate and exchange data and information with each other.


Module	Description
PLIB	Very low level interface to peripherals
Driver	Preferred method to access peripherals when creating portable applications
System Service	Used by drivers, middleware and application (Timer, File System, etc.)
Middleware	Implement complex protocols like USB, TCP/IP, GFX, Bluetooth, etc. They use driver and system services
MCC	UI based tool that provides an intuitive graphical user interface which enhances user experience to easily enable and configure the Harmony Framework components and significantly reducing user development time
Third-Party Libraries	RTOS from industry leading RTOS specialists, Graphics stack from Segger and other libraries
Plug-in	Plug-ins for Display manager, clock manager and Graphics composer

MPLAB Harmony is based on state machines that are used to divide a task into smaller sub-tasks that each subtask can be run from start to finish in a reasonable amount of time. This ensures that none of the module is starved too long for CPU time allowing each task to meet its timing requirements.

The modules interact with each other through API calls and the events percolate from PLIB to driver to middleware and the application. Driver, system services and middleware call each other's interface functions in order to accomplish the task that it needs to. In this way the overall system runs like a larger state machine, consisting of individual, independent but cooperating state machines.

MPLAB Harmony libraries are design to select a variety of configuration options to tailor them to a specific usage. The basic MPLAB Harmony model of cooperating state machine driven modules, when combined with a little configurability, becomes flexible enough to meet the needs of almost any embedded system.

Both configurability and flexibility allow selection of bare-metal or supported RTOS, blocking and non-blocking APIs, single and multi-client support, etc.

This is made possible because the Software Framework factors out the system configuration, framework and the application logic and the configuration.

Learn about Wireless Software

Features

Now:

Support MPLAB Harmony 3 Framework
WLAN subsystem support STA (station) and SoftAP (access point) mode
Up to 8 stations supported in SoftAP mode
Wi-Fi Security protocols supported: WPA/WPA2/WPA3 Personal, TLS 1.3 / SSL ()(https://www.wolfssl.com/products/wolfssl/)
TCP and UDP can support application like HTTP Server, DHCP Client and Server, DNS, FTP, SNMP, SNTP, SMTP, NDP, NBNS, Iperf, reboot
Support Network layer IPv4 and IPv6
Support FreeRTOS Operating System or other 3rd party OS that supported in MPLAB Harmony 3, and non-OS environment as well
Support of Wi-Fi related System Service for easy development
Support system shell over serial interface UART (CLI)
Support “Wi-Fi Easy Connect” feature, using web-browser to do network provisioning
Over the Air upgrade (OTAU) features

Software Architecture

The PIC32MZ W1 SDK is fully integrated into MPLAB Harmony 3 Framework.

It support PLIB for PIC32MZ W1's peripherals such as SPI, UART, ADC, CAN, Timer, etc. And it support OS or Non-OS configuration.

WLAN Library offers Wi-Fi core functionality and has 2 interface, one is data interface and one is configuration interface. Network stacks like TCP/IP, MQTT run on top of WLAN Library.

For easiness in application development, Wireless System Services and Middleware run on top of WLAN Library.

WLAN Driver

PIC32MZ W1 Wi-Fi Application SW Layers Structure

WLAN driver is acting as the interface layer between the application, system service, TCP/IP Stack and WLAN MAC SW, HW.

The WLAN driver code and API can be found at: "Harmony project path\driver\wifi\pic32mzw1".

The WLAN MAC SW is release as closed .a library, located at: "Harmony project path\driver\wifi\pic32mzw1\lib"

Deeper in WLAN Driver

Going deeper in the WLAN driver, it provides two type of interface – data interface and configuration interface.

Data interface interacts between the TCP/IP Stack and WLAN MAC, used for transmit and receive network packets.

When TCP/IP stack have packet to send to the network, it invokes WDRV_PIC32MZW_MACPakcetTx in the driver and the driver calls wdrv_pic32mzw_wlan_send_packet to send the packet out.
When WLAN MAC receives packets and need to pass the packets up to the TCP/IP stack, it writes the packet to ethRxPkList and invokes a function to update the event flag at TCPIP Stack
TCP/IP stack invoke WDRV_PIC32MZW_MACPacketRx to get the packet from ethRxPkList.

Configuration interface interacts between the application / wireless service and WLAN MAC, used for set/ get configuration like setting as AP mode, getting the RSSI etc.

Application / Wireless services call WLAN driver API (WDRV_PIC32MZW_XXX) to set or get configuration.
WLAN driver transforms the message to WID (WLAN Identifier) format and send to WLAN MAC by calling wdrv_pic32mzw_process_cfg_message in WDRV_PIC32MZ_Task
When WLAN MAC has event response to the APP/ wireless services, it writes the WID Response message to pic32mzwWIDRxQueue.
WDRV_PIC32MZW_Task is poll to read WID Resp message from pic32mzwWIDRxQueue, process in the driver and invoke the callback function to APP/ Wireless services.

Folder Structure

Location of the WLAN driver: "\driver\wifi\pic32mzw1"

The file drv_pic3mzw1.h includes all the WLAN MAC library API header called by the WLAN driver. It also includes the WLAN driver API header that the WLAN MAC library call.

Checking this file can get familiar the interface between the WLAN driver and WLAN MAC library and can help to understand the driver code and architecture.

WLAN Driver API

Client interface API are separated into several categories.


API Category	Description
System Interface	Init / Deinit the PIC32MZW1 Wi-Fi module instance or get the driver status
Open / Close	Open/Close the driver
STA	Connect/Disconnect STA
SoftAP	Start/Stop AP mode
Authentication Context	Configure the authentication context for Wi-Fi Authentication, used when start AP mode or connect STA
BSS Context	Set the BSS context such as SSID and channel for Wi-Fi connection
BSS Find	Use for scan Wi-Fi channels
Association	Provide information about the current association with a peer-device like RSSI, peer-mac addr
Information	Interface provides general information about the device like device MAC address, operating channel

Some highlighted Configuration API:


Interface API	Description
WDRV_PIC32MZW_BSSCtxSetSSID	The SSID string is copied into the BSS context
WDRV_PIC32MZW_BSSCtxSetChannel	The supplied channel value is copied into the BSS context
WDRV_PIC32MZW_AuthCtxSetPersonal	The context are configured appropriately for WPA-PSK authentication
WDRV_PIC32MZW_AuthCtxSetOpen	The context are configured appropriately for Open authentication
WDRV_PIC32MZW_BSSConnect	Connect PIC32MZW1 to the BSS as an infrastructure station
WDRV_PIC32MZW_BSSDisconnect	Disconnects from an existing BSS
WDRV_PIC32MZW_APStart	Creates and starts a Soft-AP instance
WDRV_PIC32MZW_APStop	Stops an instance of Soft-AP
WDRV_PIC32MZW_AssocRSSIGet	Retrieve the RSSI of the current association
WDRV_PIC32MZW_AssocPeerAddressGet	Retrieve the current association peer device network address
WDRV_PIC32MZW_BSSFindFirst	A scan is requested. An optional callback can be provided to receive notification of the first BSS discovered
WDRV_PIC32MZW_BSSFindNext	Requested to get next BSS information structure

Check out the WLAN Driver API doc for more details.