Porting Guide

Porting the library to a new software development framework and hardware platform entails the implementation of the corresponding I2C PAL class. In the following sections, some additional explanations and hints are provided:

Framework PAL Implementation

Implement the abstract PAL interface for you framework. The I2C class implementation is mandatory.

The Doxygen comments on the "src/pal/rgb-led-lighting-shield-pal-i2c.hpp" describe the required behavior of each function of the PAL Interface.

Consider the existing framework implementations as reference examples for your design: "/src/frawework/sample_fmwk/pal". Some of the functions are optional depending on your framework and intended usage of the library.

That is the case of init() and deinit(), which take care of the hardware peripherals init/deinitialization. If this is done in your main application (or somewhere else outside the library), there is no need of delegating such initialization to the RGB LED Lighting Shield library. The definition of these functions can just be a return with the success return code.

Framework API Wrapper

The framework API wrapper implementation is optional. It is meant to ease the usage of RGB LED Lighting Shield. The main help is to avoid the creation of the I2C object instances for the developer.

To illustrate this approach, it is easier to evaluate a concrete implementation of the Arduino Wrapper implementation "rgb-led-lighting-shield-ino.hpp/cpp" (these files should be located under "src/framework/arduino/wrapper/". More info here):

1. Adapt the constructor arguments to those used for the I2C creation in the new framework, using the native data types and structures. Hide what can be already defined for that platform and provide as much abstraction and simplicity as possible.

   For example, the core library RGB LED Lighting Shield API constructor:

   RGBShield(I2CPAL *i2c);
   

   is wrapped for Arduino like this:

   RGBShieldIno(TwoWire *wire);
   

   While it does not seems to simplify much in number of arguments, an Arduino developer can simply pass the pointer to a Wire-Class-Instance and does not take care about this general I2CPAL-Class, which could be quite confusing.

   As for the constructor, the same philosophy can apply to other functions of the public API. In case of Arduino, as a hobbyist and makers environment, clarity and simplicity might prevail over configurability and functionality. Therefore, the wrapper API further hides, group or eliminate certain functionalities.

   For each ecosystem and framework, any other criteria can be chosen, hopefully matching as well its code conventions, implementation principles and paradigms.