Common Component

Installation

The component requires ESP-IDF 5.0 and higher and is installed using IDF Component Manager.

Add this to the idf_component.yml in the project main directory or in the component directory:

dependencies:
  plasmapper/pl_common: "^1.2.2"

Add this to the source code:

#include "pl_common.h"

Add extern "C" to the app_main function:

extern "C" void app_main(void) {...}

Add this to the sdkconfig.defaults in the project directory or configure the values using Project Configuration:

CONFIG_COMPILER_CXX_RTTI=y

Features

  1. PL::Lockable - a base class for any lockable object. Descendant classes should override PL::Lockable::Lock() and PL::Lockable::Unlock().

  2. PL::LockGuard - a RAII-style lock guard class. It is used to lock an object inside a code block: PL::LockGuard lg (PL::Lockable&);.

  3. PL::Mutex - a mutex class. It inherits PL::Lockable and overrides PL::Lockable::Lock() and PL::Lockable::Unlock() with FreeRTOS xSemaphoreTakeRecursive and xSemaphoreGiveRecursive.

  4. PL::Buffer - a lockable buffer class. The memory is either allocated when the buffer is initialized or the buffer uses an already preallocated data. Buffer also can be initialized with a shared lockable (for example when one buffer is a part of another buffer). PL::Buffer::data and PL::Buffer::size.

  5. PL::TypedBuffer - a class template for a buffer with typed data. It inherits PL::Buffer and has a typed public member PL::TypedBuffer::data.

  6. PL::Event - an event class template. It can be added as a public member to the class and used by class member functions to generate events using PL::Event::Generate() and by external objects to subscribe/unsubscribe for events using PL::Event::AddHandler()/PL::Event::RemoveHandler().

  7. PL::EventHanler - an event handler class template. If class handles only one event it can inherit this class and override PL::EventHanler::HandleEvent() method. For classes with multiple event handlers template<class HandlerClass> void PL::Event::AddHandler(std::shared_ptr<HandlerClass>, void(HandlerClass::*)(Source&, Args...)) should be used.

  8. PL::Stream - a base class for any stream. A number of PL::Stream::Read() and PL::Stream::Write() functions read and write from/to the stream. Reading and writing to/from PL::Buffer object checks the data size and locks the object so these methods can be used in multithreaded applications.

  9. PL::HardwareInterface - a base class for any hardware interface. Descendant classes should override PL::HardwareInterface::Initialize(), PL::HardwareInterface::Enable(), PL::HardwareInterface::Disable(), PL::HardwareInterface::IsEnabled(), PL::HardwareInterface::Lock() and PL::HardwareInterface::Unlock().

  10. PL::Server - a base class for any server. Descendant classes should override PL::Server::Enable(), PL::Server::Disable(), PL::Server::IsEnabled(), PL::Server::Lock() and PL::Server::Unlock().

  11. PL::StreamServer - a PL::Server implementation using a PL::Stream for communication with client. The descendant class should override PL::StreamServer::HandleRequest() to handle the client request. PL::StreamServer::HandleRequest() is only called when there is incoming data in the internal buffer.

Thread safety

Class method thread safety is implemented by having the PL::Lockable as a base class and creating the class object lock guard at the beginning of the methods.

PL::StreamServer task method locks both the PL::StreamServer and the PL::Stream objects for the duration of the transaction.

API reference