This is the first post of a short series about model driven engineering using State Machines.
Here we are going to prepare the development environment for the next steps. Since modeling using state machines is particularly suitable for embedded environments, we are going to use the indicated (inexpensive) board from Microchip.

Introduction

1. Acquire the hardware

In this post we are going to use the PIC24FJ256GA705 version of the board from Microchip (Code DM240016 : https://www.microchip.com/DevelopmentTools/ProductDetails/DM240016)

2. Install the development environment.

The host operating system is going to be Microsoft Windows (64-bit). The following tools are needed to implement the application. Unless otherwise specified, please follow the installation instructions provided by the manufacturer. All the mentioned release versions are current at the time of writing.

a. MPLAB® X IDE v5.45 from Microchip

The version for Microsoft Windows available for download at https://www.microchip.com/en-us/development-tools-tools-and-software/mplab-x-ide. Select the Download button for “MPLABX-v5.45-windows-installer.exe“. According to the Microchip website (https://www.microchip.com/development-tools/) it is currently freely available.

b. MPLAB® XC16 Compiler v1.61 from Microchip

The version for Microsoft Windows available for download at https://www.microchip.com/mplab/compiler. Go to the paragraph “Downloads, Documentation and Other Resources” and click on the link for the indicated version for the Windows (x86/x64) operating system.

Please Note: the IDE must be installed before the compiler.
The compiler integrates itself in the IDE. It is freely available in its basic version, but there is also the possibility of a subscription (“Go PRO”) version, which produces better optimized code.

c. Download the PIC24FJ256GA7 Curiosity Development Board Demo code

It can be done from https://www.microchip.com/DevelopmentTools/ProductDetails/DM240016. We need this to test that the development environment works and can compile the demo program. Also, we’ll use the board support package contained in this file later. Decompress the file in a folder on your development host.

d. Download FreeRTOS™ Release 202012.00 (Source Code) ( Download )

This is the real time OS that the application is going to use. As described on the official page (https://freertos.org/index.html), FreeRTOS™ is now an open source project in the Amazon Web Services open source galaxy.

Unpack the download file in a folder of your choice on the development host. In this document this folder is going to be called <FreeRTOS_installation_folder>

Compilation of the demo program for the board

As specified in the previous paragraph, we are going to assume that the points 2.a and 2.b have been performed following the indications of the manufacturer.
In the rest of the post we are going to indicate the folder where the Demo Code for the board has been unpacked (please see Introduction point 2.c) as <Board_Demo_Code>. If we keep all the default options when decompressing the file, we should end with a folder <Board_Demo_Code>\pic24fj256ga7_curiosity_oobe.
This folder contains a read_me.txt file, needed for a successful compilation “out-of-the-box”, and a folder pic24fj256ga7_curiosity_demo.X, which contains the code for the demo.

1. Open the MPLAB® X IDE.

2. Select File -> Open Project…

3. Navigate to the folder <Board_Demo_Code>\pic24fj256ga7_curiosity_oobe.

4. Select the folder pic24fj256ga7_curiosity_demo.X

The IDE should show an icon indicating that it contains a valid MPLAB® X IDE project, then click on Open Project. The project should open in the IDE. The output  tab might show a “Configuration Loading Error” message like “warning: Configuration “default” builds with “XC16”, but indicates no toolchain directory.” If this is the case, it means that a toolchain has not been explicitly selected. In order to fix this,
a. Alternative-Click (used in this document as “Right-Click for right-handed users”) on the project name in the Projects tab -> Properties.
b. In the Categories window select Conf:[default]
c. In the Configuration panel put a tick in the “Show All” box close to the Connection Hardware Tool listbox.

d. Select the “Starter Kits (PKOB)” item from the listbox.

e. In the Compiler Toolchain window select XC16 (v1.61) [installation folder] and click on Apply -> OK.
f. File -> Close All Projects followed by the re-opening of the same project to show that the warning doesn’t appear anymore. The toolchain used for the project can also be checked in the Dashboard view, if this is selected as visible in the IDE, in the branch called Compiler Toolchain.

5. Click on Production -> Build Project to compile the demo.

If everything is configured properly, the Output tab should show a successful build. The environment for this demo is simple, therefore we don’t expect issues blocking the compilation. All the folders containing files needed for inclusion are either in the paths provided by the compiler or inside the demo itself (the bsp subfolder). Should anything go wrong at this stage, it is likely to be caused by some misconfiguration of the development environment.

6. Ready to test.

After connecting the to the computer via the USB cable according to the instructions provided by the manufacturer, click on the “Play” button in the Toolbar (“Run Project”) to download the code to the board. After a successful update, the board should be able to run the demo as expected.

A window could pop up asking for a selection of the tool to be used for the upload. With the board connected, select “Starter Kits (PKOB) …” and then OK.

A step further: Porting FreeRTOS™ to the Microchip PIC24FJ256GA7 Curiosity Board

FreeRTOS™ comes with direct support for many combinations of Microcontroller Units (MCUs) and development boards. However, given the number of possible combinations available on the market, it is almost impossible to support all of them. Instead, many families of microcontrollers are supported while providing instructions on how to adapt them to new members of the family. This is what we are going to do.
The final goal for this post is to port to the board a version of “Blinky”, a FreeRTOS™ application just slightly more complex than the classic “Hello, world!”. In our case it makes a led on the board blink, providing evidence that the OS underneath is making two tasks exchange data as expected.

The skeleton of the process is simple.
1. Create a new empty project in MPLAB® X IDE
2. Pick a version of the “blinky” application available for a “sister” board
3. Pick the packages needed from the board support package
4. Adapt the source code to the board
5. Configure the project
6. Compile, download and test the application

1. Create a new empty project in MPLAB® X IDE

a. Click File -> New Project… -> choose Standalone Project -> click Next.
b. Choose Family. In our case it’s 16-bit MCUs (PIC24).
c. Choose Device. In our case, PIC24FJ256GA705. Click Next.
d. Select Tool. Tick the box “Show All” and select Starter Kits (PKOB) from the list. Click Next.
e. Select Compiler. Under the branch XC16 select XC16 (1.61). Click Next
f. Select Project Name and Project Location according to your needs (In this post the name is going to be fj256ga705_blink) In order to avoid warnings during the creation, it helps to add a subfolder with the project name to the <Project Location>.
g. Tick the box “Use project location as the project folder”. Click on Finish. An empty project is created in the Projects tab.

2. Pick a version of the “blinky” application available for a “sister” board

The demo projects provided by FreeRTOS™ are contained in <FreeRTOS_installation_folder>\FreeRTOS\Demo\ . There are many different examples available. The folder called PIC24_MPLAB attracts the attention first. However, despite being developed for the family of MCU and compiler we are interested in, it is related to a development kit quite different from the Curiosity board. Of course, there is the possibility to port it to a different kit, but at the beginning that looked not as a Blinky type of project. Instead, the PIC32MX_MPLAB was chosen. It is for a different architecture, 32- instead of 16-bit, but the modifications needed to backport it to 16-bit, at least for the scope of this post, are trivial and we end up with a simple “blinky” project and several features of the OS tested on our board.
On the FreeRTOS™ website a guideline to create a basic project for FreeRTOS can be found. It is available at https://freertos.org/FreeRTOS-porting-guide.html . Despite the content being described at an advanced level, I believe that anyone with basic experience in programming using an IDE shouldn’t have problems in understanding the indications reported there, what they imply, and how to adapt them to their needs. After all, it’s almost only about picking the files to be part of the project and providing the folders for the #include directives to the C preprocessor.
The application implements the passing of information between two tasks at specified intervals. A queue is used to implement the mechanism. The requirements imply that there is no need of sophisticated techniques for synchronization. Every time that a message is received a led is toggled.

a. Create “the infrastructure” in the project. In the Projects tab of the IDE Alternative-click on the Source folder -> New Logical Folder.
b. Rename it to freeRTOS.
c. “Alternative-Click” on freeRTOS -> New Logical Folder.
d. Rename it to portable.
e. “Alternative-Click” on portable -> New Logical Folder.
f. Rename it to MemMang.
g. “Alternative-Click” on portable -> New Logical Folder.
h. Rename it to “MPLAB”.
i. On the file system, go to the <Project Location> folder and create mirrors of the folders just created in the IDE, that is, freeRTOS ->portable->MemMang and freeRTOS->portable->MPLAB.
j. Now it is time to copy in the right folders the files from FreeRTOS™ needed in our project. As the process described above suggests, the folders created in the IDE are only “logical” and the files can be anywhere on the physical file system.
Go to <FreeRTOS_installation_folder>\FreeRTOS\Source\portable\MPLAB\ and copy the folder PIC24_dsPIC to the MPLAB folder created in our project. The files contain the support for the access to the ports on the board.
In the Projects tab of the IDE “alternative-click” on the MPLAB folder -> Add Existing Item. Select the folder just copied from the FreeRTOS™ distribution and select all the files to be added. Select absolute as the store path.
Go to <FreeRTOS_installation_folder>\FreeRTOS\Source\portable\MemMang and copy all the files to the corresponding folder in our project. The files contain different memory allocation policies depending upon the environment.
In the Projects tab of the IDE alternative-click on the MemMang folder -> Add Existing Item. From the folder to which we just copied the files select heap_4.c . Select absolute as the store path.
Go to <FreeRTOS_installation_folder>\FreeRTOS\Source and copy croutine.c, list.c, queue.c, tasks.c and timers.c to the <Project Location>\freeRTOS folder.
In the Projects tab of the IDE alternative-click on the freeRTOS folder -> Add Existing Item. From the folder to which we just copied the files select croutine.c, list.c, queue.c, tasks.c and timers.c. Select absolute as the store path.
Go to <FreeRTOS_installation_folder>\FreeRTOS\Demo\PIC24_MPLAB and copy FreeRTOSConfig.h to the <Project Location> folder. This is a configuration file for FreeRTOS™ which can be adapted easily for the board in consideration.
In the Projects tab of the IDE alternative-click on the Important files folder -> Add Existing Item. From the folder to which we just copied the file select FreeRTOSConfig.h. Select absolute as the store path.
Go to <FreeRTOS_installation_folder>\FreeRTOS\Demo\PIC32MX_MPLAB and copy main_blinky.c to the <Project Location> folder.
This is the main file which will be adapted for the board in consideration.
In the Projects tab of the IDE alternative-click on the Source folder -> Add Existing Item. From the folder to which we just copied the file select main_blinky.c. Select absolute as the store path.

3. Pick the packages needed from the board support package

Here we put in the project everything needed from the demo project accompanying the board and from the board support package.
a. In the Projects tab of the IDE alternative-click on the Source folder -> New Logical Folder.
b. Rename it to bsp.
c. On the file system, go to the <Project Location> folder and create a mirror of the folder just created in the IDE, <Project Location>\bsp.
d. Go to <Board_Demo_Code>\pic24fj256ga7_curiosity_oobe\pic24fj256ga7_curiosity_demo.X\bsp and copy the files leds.h and leds.c to the folder created at the previous step. These files contain the support for the LEDs on the board.
e. In the Projects tab of the IDE alternative-click on the bsp folder -> Add Existing Item. From the folder to which we just copied the files select leds.c. Select absolute as the store path.
f. In the Projects tab of the IDE alternative-click on the Header Files folder -> Add Existing Item. From the folder to which we just copied the files select leds.h. Select absolute as the store path.
g. From the installation path of the compiler (normally <C:\Program Files\Microchip> go to the folder xc16\v1.61\support\PIC24F\gld and copy the file p24FJ256GA705.gld to <Project Location>. This file contains a number of configuration variables for the board in use.
h. In the Projects tab of the IDE alternative-click on the Linker Files folder -> Add Existing Item. From the folder to which we just copied the file select p24FJ256GA705.gld. Select absolute as the store path.
i. Go to <Board_Demo_Code>\pic24fj256ga7_curiosity_oobe\pic24fj256ga7_curiosity_demo.X and copy system.c to <Project Location>.
j. In the Projects tab of the IDE alternative-click on the Source folder -> Add Existing Item. From the folder to which we just copied the file select system.c. Select absolute as the store path.

4. Adapt the source code to the board

a. Modify main.c

Although not very difficult to implement, this is the trickiest point. That’s because we copied a file which contains what we want to have but implemented for a different board. A unified patch for it is provided in main_blinky.patch (alternative click -> Save Target As… to download it). It can be applied using the tool available in the IDE (Tools -> Apply Diff Patch…)

b. Modify FreeRTOSConfig.h

This step changes the specification to the one for our board and defines a few needed configuration variables for the timers used in the application. A unified patch for it is provided in FreeRTOSConfig.patch (alternative click -> Save Target As… to download it). It can be applied using the tool available in the IDE (Tools -> Apply Diff Patch…)

5. Configure the project

a. Add include directories in the project properties. Alternative-Click on the project name in the Projects tab -> Properties.

b. In the “Categories” window select XC16 (Global Options)

c. In the table on the right side click on the button with the three dots on the line Common include dirs. Add the following folders (with their absolute path)
i. <FreeRTOS_installation_folder>\FreeRTOSv10.1.1\FreeRTOS\Source\include
ii. <FreeRTOS_installation_folder>\FreeRTOS\Source\portable\MPLAB\PIC24_dsPIC
iii. <The root folder of the project>
iv. <The root folder of the project>\bsp

6. Compile, download and test the application. After this long series of easy steps, we are ready for the compilation and deployment.

a. Connect the board to the computer via the USB cable

b. Click on the Play button in the Toolbar (“Run Project”) to download the code to the board. After a successful update, the board should show LED1 blinking, meaning that messages are exchanged between the two tasks running in the application.

That’s all for now!

Based on what we have learned here, in the next post we are going to implement an event driven system for the board.

Notice on copyright holders

FreeRTOS is a trade mark of Amazon Web Services Inc., USA. MPLAB is a registered mark of Microchip Technology Inc., USA.

This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License.