From 5a06cda785d28e33ead4eb0c3f2682b9d6bf1a44 Mon Sep 17 00:00:00 2001 From: Khoi Hoang <57012152+khoih-prog@users.noreply.github.com> Date: Tue, 13 Sep 2022 23:47:23 -0400 Subject: [PATCH] Update`README.md` --- README.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 213 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 4fa4149..8e2daeb 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,56 @@ # React_Generic +[![arduino-library-badge](https://www.ardu-badge.com/badge/React_Generic.svg?)](https://www.ardu-badge.com/React_Generic) +[![GitHub release](https://img.shields.io/github/release/khoih-prog/React_Generic.svg)](https://github.com/khoih-prog/React_Generic/releases) +[![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](#Contributing) +[![GitHub issues](https://img.shields.io/github/issues/khoih-prog/React_Generic.svg)](http://github.com/khoih-prog/React_Generic/issues) ![C++](https://img.shields.io/badge/language-C++-blue.svg) [![license: MIT](https://img.shields.io/badge/license-MIT-brightgreen.svg)](https://opensource.org/licenses/MIT) +--- +--- + +## Table of Contents + +* [Why do we need this React_Generic library](#why-do-we-need-this-React_Generic-library) + * [Features](#features) + * [Why Async is better](#why-async-is-better) + * [Currently supported Boards](#currently-supported-boards) +* [Changelog](changelog.md) +* [Prerequisites](#prerequisites) +* [Installation](#installation) + * [Use Arduino Library Manager](#use-arduino-library-manager) + * [Manual Install](#manual-install) + * [VS Code & PlatformIO](#vs-code--platformio) +* [HOWTO Use](#howto-use) + * [Blink](#Blink) + * [Why Bother?](#Why-Bother) + * [Advanced callback support](#Advanced-callback-support) +* [API](#API) + * [Namespace use](#Namespace-use) + * [Event Registration Functions](#Event-Registration-Functions) + * [Management functions](#Management-functions) +* [Examples](#examples) + * [Original Examples](#original-examples) + * [ 1. minimal](examples/minimal) + * [ 2. torture_test](examples/torture_test) + * [multiFileProject Examples](#multiFileProject-examples) + * [ 1. multiFileProject](examples/multiFileProject) +* [Issues](#issues) +* [TO DO](#to-do) +* [DONE](#done) +* [Contributions and Thanks](#contributions-and-thanks) +* [Contributing](#contributing) +* [License](#license) +* [Copyright](#copyright) + +--- +--- + +### Why do we need this [React_Generic library](https://github.com/khoih-prog/React_Generic) + +#### Features + By - [Andrew Carter](https://github.com/AndrewCarterUK) @@ -15,7 +63,86 @@ The library is at the core of the [SensESP](https://github.com/SignalK/SensESP) This library gets much of its inspiration (and some code) from [`Reactduino`](https://github.com/Reactduino/Reactduino). `React_Generic`, however, has been internally re-implemented for maintainability and readability, and has significantly better performance when there are lots of defined reactions. It also supports arbitrary callables as callbacks, allowing parametric creation of callback functions. -## Blink +#### Currently supported Boards + +This [**React_Generic** library](https://github.com/khoih-prog/React_Generic) currently supports these following boards: + + 1. **ESP32** + + 2. **ESP8266** + + 3. **WT32_ETH01 (ESP32 + LAN8720A)** + + 4. **STM32F/L/H/G/WB/MP1 boards with built-in Ethernet LAN8742A** such as : + + - **Nucleo-144 (F429ZI, F767ZI)** + - **Discovery (STM32F746G-DISCOVERY)** + - **All STM32 boards (STM32F/L/H/G/WB/MP1) with 32K+ Flash, with Built-in Ethernet** + + 5. **STM32F4/F7 boards using Ethernet LAN8720** such as : + + - **Nucleo-144 (F429ZI, NUCLEO_F746NG, NUCLEO_F746ZG, NUCLEO_F756ZG)** + - **Discovery (DISCO_F746NG)** + - **STM32F4 boards (BLACK_F407VE, BLACK_F407VG, BLACK_F407ZE, BLACK_F407ZG, BLACK_F407VE_Mini, DIYMORE_F407VGT, FK407M1)** + + `Note: Must use with STM32 core v2.2.0-` + + 6. **SAMD21/SAMD51** + + 7. **nRF52 boards**, such as **AdaFruit Feather nRF52832, nRF52840 Express, BlueFruit Sense, Itsy-Bitsy nRF52840 Express, Metro nRF52840 Express, NINA_B302_ublox, NINA_B112_ublox, etc.** + + 8. **Teensy 4.1 using QNEthernet Library** + + 9. **RASPBERRY_PI_PICO** using [**arduino-pico core v2.5.2+**](https://github.com/earlephilhower/arduino-pico) + + +--- +--- + +## Prerequisites + + 1. [`Arduino IDE 1.8.19+` for Arduino](https://github.com/arduino/Arduino). [![GitHub release](https://img.shields.io/github/release/arduino/Arduino.svg)](https://github.com/arduino/Arduino/releases/latest) + 2. [`ESP32 Core 2.0.4+`](https://github.com/espressif/arduino-esp32) for ESP32-based boards. [![Latest release](https://img.shields.io/github/release/espressif/arduino-esp32.svg)](https://github.com/espressif/arduino-esp32/releases/latest/) + 3. [`ESP8266 Core 3.0.2+`](https://github.com/esp8266/Arduino) for ESP8266-based boards. [![Latest release](https://img.shields.io/github/release/esp8266/Arduino.svg)](https://github.com/esp8266/Arduino/releases/latest/). + 4. [`Adafruit nRF52 v1.3.0+`](https://github.com/adafruit/Adafruit_nRF52_Arduino) for nRF52 boards such as Adafruit NRF52840_FEATHER, NRF52832_FEATHER, NRF52840_FEATHER_SENSE, NRF52840_ITSYBITSY, NRF52840_CIRCUITPLAY, NRF52840_CLUE, NRF52840_METRO, NRF52840_PCA10056, PARTICLE_XENON, **NINA_B302_ublox**, etc. [![GitHub release](https://img.shields.io/github/release/adafruit/Adafruit_nRF52_Arduino.svg)](https://github.com/adafruit/Adafruit_nRF52_Arduino/releases/latest) + 5. [`Teensy core v1.57+`](https://www.pjrc.com/teensy/td_download.html) for Teensy (4.1, 4.0, 3.6, 3.5, 3,2, 3.1, 3.0) boards. + 6. [`ArduinoCore-mbed mbed_rp2040, mbed_nano, mbed_portenta core 3.3.0+`](https://github.com/arduino/ArduinoCore-mbed) for Arduino (Use Arduino Board Manager) **Portenta_H7, RP2040-based boards, such as Nano_RP2040_Connect, RASPBERRY_PI_PICO**. [![GitHub release](https://img.shields.io/github/release/arduino/ArduinoCore-mbed.svg)](https://github.com/arduino/ArduinoCore-mbed/releases/latest) + 7. [`Earle Philhower's arduino-pico core v2.5.2+`](https://github.com/earlephilhower/arduino-pico) for RP2040-based boards such as **RASPBERRY_PI_PICO, ADAFRUIT_FEATHER_RP2040 and GENERIC_RP2040**, etc. [![GitHub release](https://img.shields.io/github/release/earlephilhower/arduino-pico.svg)](https://github.com/earlephilhower/arduino-pico/releases/latest) + 8. [`Arduino SAM DUE core v1.6.12+`](https://github.com/arduino/ArduinoCore-sam) for SAM DUE ARM Cortex-M3 boards. + 9. [`Arduino SAMD core 1.8.13+`](https://github.com/arduino/ArduinoCore-samd) for SAMD ARM Cortex-M0+ boards. [![GitHub release](https://img.shields.io/github/release/arduino/ArduinoCore-samd.svg)](https://github.com/arduino/ArduinoCore-samd/releases/latest) +10. [`Adafruit SAMD core 1.7.10+`](https://github.com/adafruit/ArduinoCore-samd) for SAMD ARM Cortex-M0+ and M4 boards (Nano 33 IoT, etc.). [![GitHub release](https://img.shields.io/github/release/adafruit/ArduinoCore-samd.svg)](https://github.com/adafruit/ArduinoCore-samd/releases/latest) +11. [`Seeeduino SAMD core 1.8.3+`](https://github.com/Seeed-Studio/ArduinoCore-samd) for SAMD21/SAMD51 boards (XIAO M0, Wio Terminal, etc.). [![Latest release](https://img.shields.io/github/release/Seeed-Studio/ArduinoCore-samd.svg)](https://github.com/Seeed-Studio/ArduinoCore-samd/releases/latest/) + +--- +--- + +## Installation + +### Use Arduino Library Manager + +The best and easiest way is to use `Arduino Library Manager`. Search for `React_Generic`, then select / install the latest version. +You can also use this link [![arduino-library-badge](https://www.ardu-badge.com/badge/React_Generic.svg?)](https://www.ardu-badge.com/React_Generic) for more detailed instructions. + +### Manual Install + +1. Navigate to [React_Generic](https://github.com/khoih-prog/React_Generic) page. +2. Download the latest release `React_Generic-main.zip`. +3. Extract the zip file to `React_Generic-main` directory +4. Copy the whole `React_Generic-main` folder to Arduino libraries' directory such as `~/Arduino/libraries/`. + +### VS Code & PlatformIO: + +1. Install [VS Code](https://code.visualstudio.com/) +2. Install [PlatformIO](https://platformio.org/platformio-ide) +3. Install [**React_Generic** library](https://registry.platformio.org/libraries/khoih-prog/React_Generic) by using [Library Manager](https://registry.platformio.org/libraries/khoih-prog/React_Generic/installation). Search for React_Generic in [Platform.io Author's Libraries](https://platformio.org/lib/search?query=author:%22Khoi%20Hoang%22) +4. Use included [platformio.ini](platformio/platformio.ini) file from examples to ensure that all dependent libraries will installed automatically. Please visit documentation for the other options and examples at [Project Configuration File](https://docs.platformio.org/page/projectconf.html) + +--- +--- + +## HOWTO Use + +### Blink If you have worked with the Arduino framework before, it is likely that you will have come across the [blink sketch](https://www.arduino.cc/en/tutorial/blink). This is a simple program that flashes an LED every second, and it looks something like this: @@ -66,7 +193,9 @@ Instead of directly defining the program logic in the `loop()` function, _reacti The `app.tick()` call in the `loop()` function is the main loop of the program. It is responsible for calling the reactions that have been defined. You can also add additional code to the `loop()` function, any delays or other long-executing code should be avoided. -## Why Bother? +--- + +### Why Bother? Charlie wants to make a simple program which echoes data on the `Serial` port. Their Arduino sketch will looks like this: @@ -181,7 +310,9 @@ void loop() } ``` -## Advanced callback support +--- + +### Advanced callback support Callbacks can be not just void pointers but any callable supported by `std::function`. This means they can use lambda captures or argument binding using `std::bind`. For example, the following code creates 20 different repeating reactions updating different fields of an array: @@ -199,6 +330,9 @@ for (int i=0; i<20; i++) } ``` +--- +--- + ## API ### Namespace use @@ -259,47 +393,91 @@ void Reaction::remove(); Remove the reaction from the execution queue. -*Note*: Calling `remove()` for `DelayReaction` objects is only safe if the reaction has not been triggered yet. Upon triggering, the `DelayReaction` object is deleted and any pointers to it will be invalidated. +*Note*: Calling `remove()` for `DelayReaction` objects is only safe if the reaction has not been triggered yet. Upon triggering, the `DelayReaction` object is deleted and any pointers to it will be invalidated -### Examples -- [`Minimal`](examples/minimal/src/main.cpp): A minimal example with two timers switching the LED state. +--- +--- -- [`Torture test`](examples/torture_test/src/main.cpp): A stress test of twenty simultaneous repeat reactions as well as a couple of interrupts, a stream, and a tick reaction. For kicks, try changing `NUM_TIMERS` to 200. Program performance will be practically unchanged! +### Examples: -## Changes between version 1 and 2 +#### Original Examples -React_Generic version 2 has changed the software initialization approach from version 1. -Version 1 implemented the Arduino framework standard `setup()` and `loop()` functions behind the scenes, -and a user just instantiated a React_Generic object and provided a setup function as an argument: + 1. [`minimal`](examples/minimal): A minimal example with two timers switching the LED state. + 2. [`torture_test`](examples/torture_test): A stress test of twenty simultaneous repeat reactions as well as a couple of interrupts, a stream, and a tick reaction. For kicks, try changing `NUM_TIMERS` to 200. Program performance will be practically unchanged! -``` -React_Generic app([]() -{ - app.onDelay(...); -}); -``` +#### multiFileProject Examples -While this approach was "neat", it was also confusing to many users familiar with the Arduino framework. Therefore, React_Generic version 2 has reverted back to the more conventional approach: +- [`multiFileProject`](examples/multiFileProject) -``` -React_Generic app; +--- +--- -void setup() -{ - app.onDelay(...); -} -void loop() -{ - app.tick(); -} -``` +### Issues ### + +Submit issues to: [React_Generic issues](https://github.com/khoih-prog/React_Generic/issues) + +--- + +### TO DO + +1. Bug Searching and Killing +2. Support more types of boards + +### DONE + + 1. Add support to **Arduino SAMD21 (ZERO, MKR, NANO_33_IOT, etc.)** + 2. Add support to **Adafruit SAMD21 (Itsy-Bitsy M0, Metro M0, Feather M0 Express, etc.)**. + 3. Add support to **Adafruit SAMD51 (Itsy-Bitsy M4, Metro M4, Grand Central M4, Feather M4 Express, etc.)**. + 4. Add support to **Adafruit nRF52 ( Feather nRF52832, nRF52840 Express, BlueFruit Sense, Itsy-Bitsy nRF52840 Express, Metro nRF52840 Express, NINA_B302_ublox, NINA_B112_ublox, etc.**. + 5. Add support to RP2040-based boards such as RASPBERRY_PI_PICO, using [**Arduino-mbed RP2040** core](https://github.com/arduino/ArduinoCore-mbed) + 6. Add support to RP2040-based boards such as RASPBERRY_PI_PICO, using [**Earle Philhower's arduino-pico** core](https://github.com/earlephilhower/arduino-pico) + 7. Add support to Teensy + +--- +--- + +### Contributions and Thanks + +Many thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library. + +1. Based on and modified from [Andrew Carter's Reactduino](https://github.com/Reactduino/Reactduino) +2. Based on and modified from [Matti Airas' ReactESP](https://github.com/mairas/ReactESP) + + + + + + + +
AndrewCarterUK
⭐️ Andrew Carter
mairas
⭐️ Matti Airas
+ +--- + +### 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 library is licensed under [MIT](https://github.com/khoih-prog/React_Generic/blob/main/LICENSE) + +--- + + +## Copyright + -Note the changes: +Copyright 2017- Andrew Carter +Copyright 2019- Matti Airas +Copyright 2022- Khoi Hoang -- React_Generic app object is instantiated without any arguments -- There is an explicit `setup()` function. - Its contents can be copied verbatim from the version 1 lambda function. -- There is an explicit `loop()` function. - `app.tick()` must be called in the loop. +