ArduProf framework

The ArduProf lib library provides a thin layer framework that makes it easier for developers to code inter-thread communication by an event driven method.
version 1.0.0 supports FreeRTOS on ESP32.
version 2.0.0 (plan) supports Mbed OS on Raspherry Pi Pico (RP2040)

---

supported Hardware (ESP32, ESP32-S3, ESP32C3)

The following boards are supported by this project:

• ESP32-DevKitC V1
• ESP32-S3-DevKitC-1 v1.1
• ESP32C3-CORE
• (v2.0.0 plan) Raspberry Pi Pico
• (v2.0.0 plan) W5100S-EVB-Pico
• (v2.0.0 plan) WizFi360-EVB-Pico

---

ArduProf framework diagram

---

Software setup for ESP32, ESP32-S3, ESP32C3

• Install Arduino IDE 2.2+ for Arduino
• Install Arduino-ESP32
• Install Arduino DebugLog
• Install ArduinoJson
• Install ArduProf

Software setup for Raspherry Pi Pico (plan)

• Install Arduino IDE 2.2+ for Arduino
• Install Arduino Mbed OS RP2040 Boards 4.0.6+
• Install Arduino DebugLog
• Install ArduinoJson
• Install ArduProf

---

Build demo code (basic example for ESP32C3)

• launch the Arduino IDE
• create a new project of example "basic" by clicking Menu -> "File" -> "Examples" -> "ArduProf" -> "basic"
  
• select ESP32C3 Dev Module by clicking Menu -> “Tools” -> “Select Board” -> "ESP32C3 Dev Module"
• config ESP32C3 Dev Module settings as below
  
• build the code by clicking Menu -> “Sketch” -> “Compile/Verify”
  If everything goes smoothly, you should see the following screen.

Flash and run demo code (basic example for ESP32C3)

• select the ESP32C3 virtual port by clicking Menu -> “Tools” -> “Port” -> ...
• build the code by clicking Menu -> “Sketch” -> “Upload”
  If everything goes smoothly, you should see the following screen.

Serial monitor log output

Example code explanation (basic example)

Message format: Format of event message between threads is defined in the file "src/type/Message.h".
It includes fields such as "event" (signed word), "iParam" (signed word), "uParam" (unsigned word) and "lParam" (unsigned double word)

    typedef struct _Message
    {
        int16_t event;
        int16_t iParam;
        uint16_t uParam;
        uint32_t lParam;
    } Message;

Example 1: post event from Arduino loop to ThreadApp
The first step to use ArduProf framework is including the "ArduProf.h" header file. Then defines "queueMain" and "threadApp" and starts them. Posting an event "EventNull" from "queueMain" to "threadApp" is simply as "queueMain.postEvent(context.threadApp, EventNull)" Sample code is listed in file "basic.ino"

#include <ArduProf.h>
...

// define variable "queueMain" for Arduino thred to interact with ArduProf framework.
static QueueMain queueMain;

// define variable "threadApp" for application thread. (Define other thread as you need)
static ThreadApp threadApp;

// define variable "context" and initialize pointers to "queueMain" and "threadApp"
static AppContext context = {
    .queueMain = &queueMain,
    .threadApp = &threadApp,
};

void setup()
{
    ...
    
    // initialize queueMain
    queueMain.start(&context);

    // start threadApp
    threadApp.start(&context);
}

void loop()
{
    ...

    // delay 1s
    delay(1000);

    // post an event "EventNull" to threadApp
    queueMain.postEvent(context.threadApp, EventNull);
}

Example 2: handling event "EventNull" in ThreadApp There are 3 steps to handle an event. They are:

1. declare event handler
2. define event handler
3. setup event handler (map event to handler)

Sample code of declare event handler in "ThreadApp.h"

class ThreadApp : public ThreadBase
{
    ...

    ///////////////////////////////////////////////////////////////////////
    // declare event handler
    ///////////////////////////////////////////////////////////////////////
    __EVENT_FUNC_DECLARATION(EventNull) // void handlerEventNull(const Message &msg);

}

Sample code of define event handler in "ThreadApp.cpp"

// define EventNull handler
__EVENT_FUNC_DEFINITION(QueueMain, EventNull, msg) // void QueueMain::handlerEventNull(const Message &msg)
{
    LOG_TRACE("EventNull(", msg.event, "), iParam=", msg.iParam, ", uParam=", msg.uParam, ", lParam=", msg.lParam);
}

Sample code of setup event handler (map event to handler) in "ThreadApp.cpp"

ThreadApp::ThreadApp() : ...
{
    ...

    // setup event handlers
    handlerMap = {
        __EVENT_MAP(ThreadApp, EventNull), // {EventNull, &ThreadApp::handlerEventNull},
    };
}

---

Debug

Enable or disable log be modifying macro on "src/LibLog.h"

Debug is disabled by "#define DEBUGLOG_DISABLE_LOG" Enable trace debug by "#define DEBUGLOG_DEFAULT_LOG_LEVEL_TRACE"

Example of src/LibLog.h

// Disable Logging Macro (Release Mode)
// #define DEBUGLOG_DISABLE_LOG
// You can also set default log level by defining macro (default: INFO)
// #define DEBUGLOG_DEFAULT_LOG_LEVEL_WARN // for release version
#define DEBUGLOG_DEFAULT_LOG_LEVEL_TRACE // for debug version
#include <DebugLog.h>                    // https://github.com/hideakitai/DebugLog

---

Troubleshooting

If you get compilation errors, more often than not, you may need to install a newer version of the core for Arduino boards.

Sometimes, the project will only work if you update the board core to the latest version because I am using newly added functions.

---

Issues

Submit issues to: ArduProf issues

---

TO DO

• Search for bug and improvement.
• Support Raspberry Pi Pico (RP2040) for version 2.0.0

---

Contributions and Thanks

Many thanks to the following authors who have developed great audio data and Arduino libraries.

• DebugLog
• ArduinoJson

Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this project.

---

Contributing

If you want to contribute to this project:

• Report bugs and errors
• Ask for enhancements
• Create issues and pull requests
• Tell other people about this library

---

License

• The project is licensed under GNU GENERAL PUBLIC LICENSE Version 3

---

Copyright

• Copyright 2024 teamprof.net@gmail.com. All rights reserved.