====================================================================================================

                                       * ***
                                     *  ****  *
                                    *  *  ****
                                   *  **   **
                                  *  ***         ***    ***     ***    ***
                          ***    **   **        * ***  **** *  * ***  **** *
                         * ***   **   **           *** *****      *** *****
                        *   ***  **   **            ***  **        ***  **
                       **    *** **   **             ***            ***
                       ********  **   **            * ***          * ***
                       *******    **  **           *   ***        *   ***
                       **          ** *      *    *     ***      *     ***
                       ****    *    ***     *    *       *** *  *       *** *
                        *******      *******    *         ***  *         ***
                         *****         ***

                                            A C++ Library for AVR and NodeMCU
                      ~ tailored for micro LED displays and lighting effects ~

====================================================================================================
Please refer to LICENSE file for the licensing details.
====================================================================================================


====================================================================================================
Feature Summary
====================================================================================================

eCxx's SVN repository and distribution packages consists of Open Source Software library as well as
Open Hardware schematic and PCB designs for AVR and NodeMCU.

The SVN repository and distribution packages also include some Java-based and Python-based utility
applications.

--------------
Basic Features
--------------
    1. Utility templates and template functions similar to C++11 (some with different names).
    2. UniquePtr<T>, SharedPtr<T>, WeakPtr<T>, and NumericLimits<T> classes.
    3. RingBuffer<T>, Array<T>, String<T>, and FixedPoint classes.
    4. Conversion utility for strings and numbers with simple numeric-punctuation support.
    5. Math utility functions.
    6. Color space utility functions and color effect classes (including a simple painter).
    7. Color animator classes (with their ready-to-use animation processor classes).

-------------------------
Hardware-Related Features
-------------------------
All
     1. Static application class with UART, SPI, TWIMaster, TWISlave, and OWIMaster support.
     2. Non-volatile data storage (available/usable capacity depends on the platform).
     3. Multiple switch debouncing methods.
     4. Keypad scanner that supports reading multiple key press (depending on the hardware).
     5. Keypad debouncing that supports modifier key(s) and multiple key presses.
     6  Simple reader class for two-axis analog joystick with one switch (push button).
     7. Character LCD driver supporting 4-bit parallel, UART, and TWI output modes.
     8. A one-wire, half-duplex, software UART for low and medium speed transmission.
     9. Data-stream sampler for very low speed transmission.
    10. Hardware information provider class.
    11. Memory card reader and writer class (raw mode).
    12. A simple slot-based file system.
    13. BCM (binary code modulation) waveform generator.
    14. Drivers for LED strip and LED matrix.

Special for AVR and AVRX Only
    1. Analog comparator support.
    2. Measurement of internal bandgap/reference voltage and temperature
       (not all MCUs support this feature).

Special for AVRX Only
    1. Additional timers/counters.
    2. Real-time counter support.
    3. Power-down and wake-up support.
    4. Event system support.
    5. Configurable custom logic support.

Special for NodeMCU Only
    1. OTA (over-the-air) programming support.
    2. DMA (I2S) support (output-only).
    3. TCP client and server.
    4. TCP console (can be used for debugging without connecting to a physical serial port).
    5. Web server and SSL web server.

-------------------------------
Open Hardware (Schematic & PCB)
-------------------------------
    1. Development board for ATmega1284P with series resistors on the GPIO pins.
    2. Development board for NodeMCU with tri-state buffers and series resistors on the GPIO pins.
    3. IO expander board based on SIPO and PISO shift registers.
    4. UART-based LCD backpack module.
    5. AVR uploader/programmer module with remote serial terminal support (using ESP-01 module).


====================================================================================================
Supported AVR MCUs
====================================================================================================

    ┌────────────────────────────┬─────────────┬──────────────────────────────┐
    │ Generation                 │ MCU Group   │ Verified using Real Hardware │
    ├────────────────────────────┼─────────────┼──────────────────────┬───────┤
    │ Original                   │ ATmega8     │                      │       │
    │                            │ ATmega8A    │ Yes                  │ ★★    │
    │                            │ ATmega16    │                      │       │
    │                            │ ATmega32    │                      │       │
    │                            │ ATmega64    │                      │       │
    │                            │ ATmega128   │                      │       │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ Improved (Smaller Package) │ ATmega48P   │                      │       │
    │                            │ ATmega88P   │                      │       │
    │                            │ ATmega168P  │                      │       │
    │                            │ ATmega328P  │ Yes                  │ ★★★★★ │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ Improved (Smaller Package) │ ATmega48PB  │                      │       │
    │                            │ ATmega88PB  │                      │       │
    │                            │ ATmega168PB │                      │       │
    │                            │ ATmega328PB │ Yes                  │ ★     │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ Improved (Larger Package)  │ ATmega164P  │                      │       │
    │                            │ ATmega324P  │                      │       │
    │                            │ ATmega644P  │                      │       │
    │                            │ ATmega1284P │ Yes                  │ ★★    │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ Largest Package            │ ATmega1280  │                      │       │
    │                            │ ATmega2560  │ Yes                  │ ★★★★  │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ With USB Device Module     │ ATmega16U4  │                      │       │
    │                            │ ATmega32U4  │ Yes                  │ ★★★   │
    │                            │ AT90USB646  │                      │       │
    │                            │ AT90USB1286 │ Yes                  │ ★     │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ With Configurable          │ ATmega808   │                      │       │
    │      Custom Logic          │ ATmega1608  │                      │       │
    │                            │ ATmega3208  │                      │       │
    │                            │ ATmega4808  │ Yes                  │ ★★★   │
    ├────────────────────────────┼─────────────┼──────────────────────┼───────┤
    │ With Configurable          │ ATmega809   │                      │       │
    │      Custom Logic          │ ATmega1609  │                      │       │
    │                            │ ATmega3209  │                      │       │
    │                            │ ATmega4809  │ Yes                  │ ★     │
    └────────────────────────────┴─────────────┴──────────────────────┴───────┘

Note:
    # The number of black stars (★) indicates how extensive eCxx has been tested on the respective
      AVR MCUs.
    # Some of the AVR MCUs may have flash memories that are too small to support some of the test
      applications.


====================================================================================================
Supported ESP8266 Boards
====================================================================================================

All NodeMCU variants with:
    * ESP8266 (ESP-12E Module)
    * CPU frequency 80/160 MHz
    * Flash size 4 MB

All ESP-01 variants with:
    * CPU frequency 80 MHz
    * Flash size 1 MB


====================================================================================================
Getting Started
====================================================================================================

AVR and/or NodeMCU build toolkit and SDK are needed to build eCxx. The easiest method is to install
an Arduino IDE. For NodeMCU, you will need to install an additional package (please refer to
https://create.arduino.cc/projecthub/electropeak/getting-started-w-nodemcu-esp8266-on-arduino-ide-28184f
for more details).

To start building eCxx library and its test applications and firmware, simply edit the
Makefile.config[.*] files to reflect your build environment. After that, simply type make to see the
available targets.

-------------------------------------
Namespace Names for Literal Operators
-------------------------------------

The literal operators are defined within their own namespaces. Therefore, the C++ using-directives
will be needed to bring them to the active scope before using:

    using namespace eCxx::fixed_point_literals;
    using namespace eCxx::program_string_literals;

The program string literals will only be available if the ECXX_HAVE_PROGRAM_STRING_LITERALS macro is
defined.

------------------------------------------------------------------------------------
Troubleshooting Errors Like
"make: *** No rule to make target '<???>.cpp', needed by 'build/<???>.cpp.d'. Stop."
------------------------------------------------------------------------------------

Try if executing this command twice fixes the problem:

    make fdepend -k

====================================================================================================

--------------------------------------------------
Using AVR Device Pack (AVR DFP) for Newer AVR MCUs
--------------------------------------------------

Please download the latest ATmega series device pack from:
    http://packs.download.atmel.com
and extract (unzip) it to a base directory named Atmel.ATmega_DFP.x.x.xxx.

The base directory should then be placed inside one of this locations:

    /usr
    /usr/share
    /etc
    /usr/local
    /usr/local/share
    /usr/local/etc
    /opt
    /home/<user_name>
    /home/<user_name>/Arduino
    /home/<user_name>/arduino
    /home/<user_name>/.arduino
    /home/<user_name>/.arduino/packages

-------------------------------------------------------------------
Troubleshooting Errors Like "/dev/ttyACM0: Device or resource busy"
-------------------------------------------------------------------

Due to eCxx uses free shared USB VID/PID pair for CDC devices (VID=0x16C0 ; PID=0x05E1) from:

    https://github.com/obdev/v-usb/blob/master/usbdrv/USB-IDs-for-free.txt

on Linux machines with ModemManager installed, the device may show up as busy for ~15 seconds while
modem manager tries to decide if its a modem. To disable this, you can add a custom UDEV rule:

    echo 'ATTRS{idVendor}=="16c0" ATTRS{idProduct}=="05e1", ENV{ID_MM_DEVICE_IGNORE}="1"' >> \
    /etc/udev/rules.d/99-ttyacms.rules

    udevadm control --reload-rules

-------------------------------------------------------------------------------------
Troubleshooting Baudrate Mismatch between the Target MCU and the Arduino Micro in the
JTAG2UPDI_Serial_Bridge_Micro_ProMini Board
-------------------------------------------------------------------------------------

Upon power-on (plugged to a host PC's USB port), the hardware UART of the Arduino Micro will be set
to the default baudrate of 57600 bps.

If the serial device has been opened using a different baudrate by the host PC, and then the board
is unplugged and plugged back to the host PC, the OS may not know that the baudrate has been reset
to 57600 bps. In this case, the serial console may connect with a mismatched baudrate. To fix this,
simply start the serial console with a different baudrate, close it, and start it again using the
intended baudrate.

====================================================================================================

-----------------------------
ESP8266 GPIO Behavior at Boot
-----------------------------

When ESP8266 is booting, some of its GPIOs will output pulses. It may even fail to boot if some of
the GPIOs are pulled low or high during the booting phase. For more information, please refer to:

    https://rabbithole.wwwdotorg.org/2017/03/28/esp8266-gpio.html
    https://randomnerdtutorials.com/esp8266-pinout-reference-gpios

This behavior may cause problems to and from the attached peripherals. This is why eCxx's NodeMCU
development board has 74LVC541 buffers for those GPIOs. The buffers must be activated manually from
within the user code (as shown in some of the test applications).

Because the buffers' outputs will be in high impedance when they are inactive, noise may affect the
attached peripherals. This problem can be solved by adding pull-up or pull-down resistors for those
outputs. However, the eCxx's NodeMCU development board does not have this resistors onboard because
it can not possibly know if the attached peripherals will need to be pulled high or low during the
booting phase.

-----------------------------
Using Custom Xtensa LX106 GCC
-----------------------------

Please download the GCC package matching your host PC's architecture from:

    https://github.com/earlephilhower/esp-quick-toolchain/releases

Extract the package and put its main directory to one of this locations:

    /opt
    /usr/local
    /usr/share

If using custom Xtensa LX106 GCC with newlib 4.0.0, please set the USE_NEWLIB variable in the file
Makefile.config.nodemcu (or Makefile.shadow.config to 1); otherwise, it will fail to build.

Please note that newlib 4.0.0 is binary incompatible with the previous releases because of time_t
size change. Therefore, do not mix code compiled using the new library with code compiled using
the previous releases.

---------------------------------------------------------------------------------------
Troubleshooting Errors Like "/lib64/libstdc++.so.6: version 'GLIBCXX_3.4.21' not found"
when Executing "mklittlefs"
---------------------------------------------------------------------------------------

The "mklittlefs" utility requires at least GLIBCXX version 3.4.21 which is included with GCC version
5.1.0 and later.

In case your system has multiple GCC installations, setting the LD_LIBRARY_PATH environment variable
would solve the problem; for example:

    export LD_LIBRARY_PATH=/opt/gcc-5.3.0/lib64:$LD_LIBRARY_PATH
    export LD_LIBRARY_PATH=/opt/gcc-7.5.0/lib64:$LD_LIBRARY_PATH

In case of 32-bit system, replace "lib64" with "lib".


====================================================================================================
