FreeRTOS Examples

The Sapphire High-Performance SoC supports the popular FreeRTOS real-time operating system, and includes example software projects targeting the RTOS. For more details on using FreeRTOS, go to their web site at https://www.freertos.org.

Download the FreeRTOS

By default, the RISC-V IDE is bundled with FreeRTOS version 202212.01. It will be auto detected when creating or importing projects. Follow these steps if you need a different version FreeRTOS.

Download the FreeRTOS zip file from https://www.freertos.org.
Unzip the folder to any directory.
Point to the folder when importing existing project or creating new project.

After you have downloaded the FreeRTOS, you use the software projects in the same manner as the other example software.

freertosDemo

This example shows how the FreeRTOS schedular handles two program executions using task and queue allocation. Generally, the FreeRTOS queue is used as a thread FIFO buffer and for intertask communication. This example creates two tasks and one queue; the queue sends and receives traffic. The receive traffic (or receive queue) blocks the program execution until it receives a matching value from the send traffic (or send queue).

Tasks in the send queue sit in a loop that blocks execution for 1,000 miliseconds before sending the value 100 to the receive queue. Once the value is sent, the task loops, i.e., blocks for another 1,000 miliseconds.

When the receive queue receives the value 100, it begins executing its task, which sends the message Blink to the UART peripheral and toggles an LED on the development board.

Hello world, this is FreeRTOS
Blink
Blink
Blink

freertosEchoServerDemo

This example demonstrates an Ethernet server that echoes the data packets received from the client, which in this case would be your machine. The echoed data will be printed out via the UART terminal. The design utilizes the FreeRTOS-Plus-TCP library.

Note: Before running this design, you need to set up your Ethernet adapter similar to the lwipIperfServer example.

To run this design, you need to download the echoTool and run it in PowerShell with the following command:

.\echotool.exe "192.168.31.55" /p tcp /r 10000 /d strawberry /n 1
.\echotool.exe "192.168.31.55" /p tcp /r 10000 /d apple /n 1

The application displays messages on a UART terminal:

***Hello world, this is FreeRTOS Echo Server***
Linked Up
Link Partner Full duplex 1000 Mbps

Received bytes: 10, Received data strawberry
Received bytes: 5, Received data apple

freertosFatDemo

This example demonstrates how to use the FreeRTOS-Plus-FAT library to initialize the SD card as well as to write a text file, freertos.txt into the SD Card. This example prints out the SD Card information.

Note: An SD card formatted to FAT32 is required.

The application displays messages on a UART terminal:

***Hello world, this is FreeRTOS FAT demo***

--- FreeRTOS Demo Start ---

Initialize...FF_Part: no partitions, try as PBR
****** FreeRTOS+FAT initialized 60432384 sectors
Reading FAT and calculating Free Space
Partition Nr   0
Type           12 (FAT32)
VolLabel       'NO NAME    ' 
TotalSectors   60432384
SecsPerCluster 32
Size           29492 MB
FreeSize       29491 MB ( 100 percent free )
FF_SDDiskInit: Mounted SD-card as root "/sd0"
Reading FAT and calculating Free Space
Partition Nr   0
Type           12 (FAT32)
VolLabel       'NO NAME    ' 
TotalSectors   60432384
SecsPerCluster 32
Size           29492 MB
FreeSize       29491 MB ( 100 percent free )

--- FreeRTOS Demo Finish ---

freertosIperfDemo

This example demonstrates how to use the FreeRTOS-Plus-TCP library to enable the Sapphire High-Performance SoC as an Iperf server on FreeRTOS OS. Iperf is a simple performance measuring tool used to check Ethernet bandwidth. You can use iPerf3 on a PC as the client. Before running the iPerf3 tool, establish connection between your device and your computer.

Note:

Before running this design, you need to set up your Ethernet adapter similar to the lwipIperfServer example.
You need to use iPerf3 version 3.1.3 to test. This demo is validated with this version.

***Hello world, this is FreeRTOS iPerf demo***
Linked Up
Link Partner Full duplex 1000 Mbps

vIPerfTask: created TCP server socket 210832 port 5001: 0 listen 0
vIPerfTask: created UDP server socket 211328 port 5001: 0
Use for example:
FreeRTOS receive: iperf3 -c 192.168.31.55 -p 5001 -n 100M 
FreeRTOS send:    iperf3 -c 192.168.31.55 -p 5001 -n 100M -R
vIPerfTask: Received a connection from 192.168.31.222:1292
TCP[ port 1292 ] recv[ 0 ] 37
Got Control Socket: rc -1: exp: '' got: 'DESKTOP-MI0I69O.1717996238.242000.71'
TCP[ port 1292 ] recv[ 1 ] 4
TCP skipcount 88 xRecvResult 4
TCP[ port 1292 ] recv[ 2 ] 88
Control string: {"tcp":true,"omit":0,"num":104857600,"parallel":1,"len":131072,"client_version":"3.1.3"}
vIPerfTask: Received a connection from 192.168.31.222:1293
TCP[ port 1293 ] recv[ 0 ] 37
Got expected client: rc 0: 'DESKTOP-MI0I69O.1717996238.242000.71'
TCP[ port 1292 ] recv[ 3 ] 1
TCP[ port 1292 ] recv 1 bytes: 0x00000004
TCP[ port 1292 ] recv[ 4 ] 4
TCP skipcount 196 xRecvResult 4
TCP[ port 1292 ] recv[ 5 ] 196
vIPerfTCPClose: Closing server socket 192.168.31.222:1293 after 104743357 bytes
vIPerfTCPClose: Closing server socket 192.168.31.222:1292 after 331 bytes
vIPerfTask: Received a connection from 192.168.31.222:5471
TCP[ port 5471 ] recv[ 0 ] 37
Got Control Socket: rc -1: exp: '' got: 'DESKTOP-MI0I69O.1717996257.895331.2b'
TCP[ port 5471 ] recv[ 1 ] 4
TCP skipcount 103 xRecvResult 4
TCP[ port 5471 ] recv[ 2 ] 103
Control string: {"tcp":true,"omit":0,"num":104857600,"parallel":1,"reverse":true,"len":131072,
"client_version":"3.1.3"}
Reverse 1 send 104857600 bytes timed 0: 0
vIPerfTask: Received a connection from 192.168.31.222:5472
TCP[ port 5472 ] recv[ 0 ] 37
Got expected client: rc 0: 'DESKTOP-MI0I69O.1717996257.895331.2b'
TCP[ port 5471 ] recv[ 3 ] 1
TCP[ port 5471 ] recv 1 bytes: 0x00000004
Shutdown connection
TCP[ port 5471 ] recv[ 4 ] 4
TCP skipcount 197 xRecvResult 4
TCP[ port 5471 ] recv[ 5 ] 197
vIPerfTCPClose: Closing server socket 192.168.31.222:5472 after 37 bytes
vIPerfTCPClose: Closing server socket 192.168.31.222:5471 after 347 bytes

freertosMqttPlainTextDemo

This demo illustrates how to use the FreeRTOS-Plus coreMQTT library. It connects to a local broker, mosquitto, subscribes to a topic, publishes a message to the broker, reads back the message from the broker, and finally unsubscribes from the broker.

The plaintext MQTT demo means that the message transactions are not encrypted.

To get started, you are required to do the following steps:

Download Mosquitto to act as a local broker.
Edit the mosquitto.conf file by adding the following lines:
```
Listener 1883 192.168.31.222
allow_anonymous true
```
Execute the mosquitto executable in PowerShell with the following command:
```
.\mosquitto.exe -v -c .\mosquitto.conf
```

There would be plenty of printout during an MQTT transaction. The application would display the following messages on a UART terminal indicating that the MQTT transaction has been completed:

[INFO] [MQTTDemo] [prvMQTTUnsubscribeFromTopics:870] Unsubscribing from topic testClient09:10:51/example/topic0.

[INFO] [MQTTDemo] [prvMQTTUnsubscribeFromTopics:870] Unsubscribing from topic testClient09:10:51/example/topic1.

[INFO] [MQTTDemo] [prvMQTTUnsubscribeFromTopics:870] Unsubscribing from topic testClient09:10:51/example/topic2.

[INFO] [MQTTDemo] [prvMQTTProcessResponse:947] PUBREL received for packet id PUBCOMP received for packet id 
[INFO] [MQTTDemo] [prvMQTTProcessResponse:924] UNSUBACK received for packet ID PINGRESP should not be handled by the application callback when using MQTT_ProcessLoop.

[INFO] [MQTTDemo] [prvMQTTDemoTask:553] Disconnecting the MQTT connection with 192.168.31.222.

[INFO] [MQTTDemo] [prvMQTTDemoTask:568] prvMQTTDemoTask() completed an iteration successfully. Total free heap is Demo completed successfully.

[INFO] [MQTTDemo] [prvMQTTDemoTask:569] Demo completed successfully.

[INFO] [MQTTDemo] [prvMQTTDemoTask:570] -------DEMO FINISHED-------

[INFO] [MQTTDemo] [prvMQTTDemoTask:571] Short delay before starting the next iteration....