Merge pull request #903 from adafruit/uv-7331

Add Adafruit AS7331 UV A/B/C Sensor (PID 7331)

Author: tyeth

.agents/skills/add-sensor-component-v1/SKILL.md

@@ -16,6 +16,40 @@ postRun: >
 
 # Add I2C Sensor Component to WipperSnapper v1
 
+## Hard Gates — violations of these rules produce broken drivers
+
+These rules exist because agents have previously skipped the learn guide, guessed GitHub URLs for
+libraries, silently ignored 404s, and constructed library names from repo names instead of looking
+them up. Each of these produced drivers that either called non-existent APIs or failed to compile
+because the dependency couldn't be resolved.
+
+1. **Learn guide is a prerequisite, not a nice-to-have.** You must find and read the Adafruit
+   learn guide for the product before writing any driver code. The research chain is:
+   web search for product page → extract learn guide URL from the product page → fetch the
+   `.md?view=all` version of the learn guide → extract the Arduino library name from the
+   `## Arduino` section. If you cannot find the learn guide after reasonable effort, **STOP and
+   ask the user** for the library name and API details. Do not guess library names from chip or
+   sensor part numbers — boards with a known chip onboard may have a dedicated wrapper library
+   with a completely different name and API.
+
+2. **Library names come from `library.properties`, not from the repo name.** The GitHub repo name
+   and the Arduino/PlatformIO library name are often different (e.g. repo `Adafruit_AS7331` →
+   library `Adafruit AS7331 Library`). An agent once guessed `adafruit/Adafruit AS7331` for
+   `platformio.ini` and got `UnknownPackageError: Could not find the package`. The fix is simple:
+   in Step 0c, fetch the library's `library.properties` file and read its `name=` field. Use that
+   exact string everywhere — `platformio.ini` `lib_deps` and the firmware's `library.properties`
+   `depends=` line.
+
+3. **A 404 or failed fetch is a red flag, not an inconvenience to route around.** If any WebFetch,
+   curl, or gh API call for a library header, example sketch, .cpp file, or learn guide returns
+   a 404, timeout, or error: **immediately report the failure to the user** with the URL that
+   failed and what you were trying to find. Do not silently fall through to the next step. Do not
+   write driver code based on partial or unverified information. A 404 on an expected GitHub URL
+   often means the library doesn't exist, has a different repo name, or the file structure differs
+   from what you assumed. Any of these will produce a driver that doesn't compile.
+
+---
+
 Changes span **two repositories**:
 1. **Adafruit_Wippersnapper_Arduino** — C++ firmware: new driver + registration
 2. **Wippersnapper_Components** — JSON definition + product image
@@ -86,13 +120,66 @@ PRs to both repos run CI. Key checks to pass before submitting:
 
 ## Step 0 — Research the Sensor **MUST BE DONE BEFORE WRITING ANY CODE**
 
-Before writing any code, gather this information:
+Before writing any code, gather this information. Steps 0a–0c are **sequential gates** — each
+must succeed before moving to the next. If any gate fails, stop and ask the user.
+
+### 0a. Find the product page
+
+Search the web for "adafruit <SENSOR>" to find the product page. The product page
+(`https://www.adafruit.com/product/<PRODUCT_ID>`) html data has links to the learn guide (do not
+use the API or guess URLs). Use a tool like wget or curl:
+`curl -sL https://www.adafruit.com/product/5817 | grep "learn.adafruit.com"`
+(Replace `5817` with the actual product ID found via search.)
+
+**If this fails:** try WebSearch for "adafruit <SENSOR> site:adafruit.com". If you still can't
+find a product page, ask the user for the product URL or learn guide link.
+
+### 0b. Find and read the learn guide (GATE — cannot proceed without this)
+
+Extract the learn guide URL from the product page. Then fetch the **text view** version:
+`https://learn.adafruit.com/<guide-slug>.md?view=all`
+
+If the `.md?view=all` URL 404s, try:
+1. The HTML version: `https://learn.adafruit.com/<guide-slug>?view=all`
+2. WebSearch for `"learn.adafruit.com" "<SENSOR>"` to find the correct slug
+3. Ask the user
+
+From the learn guide, extract:
+- The **exact Arduino library name** from the `## Arduino` section
+- The **example code link** (usually a GitHub URL in the `## Example Code` section)
+- The **I2C address(es)**
+- What the sensor **measures** (map to subcomponent types)
+
+**If you cannot find or read the learn guide after trying all fallbacks above, STOP and ask the
+user.** Do not guess the library name from the sensor part number.
+
+### 0c. Confirm the library exists and get its exact registered name
+
+Verify the library by checking at least one of:
+- `gh search repos "<Library Name>" --owner adafruit`
+- WebFetch the library's GitHub page or header file
+- The library appears in the Arduino Library Manager
+
+**If the library cannot be found**, it may not be released yet, or it may have a different name
+than expected. Ask the user before proceeding.
+
+**Then, fetch the library's `library.properties` to get the exact registered name:**
+
+```bash
+gh api repos/adafruit/<Repo>/contents/library.properties --jq '.content' | base64 -d
+```
+
+Extract the `name=` value — this is the **canonical library name** used by both the Arduino
+Library Manager and PlatformIO registry. It often differs from the GitHub repo name (e.g. repo
+`Adafruit_AS7331` → library name `Adafruit AS7331 Library`; repo `Adafruit_TMP117` → library
+name `Adafruit TMP117`). Guessing the library name from the repo name will produce "package not
+found" build failures. Record this name and use it verbatim in Step 4 for both `platformio.ini`
+and the firmware's `library.properties`.
+
+### 0d. Gather remaining details
 
 | What | Where to look |
 |------|---------------|
-| Product page | Search the web for "adafruit <SENSOR>" to find the product page. The product page (`https://www.adafruit.com/product/<PRODUCT_ID>`) html data has links to the learn guide (do not use the API or guess URLs). Use a tool like wget or curl: `curl -sL https://www.adafruit.com/product/5817 \| grep "learn.adafruit.com"` (Note: replace `5817` with the actual product ID found via search). |
-| Learn guide | **Always read the learn guide before writing any code.** Fetch the text view `.md?view=all` version of the guide found on the product page (e.g., `curl -sL "https://learn.adafruit.com/<guide-slug>.md?view=all"`). The Arduino section (`## Arduino`) names the exact library to use. Do NOT skip this step even if you think you recognise a sub-component. There is also a `## Example Code` section showing the basic example sketch. |
-| Adafruit Arduino library | Named in the learn guide. Or: `gh search repos "<SENSOR>" --owner adafruit`. If no dedicated library from adafruit, check related chips (e.g. TMP119 lives inside `Adafruit_TMP117`). Try partial matches like `TMP11` if exact fails. Fall back to 3rd party or ask user. |
 | Library API | Read the library header on GitHub — find `begin()` signature and sensor read methods (`getEvent`, `readTempC`, etc.) |
 | I2C addresses | Sensor datasheet or Adafruit product page or learn guide or driver. Check https://learn.adafruit.com/i2c-addresses/the-list |
 | What it measures | Datasheet — map each reading to a subcomponent type (see table below) |
@@ -173,6 +260,13 @@ gh api repos/adafruit/<Library_Repo>/contents/examples --jq '.[].name'
    section usually contains example code link showing the exact API (or embedded code if non-markdown version).
 3. **Ask the user:** If tools are restricted, ask them to paste the library header and example.
 
+**If any fetch returns a 404 or error:** Do not silently move to the next fallback and then
+forget that all routes failed. If every fallback also fails, you have no verified API to code
+against. **Report all failed URLs to the user** and ask them to provide the example code or
+confirm the library repo name and structure. Writing driver code without having successfully
+read either the example sketch or the learn guide's embedded code is forbidden — you will
+produce code that calls methods which may not exist.
+
 From the example, extract the **exact method signatures** used:
 - `begin()` — what arguments, what return type
 - How readings are triggered (`getEvent()`, `readMeasurement()`, `measureSingleShot()`, etc.)
@@ -194,8 +288,13 @@ gh api repos/adafruit/<Library_Repo>/contents/<Library_Name>.h --jq '.content' |
 
 Or via WebFetch: `https://raw.githubusercontent.com/adafruit/<Library_Repo>/main/<Library_Name>.h`
 
-If GitHub is blocked, the learn guide `.md?view=all` may contain enough API detail from code
-snippets. If not, ask the user for the header content.
+**If this fetch 404s**, the repo name or header filename may differ from what you assumed. Try:
+1. List the repo contents: `gh api repos/adafruit/<Library_Repo>/contents --jq '.[].name'`
+2. WebFetch the repo's main page to find the actual header filename
+3. Fall back to the learn guide `.md?view=all` which may contain enough API detail from code snippets
+
+If none of these work, **ask the user for the header content.** Do not proceed to write the
+driver without having verified the actual method signatures.
 
 **Explicitly set every configuration parameter that the library defaults in `begin()`/`_init()`.**
 This pins behavior so library updates can't silently change WipperSnapper.
@@ -307,23 +406,28 @@ Wippersnapper_Components repo.
 
 Skip if the sensor class lives in an already-listed library (e.g. TMP119 in Adafruit_TMP117).
 
+**Use the exact `name=` value from the library's own `library.properties` that you fetched in
+Step 0c.** Do not construct the name from the GitHub repo name — they frequently differ
+(underscores vs spaces, trailing "Library" suffix, etc.) and a wrong name causes "package not
+found" build failures.
+
 ### 4a. platformio.ini
 
-Add to `[env]` `lib_deps` in **alphabetical order** ignoring any purpose specific sections of the lib_deps:
+Add to `[env]` `lib_deps` in **alphabetical order** ignoring any purpose specific sections of the lib_deps, using the
+`adafruit/<exact library.properties name>` format:
 ```ini
-    adafruit/Adafruit <Library Name>              # released Arduino library
-    https://github.com/<owner>/<repo>.git         # unreleased / third-party
+    adafruit/Adafruit <Exact Name From library.properties>   # released Arduino library
+    https://github.com/<owner>/<repo>.git                    # unreleased / third-party
 ```
 
 ### 4b. library.properties
 
-Add the library's **Arduino Library Manager name** to the comma-separated `depends=` line. This
-is the name as it appears in the Arduino IDE Library Manager + library.properties, not the GitHub repo name. Add it in
-a logical position among the existing entries.
+Add the **exact same `name=` value** to the comma-separated `depends=` line. Add it in a logical
+position among the existing entries.
 
-Example: to add a library called "Adafruit FooBar":
+Example: if the library's `library.properties` contains `name=Adafruit FooBar Library`:
 ```
-depends=..., Adafruit FooBar, ...
+depends=..., Adafruit FooBar Library, ...
 ```
 GitHub-only libraries can't go in `library.properties` — note this in the PR description (and advise to fork n release ardu lib).
 
@@ -538,7 +642,7 @@ protected:
 
   bool _readSensor() {
     unsigned long now = millis();
-    if (_lastRead != 0 && now - _lastRead < 1000)
+    if (_lastRead != 0 && now - _lastRead < ONE_SECOND_IN_MILLIS)
       return true; // recently read, use cached value
     if (!_tmp119->getEvent(&_cachedTemp))
       return false;

.agents/skills/add-sensor-component-v1/evals/evals.json

@@ -18,6 +18,18 @@
       "prompt": "Add the BMP581 barometric pressure sensor to WipperSnapper. It measures temperature, pressure, and altitude.",
       "expected_output": "Checks if driver already exists (BMP5XX covers BMP580/581/585), identifies the existing driver handles this, and advises that only a components definition may be needed if not already present.",
       "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "Add the AS7331 UV sensor to wippersnapper, publishing UVB as raw and debug-logging UVA/B/C on each read.",
+      "expected_output": "Finds the Adafruit product page, extracts the learn guide URL, reads the learn guide to confirm the library is 'Adafruit AS7331', fetches and reads the example sketch to learn the API (oneShot, readAllUV, etc.), then writes the driver. If any fetch 404s, reports the failure to the user instead of silently proceeding. Does NOT guess the GitHub URL or write code based on an unverified header file alone.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Let's add the STCC4 sensor to WipperSnapper. It has an SHT41 onboard.",
+      "expected_output": "Does NOT assume the library is Adafruit_SHT4X based on the SHT41 sub-component. Finds the product page, reads the learn guide, and discovers the correct library is 'Adafruit_STCC4' — a dedicated library. The learn guide is the source of truth for the library name, not chip sub-component names.",
+      "files": []
     }
   ]
 }

.gitignore

@@ -65,4 +65,5 @@ Doxyfile
 .repos/
 repos/
 Wippersnapper_Components/
-Wippersnapper_Boards/
+Wippersnapper_Boards/
+.claude/settings.local.json

agents.md

@@ -0,0 +1 @@
+Use skills in `./.agents/skills/`

claude.md

@@ -0,0 +1 @@
+See @agents.md

gemini.md

@@ -0,0 +1 @@
+See @agents.md

library.properties

@@ -1,10 +1,10 @@
 name=Adafruit WipperSnapper
-version=1.0.0-beta.125
+version=1.0.0-beta.126
 author=Adafruit
 maintainer=Adafruit <adafruitio@adafruit.com>
 sentence=Arduino application for Adafruit.io WipperSnapper
 paragraph=Arduino application for Adafruit.io WipperSnapper
 category=Communication
 url=https://github.com/adafruit/Adafruit_Wippersnapper_Arduino
 architectures=*
-depends=OmronD6T - Community Fork, SdFat - Adafruit Fork, Adafruit NeoPixel, Adafruit SPA06_003, Adafruit SPIFlash, ArduinoJson, Adafruit DotStar, Adafruit HDC302x, Adafruit INA219, Adafruit INA260 Library, Adafruit INA237 and INA238 Library, Adafruit LTR329 and LTR303, Adafruit LTR390 Library, Adafruit MCP3421, Adafruit MLX90632 Library, Adafruit NAU7802 Library, Adafruit SleepyDog Library, Adafruit TMP117, Adafruit TinyUSB Library, Adafruit AHTX0, Adafruit APDS9999, Adafruit AS5600 Library, Adafruit BME280 Library, Adafruit BMP280 Library, Adafruit BMP3XX Library, Adafruit BMP5xx Library, Adafruit DPS310, Adafruit DS248x, Adafruit SCD30, Adafruit SGP30 Sensor, Adafruit SGP40 Sensor, Adafruit SGP41, Sensirion I2C SCD4x, Sensirion I2C SEN5X, Sensirion I2C SEN66, arduino-sht, Adafruit Si7021 Library, Adafruit MQTT Library, Adafruit MS8607, Adafruit MCP9808 Library, Adafruit MCP9600 Library, Adafruit MPL115A2, Adafruit MPRLS Library, Adafruit TSL2591 Library, Adafruit_VL53L0X, Adafruit VL53L1X, STM32duino VL53L4CD, STM32duino VL53L4CX, Adafruit_VL6180X, Adafruit PM25 AQI Sensor, Adafruit QMC5883P Library, Adafruit VCNL4020 Library, Adafruit VCNL4040, Adafruit VCNL4200 Library, Adafruit VEML7700 Library, Adafruit LC709203F, Adafruit LPS2X, Adafruit LPS28, Adafruit LPS35HW, Adafruit seesaw Library, Adafruit BME680 Library, Adafruit MAX1704X, Adafruit ADT7410 Library, Adafruit HTS221, Adafruit HTU21DF Library, Adafruit HTU31D Library, Adafruit PCT2075, hp_BH1750, ENS160 - Adafruit Fork, Adafruit BusIO, Adafruit Unified Sensor, Sensirion Core, Adafruit GFX Library, Adafruit LED Backpack Library, Adafruit LiquidCrystal, Adafruit SH110X, Adafruit SSD1306, Adafruit EPD, Adafruit ST7735 and ST7789 Library
+depends=OmronD6T - Community Fork, SdFat - Adafruit Fork, Adafruit NeoPixel, Adafruit SPA06_003, Adafruit SPIFlash, ArduinoJson, Adafruit DotStar, Adafruit HDC302x, Adafruit INA219, Adafruit INA260 Library, Adafruit INA237 and INA238 Library, Adafruit LTR329 and LTR303, Adafruit LTR390 Library, Adafruit MCP3421, Adafruit MLX90632 Library, Adafruit NAU7802 Library, Adafruit SleepyDog Library, Adafruit TMP117, Adafruit TinyUSB Library, Adafruit AHTX0, Adafruit APDS9999, Adafruit AS5600 Library, Adafruit AS7331 Library, Adafruit BME280 Library, Adafruit BMP280 Library, Adafruit BMP3XX Library, Adafruit BMP5xx Library, Adafruit DPS310, Adafruit DS248x, Adafruit SCD30, Adafruit SGP30 Sensor, Adafruit SGP40 Sensor, Adafruit SGP41, Sensirion I2C SCD4x, Sensirion I2C SEN5X, Sensirion I2C SEN66, arduino-sht, Adafruit Si7021 Library, Adafruit MQTT Library, Adafruit MS8607, Adafruit MCP9808 Library, Adafruit MCP9600 Library, Adafruit MPL115A2, Adafruit MPRLS Library, Adafruit TSL2591 Library, Adafruit_VL53L0X, Adafruit VL53L1X, STM32duino VL53L4CD, STM32duino VL53L4CX, Adafruit_VL6180X, Adafruit PM25 AQI Sensor, Adafruit QMC5883P Library, Adafruit VCNL4020 Library, Adafruit VCNL4040, Adafruit VCNL4200 Library, Adafruit VEML7700 Library, Adafruit LC709203F, Adafruit LPS2X, Adafruit LPS28, Adafruit LPS35HW, Adafruit seesaw Library, Adafruit BME680 Library, Adafruit MAX1704X, Adafruit ADT7410 Library, Adafruit HTS221, Adafruit HTU21DF Library, Adafruit HTU31D Library, Adafruit PCT2075, hp_BH1750, ENS160 - Adafruit Fork, Adafruit BusIO, Adafruit Unified Sensor, Sensirion Core, Adafruit GFX Library, Adafruit LED Backpack Library, Adafruit LiquidCrystal, Adafruit SH110X, Adafruit SSD1306, Adafruit EPD, Adafruit ST7735 and ST7789 Library

opencode.md

@@ -0,0 +1 @@
+See @agents.md

platformio.ini

@@ -25,6 +25,7 @@ lib_deps =
     adafruit/Adafruit AHTX0
     adafruit/Adafruit APDS9999
     adafruit/Adafruit AS5600 Library
+    adafruit/Adafruit AS7331 Library
     adafruit/Adafruit BME280 Library
     adafruit/Adafruit BMP280 Library
     adafruit/Adafruit BMP3XX Library

src/Wippersnapper.h

@@ -167,7 +167,7 @@
 #endif
 
 #define WS_VERSION                                                             \
-  "1.0.0-beta.125" ///< WipperSnapper app. version (semver-formatted)
+  "1.0.0-beta.126" ///< WipperSnapper app. version (semver-formatted)
 
 // Reserved Adafruit IO MQTT topics
 #define TOPIC_IO_THROTTLE "/throttle" ///< Adafruit IO Throttle MQTT Topic