placing API definitions in separate include file ??

[aintgotnoname]

Let's move this into general discussion (and delete if you wish).

I'm happily using a modified version of the library include file in multiple .cpp files throughout a larger (15 file) platform io project.
In my project, various files perform adc reads, led operations, gpio and io stuff locally in each of the files using various library calls. Thus, the library file (or its api definitions) need to be included in multiple source files. I cannot use the heltec_unofficial.h as originally written without encountering two errors in PlatformIO/VSC/cpp.

The first error, reported in issue #24, is the duplicate definitions from pins_arduino.h. These could simply be #ifdef'd (//'d) out in the heltec_unoffical.h to avoid the redefinition. The PLATFORMIO define is defined and contains (I think) their version number. Creating our own USING_PLATFORMIO define and setting it before the include would follow your original scheme.

#ifndef PLATFORMIO
#define SS        GPIO_NUM_8
#define MOSI      GPIO_NUM_10
#define MISO      GPIO_NUM_11
#define SCK       GPIO_NUM_9
#endif

The second error that occurs is a linker error for the duplicate code blocks and declarations within heltec_unofficial.h when multiply included. In my little world, I needed to include API calls (function prototypes) for the library in multiple source files. However, using the heltec_unoffical.h unmodified, this gave me linker errors for duplicate definitions (PrintSplitter for example) and declarations.

I can overcome this second error by using two files. First, a new file heltec_unofficial_api.h that contains all of the function prototypes and PrintSplitter class definitions, that extern's the various constants and declarations. Including this heltec_unofficial_api.h file allows all of my sources to compile without any (duplicate) declarations when including the original heltec_unoffical.h. After all, this is just duplicating the prototypes and definitions.

/**

• @file heltec_api.h
• @brief Header file for the Heltec library.
• This file contains the definitions and declarations for the Heltec library.
• The library provides functions for controlling the Heltec ESP32 LoRa V3
• board, including LED brightness control, voltage measurement, deep sleep
• mode, and more.
  */

#ifndef heltec_api_h
#define heltec_api_h

// 'PRG' Button
#define BUTTON GPIO_NUM_0
// LED pin & PWM parameters
#define LED_PIN GPIO_NUM_35
#define LED_FREQ 5000
#define LED_CHAN 0
#define LED_RES 8
// External power control
#define VEXT GPIO_NUM_36
// Battery voltage measurement
#define VBAT_CTRL GPIO_NUM_37
#define VBAT_ADC GPIO_NUM_1
// SPI pins
//#define SS GPIO_NUM_8
//#define MOSI GPIO_NUM_10
//#define MISO GPIO_NUM_11
//#define SCK GPIO_NUM_9
// Radio pins
#define DIO1 GPIO_NUM_14
//#define RST_LoRa GPIO_NUM_12
//#define BUSY_LoRa GPIO_NUM_13
// Display pins
//#define SDA_OLED GPIO_NUM_17
//#define SCL_OLED GPIO_NUM_18
//#define RST_OLED GPIO_NUM_21

#ifndef HELTEC_NO_RADIOLIB
#include "RadioLib.h"
// make sure the power off button works when using RADIOLIB_OR_HALT
// (See RadioLib_convenience.h)
#define RADIOLIB_DO_DURING_HALT heltec_delay(10)
#include "RadioLib_convenience.h"
String radiolib_result_string(const int16_t result);
#endif

#ifdef HELTEC_NO_DISPLAY
#define HELTEC_NO_DISPLAY_INSTANCE
#else
#include "SSD1306Wire.h"
#endif

//#include "HotButton.h"

#ifndef HELTEC_NO_RADIO_INSTANCE
#ifndef HELTEC_NO_RADIOLIB
extern SX1262 radio;
#endif
#endif

// Don't you just hate it when battery percentages are wrong?
//
// I measured the actual voltage drop on a LiPo battery and these are the
// average voltages, expressed in 1/256'th steps between min_voltage and
// max_voltage for each 1/100 of the time it took to discharge the battery. The
// code for a telnet server that outputs battery voltage as CSV data is in
// examples, and a python script that outputs the constants below is in
// src/tools.
extern const float min_voltage;
extern const float max_voltage;
extern const uint8_t scaled_voltage[100];

/**

• @Class PrintSplitter
• @brief A class that splits the output of the Print class to two different

•    Print objects.
  

• The PrintSplitter class is used to split the output of the Print class to two
• different Print objects. It overrides the write() function to write the data
• to both Print objects.
  /
  class PrintSplitter : public Print {
  public:
  PrintSplitter(Print &_a, Print &_b) : a(_a), b(_b) {}
  size_t write(uint8_t c) {
  a.write(c);
  return b.write(c);
  }
  size_t write(const char str) {
  a.write(str);
  return b.write(str);
  }
  private:
  Print &a;
  Print &b;
  };

extern SSD1306Wire display;
extern PrintSplitter both;

// extern HotButton button;

/**

• @brief Controls the LED brightness based on the given percentage.
• This function sets up the LED channel, frequency, and resolution, and then
• adjusts the LED brightness based on the given percentage. If the percentage
• is 0 or less, the LED pin is set as an input pin.
• @param percent The brightness percentage of the LED (0-100).
  */
  void heltec_led(int percent);

/**

• @brief Controls the VEXT pin to enable or disable external power.
• This function sets the VEXT pin as an output pin and sets its state based on
• the given parameter. If the state is true, the VEXT pin is set to LOW to
• enable external power. If the state is false, the VEXT pin is set to INPUT to
• disable external power.
• @param state The state of the VEXT pin (true = enable, false = disable).
  */
  void heltec_ve(bool state);

/**

• @brief Measures the battery voltage.
• This function measures the battery voltage by controlling the VBAT_CTRL pin
• and reading the analog value from the VBAT_ADC pin. The measured voltage is
• then converted to a float value and returned.
• @return The battery voltage in volts.
  */
  float heltec_vbat();

/**

• @brief Puts the device into deep sleep mode.
• This function prepares the device for deep sleep mode by disconnecting from
• WiFi, turning off the display, disabling external power, and turning off the
• LED. It can also be configured to wake up after a certain number of seconds
• using the optional parameter.
• @param seconds The number of seconds to sleep before waking up (default = 0).
  */
  void heltec_deep_sleep(int seconds = 0);

/**

• @brief Calculates the battery percentage based on the measured battery
• voltage.
• This function calculates the battery percentage based on the measured battery
• voltage. If the battery voltage is not provided as a parameter, it will be
• measured using the heltec_vbat() function. The battery percentage is then
• returned as an integer value.
• @param vbat The battery voltage in volts (default = -1).
• @return The battery percentage (0-100).
  */
  int heltec_battery_percent(float vbat = -1);

/**

• @brief Checks if the device woke up from deep sleep due to button press.
• @return True if the wake-up cause is a button press, false otherwise.
  */
  bool heltec_wakeup_was_button();

/**

• @brief Checks if the device woke up from deep sleep due to a timer.
• This function checks if the device woke up from deep sleep due to a timer.
• @return True if the wake-up cause is a timer interrupt, false otherwise.
  */
  bool heltec_wakeup_was_timer();

/**

• @brief Measures esp32 chip temperature
• @return float with temperature in degrees celsius.
  */
  float heltec_temperature();

/**

• @brief Initializes the Heltec library.
• This function should be the first thing in setup() of your sketch. It
• initializes the Heltec library by setting up serial port and display.
  */
  void heltec_setup();

/**

• @brief The main loop function for the Heltec library.
• This function should be called in loop() of the Arduino sketch. It updates
• the state of the power button and implements long-press power off if used.
  */
  void heltec_loop();

/**

• @brief Delays the execution of the program for the specified number of

•    milliseconds.
  

• This function delays the execution of the program for the specified number of
• milliseconds. During the delay, it also calls the heltec_loop() function to
• allow for the power off button to be checked.
• @param ms The number of milliseconds to delay.
  */
  void heltec_delay(int ms);

#endif // heltec_api_h

The simple inclusion of such an API definition file (for those who wish to use it) in your library would go a long way in solving the problems I've encountered with PlatformIO. As a standalone companion to the original file, nothing else "needs to" change.

Going beyond, it is appropriate as good practice to link the original include and API declarations to avoid mismatch. To that end, I have modified the heltec_unofficial.h to include the ...api.h file to ensure the prototypes and definitions match between the two files. In doing so, I've created my own can of worms, though a little one. I've had to remove some of the default parameter specifications from the heltec_unofficial.h; though they are in the (included) ..._api.h file. I then must use one instance of the modified heltec_official.h file to declare the consts and objects used. For me, this is main.c. All other files simply include the ..._api.h file instead.

As the main.c pulls in (essentially) the same heltec_unoffical.h (and internally the heltec_unoffical_api.h), all functions work the same. I have no problem with HotButton or heltec_loop() inside loop, or display/serial/both anywhere in any file. This is really just a different compilation exercise. Of course, I get to modify everything to follow your updates since I'm going at it on my own.

Is it worth it for me to create a fork just to show this?

and again, thanks for all this.