lf-ir-obstacle

Reusable IR Reflective / Obstacle Avoidance Sensor driver library for the Raspberry Pi Pico C SDK, packaged as a Conan package. Designed for 3-pin IR phototransistor-comparator breakout modules (e.g. TCRT5000 / KY-033) for short-range obstacle detection (intended for distances no further than 5-10cm).

This is part of the Lost + Found suite of projects.

---

🔍 Module Architecture & Theory of Operation

A standard 3-pin IR obstacle / line-tracker breakout module combines an optical front-end with an on-board analog comparator:

               COMMERCIAL IR OBSTACLE BREAKOUT MODULE
               
       +3.3V ───[220R]───► [IR LED] ──► GND
       
       +3.3V ───[ 10k]───┬───────────────┐ (+)
                         │               ▼
                      [RX PTX]       ┌───────┐
                         │           │ LM393 │───► OUT (Digital Pin)
                        GND          │ Comp. │
                                 ┌──►│       ├───► [On-board SMD LED]
       +3.3V ───[Potentiometer]──┘(-)└───────┘
                     (Trim Pot)

1. Optical Front-End: An infrared TX LED paired with an RX Phototransistor in a 10 kΩ pull-up divider.
2. LM393 Comparator & Trim Potentiometer: An on-board analog comparator (LM393) compares the phototransistor's voltage divider output against a reference voltage set by turning the on-board blue potentiometer screw.
3. Digital Output: When an obstacle reflects sufficient infrared light to drop the phototransistor voltage below the potentiometer threshold, the LM393 pulls the digital OUT pin LOW (active-low) and illuminates an on-board indicator LED.

---

🥊 Module Breakout (lf-ir-obstacle) vs. Discrete ADC (lf-phototransistor)

Feature	lf-ir-obstacle (This Library)	lf-phototransistor (Discrete ADC Library)
Hardware	Commercial LM393 Breakout Module	Discrete 5mm/3mm LED + Phototransistor on ADC
Output Type	1-bit Digital Switch (HIGH / LOW)	12-bit Continuous Analog Voltage & Intensity
Thresholding	Physical screwdriver adjustment on potentiometer	Dynamic software configuration in firmware
Ambient Light Rejection	Vulnerable to bright sunlight/ambient glare	Synchronous LED pulsing eliminates room light
Best For	Quick plug-and-play digital proximity/limit switches	Precision distance, auto-ranging HDR, and colorimetry

(If you are building your own circuit from discrete components or need continuous analog ADC readings, see the sibling package lf-phototransistor).

---

🛠️ Usage with CMake

Copy the driver directory into your project as a subdirectory:

add_subdirectory(lib/lf-ir-obstacle)

target_link_libraries(your_project PRIVATE
    lf-ir-obstacle
)

And in your C/C++ code:

#include "lf_ir_obstacle.h"

---

🔌 Hardware Setup

Connect the IR obstacle sensor breakout pins to your Raspberry Pi Pico/Pico 2:

Sensor Pin	Pico 2 GPIO Pin	Pico 2 Physical Pin	Notes
VCC	3V3	Pin 36	Run at 3.3V to keep the OUT pin logic level safe for the RP2350 GPIO.
GND	GND	Pin 38 (or any GND)	Ground.
OUT	GP15 (or any GPIO)	Pin 20	Digital input pin.

---

⚙️ Driver API Description

The driver encapsulates GPIO setup, state evaluation, and software debouncing inside a clean, object-oriented context structure:

typedef struct {
    uint gpio_pin;
    bool active_low;
    bool last_stable_state;
    volatile bool state_changed;
} lf_ir_obstacle_t;

Main API Functions:

• bool lf_ir_obstacle_init(lf_ir_obstacle_t *device, uint gpio_pin, bool active_low)
  Initializes the GPIO pin as input with pull-up and configures the driver context.
• void lf_ir_obstacle_irq_handler(lf_ir_obstacle_t *device)
  To be called in the GPIO callback interrupt. It disables interrupts on the pin to filter contact bounce.
• bool lf_ir_obstacle_check_and_clear_changed(lf_ir_obstacle_t *device, bool *out_detected)
  Should be polled in your main thread loop. If a state transition occurred, it waits for 30ms to let the hardware signal settle, reads the stable state, re-arms the interrupts, and returns true.

---

🚀 Standalone Build & Run (Demo)

You can build and test this driver library standalone:

1. Configure with CMake:

   mkdir -p build && cd build
   cmake -DPICO_BOARD=pico2 ..
   

2. Build:

   make -j$(nproc)
   

3. Flash: Load the compiled ir_obstacle_demo.uf2 file onto your Pico 2.