ESP-IDF-InkPlate/CHANGES.md

Modifications done to the Arduino Inkplate Source code

As you can expect, the ESP-IDF framework is quit different than the Arduino framework. The porting effort of the Inkplate source code done here is not just a transformation to make it runs, but also getting it inline with the available packages available with the ESP-IDF. Many aspects must be transformed in this regard.

The code is also being transformed to be closer to C++ functionalities, targetting a stronger usage of the language elements that will sustain the author's software developement. A bit less C and more C++...

The source code is divided in two major groups: the low-level device drivers group, under the inkplate_platform class, and the mid-level graphical group, under the inkplate class. The coupling between these groups is minimal: one can take the inkplate-platform and build on top of it without the graphical portion. As the graphical group rely on the drivers, it is inline with the Arduino counterpart. The coupling between the two groups is light as it is done through aggregation instead of inheritence.

Here is a list of the changes being done:

Global changes

Some of these changes have been done partially and will be completed in subsequent versions.

• Give the overall drivers source code a transformation to use what is called modern C++, alligned with C++11 and beyond
• All .h files are renamed .hpp
• macro definitions (#define) are reduced to a bare minimum
• enum class are used everywhere possible in the drivers group. This reinforce source code documentation and compiler support for finding coding errors.
• source code filenames are all in lower_case. A lot easier visually to digg into the source folder and easier to remember filenames.
• all driver and support classes are using the following naming conventions:
  • class names are in ChamelCase
  • constants are in UPPER_CASE
  • variables and method names are in lower_case
• all graphical libraries and class remains with their Arduino naming convention
• classes inheritence are reduced to insure independance of usage of the drivers group. By design, the grapphical portion remains as defined for the Arduino framework with some internal transformation to be more inline with C++.
• A TAG is added in the protected/private portion of driver classes in support of the ESP-IDF Logging mechanism (ESP_LOGx defines)
• min() definition replaced with std::min()
• _swap...() definitions replaced with std::swap()
• String replaced with std::string (No PROGMEM support required with the ESP32)

Wire class and multi-threading support

A Wire class that mimics the equivalent Arduino class has been added to the library.

Access control to the I2C interface has been added to allow for interrupt based devices access and multi-threading. In the library, all code sequences that require the use of I2C are calling class methods Wire::enter() and Wire::leave() to reserve and free the interface.

defines.hpp

The content is now at a bare minimum: DisplayMode enum class that defines both INKPLATE_1BIT and INKPLATE_3BIT modes. Also, BLACK and WHITE color values for INKPLATE_1BIT mode.

As the DisplayMode is an enum class, it is then required to access the values as follow:

• DisplayMode::INKPLATE_1BIT
• DisplayMode::INKPLATE_3BIT

graphics (.hpp, .cpp)

The class is now the owner of the _partial and DMemory4Bit frame buffers. As such, methods that where defined in Inkplate.hpp are relocated into that class, namely:

• clearDisplay()
• display()
• preloadScreen()
• partialUpdate()

They select the appropriate frame buffer and call the e_ink class methods.

This change is transparent for the user application.

SdCard

• The module is used only to initialize the ESP-IDF drivers (SPI and FAT filesystem are used). The card can then be accessed through the standard C++/C capabilities, as supplied through the ESP-IDF framework. All filenames located on the card must be prefixed with /sdcard/.

Image (image.hpp, image.cpp)

• the drawXXXXFromWeb(WiFiClient *s, ...) methods are no longer available. WiFiCLient doesn't exists in an ESP-IDF context.
• the bool drawXXXXFromSd(SdFile *p, ...) methods are renamed bool drawXXXXFromFile(FILE *p, ...). This allow for accessing files located in a SPIFFS partition (using /spiffs/ filename prefix) as well as SDCard files (using /sdcard/ filename prefix) or any other file system integrated with ESP-IDF.
• functions-like related to image / pixel manipulation present in defines.h have been migrated here. Namely: RED, BLUE, GREEN, READ32, READ16, ROWSIZE, RGB8BIT, RGB3BIT. They are now inline functions with appropriate types named red, blue, green, read32, read16, rowSize, rgb8Bit, rgb3Bit.

mcp23017 (.hpp, .cpp)

This class is implementing a generic MCP23017 driver. It is instanciated in the inkplate_platform.hpp, depending on the type of Inkplate device:

• as mcp_int (for all Inkplate devices)
• as mcp_ext (for the Inkplate-10, and Inkplate-6Plus).

Each class that uses the MCPs are independant from each other in terms of initialzing and accessing the MCP. This is the case for EInk, Battery, TouchKeys, TouchScreen, Frontlight. They all uses Wire::enter() and Wire::leave() to reserve access to the I2C bus.

battery, touch_keys (.hpp, .cpp)

Those classes implement basic access to the battery and touch keys state.

system class renamed InkplatePlatform

This name reflect more what it is: the integration of all physical drivers for an Inkplate device.

FrameBuffer classes

A hierarchy of frame buffer classes has been added. These allow for flexible adaptation to the different geometry of devices and pixel sizes.

press_keys (.hpp, .cpp)

This class implements the Buttons Extension: 6 mechanical press buttons that replace the touch keys. To be used, at compile time, EXTENDED_CASE must be #defined. The TouchKeys class will then not be included.

Screen Rotation

All drivers implement physical screen coordinates. The rotation is the property of the graphical environment that sit on top of the drivers. As such, all rotation related methods have been moved outside of the driver classes.