Skip to content

Commit f5ae46c

Browse files
committed
fix(skill): Add mandatory steps in add_sensor_component_v1
1 parent 3e96525 commit f5ae46c

File tree

1 file changed

+30
-17
lines changed
  • .agents/skills/add_sensor_component_v1

1 file changed

+30
-17
lines changed

.agents/skills/add_sensor_component_v1/SKILL.md

Lines changed: 30 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -141,33 +141,46 @@ where both °C and °F subcomponents are enabled.
141141

142142
**File:** `src/components/i2c/drivers/WipperSnapper_I2C_Driver_<SENSOR>.h`
143143

144-
### First: Read the library's example sketch
144+
### First: Read the library's example sketch — MANDATORY before writing any code
145145

146-
Before writing any driver code, find and read the library's `simpletest` or `basic_test` or some example not using interrupts (data ready flags are okay)
146+
**Do NOT assume the library API based on other sensors.** Every library is different. You must
147+
read the actual example code to know the real API. Guessing from similar sensors (e.g. assuming
148+
SCD30-style `getEvent()` for an STCC4) will produce a driver that does not compile.
149+
150+
Before writing any driver code, find and read the library's `simple test` or `basic_usage` or all examples not using interrupts (data ready flags are okay)
147151
on GitHub. Check all matches for suitable usage suggestions. This is your source of truth for how the sensor is meant to be used:
148152

149153
```bash
150154
gh api repos/adafruit/<Library_Repo>/contents/examples --jq '.[].name'
151-
# then read the relevant .ino file
155+
# then read the .ino file for the simpletest/basic_test/singleshot example
152156
```
153157

154-
Study the example for:
155-
- Which `begin()` overload is used and what arguments it takes
156-
- Any setup calls after `begin()` (mode, averaging, resolution, range, etc.)
157-
- Whether `dataReady()` is polled before reading
158-
- How readings are obtained (`getEvent()` vs `readTempC()` vs `read()` etc.)
159-
- Any delays or timing requirements
158+
If `gh`/Bash is unavailable, use WebFetch on the raw GitHub URL:
159+
`https://raw.githubusercontent.com/adafruit/<Library_Repo>/main/examples/<example>/<example>.ino` (you may need to access the web version to view default branch andexample related folder structure).
160+
161+
From the example, extract the **exact method signatures** used:
162+
- `begin()` — what arguments, what return type
163+
- How readings are triggered (`getEvent()`, `readMeasurement()`, `measureSingleShot()`, etc.)
164+
- What the return values look like (Unified Sensor `sensors_event_t`? Raw floats? uint16_t pointers?)
165+
- Any required setup calls (continuous mode, conditioning, etc.)
166+
- Any delays or polling (`dataReady()`, fixed delays between reads)
167+
168+
### Then: Read the library header — MANDATORY
160169

161-
### Then: Read the library's source code
170+
Read the `.h` file to see **all public methods and their exact signatures**. This is essential
171+
because:
172+
- The example may only show one usage pattern; the header shows everything available
173+
- You need the exact types (float vs uint16_t, pointer args vs return values)
174+
- You need to identify default configuration set in `begin()`/`_init()`
175+
176+
```bash
177+
gh api repos/adafruit/<Library_Repo>/contents/<Library_Name>.h --jq '.content' | base64 -d
178+
```
162179

163-
Also read the library's `begin()` / `_init()` implementation to see what default configuration
164-
it applies — measurement mode, averaging count, resolution, conversion time, etc. These defaults
165-
are often not visible in the example sketch but they affect sensor behavior. If a future library
166-
update changes any of these defaults, it would silently change WipperSnapper's behavior too.
180+
Or via WebFetch: `https://raw.githubusercontent.com/adafruit/<Library_Repo>/main/<Library_Name>.h`
167181

168-
When writing the WipperSnapper driver, **explicitly set every configuration parameter that the
169-
library sets as a default in its `begin()` or `_init()`** chain. This pins the behavior so that library
170-
updates cannot break WipperSnapper without a deliberate driver change on our side.
182+
**Explicitly set every configuration parameter that the library defaults in `begin()`/`_init()`.**
183+
This pins behavior so library updates can't silently change WipperSnapper.
171184

172185
For example, if the library's `_init()` sets continuous mode with 8x averaging as defaults:
173186
```cpp

0 commit comments

Comments
 (0)