v1.8.0 to fix multiple-definitions linker error

### Releases v1.8.0

1. Fix `multiple-definitions` linker error. Drop `src_cpp` and `src_h` directories
2. Add example `Argument_Complex_Multi` to demonstrate how to avoid `multiple-definitions` linker error in multiple-file projects

Author: khoih-prog

CONTRIBUTING.md

@@ -14,7 +14,7 @@ If you don't find anything, please [open a new issue](https://github.com/khoih-p
 
 Please ensure to specify the following:
 
-* Arduino IDE version (e.g. 1.8.16) or Platform.io version
+* Arduino IDE version (e.g. 1.8.19) or Platform.io version
 * `Arduino AVR` or `Adafruit AVR` Core Version (e.g. Arduino AVR core v1.8.3 or Adafruit AVR Core v1.4.14)
 * Contextual information (e.g. what you were trying to achieve)
 * Simplest possible steps to reproduce
@@ -26,10 +26,10 @@ Please ensure to specify the following:
 ### Example
 
 ```
-Arduino IDE version: 1.8.16
+Arduino IDE version: 1.8.19
 Arduino AVR Core Version 1.8.3
 OS: Ubuntu 20.04 LTS
-Linux xy-Inspiron-3593 5.4.0-90-generic #101-Ubuntu SMP Fri Oct 15 20:00:55 UTC 2021 x86_64 x86_64 x86_64 GNU/Linux
+Linux xy-Inspiron-3593 5.4.0-96-generic #109-Ubuntu SMP Wed Jan 12 16:49:16 UTC 2022 x86_64 x86_64 x86_64 GNU/Linux
 
 Context:
 I encountered a crash while trying to use the Timer Interrupt.

README.md

@@ -50,7 +50,8 @@
   * [ 10. SwitchDebounce](examples/SwitchDebounce)
   * [ 11. TimerDuration](examples/TimerDuration)
   * [ 12. TimerInterruptTest](examples/TimerInterruptTest)
-  * [ 13. Change_Interval_HF](examples/Change_Interval_HF). **New**
+  * [ 13. Change_Interval_HF](examples/Change_Interval_HF).
+  * [ 14. Argument_Complex_Multi](examples/Argument_Complex_Multi). **New**
 * [Example ISR_16_Timers_Array_Complex](#example-isr_16_timers_array_complex)
 * [Debug Terminal Output Samples](#debug-terminal-output-samples)
   * [1. ISR_16_Timers_Array_Complex on Arduino AVR Nano-V3 board](#1-isr_16_timers_array_complex-on-arduino-avr-nano-v3-board)
@@ -167,24 +168,26 @@ Another way to install is to:
 
 ### HOWTO Fix `Multiple Definitions` Linker Error
 
-The current library implementation, using **xyz-Impl.h instead of standard xyz.cpp**, possibly creates certain `Multiple Definitions` Linker error in certain use cases. Although it's simple to just modify several lines of code, either in the library or in the application, the library is adding 2 more source directories
+The current library implementation, using `xyz-Impl.h` instead of standard `xyz.cpp`, possibly creates certain `Multiple Definitions` Linker error in certain use cases.
 
-1. **scr_h** for new h-only files
-2. **src_cpp** for standard h/cpp files
+You can use
 
-besides the standard **src** directory.
+```
+#include <TimerInterrupt.hpp>         //https://github.com/khoih-prog/TimerInterrupt
+#include <ISR_Timer.hpp>              //https://github.com/khoih-prog/TimerInterrupt
+```
 
-To use the **old standard cpp** way, locate this library' directory, then just 
+in many files. But be sure to use the following `#include <TimerInterrupt.h>` or `#include <ISR_Timer.h>` **in just 1 `.h`, `.cpp` or `.ino` file**, which must **not be included in any other file**, to avoid `Multiple Definitions` Linker Error
 
-1. **Delete the all the files in src directory.**
-2. **Copy all the files in src_cpp directory into src.**
-3. Close then reopen the application code in Arduino IDE, etc. to recompile from scratch.
+```
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
+#include "TimerInterrupt.h"           //https://github.com/khoih-prog/TimerInterrupt
 
-To re-use the **new h-only** way, just 
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
+#include "ISR_Timer.h"                //https://github.com/khoih-prog/TimerInterrupt
+```
 
-1. **Delete the all the files in src directory.**
-2. **Copy the files in src_h directory into src.**
-3. Close then reopen the application code in Arduino IDE, etc. to recompile from scratch.
+Check new [**Argument_Complex_Multi** example](examples/Argument_Complex_Multi) for the demo how to avoid `Multiple Definitions` Linker Error. 
 
 ---
 ---
@@ -452,7 +455,8 @@ void setup()
 10. [SwitchDebounce](examples/SwitchDebounce)
 11. [TimerDuration](examples/TimerDuration)
 12. [TimerInterruptTest](examples/TimerInterruptTest)
-13. [**Change_Interval_HF**](examples/Change_Interval_HF). New.
+13. [**Change_Interval_HF**](examples/Change_Interval_HF).
+14. [**Argument_Complex_Multi**](examples/Argument_Complex_Multi). **New**
 
 ---
 
@@ -478,7 +482,10 @@ void setup()
   #warning Using Timer3
 #endif
 
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
 #include "TimerInterrupt.h"
+
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
 #include "ISR_Timer.h"
 
 #include <SimpleTimer.h>              // https://github.com/schinken/SimpleTimer
@@ -821,7 +828,7 @@ While software timer, **programmed for 2s, is activated after more than 10.000s
 ```
 
 Starting ISR_16_Timers_Array_Complex on Arduino AVR UNO, Nano, etc.
-TimerInterrupt v1.7.0
+TimerInterrupt v1.8.0
 CPU Frequency = 16 MHz
 Starting  ITimer1 OK, millis() = 7
 SimpleTimer : 2, ms : 10007, Dms : 10007
@@ -971,7 +978,7 @@ The following is the sample terminal output when running example [Change_Interva
 
 ```
 Starting Change_Interval on Arduino AVR Mega2560/ADK
-TimerInterrupt v1.7.0
+TimerInterrupt v1.8.0
 CPU Frequency = 16 MHz
 Starting  ITimer1 OK, millis() = 5
 Starting  ITimer3 OK, millis() = 8
@@ -999,7 +1006,7 @@ The following is the sample terminal output when running example [Change_Interva
 
 ```
 Starting Change_Interval_HF on Arduino AVR UNO, Nano, etc.
-TimerInterrupt v1.7.0
+TimerInterrupt v1.8.0
 CPU Frequency = 16 MHz
 [TISR] T1
 [TISR] Freq * 1000 = 5000000.00
@@ -1042,7 +1049,7 @@ The following is the sample terminal output when running example [Change_Interva
 ```
 
 Starting Change_Interval_HF on Arduino AVR Mega2560/ADK
-TimerInterrupt v1.7.0
+TimerInterrupt v1.8.0
 CPU Frequency = 16 MHz
 [TISR] T1
 [TISR] Freq * 1000 = 5000000.00
@@ -1138,6 +1145,8 @@ Submit issues to: [TimerInterrupt issues](https://github.com/khoih-prog/TimerInt
 13. Add Timer3 and Timer4 support to **ATmega32U4 and ATmega16U4**.
 14. Fix bug resulting half frequency when using high frequencies.
 15. Fix bug resulting wrong frequency for some low frequencies.
+16. Fix `multiple-definitions` linker error. Drop `src_cpp` and `src_h` directories
+
 
 ---
 ---

changelog.md

@@ -11,6 +11,7 @@
 ## Table of Contents
 
 * [Changelog](#changelog)
+  * [Releases v1.8.0](#releases-v180)
   * [Releases v1.7.0](#releases-v170)
   * [Releases v1.6.0](#releases-v160)
   * [Releases v1.5.0](#releases-v150)
@@ -28,6 +29,11 @@
 
 ## Changelog
 
+### Releases v1.8.0
+
+1. Fix `multiple-definitions` linker error. Drop `src_cpp` and `src_h` directories
+2. Add example `Argument_Complex_Multi` to demonstrate how to avoid `multiple-definitions` linker error in multiple-file projects
+
 ### Releases v1.7.0
 
 1. Fix bug resulting wrong frequency for some low frequencies.

examples/Argument_Complex/Argument_Complex.ino

@@ -42,6 +42,7 @@
   #warning Using Timer3
 #endif
 
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
 #include "TimerInterrupt.h"
 
 #if !defined(LED_BUILTIN)

examples/Argument_Complex_Multi/Argument_Complex_Multi.cpp

@@ -0,0 +1,53 @@
+/****************************************************************************************************************************
+  Argument_Complex_Multi.cpp
+  For Arduino and Adadruit AVR 328(P) and 32u4 boards
+  Written by Khoi Hoang
+
+  Built by Khoi Hoang https://github.com/khoih-prog/TimerInterrupt
+  Licensed under MIT license
+
+  Now we can use these new 16 ISR-based timers, while consuming only 1 hardware Timer.
+  Their independently-selected, maximum interval is practically unlimited (limited only by unsigned long miliseconds)
+  The accuracy is nearly perfect compared to software timers. The most important feature is they're ISR-based timers
+  Therefore, their executions are not blocked by bad-behaving functions / tasks.
+  This important feature is absolutely necessary for mission-critical tasks.
+
+  Notes:
+  Special design is necessary to share data between interrupt code and the rest of your program.
+  Variables usually need to be "volatile" types. Volatile tells the compiler to avoid optimizations that assume
+  variable can not spontaneously change. Because your function may change variables while your program is using them,
+  the compiler needs this hint. But volatile alone is often not enough.
+  When accessing shared variables, usually interrupts must be disabled. Even with volatile,
+  if the interrupt changes a multi-byte variable between a sequence of instructions, it can be read incorrectly.
+  If your data is multiple variables, such as an array and a count, usually interrupts need to be disabled
+  or the entire sequence of your code which accesses the data.
+*****************************************************************************************************************************/
+
+// To demonstrate the usage of complex multiple files to avoid `multi definition linker` error
+// by using TimerInterrupt.hpp in multiple files but TimerInterrupt.h in only main file
+
+#include "Argument_Complex_Multi.h"
+
+void TimerHandler(unsigned int outputPinsAddress)
+{
+  static bool toggle = false;
+
+  //timer interrupt toggles pins
+#if (TIMER_INTERRUPT_DEBUG > 1)
+  Serial.print("Toggle pin1 = "); Serial.println( ((pinStruct *) outputPinsAddress)->Pin1 );
+#endif
+  
+  digitalWrite(((pinStruct *) outputPinsAddress)->Pin1, toggle);
+
+#if (TIMER_INTERRUPT_DEBUG > 1)
+  Serial.print("Read pin2 A0 ("); Serial.print(((pinStruct *) outputPinsAddress)->Pin2 );
+  Serial.print(") = ");
+  Serial.println(digitalRead(((pinStruct *) outputPinsAddress)->Pin2) ? "HIGH" : "LOW" );                          
+
+  Serial.print("Read pin3 A1 ("); Serial.print(((pinStruct *) outputPinsAddress)->Pin3 );
+  Serial.print(") = ");
+  Serial.println(digitalRead(((pinStruct *) outputPinsAddress)->Pin3) ? "HIGH" : "LOW" );  
+#endif
+                 
+  toggle = !toggle;
+}

examples/Argument_Complex_Multi/Argument_Complex_Multi.h

@@ -0,0 +1,69 @@
+/****************************************************************************************************************************
+  Argument_Complex_Multi.h
+  For Arduino and Adadruit AVR 328(P) and 32u4 boards
+  Written by Khoi Hoang
+
+  Built by Khoi Hoang https://github.com/khoih-prog/TimerInterrupt
+  Licensed under MIT license
+
+  Now we can use these new 16 ISR-based timers, while consuming only 1 hardware Timer.
+  Their independently-selected, maximum interval is practically unlimited (limited only by unsigned long miliseconds)
+  The accuracy is nearly perfect compared to software timers. The most important feature is they're ISR-based timers
+  Therefore, their executions are not blocked by bad-behaving functions / tasks.
+  This important feature is absolutely necessary for mission-critical tasks.
+
+  Notes:
+  Special design is necessary to share data between interrupt code and the rest of your program.
+  Variables usually need to be "volatile" types. Volatile tells the compiler to avoid optimizations that assume
+  variable can not spontaneously change. Because your function may change variables while your program is using them,
+  the compiler needs this hint. But volatile alone is often not enough.
+  When accessing shared variables, usually interrupts must be disabled. Even with volatile,
+  if the interrupt changes a multi-byte variable between a sequence of instructions, it can be read incorrectly.
+  If your data is multiple variables, such as an array and a count, usually interrupts need to be disabled
+  or the entire sequence of your code which accesses the data.
+*****************************************************************************************************************************/
+
+// To demonstrate the usage of complex multiple files to avoid `multi definition linker` error
+// by using TimerInterrupt.hpp in multiple files but TimerInterrupt.h in only main file
+
+#ifndef Argument_Complex_Multi_h
+#define Argument_Complex_Multi_h
+
+// These define's must be placed at the beginning before #include "TimerInterrupt.h"
+// _TIMERINTERRUPT_LOGLEVEL_ from 0 to 4
+// Don't define _TIMERINTERRUPT_LOGLEVEL_ > 0. Only for special ISR debugging only. Can hang the system.
+#define TIMER_INTERRUPT_DEBUG         0
+#define _TIMERINTERRUPT_LOGLEVEL_     3
+
+#if ( defined(__AVR_ATmega644__) || defined(__AVR_ATmega644A__) || defined(__AVR_ATmega644P__) || defined(__AVR_ATmega644PA__)  || \
+        defined(ARDUINO_AVR_UNO) || defined(ARDUINO_AVR_NANO) || defined(ARDUINO_AVR_MINI) ||    defined(ARDUINO_AVR_ETHERNET) || \
+        defined(ARDUINO_AVR_FIO) || defined(ARDUINO_AVR_BT)   || defined(ARDUINO_AVR_LILYPAD) || defined(ARDUINO_AVR_PRO)      || \
+        defined(ARDUINO_AVR_NG) || defined(ARDUINO_AVR_UNO_WIFI_DEV_ED) || defined(ARDUINO_AVR_DUEMILANOVE) || defined(ARDUINO_AVR_FEATHER328P) || \
+        defined(ARDUINO_AVR_METRO) || defined(ARDUINO_AVR_PROTRINKET5) || defined(ARDUINO_AVR_PROTRINKET3) || defined(ARDUINO_AVR_PROTRINKET5FTDI) || \
+        defined(ARDUINO_AVR_PROTRINKET3FTDI) )
+  #define USE_TIMER_1     true
+  #warning Using Timer1
+#else          
+  #define USE_TIMER_3     true
+  #warning Using Timer3
+#endif
+
+// Can be included in many files without `Multiple Definitions` Linker Error
+#include "TimerInterrupt.hpp"
+
+#if !defined(LED_BUILTIN)
+  #define LED_BUILTIN     13
+#endif
+
+struct pinStruct
+{
+  unsigned int Pin1;
+  unsigned int Pin2;
+  unsigned int Pin3;
+};
+
+#define TIMER_INTERVAL_MS    1000
+
+void TimerHandler(unsigned int outputPinsAddress);
+
+#endif      // Argument_Complex_Multi_h

examples/Argument_Complex_Multi/Argument_Complex_Multi.ino

@@ -0,0 +1,91 @@
+/****************************************************************************************************************************
+  Argument_Complex_Multi.ino
+  For Arduino and Adadruit AVR 328(P) and 32u4 boards
+  Written by Khoi Hoang
+
+  Built by Khoi Hoang https://github.com/khoih-prog/TimerInterrupt
+  Licensed under MIT license
+
+  Now we can use these new 16 ISR-based timers, while consuming only 1 hardware Timer.
+  Their independently-selected, maximum interval is practically unlimited (limited only by unsigned long miliseconds)
+  The accuracy is nearly perfect compared to software timers. The most important feature is they're ISR-based timers
+  Therefore, their executions are not blocked by bad-behaving functions / tasks.
+  This important feature is absolutely necessary for mission-critical tasks.
+
+  Notes:
+  Special design is necessary to share data between interrupt code and the rest of your program.
+  Variables usually need to be "volatile" types. Volatile tells the compiler to avoid optimizations that assume
+  variable can not spontaneously change. Because your function may change variables while your program is using them,
+  the compiler needs this hint. But volatile alone is often not enough.
+  When accessing shared variables, usually interrupts must be disabled. Even with volatile,
+  if the interrupt changes a multi-byte variable between a sequence of instructions, it can be read incorrectly.
+  If your data is multiple variables, such as an array and a count, usually interrupts need to be disabled
+  or the entire sequence of your code which accesses the data.
+*****************************************************************************************************************************/
+
+// To demonstrate the usage of complex multiple files to avoid `multi definition linker` error
+// by using TimerInterrupt.hpp in multiple files but TimerInterrupt.h in only main file
+
+// These definitions must be placed before #include <TimerInterrupt.h> 
+#include "Argument_Complex_Multi.h"
+
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
+#include "TimerInterrupt.h"
+
+volatile pinStruct myOutputPins = { LED_BUILTIN, A0, A1 };
+
+#define TIMER_INTERVAL_MS    1000
+
+void setup()
+{
+  pinMode(myOutputPins.Pin1, OUTPUT);
+  pinMode(myOutputPins.Pin2, OUTPUT);
+  pinMode(myOutputPins.Pin3, OUTPUT);
+    
+  Serial.begin(115200);
+  while (!Serial);
+
+  Serial.print(F("\nStarting Argument_Complex on "));
+  Serial.println(BOARD_TYPE);
+  Serial.println(TIMER_INTERRUPT_VERSION);
+  Serial.print(F("CPU Frequency = ")); Serial.print(F_CPU / 1000000); Serial.println(F(" MHz"));
+
+  // Timer0 is used for micros(), millis(), delay(), etc and can't be used
+  // Select Timer 1-2 for UNO, 1-5 for MEGA, 1,3,4 for 16u4/32u4
+  // Timer 2 is 8-bit timer, only for higher frequency
+  // Timer 4 of 16u4 and 32u4 is 8/10-bit timer, only for higher frequency
+
+  // Using ATmega328 used in UNO => 16MHz CPU clock ,
+  // For 16-bit timer 1, 3, 4 and 5, set frequency from 0.2385 to some KHz
+  // For 8-bit timer 2 (prescaler up to 1024, set frequency from 61.5Hz to some KHz
+  
+#if USE_TIMER_1
+
+  ITimer1.init();
+
+  // Using ATmega328 used in UNO => 16MHz CPU clock ,
+
+  if (ITimer1.attachInterruptInterval(TIMER_INTERVAL_MS, TimerHandler, (unsigned int) &myOutputPins))
+  {
+    Serial.print(F("Starting  ITimer1 OK, millis() = ")); Serial.println(millis());
+  }
+  else
+    Serial.println(F("Can't set ITimer1. Select another freq. or timer"));
+    
+#elif USE_TIMER_3
+
+  ITimer3.init();
+
+  if (ITimer3.attachInterruptInterval(TIMER_INTERVAL_MS, TimerHandler, (unsigned int) &myOutputPins))
+  {
+    Serial.print(F("Starting  ITimer3 OK, millis() = ")); Serial.println(millis());
+  }
+  else
+    Serial.println(F("Can't set ITimer3. Select another freq. or timer"));
+
+#endif
+}
+
+void loop()
+{
+}

examples/Argument_None/Argument_None.ino

@@ -44,6 +44,7 @@
   #warning Using Timer1, Timer3
 #endif
 
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
 #include "TimerInterrupt.h"
 
 #define TIMER1_INTERVAL_MS    1000

examples/Argument_Simple/Argument_Simple.ino

@@ -44,6 +44,7 @@
   #warning Using Timer3
 #endif
 
+// To be included only in main(), .ino with setup() to avoid `Multiple Definitions` Linker Error
 #include "TimerInterrupt.h"
 
 #if !defined(LED_BUILTIN)