RTOS Demonstrations

MPLAB Harmony Integrated Software Framework

RTOS Demonstrations This section provides descriptions of the RTOS demonstrations.

MPLAB Harmony is available for download from the Microchip website by visiting: http://www.microchip.com/mplabharmony. Once you are on the site, click the Downloads tab to access the appropriate download for your operating system. For additional information on this demonstration, refer to the “Applications Help” section in the MPLAB Harmony Help. Introduction RTOS Demonstration Applications Help Description This distribution package contains a variety of RTOS-based firmware projects that demonstrate the capabilities of the MPLAB Harmony services and stacks integrated with RTOS running on PIC32 devices. This section describes the hardware requirement and procedures to run these firmware projects on Microchip demonstration and development boards. To learn more about MPLAB Harmony stacks and libraries refer to the related documentation in Volume V: MPLAB Harmony Framework Reference.

Source Code Disclaimers OPENRTOS The OPENRTOS demonstrations provided in MPLAB Harmony use the OPENRTOS evaluation license, which is meant for demonstration purposes only. Customers desiring development and production on OPENRTOS must procure a suitable license. Please refer to one of the following documents, which are located in the third-party folder of the MPLAB Harmony installation, for information on obtaining an evaluation license for your device: • OpenRTOS Click Thru Eval License PIC32MXxx.pdf • OpenRTOS Click Thru Eval License PIC32MZxx.pdf Micriµm All µC/OS-III demonstrations have added the crt0.S "C" run-time library start-up file to the project. The demonstration sets the linker option "do not link startup code". This is necessary for µC/OS-III to work correctly with PIC32 devices as the general exception vector is located in crt0.S. µC/OS-III overrides this interrupt source (general exception handler) to perform OS-specific functionality. If the user wants to implement their own application using µC/OS-III and a PIC32 device, they must add the crt0.S file to their project and override the general exception interrupt vector. See the current RTOS examples for this implementation. A crt0.S template file can be found in the MPLAB XC32 C/C++ Compiler installation directory: ..\Microchip\xc32\\pic32-libs\libpic32.

The Micriµm µC/OS-II and µC/OS-III source code that is distributed with MPLAB Harmony is for FREE Important! short-term evaluation, for educational use, or peaceful research. If you plan or intend to use µC/OS-II and µC/OS-III in a commercial application/product, you need to contact Micriµm to properly license µC/OS-II and µC/OS-III for its use in your application/product. The source code is provided for your convenience and to help you experience µC/OS-II and µC/OS-III. The fact the source is provided does NOT mean that you can use it commercially without paying a licensing fee. Knowledge of the source code may NOT be used to develop a similar product. If you are unsure about whether you need to obtain a license for your application, please contact Micriµm and discuss the intended use with a sales representative (www.micrium.com).

Express Logic ThreadX The source code for the ThreadX RTOS is not freely distributed. To obtain source code and the proper licensing agreement go to the Express Logic ThreadX website: http://rtos.com/products/threadx/. SEGGER embOS The SEGGER embOS libraries provided with MPLAB Harmony use the SEGGER evaluation license, which is meant for demonstration purposes only. Customers desiring development must procure a suitable license from SEGGER. To obtain source code and the proper licensing agreement visit the SEGGER embOS website: https://www.segger.com/license-models.html. Express Logic ThreadX Demonstrations This section provides descriptions of the Express Logic ThreadX RTOS demonstrations.

basic This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description

Source Code Disclaimer The source code for this ThreadX RTOS demonstration is not freely distributed. To obtain source code and the proper licensing agreement go to the Express Logic ThreadX website: http://rtos.com/products/threadx/. So that ThreadX can work with the applicable MPLAB Harmony demonstrations, install the source in the following location: /third_party/rtos/ThreadX/. The demonstrations will not compile unless the source code is provided and installed in the correct location.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the ThreadX Basic Demonstration. Description To build this project, you must open the basic_threadx.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/threadx/basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_threadx.X /apps/rtos/threadx/basic

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name

pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mz_ef_sk_microMIPS pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit in microMIPS mode. pic32mx_sk_mips16 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II. pic32mx_sk pic32mx_usb_sk2, pic32mx_usb_sk3, This configuration runs on PIC32MX-based starter pic32mx_eth_sk, and pic32mx_eth_sk2 kits: PIC32 Ethernet Starter Kit, PIC32 Ethernet Starter Kit II, PIC32 USB Starter Kit II, PIC32 USB Starter Kit III.

usb This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration.

Description

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Express Logic ThreadX and MPLAB Harmony Graphics plus USB Library Demonstration. Description To build this project, you must open the usb_threadx.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/threadx/usb. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location usb_threadx.X /apps/rtos/threadx/usb

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mx_usb_sk2 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II.

FreeRTOS Demonstrations This section provides descriptions of the FreeRTOS RTOS demonstrations.

basic This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description The demonstration blinks the three user LEDs on a starter kit to show the RTOS threads that are running and to indicate status.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the FreeRTOS Basic Demonstration. Description To build this project, you must open the basic_freertos.X project in MPLAB X IDE, and then select the desired configuration.

The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/freertos.

MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_freertos.X /apps/rtos/freertos/basic

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP(s) Used Description Name

pic32mx_sk pic32mx_usb_sk2, pic32mx_usb_sk3, This configuration runs on PIC32MX-based starter pic32mx_eth_sk, and pic32mx_eth_sk2 kits: PIC32 Ethernet Starter Kit, PIC32 Ethernet Starter Kit II, PIC32 USB Starter Kit II, PIC32 USB Starter Kit III. pic32mx_sk_mips16 pic32mx_usb_sk2, pic32mx_usb_sk3, This configuration runs on PIC32MX-based starter pic32mx_eth_sk, and pic32mx_eth_sk2 kits in MIPS16 mode: PIC32 Ethernet Starter Kit, PIC32 Ethernet Starter Kit II, PIC32 USB Starter Kit II, PIC32 USB Starter Kit III. pic32mz_sk pic32mz_ec_sk This configuration runs on the PIC32MZ EC Starter Kit. pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mz_ef_sk_microMIPS pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit in microMIPS mode.

cdc_com_port_dual This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. This RTOS based demonstration application creates a USB CDC Device that enumerates as two serial ports on the USB Host personal computer. This application demonstrates the ability of the MPLAB Harmony USB Stack to operate in an Real-Time Operating System (this example uses FreeRTOS) and to support multiple instances of the same device class.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for this demonstration application. Description To build this project, you must open the cdc_com_port_dual.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/freertos/cdc_com_port_dual. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location cdc_com_port_dual.X /apps/rtos/freertos/cdc_com_port_dual/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project Configuration BSP Used Description Name

pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this configuration to run the demonstration application on the PIC32 USB Starter Kit II in Interrupt mode and dynamic operation. pic32mz_ef_sk_int_dyn pic32mz_ef_sk Select this configuration to run the demonstration application on the PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit in Interrupt mode and dynamic operation.

cdc_msd_basic

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for this demonstration application. Description To build this project, you must open the cdc_msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/freertos/cdc_msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location cdc_msd_basic.X /apps/rtos/freertos/cdc_msd_basic/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project Configuration BSP Used Description Name

pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this configuration to run the demonstration application on the PIC32 USB Starter Kit II in Interrupt mode and dynamic operation. pic32mz_ec_sk_int_dyn pic32mz_ec_sk Select this MPLAB X IDE project configuration to run the demonstration on the PIC32MZ Embedded Connectivity (EC) Starter Kit configured for Interrupt mode and dynamic operation.

tcpip_client_server This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description The TCP/IP Client Server application, tcpip_client_server, demonstrates how to run multiple TCP and UDP servers and clients using the TCP/IP Stack in an RTOS environment. The demonstration also has the HTTP Web server running using the Non-Volatile Memory (NVM) Microchip Proprietary File System (MPFS) to store the web pages in the internal PIC32 Flash.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the FreeRTOS and MPLAB Harmony TCP/IP Demonstration. Description To build this project, you must open the tcpip_client_server.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/freertos. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location tcpip_client_server.X /apps/rtos/freertos/tcpip_client_server/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project BSP Used Description Configuration Name pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit and the Starter Kit I/O Expansion Board. pic32mx_eth_sk pic32mx_eth_sk This configuration runs on the PIC32 Ethernet Starter Kit and the Starter Kit I/O Expansion Board.

Micrium uC_OS_II Demonstrations This section provides descriptions of the Micriµm µC/OS-II RTOS demonstrations.

basic This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description The demonstration blinks a user LED on a starter kit to show the RTOS threads that are running and to indicate status.

Legal Disclaimer The source code for this demonstration is not freely distributed. To obtain the proper licensing agreement go to the Micriµm

website: http://www.micrium.com. The Micriµm µC/OS-II source has been installed in the following location, /third_party/rtos/MicriumOSII/Software, so that the applicable MPLAB Harmony demonstrations can work.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Micriµm µC/OS-II Basic Demonstration. Description To build this project, you must open the basic_ucos_II.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/uC_OS_II.

MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_ucos_II.X /apps/rtos/uC_OS_II/basic

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name

pic32mx_sk pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II. pic32mz_sk pic32mz_ec_sk This configuration runs on the PIC32MZ EC Starter Kit. pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mz_ef_sk_microMIPS pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit in microMIPS mode.

Micrium uC/OS-III Demonstrations This section provides descriptions of the Micriµm µC/OS-III RTOS demonstrations.

basic This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description The demonstration blinks a user LED on a starter kit to show the RTOS threads that are running and to indicate status.

Legal Disclaimer The source code for this demonstration is not freely distributed. To obtain the proper licensing agreement go to the Micriµm website: http://www.micrium.com. The Micriµm µC/OS-III source has been installed in the following location, /third_party/rtos/MicriumOSIII/Software, so that the applicable MPLAB Harmony demonstrations can work.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Micriµm µC/OS-III Basic Demonstration. Description To build this project, you must open the basic_ucos_III.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/uC_OS_III.

MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_ucos_III.X /apps/rtos/uC_OS_III/basic

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name

pic32mx_sk pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II. pic32mz_sk pic32mz_ec_sk This configuration runs on the PIC32MZ EC Starter Kit. pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mx_sk_mips16 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II in MIPS16 mode. pic32mz_ef_sk_microMIPS pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit in microMIPS mode

usb This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the Micriµm µC/OS-III and MPLAB Harmony Graphics plus USB Library Demonstration. Description To build this project, you must open the usb_ucos_III.X project in MPLAB X IDE, and then select the desired configuration.

The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/uC_OS_III/usb. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location usb_ucos_III.X /apps/rtos/uC_OS_III/usb

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

OPENRTOS Demonstrations This section provides descriptions of the OPENRTOS RTOS demonstrations.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the OPENRTOS Basic Demonstration. Description To build this project, you must open the basic_openrtos.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/openrtos/basic.

MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_openrtos.X /apps/rtos/openrtos/basic

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project BSP Used Description Configuration Name pic32mz_sk pic32mz_ec_sk This configuration runs on the PIC32MZ EC Starter Kit.

pic32mx_sk pic32mx_usb_sk2, pic32mx_usb_sk3, This configuration runs on PIC32MX-based starter kits: pic32mx_eth_sk, and pic32mx_eth_sk2 PIC32 Ethernet Starter Kit, PIC32 Ethernet Starter Kit II, PIC32 USB Starter Kit II, and PIC32 USB Starter Kit III.

cdc_com_port_dual This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. This RTOS based demonstration application creates a USB CDC Device that enumerates as two serial ports on the USB Host personal computer. This application demonstrates the ability of the MPLAB Harmony USB Stack to operate in an Real-Time Operating System (this example uses OPENRTOS) and to support multiple instances of the same device class.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for this demonstration application. Description To build this project, you must open the cdc_com_port_dual.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/openrtos/cdc_com_port_dual. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location cdc_com_port_dual.X /apps/rtos/openrtos/cdc_com_port_dual/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project Configuration BSP Used Description Name

cdc_msd_basic Demonstrates host support for a composite USB Device in a RTOS application. Description This demonstration application creates a USB Host application that demonstrates operation of composite USB Device. The Host application enumerates the CDC and MSD interfaces on the attached composite devices and then operates these in one application. The demonstration application uses a RTOS to create thread that manage the CDC and MSD aspects of the Host application.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for this demonstration application. Description To build this project, you must open the cdc_msd_basic.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/openrtos/cdc_msd_basic. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location cdc_msd_basic.X /apps/rtos/openrtos/cdc_msd_basic/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./firmware/src/system_config.

Project Configuration BSP Used Description Name pic32mx_usb_sk2_int_dyn pic32mx_usb_sk2 Select this configuration to run the demonstration application on the PIC32 USB Starter Kit II in Interrupt mode and dynamic operation.

SEGGER embOS Demonstrations This section provides descriptions of the SEGGER embOS RTOS demonstrations.

basic This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description The demonstration blinks the LED1 on a starter kit to show the RTOS threads are running and to indicate status.

Legal Disclaimer The source code for this SEGGER embOS RTOS demonstration is not freely distributed. To obtain source code and the proper licensing agreement visit the SEGGER embOS website: https://www.segger.com/license-models.html.

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the SEGGER embOS Basic Demonstration. Description To build this project, you must open the basic_embos.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/embos/basic.

The floating point options used may depend on the libraries shared by SEGGER. The default libraries shared with Note: MPLAB Harmony uses the soft floating point (mfloat-abi=softfp) option.

MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location basic_embos.X /apps/rtos/embos/basic/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name pic32mx_usb_sk2 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II. pic32mx_usb_sk2_mips16 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II in MIPS16 mode. pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit. pic32mz_ef_sk_microMIPS pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit in microMIPS mode.

usb This section provides information on the supported demonstration boards, how to configure the hardware (if needed), and how to run the demonstration. Description

Building the Application This section identifies the MPLAB X IDE project name and location and lists and describes the available configurations for the SEGGER embOS and MPLAB Harmony Graphics plus USB Library Demonstration. Description To build this project, you must open the usb_embos.X project in MPLAB X IDE, and then select the desired configuration. The following tables list and describe the project and supported configurations. The parent folder for these files is /apps/rtos/embos/usb. MPLAB X IDE Project This table lists the name and location of the MPLAB X IDE project folder for the demonstration.

Project Name Location usb_embos.X /apps/rtos/embos/usb/firmware

MPLAB X IDE Project Configurations This table lists and describes the supported configurations of the demonstration, which are located within ./src/system_config.

Project Configuration BSP Used Description Name pic32mz_ef_sk pic32mz_ef_sk This configuration runs on the PIC32MZ EF Starter Kit.

pic32mx_usb_sk2 pic32mx_usb_sk2 This configuration runs on the PIC32 USB Starter Kit II.

Index B basic 3, 4, 7, 8, 10, 12 Building the Application 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 C cdc_com_port_dual 5, 11 cdc_msd_basic 6, 11 E Express Logic ThreadX Demonstrations 2 F FreeRTOS Demonstrations 4 I Introduction 2 M Micrium uC/OS-III Demonstrations 8 Micrium uC_OS_II Demonstrations 7 O OPENRTOS Demonstrations 10 R RTOS Demonstrations 2 S SEGGER embOS Demonstrations 12 T tcpip_client_server 7 U usb 3, 9, 13