PCF8574 Library 2.4.0 update with Ultrasonic sensor management

A focused, practical update that improves HC‑SR04 ultrasonic sensor support and startup diagnostics. This release introduces NewPing‑style convenience methods, polling-friendly variants to reduce I2C traffic, and diagnostics helpers that make bring‑up and debugging faster across Arduino, ESP32, ESP8266 and other supported platforms.

---

Highlights

• New NewPing‑style ultrasonic API for HC‑SR04 (convenient and familiar): ping(), ping_cm(), ping_in(), ping_median().
• Polling variants (pingPoll, ping_cm_poll, ping_median_poll) to dramatically reduce I2C requests and improve multi‑sensor behavior.
• beginResult() diagnostic API (and helpers) to help users surface common initialization problems (I2C wiring, wrong address, missing pinMode() calls).
• Hybrid usage recommendations (PCF8574 → TRIG, MCU → ECHO) documented and exampled for best accuracy vs. pin‑savings tradeoffs.
• Documentation updates, new examples, and three small diagrams to illustrate wiring, hybrid setup and polling tradeoffs.

---

Key changes

1. Ultrasonic API (NewPing style)

   • unsigned long ping(uint8_t trigPin, uint8_t echoPin, unsigned long maxDistance_cm = 500);

     • Returns pulse duration in microseconds.

   • unsigned long ping_cm(uint8_t trigPin, uint8_t echoPin, unsigned long maxDistance_cm = 500);

     • Returns distance in centimeters (0 on timeout).

   • unsigned long ping_in(uint8_t trigPin, uint8_t echoPin, unsigned long maxDistance_cm = 500);

     • Returns distance in inches (0 on timeout).

   • unsigned long ping_median(uint8_t trigPin, uint8_t echoPin, uint8_t iterations = 5, unsigned long maxDistance_cm = 500);

     • Returns the median distance across iterations samples for more stable readings.

   • Polling variants for each of the above: pingPoll, ping_cm_poll, ping_in_poll, ping_median_poll with a pollIntervalMicros parameter to reduce I2C traffic.

2. Diagnostics & initialization

   • BeginResult beginResult() — returns detailed initialization status (OK, I2C_ERROR, NO_PINS_CONFIGURED, INVALID_ADDRESS).
   • PCF8574::beginResultToString() and printBeginResult() — helpers that produce readable diagnostics for quick troubleshooting.
   • beginWithResultPrint() — convenience wrapper that runs beginResult() and prints friendly diagnostics.

3. Documentation and examples

   • Examples updated with recommended usage patterns: polling defaults, median filtering, hybrid TRIG/ECHO wiring.
   • Added three SVG diagrams in docs/resources/ illustrating wiring, hybrid approach, and poll‑interval tradeoffs.

4. Minor improvements

   • Improved I2C timing behavior and reliability on ESP32/ESP8266 and other platforms.
   • Small bugfixes and code cleanups related to begin/initialization flow.

---

Migration notes and recommended practices

• Backwards compatibility: No breaking API changes are expected for standard digital read/write or encoder APIs.
• For ultrasonic usage, prefer the polling variants for PCF8574‑based ECHO measurements to reduce I2C traffic. Example:

// Recommended default for PCF8574: poll every 100µs
unsigned long cm = pcf.ping_cm_poll(TRIG_PIN, ECHO_PIN, 400, 100);

• For best accuracy, use the hybrid approach: trigger the sensor via PCF8574 (TRIG) and measure ECHO directly on the MCU interrupt/GPIO pin (use pulseIn() on a native pin).

• Always call pcf.pinMode() for the PCF8574 pins before calling pcf.begin() — this avoids a common initialization pitfall.

• During initial hardware bring‑up, enable PCF8574_BEGIN_ENUM_RESULT in your sketch and use beginResult() to inspect the device state.

#define PCF8574_BEGIN_ENUM_RESULT
#include <PCF8574.h>

PCF8574 pcf(0x20);

void setup(){
  Serial.begin(115200);
  pcf.pinMode(P0, OUTPUT);
  BeginResult r = pcf.beginResult();
  Serial.println(PCF8574::beginResultToString(r));
}

---

Example: median polling (stable, low‑traffic)

// Take median of 5 samples, poll every 100µs to reduce I2C load
unsigned long distance_cm = pcf.ping_median_poll(TRIG_PIN, ECHO_PIN, 5, 400, 100);
if (distance_cm == 0) {
  // Timeout or out of range
} else {
  // Use distance_cm
}

---

Notes & credits

• Full source and examples: https://github.com/xreef/PCF8574_library
• Documentation and posts: https://www.mischianti.org/category/my-libraries/pcf8574/

We hope this release makes it simpler and more reliable to use ultrasonic sensors with the PCF8574 on small embedded platforms — happy prototyping! 🚀