diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 518df79..f12609f 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -383,6 +383,15 @@ "strict": false, "description": "Optimize and build programmatic prompt systems with Stanford DSPy. Signatures, modules (Predict, ChainOfThought, ReAct), optimizer/teleprompter selection, compilation, caching, evaluation. Use when doing programmatic prompt optimization or building compiled prompt programs. Do not use this skill for unrelated requests; route to the nearest named specialist." }, + { + "name": "electronics", + "source": "./", + "skills": [ + "./electronics" + ], + "strict": false, + "description": "Design, review, prototype, measure, and troubleshoot electronic circuits using component evidence, worst-case calculations, interface contracts, and staged bench verification. Use for component selection, analog or digital building blocks, power and protection, sensor conditioning, schematic-to-wiring review, instrumented diagnosis, and I2C electrical integration. Do not use as a substitute for exact device documentation, ESP32 firmware operations, FPGA RTL development, named CAD-tool operation, or regulated design certification." + }, { "name": "email", "source": "./", diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 10ce227..ec678a8 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -60,6 +60,7 @@ "./documents", "./dsm5", "./dspy", + "./electronics", "./email", "./enterprise-architecture", "./epub", diff --git a/README.md b/README.md index c63e084..180b4c1 100644 --- a/README.md +++ b/README.md @@ -172,6 +172,10 @@ Assess and explain mental health and neurocognitive questions against DSM-5-TR d An expert-level skill for **programmatic prompt optimization** with Stanford's DSPy framework. You write Python programs with typed signatures; DSPy optimizes the prompts automatically. This is the framework for prompt engineering that doesn't feel like engineering. +### [electronics](electronics/SKILL.md) + +Design, review and troubleshoot electronic circuits with component evidence, worst-case calculations, interface contracts and staged bench verification. Includes detailed references and reusable design, calibration, measurement and fault-isolation templates. + ### [email](email/SKILL.md) Send and diagnose transactional email through Twilio SendGrid: send with `--dry-run`/`--yes` confirmation, check deliverability (bounces and spam reports), and verify Signed Event Webhook signatures with a self-contained ECDSA P-256 verifier. Ships a bounded stdlib CLI with `--json` and `--limit`. diff --git a/electronics/README.md b/electronics/README.md new file mode 100644 index 0000000..f2681b1 --- /dev/null +++ b/electronics/README.md @@ -0,0 +1,35 @@ +# Electronics + +Design, review and troubleshoot circuits with calculations and measurements you can defend. + +## Why Install This Skill + +A circuit can look correct and still fail because a component is loaded differently than expected, a sensor saturates, a supply overheats or a probe changes the signal. This skill helps your agent connect component specifications, circuit models, physical assembly and measured behavior into one engineering decision. + +It provides detailed references and reusable worksheets for selecting parts, bounding errors, reviewing power and protection, integrating sensors, diagnosing I2C and planning bench tests. You get concrete review artifacts and explicit evidence gaps, with ESP32 firmware work kept in its existing specialist skill. + +## What You Get + +| Contents | Purpose | +|---|---| +| `SKILL.md` | Task selection and the design-to-verification workflow | +| `references/` | Ten detailed guides for components, calculations, circuits, power, sensors, I2C, assembly and measurement | +| `templates/` | Eight reusable component, calculation, calibration, wiring, bus, measurement, fault and acceptance records | +| `evals/` | Eight output-quality scenarios covering calculations, uncertain evidence and diagnosis | + +## Quick Start + +Provide the schematic, exact component identities and the decision you need. Ask for a component contract, calculation record or measurement plan; the templates work without installing a toolchain. + +## Triggers + +- Review a schematic, component substitution or electrical interface. +- Calculate worst-case error, loading, power or thermal margin. +- Integrate sensors or diagnose an intermittent I2C bus. +- Plan bench measurements, localize a fault or verify an assembly. + +Try: “Review this divider against the ADC input limit, including resistor tolerances and loading, and produce a calculation record.” + +## Requirements + +Reading and planning require no installed tools. Device-specific decisions require the exact datasheets, schematics and operating requirements. Physical verification requires appropriate instruments, target access and a safe measurement setup. This skill does not provide certification or replace specialized high-energy, RF or high-speed design review. diff --git a/electronics/SKILL.md b/electronics/SKILL.md new file mode 100644 index 0000000..34541b6 --- /dev/null +++ b/electronics/SKILL.md @@ -0,0 +1,88 @@ +--- +name: electronics +description: >- + Design, review, prototype, measure, and troubleshoot electronic circuits using component evidence, worst-case calculations, interface contracts, and staged bench verification. Use for component selection, analog or digital building blocks, power and protection, sensor conditioning, schematic-to-wiring review, instrumented diagnosis, and I2C electrical integration. Do not use as a substitute for exact device documentation, ESP32 firmware operations, FPGA RTL development, named CAD-tool operation, or regulated design certification. +license: MIT +--- + +# Electronics + +Turn a desired physical behavior into a justified circuit and an observable verification result. Treat the schematic, components, layout, power source, load, measurement setup, and environment as one system. A plausible schematic or successful simulation is an intermediate artifact, not proof of a working assembly. + +## Working contract + +1. Identify the requested decision: explain, calculate, select, review, diagnose, build, or verify. Produce the artifact needed for that decision; do not demand a full design dossier for a bounded calculation. +2. Record exact component and board identities when device-specific claims matter. Use the manufacturer datasheet revision, package and operating conditions. Separate recommended operation, absolute maximum, typical performance, guaranteed bounds and measured behavior. +3. Model the relevant signal, power, timing and thermal paths. State units, sign conventions, assumptions and corners. Compute a useful conditional result from supplied hypothetical inputs; do not invent missing measurements or guaranteed ratings. +4. Define acceptance before experimentation. Each measurement needs a predicted value/range, instrument configuration, validity limits and a decision it will resolve. +5. Change one explanatory variable at a time when feasible. Preserve the initial symptom and distinguish observation from hypothesis and inference. +6. Before changing wiring, applying power, driving signals or operating connected equipment, confirm the target, scope, and rollback path before acting. Read-only discovery may proceed without confirmation. Obtain the measurement and recovery plan appropriate to the actual energy and fault paths. +7. Stop if the next action exceeds verified device, instrument or isolation limits. Missing high-risk facts require a bounded evidence request, not a guessed command or connection. + +## Route the work + +Load only the references needed for the current decision. Each reference contains assumptions, worked reasoning, failure patterns and acceptance guidance; templates turn that reasoning into reviewable artifacts. + +| Task | Reference | Artifact | +|---|---|---| +| Choose or replace a component | [Component selection](references/component-selection.md) | [Component contract](templates/component-contract.md) | +| Bound a ratio, threshold, accuracy or loading error | [Tolerance and error budgets](references/tolerances-and-error-budgets.md) | [Calculation record](templates/design-calculation-record.md) | +| Review a supply, switch, driver, clamp or heat problem | [Power, thermal and protection](references/power-thermal-and-protection.md) | Component contract and calculation record | +| Review amplification, thresholds, logic and interface behavior | [Analog and digital building blocks](references/analog-and-digital-building-blocks.md) | Component contract | +| Integrate or calibrate a sensor | [Sensors and conditioning](references/sensors-and-conditioning.md) | [Calibration plan](templates/sensor-calibration-plan.md) | +| Translate a schematic into physical connections | [Schematic to bench](references/schematic-to-bench.md) | [Schematic review](templates/schematic-review.md) | +| Choose or interpret a measurement | [Measurement and instrumentation](references/measurement-and-instrumentation.md) | [Measurement plan](templates/measurement-plan.md) | +| Review I2C electrical behavior and transaction evidence | [I2C integration](references/i2c-integration.md) | [Bus electrical budget](templates/bus-electrical-budget.md) | +| Localize a fault | [Fault isolation](references/fault-isolation.md) | [Fault ledger](templates/fault-ledger.md) | +| Accept an assembly and its observed behavior | [Assembly and verification](references/assembly-and-verification.md) | [Assembly acceptance](templates/assembly-acceptance.md) | + +## Default engineering sequence + +### 1. Establish function and boundaries + +Record what the circuit must do and what failure would mean. Identify supplies, loads, signal ranges, timing or bandwidth, duty cycle, environment, allowable error and operating modes. Distinguish a component, a module with additional circuitry, and a complete board. A photograph can suggest identity but cannot establish pinout, rating, isolation or health. + +Request only missing inputs that affect the decision. Label each as blocking, useful for confidence, or unnecessary for the current calculation. If specifications conflict, surface the conflict and present feasible changes rather than selecting a nominal compromise silently. + +### 2. Build the model and compare corners + +Use the actual topology. Include parallel paths, source/load impedance, bias/leakage, power-up states and temperature dependencies where material. State whether an error budget is a guaranteed bound or a statistical estimate and why the combination method is valid. Do not combine correlated systematic errors as independent noise. + +Evaluate component and instrument limitations together. A meter or probe changes the circuit it observes. A low DC error does not establish settling, stability, bandwidth or noise performance. A protection device must survive the relevant fault waveform and leave the protected device inside its own limits. + +Record the controlling corner and margin, then identify assumptions whose uncertainty could reverse the decision. Prefer a simple independently checked model over an elaborate simulation with undocumented component models. + +### 3. Review physical implementation + +Trace current loops, return paths, polarity, reference nodes, connectors and power sequencing. Check schematic connectivity against the real breadboard or assembly. Identify paths that can back-power an unpowered device. Separate board logic pins from load power paths; driver and protection choices depend on the actual load and fault conditions. + +Do not treat generic layout advice as a verified PCB design. Trace the relevant coupling or current-return mechanism, consult the actual component's guidance, and specify how the proposed arrangement will be tested. + +### 4. Plan and perform bounded verification + +Start with appropriate unpowered inspection and continuity/resistance checks, then controlled power and progressively enabled functions. Meter mode, lead jack, probe rating, reference connection and energy source must be correct for the measurement. A current limit is not a substitute for understanding stored energy or the instrument grounding path. + +For connected hardware, retain target identity, instrument configuration, initial state, expected result, observation and restoration steps. A bus scan is an active transaction and may change a device; an ACK is not an identity or functional test. + +### 5. Decide and retain evidence + +Conclude with one of: accepted for the stated conditions; rejected with the controlling failure; conditionally acceptable under named assumptions; or inconclusive with the smallest decisive next test. Separate modeled, simulated and physically measured evidence. Record design/firmware revision when software affects the circuit. + +For a measurement diagnosis, include a compact evidence row even in a short +answer: quantity/test point, stated instrument configuration, model prediction, +reported observation, interpretation and next check. Mark supplied readings as +user-reported and unperformed measurements as planned; do not turn a prediction +into a claimed observation. Use the measurement template for larger tasks. + +For troubleshooting, stop after three non-converging passes and summarize the evidence, eliminated hypotheses, remaining uncertainty and next specialist or artifact needed. Do not keep swapping components or repeating scans without a new hypothesis. + +## When not to use + +- For ESP32 board identification, pin restrictions, firmware frameworks, flashing, boot/recovery or OTA, use the repository's `esp32-development` skill. This skill still owns the electrical model and measurement reasoning for the attached circuit; do not duplicate framework instructions here. +- For programmable-logic architecture, RTL, simulation, synthesis or timing closure, use an available FPGA discipline skill. Electrical compatibility remains part of this skill's scope. +- For a named CAD, simulator, programmer or instrument automation system, consult its exact tool documentation or existing operational skill. Do not invent nonexistent catalog routes. +- Mains, high energy, RF/high-speed layout, functional safety, medical or other regulated acceptance requires the appropriate specialist evidence and review. This skill can organize requirements and evidence; it cannot confer certification or replace those disciplines. + +## Completion criteria + +The requested decision has a concrete artifact; assumptions and unknowns are visible; calculations and units are reproducible; chosen operating conditions are justified; relevant measurements or outstanding tests are recorded; and the conclusion matches the strength and scope of the evidence. An analysis task can finish with a sound conditional result. A hardware verification task cannot finish on calculation or simulation alone. diff --git a/electronics/evals/evals.json b/electronics/evals/evals.json new file mode 100644 index 0000000..6988fa6 --- /dev/null +++ b/electronics/evals/evals.json @@ -0,0 +1,97 @@ +{ + "schema_version": 1, + "skill_name": "electronics", + "evals": [ + { + "id": "divider-loading-corners", + "prompt": "Review a DC monitor: supply 12 V \u00b15%, upper resistor 100 kohm \u00b11%, lower 33 kohm \u00b11%, ADC input modeled as 1 Mohm to ground, allowed ADC voltage 0\u20133.0 V. Ignore leakage and dynamic sampling for this first calculation. Is it acceptable? Show the worst-case result and what remains before release.", + "expected_output": "Loaded divider interval calculation and a rejected unsafe corner with follow-on dynamic checks.", + "assertions": [ + "Uses lower resistor parallel with 1 Mohm, not an unloaded divider.", + "Computes upper output corner approximately 3.10 V (\u00b10.02 V) using supply high, upper resistor low, lower resistor high.", + "Rejects the design against 3.0 V rather than accepting nominal behavior.", + "Separates this static model from acquisition-time, input protection, leakage and reference checks." + ] + }, + { + "id": "i2c-no-feasible-pullup", + "prompt": "A hypothetical open-drain bus has Vpullup=3.3 V, guaranteed VOL\u22640.4 V at 2 mA, measured total capacitance 450 pF, and required 30\u201370% rise time\u2264300 ns. Existing pull-ups are two 4.7 kohm resistors in parallel per line. Use tr=0.8473RC. Decide whether changing the resistor alone can meet both requirements and propose a verification plan.", + "expected_output": "Shows incompatible pull-up bounds and changes the bus design.", + "assertions": [ + "Calculates effective existing resistance2350 ohm and rise time about896 ns.", + "Calculates lower bound1450 ohm and upper boundabout787 ohm.", + "States no passive resistor value meets both constraints.", + "Proposes reducing capacitance/segmentation or changing supported operating mode rather than arbitrarily stronger pullups.", + "Requires checking actual VOL/rise time at relevant endpoints and device capabilities." + ] + }, + { + "id": "power-thermal-model", + "prompt": "A linear regulator drops 9 V to3.3 V at180 mA. Ignore quiescent current. Ambient55 C, claimed thetaJA85 C/W from a datasheet test board, maximum junction125 C. Our board copper differs. Review the thermal claim and next action.", + "expected_output": "Compute first-order risk without claiming exact target temperature.", + "assertions": [ + "Computes loss1.026 W and estimated junctionabout142 C under the stated model.", + "Rejects thermal acceptance under the stated assumptions.", + "Explains thetaJA depends on board/environment and is not a universal device constant.", + "Proposes changing dissipation/thermal path and verifying target-board temperature with an appropriate model/measurement." + ] + }, + { + "id": "measurement-loading", + "prompt": "A1.0 V ideal source feeds a node through1 Mohm. The node is measured using a10 Mohm DMM and readsabout0.91 V. A colleague calls the source defective. Write a short diagnosis, calculation and next measurement.", + "expected_output": "Identifies instrument loading and distinguishes observations from fault.", + "assertions": [ + "Calculates1*10/(1+10)=about0.909 V.", + "Explains reading is consistent with loading, not evidence source defective.", + "Selects a measurement that isolates source behavior from the loading artifact—such as a higher-input-impedance measurement, justified buffer, or source-side measurement—and checks relevant instrument/input errors.", + "Records probe/meter configuration and preserves expected-versus-observed values." + ] + }, + { + "id": "sensor-calibration-holdout", + "prompt": "A pressure sensor calibration uses five increasing-pressure points and fits a cubic with nearly zero residual. No decreasing sweep, temperature variation or independent check points were collected. Can we claim0.1% accuracy across the rated temperature range? Draft a validation plan.", + "expected_output": "Reject unsupported accuracy while producing a usable calibration validation plan.", + "assertions": [ + "Does not equate training-fit residual with accuracy.", + "Separates reference uncertainty, repeatability, hysteresis, drift and temperature effects.", + "Requires independent validation points and both increasing/decreasing sweeps.", + "Defines acceptance from requirements and avoids inventing0.1% evidence or arbitrary universal sample counts." + ] + }, + { + "id": "i2c-scan-and-recovery", + "prompt": "A shared controller bus returned an ACK at0x48 yesterday. Today SDA is low and SCL is high. A teammate wants repeated address scans and nine clock pulses while another controller remains active. Device model unknown. Give a bounded diagnostic/recovery decision.", + "expected_output": "Avoids scan-as-identity and uncontrolled bus recovery.", + "assertions": [ + "Distinguishes ACK from exact device identity or correct register behavior.", + "Recognizes scanning can have side effects and is not purely passive.", + "Requires ownership/quiescence of all controllers before attempting recovery.", + "Distinguishes SDA-stuck recovery from SCL held low; conditions clock pulses on actual line release and documented device behavior.", + "Escalates to exact device reset/power recovery only with state/recovery implications understood." + ] + }, + { + "id": "analog-settling", + "prompt": "An op amp described as rail-to-rail drives an ADC through a cable. DC voltage is plausible but conversions alternate and the scope shows ringing. We know neither op amp part nor ADC acquisition timing. Propose the minimum useful evidence and an ordered diagnosis; do not select component values yet.", + "expected_output": "Prioritizes source/load/acquisition and stability evidence.", + "assertions": [ + "Requests exact amplifier and ADC specifications plus source/load/cable and sampling context.", + "Checks common-mode/output swing under actual load instead of assuming rail-to-rail means unlimited operation.", + "Distinguishes capacitive-load stability from ADC acquisition settling and aliasing.", + "Does not prescribe arbitrary resistor/capacitor values; proposes decisive waveform/capture observations." + ] + }, + { + "id": "schematic-to-bench", + "prompt": "I have a battery-powered low-voltage prototype with a transistor switching an inductive load. Only a photo and a handwritten transistor label are available. Prepare a build-review artifact before power-up, including the information you need, checks, and exit criteria.", + "expected_output": "Concrete evidence-based build review without invented pins/ratings.", + "assertions": [ + "Requests exact transistor/load/supply identity and verified pinout/schematic.", + "Includes driver state, load current/inrush, inductive energy/clamp path and device ratings.", + "Defines unpowered wiring/polarity/short checks and controlled staged power-up with stated criteria.", + "Does not infer safe pinout/current rating from appearance or label alone.", + "Produces an actionable review/measurement record, not only a list of warnings." + ] + } + ] +} diff --git a/electronics/references/analog-and-digital-building-blocks.md b/electronics/references/analog-and-digital-building-blocks.md new file mode 100644 index 0000000..90a7f50 --- /dev/null +++ b/electronics/references/analog-and-digital-building-blocks.md @@ -0,0 +1,54 @@ +# Analog and digital building blocks + +## Input and output legality + +For an op amp, comparator, reference, logic IC, timer, or converter, check input common-mode range, differential input limit, bias/leakage, output swing at the real load, output current, supply headroom, startup state, overload recovery, timing, noise, and temperature guarantees. “Rail-to-rail” describes a region or condition, not an exact rail voltage at arbitrary current and frequency. + +A comparator and op amp may share a schematic symbol but differ in output topology, input protection, propagation behavior, recovery, and stability. Select by required threshold behavior and output interface, not symbol. + +## Feedback and stability + +Identify the feedback factor, noise gain, source impedance, input capacitance, output capacitance, cable, ADC sample capacitor, protection network, and load. Simulate the actual network, then test a populated board with step response, load transients, and supply corners. TI's [stability theory note](https://e2e.ti.com/cfs-file/__key/communityserver-discussions-components-files/14/SBOA626_2D00_stability_2D00_9_2D00_16_2D00_2025.pdf) and [capacitive-load article](https://www.ti.com/document-viewer/lit/html/SSZT999) document ringing, long settling, and oscillation from added poles and phase-margin loss. Applicability: TI amplifier methods; use the exact amplifier stability specification. + +An isolation resistor can decouple an op-amp output from capacitance, but it also creates an RC pole with the load and may change settling, current limit, and filter response. Record its value, load range, capacitor bias dependence, and worst-case step response. Do not “fix” oscillation by adding arbitrary capacitance to a feedback node. + +## Threshold design + +Define rising and falling thresholds, reference source and tolerance, noise band, hysteresis, propagation delay, pull-up/pull-down, output load, and supply-ramp behavior. TI's [comparators with hysteresis](https://www.ti.com/lit/an/snoa654a/snoa654a.pdf) explains the risk of a slowly changing input lingering in a high-gain transition region. Hysteresis, filtering, and firmware debounce solve different problems. + +### Original threshold example + +A 0–3.3 V sensor should assert at 2.10 V and deassert at 1.95 V. The 150 mV gap is a system requirement, not automatically a resistor value. Allocate reference error, divider tolerance, input offset, input noise, and temperature drift first. If their worst-case sum consumes 120 mV, only 30 mV remains for switching uncertainty; redesign the reference or thresholds before implementing positive feedback. Verify both transitions with a slow ramp and injected noise, plus power-up and sensor-disconnect tests. + +## ADC and digital boundaries + +Check source impedance against acquisition time, anti-alias filter loading, reference drive and decoupling, grounding, return currents, clock coupling, code width, missing codes, and sample timing. Microchip [AN688](https://www.microchip.com/en-us/application-notes/an688) states that ADC layout depends on the complete system and environment. Analog Devices [MT-031](https://www.analog.com/MT-031) covers mixed-signal grounding, routing, and decoupling. These are general guidance; the converter's datasheet and evaluation board take precedence. + +For logic, verify VIH/VIL at the receiver's supply and temperature, VOH/VOL at the actual load, edge rate, pull resistor current, boot-state contention, and level translation. A nominal “3.3 V logic” label does not prove compatibility across families. + +## Failure signatures + +| Observation | Candidate causes | Check | +|---|---|---| +| ringing after edges | phase margin, cable/load capacitance | isolate load; measure step | +| threshold chatter | hysteresis, noise, reference coupling | slow ramp with injected noise | +| codes wrong only with firmware | digital return or sampling coupling | quiet-clock capture | +| output misses rail | load current or topology | sweep load and inspect limits | +| slow overload recovery | saturation or protection conduction | measure recovery | + +An inverting stage with `Rin=12 kΩ` and `Rf=180 kΩ` has ideal gain `-15`. A forgotten 3 kΩ source resistance changes it to `-12`, before tolerance, bias, and finite open-loop effects. Redraw source impedance and recompute noise gain, bandwidth, and stability. For counters, shift registers, timers, and displays, record clock tolerance, setup/hold, propagation delay, reset release, metastability exposure, output enable, and power-up state; validate voltage and temperature corners. + +## Verification output + +Return a legal operating region, worst-case threshold or gain, stability evidence, interface timing, measurement setup, and any unknowns. A simulation that omits package, cable, ADC sampling, or load capacitance is a hypothesis, not proof. +## Noise gain and settling + +For an op amp, noise gain is determined by the feedback network even when signal gain is different. Use noise gain for stability, input voltage-noise contribution, and bandwidth. Check settling to the required error band after a full-scale step; a small-signal bandwidth number does not prove settling. + +## Comparator rejection + +Reject a comparator topology when its input range, output pull-up, propagation delay, or hysteresis is unspecified at the real supply. Test a slow ramp, noisy ramp, fast overdrive, input disconnect, and supply ramp. Record both threshold directions and output state when unpowered. + +## Digital evidence + +A logic analyzer can miss analog ringing and marginal VIH/VIL. Pair protocol decoding with oscilloscope voltage at the receiver pin and current in the return path. diff --git a/electronics/references/assembly-and-verification.md b/electronics/references/assembly-and-verification.md new file mode 100644 index 0000000..17507d2 --- /dev/null +++ b/electronics/references/assembly-and-verification.md @@ -0,0 +1,67 @@ +# Assembly and verification + +Acceptance is a chain from physical workmanship to observed behavior. + +## Unpowered inspection + +Inspect orientation, reference designators, solder bridges, wetting, lifted +pads, connector seating, strain relief, and selectable pull-ups/address links. +Check intended continuity and rail-to-rail/signal shorts with power removed; +discharge capacitors first. Compare the assembly against the current BOM, +schematic, layout, and assembly revision. Photograph or annotate anomalies. + +## Controlled first power + +Use a current-limited source when appropriate. Start with loads disabled and +measure rail voltage, startup/steady current, reset behavior, and temperature. +Add peripherals and outputs one at a time. Verify idle levels before enabling +drivers. A current limit is a protective aid, not a replacement for a supply +budget or fault analysis. + +## Functional acceptance + +Require an identity-level check for each bus device, a known input/output +response, and documented reset and power-cycle behavior. For I2C, retain the +raw capture or transaction log, address convention, measured rise time, +effective pull-up, and recovery result. For analog or timed behavior, record +calibration/reference, sample conditions, tolerance, and measurement setup. + +Repeat critical tests after mechanical handling and any relevant thermal or +power condition. Record exact board/component/firmware revisions and every +open risk. “It worked once” is not an acceptance criterion. + +| Failure at acceptance | Containment | Evidence needed before release | +|---|---|---| +| Rail short or excess startup current | power off; isolate branch; inspect orientation/bridges | corrected inspection and current trace | +| Correct rail, wrong idle state | disable load; check reset pulls and external straps | schematic-to-measured state comparison | +| Bus responds but identity fails | stop application writes; preserve raw capture | documented identity read and address convention | +| Intermittent after handling | repeat visual/continuity and capture under movement | reproducible mechanical condition or closure | +| Recovery leaves line low | keep controller quiescent; reset/power-cycle holder | before/after line capture and owner | + +Release requires a named disposition for every failure: fixed and retested, +accepted with an explicitly bounded risk, or blocked pending an artifact or +measurement. A passing functional test cannot waive an unresolved electrical +limit. + +The acceptance artifact is complete when another operator can reproduce the +test, distinguish design evidence from instrument setup, and see the rollback +or recovery path for every state-changing test. + +## Acceptance stage record + +At inspection, record component reference, defect class, image identifier, and +disposition. At unpowered test, record meter mode, lead resistance, test points, +and measured values; a continuity beep alone is insufficient. At first power, +record current-limit setting, source voltage, startup peak, steady current, +rail ripple, reset reason, and temperature. At functional test, record stimulus, +expected response, actual response, repeat count, and environmental condition. + +For a soldered I2C connector, visual inspection may show correct pin placement, +while end-to-end resistance proves only a low-current path. Far-end idle voltage, +rise time with the actual probe, and identity readback establish separate facts. +If those disagree, retain all results and localize the defect instead of marking +the connector “passed.” + +Release is a disposition, not a checkbox: passed and repeatable, accepted with +an explicitly bounded risk and owner, or blocked pending evidence. Rework must +repeat the tests affected by the rework. diff --git a/electronics/references/component-selection.md b/electronics/references/component-selection.md new file mode 100644 index 0000000..347c78b --- /dev/null +++ b/electronics/references/component-selection.md @@ -0,0 +1,87 @@ +# Component selection + +## Start with the job + +Translate the request into an observable behavior before naming a part. + +| Question | Required record | +|---|---| +| What crosses the boundary? | Voltage, current, force, temperature, light, sound, position, data, or energy | +| What are the corners? | Minimum, nominal, maximum, transients, fault states, temperature, supply | +| What must be guaranteed? | Accuracy, latency, ripple, lifetime, noise, efficiency, safety, availability | +| What constrains implementation? | Package, assembly, PCB area, isolation, firmware, cost, sourcing | + +“Use a transistor” is not a requirement. Identify switching versus amplification, high-side versus low-side, linear versus switched operation, and whether the device must fail open, fail safe, or remain isolated. + +## Evidence ladder + +1. Identify the exact ordering code, package, revision, qualification, and lifecycle status. +2. Retrieve the current manufacturer datasheet and applicable application note. +3. Separate absolute maximum, recommended operation, guaranteed electrical characteristics, typical curves, and marketing claims. +4. Read pinout, truth tables, timing, startup, shutdown, thermal, layout, and errata sections. +5. Check the actual schematic, load, source impedance, cable, connector, board, and software assumptions. +6. Mark every unverified value `UNKNOWN`; do not fill gaps with a family-level typical. + +Distributor pages and breakout-board labels are discovery aids. They do not establish pin compatibility, current rating, thermal performance, or safe operating area. + +## Requirements matrix + +For each candidate, maintain one row per requirement and one column for evidence, corner, calculated result, margin, and verification method. Reject a candidate when a required value is unavailable, out of range, or only typical where a guarantee is required. Record the controlling corner rather than only a nominal pass. + +Useful screening columns include: + +- input/output range and polarity; +- DC, RMS, peak, surge, and inrush current; +- frequency, edge rate, duty cycle, and timing tolerance; +- common-mode range, input/output impedance, leakage, and loading; +- efficiency, dissipation, junction-to-ambient or board thermal path; +- protection thresholds and fault energy; +- package, pinout, exposed pad, creepage, clearance, and assembly limits; +- calibration, drift, production test, and field diagnostics; +- supply chain, alternates, firmware/driver maturity, and end-of-life risk. + +## Original worked example: low-side actuator switch + +Suppose a 12 V actuator is specified by the system owner as 0.42 A steady state, 0.9 A for 120 ms at cold start, and 18 V maximum supply during charging. The controller output is 3.0 V with 4 mA available. A candidate MOSFET is considered. + +The selection cannot use only the nominal current and `RDS(on)` headline. Check gate voltage at 3.0 V, drain voltage including turn-off overshoot, pulse SOA during startup, body-diode direction, avalanche or clamp path, and package thermal resistance. If a measured drain overshoot is 26 V, a 30 V absolute maximum is not a credible margin; add a defined clamp and remeasure. If the candidate's guaranteed `RDS(on)` at the available gate voltage is 180 mΩ, steady-state loss is approximately `0.42^2 × 0.18 = 32 mW`, while the 0.9 A pulse is `0.9^2 × 0.18 = 146 mW` before temperature dependence. Those calculations are screening only; verify hot resistance and pulse thermal impedance in the exact package and layout. + +The output should name the driver, clamp, gate pulldown, supply path, fault response, measurement points, and the evidence still missing. + +## Role screening + +| Role | First constraints | False shortcut | +|---|---|---| +| Power switch | gate drive, SOA, loss, surge, fault energy | nominal current | +| Regulator | input transients, load steps, stability, heat | output voltage only | +| Op amp | common-mode, noise gain, load, stability | offset alone | +| Comparator | thresholds, hysteresis, output, delay | op amp substitution | +| Sensor | output class, excitation, installation, drift | module range as accuracy | +| Protection | waveform, repetition, clamp, failure mode | package size | + +Record whether each interface is voltage-mode, current-mode, open-drain, push-pull, differential, isolated, or bidirectional. Include startup contention and unpowered behavior. Treat a second source as a new candidate: redo thermal, timing, protection, and calibration checks. Return requirement, candidate, evidence, controlling corner, margin, verification, and unknowns. + +## Routing + +Route to the exact component datasheet for numeric limits. Route to `power-thermal-and-protection.md` for energy, heat, SOA, and fault design. Route to `tolerances-and-error-budgets.md` for accuracy. Route to `analog-and-digital-building-blocks.md` for feedback, thresholds, and ADC interfaces. Route to `sensors-and-conditioning.md` for transducers and calibration. For ESP32 board, pin, firmware, flashing, or recovery choices, route to `esp32-development`. + +## Stop criteria + +Selection is complete when one candidate satisfies every recorded corner with an evidence-backed margin, rejected options have reasons, the schematic and layout constraints are represented, and a bench or production verification plan exists. Otherwise return a bounded shortlist and explicit unknowns. + +## Primary sources + +- [TI Precision Analog Applications Seminar — Remote System Monitor Applications](https://www.ti.com/lit/pdf/slyp160) — bridge/divider and sensor-interface examples; a 2005 instructional seminar, not a component guarantee. +- [TI regulator divider accuracy](https://www.ti.com/lit/an/slva423/slva423.pdf) — feedback-divider error and environmental contributors; apply to the described regulator topology. +- [TI difference-amplifier matching](https://www.ti.com/lit/pdf/sboa582) — ratio matching and CMRR; assumptions are circuit-specific. +## Rejection reasoning + +Reject a part when a required limit is typical only, when the test condition differs from the product corner, when the thermal path is unspecified, when an alternate changes pin or startup behavior, or when protection depends on an unverified waveform. State the evidence and the smallest next measurement. + +## Candidate experiment + +For an uncertain actuator, use a current-limited supply and a substitute load with measured resistance and inductance. Capture gate, switch, load, and supply simultaneously. Sweep cold-start, stall, reversal, disconnect, and brownout. Retain waveforms and temperature, then update the candidate matrix. + +## Datasheet extraction + +Copy no values without units, conditions, min/typ/max status, and temperature. Record footnotes, test circuit, package variant, and revision. A value from a graph is an estimate and needs margin or measurement. diff --git a/electronics/references/fault-isolation.md b/electronics/references/fault-isolation.md new file mode 100644 index 0000000..90ea702 --- /dev/null +++ b/electronics/references/fault-isolation.md @@ -0,0 +1,48 @@ +# Fault isolation + +Write one leading hypothesis per branch. For each, state the predicted +observation, least-intrusive decisive test, mutation or safety effect, result, +and next branch. Keep power, topology, electrical levels, timing, protocol, +driver, and application assumptions as separate layers. + +| Observation | Prediction to test first | Decisive evidence | +|---|---|---| +| Rail correct at rest, resets under load | supply impedance or transient current | scope rail during event; measure source current | +| I2C line never rises | short, unpowered device, wrong rail, or held line | resistance/power isolation and scope idle level | +| Slow rise, marginal high | excessive C, duplicate/weak pull-up, probe loading | measured `tr`, effective pull-up, repeat with low-C probe | +| Address ACKs, identity wrong | address notation, wrong device, pointer/order | documented identity register and raw capture | +| NAK after reset only | readiness/reset timing or power sequence | reset-to-first-command timing and status polling | +| Bus hangs in software | missing timeout or unsupported stretch | captured SCL/SDA ownership and bounded wait result | +| Probe changes behavior | probe capacitance/ground inductance/loading | compare probe attachments and saved waveforms | + +Do not “fix” a symptom by increasing speed, disabling brownout, erasing state, +or adding stronger pull-ups before measuring the layer that failed. Close a +hypothesis only when an observation discriminates it from its nearest rival. +Record absent schematics, datasheets, captures, or labels as blocked evidence. + +For an intermittent issue, capture a failing and passing event with the same +trigger and settings. Compare timing, rail droop, ACK position, reset reason, +temperature, and mechanical state. Change one variable at a time and preserve +the firmware, wiring, and instrument revisions. + +Exit when the failure is reproduced or bounded to a missing artifact, the next +test has a predicted outcome, and recovery leaves the system in a known state. + +## Test quality and localization + +Name the observation before running the test. “Read returned zero” is a result; +“device absent” is an inference requiring address, power, reset, and scan-method +evidence. “Continuity passed” is a result; “solder joint good” exceeds what that +test establishes. For each inference, list the nearest competing cause and the +evidence that excludes it. + +For intermittent faults, preserve passing and failing captures with the same +trigger, settings, firmware, and physical state. If attaching a probe makes a +fault disappear, treat the probe as a possible pull-up, capacitance, ground +return, or mechanical stabilizer. Remove it and repeat before changing the +circuit. If reducing I2C speed helps, classify it as a timing or signal- +integrity clue, not a root-cause fix. + +After three non-converging tests, escalate in a bounded way: identify the +missing exact schematic, datasheet, capture, or known-good comparison; state +the safe next acquisition; and stop the branch until it exists. diff --git a/electronics/references/i2c-integration.md b/electronics/references/i2c-integration.md new file mode 100644 index 0000000..fe4019b --- /dev/null +++ b/electronics/references/i2c-integration.md @@ -0,0 +1,102 @@ +# I2C integration + +Treat I2C as an electrical bus plus a transaction contract. + +## Electrical budget + +Confirm every device's logic rail, open-drain behavior, input thresholds, +leakage, sink current, clock-stretch support, and address straps. Calculate the +effective parallel pull-up resistance, including module defaults. Choose `Rp` +between the sink-current lower bound and rise-time upper bound: + +`Rp(min) = (VDD(max) - VOL(max)) / IOL(guaranteed)` + +Use the weakest guaranteed sink capability of every line driver at the +required low voltage, not an absolute-maximum pin-current rating. Include rail +and resistor tolerances; a buffer or rise-time accelerator changes the simple +RC model and needs its own segment analysis. + +For the usual 30%-to-70% definition, `tr = 0.8473 × Rp × Cb`, so +`Rp(max) = tr(max)/(0.8473 × Cb)`. TI's SLVA689 lists 1000/300/120 ns +rise-time limits for Standard/Fast/Fm+ and 400/400/550 pF reference loads; +the target datasheets and selected mode control. A smaller resistor improves +rise time but increases low-level current and power. Measure actual rise time; +do not treat a nominal resistor as proof of compliance. + +Source: TI SLVA689: +https://www.ti.com/lit/an/slva689/slva689.pdf +NXP UM10204 sections 3 and 7: +https://www.nxp.com/docs/en/user-guide/UM10204.pdf + +### Worked design check + +Suppose the measured/estimated line capacitance is 120 pF, the rail is 3.3 V, +and Fast-mode operation is required. The TI relation gives +`Rp(max) ≈ 300 ns/(0.8473 × 120 pF) ≈ 2.95 kΩ`. If the device's low-level +specification is 0.4 V at 3 mA, the simple lower bound is approximately +`(3.3 - 0.4)/3 mA ≈ 967 Ω`. That interval still needs device-specific leakage, +rail tolerance, parallel pull-ups, series resistors, and measured waveform +checks. A 2.2 kΩ candidate may be reasonable for this stated case; it is not a +portable default. + +If two 4.7 kΩ pull-ups are fitted on separate modules, their effective value is +2.35 kΩ before any other pull-up is counted. Removing one may improve low-level +current margin while preserving rise time. Conversely, replacing 4.7 kΩ with +10 kΩ without measuring Cb can create a slow edge that a nominal frequency +setting hides. + +## Bring-up and transaction evidence + +1. With power removed and stored energy discharged, check for unintended shorts. + Then power the intended domains in their documented sequence and measure idle + SDA/SCL levels. Do not apply pull-up power to an unpowered device unless its + powered-off pin behavior permits it; protection structures may back-power it. +2. At conservative speed, capture idle levels and one transaction. Record + start/repeated-start/stop, 7-bit address, direction, ACK/NAK, register bytes, + data, and clock stretching. +3. Use a scan only as an address-response clue. Some probe methods can alter a + device state; write-only devices may not respond to reads. A found address + is not identity. Read a documented manufacturer/device/revision or status + register before trusting the driver. +4. Check reset state, register pointer semantics, endian/order, readiness delay, + and documented repeated-start requirements. + +### Scan decision table + +| Scan result | Next test | Do not conclude | +|---|---|---| +| Both lines low | isolate power/devices; identify holder | that the controller API is wrong | +| Both lines high, no ACK | verify rail, reset, pins, straps, address notation | that the device is dead | +| One or more ACKs | read documented identity/status register | that ACK proves device identity | +| Unexpected extra ACK | remove modules one at a time; inspect parallel pull-ups/ghosts | that every responder is intended | +| ACK then hang | capture phase and line owner; enforce timeout | that lower speed fixes root cause | + +Before a scan, decide whether the probing operation is read, write, or a +controller-specific “quick” transaction, and whether the target permits it. +Store that decision with the capture. For a write-capable device, a scan that +touches a command register is a state mutation and needs an explicit rollback +or reset plan. + +## Recovery ownership + +The controller owns timeout and recovery policy. Every wait for SCL, ACK, or a +device-ready state has a deadline and reports the phase. If SDA is stuck low, +NXP's bus-clear procedure calls for nine clock pulses; if it remains low, use +hardware reset or power-cycle. If SCL is stuck low, reset or power-cycle first. +Only pulse lines when the controller is electrically allowed to take ownership, +all other controllers are quiescent, and the action cannot trigger an unsafe +write. Capture line state before and after recovery and identify the holder if +possible. + +## Fault localization + +If 0x48 ACKs but ADC identity/readback is wrong, capture address and direction, +resolve 7-bit versus shifted 8-bit notation, then check identity register, +pointer byte, repeated-start, reset readiness, and endian order. This localizes +the fault to selection, transaction contract, reset, or bus corruption; it does +not prove the library is at fault. + +If SDA is low before START, isolate modules and measure each branch. If it falls +after a byte, capture ACK and ownership. If SCL is low, distinguish documented +clock stretching from a stuck output using a deadline and waveform. Recovery +records before/after state, pulse count, reset/power action, and line owner. diff --git a/electronics/references/measurement-and-instrumentation.md b/electronics/references/measurement-and-instrumentation.md new file mode 100644 index 0000000..da3fbc3 --- /dev/null +++ b/electronics/references/measurement-and-instrumentation.md @@ -0,0 +1,129 @@ +# Measurement and instrumentation + +Choose the instrument from the question being asked. A DMM establishes DC +voltage, resistance, continuity, diode behavior, and bounded current only when +connected correctly. A scope shows time behavior and ripple; a logic analyzer +decodes digital states but cannot establish analog voltage margin or power +integrity by itself. + +## DMM discipline + +Before touching the circuit, set function and range, verify the black lead is +in COM, and verify the red lead is in the voltage/ohms jack for voltage, +resistance, diode, and continuity. Current jacks are low impedance and are +intended for a series insertion across a deliberate circuit break. A voltage +measurement with the lead in a current jack can short the source through the +meter shunt. Confirm the current-input fuse rating and interrupt capacity from +the meter manual; a fuse is not permission to exceed the meter, lead, or source +rating. Prefer a clamp or shunt designed for the current when opening the path +is unsafe. + +For resistance/continuity, remove power and discharge capacitors. For current, +predict the range and polarity, start on the highest range, connect in series, +and restore the lead to the voltage jack immediately afterward. Record whether +the reading is startup, steady-state, or a burst. + +Source: Fluke, *ABCs of DMMs*: +https://media.fluke.com/ade6b718-4577-4b57-903b-b10600664c67_original%20file.pdf + +Use a lead-position interlock in the procedure: announce “voltage” before +placing the tip, visually confirm COM plus V/Ω, and return the red lead to V/Ω +after every current measurement. If the meter's current fuse is open, a current +reading may silently become an open circuit; verify the instrument on a known +source or its self-test rather than assuming zero current. For low-side shunt +measurements, account for the shunt voltage drop and common-reference shift. + +## Scope setup + +A conventional benchtop scope has probe commons tied to protective earth and +all channel commons share that node. Connect the probe to the scope first, +then connect its ground to a known DUT reference before the tip. Never defeat +the protective earth or clip the common lead to a switching node. If neither +measurement point is safely at earth reference, use a correctly rated +differential or isolated probe and verify common-mode, differential, CAT, and +transient limits. + +Select bandwidth and attenuation for the fastest edge and voltage range. Use a +short ground spring or coaxial fixture when edge shape matters. A long ground +lead adds inductance and can create ringing. Probe input capacitance is part of +the circuit: it can slow I2C rise time or change a marginal oscillator. Record +probe model, capacitance, attenuation, bandwidth limit, sample rate, coupling, +trigger, test point, and ground attachment. + +Sources: Tektronix, *Floating Oscilloscope Measurements and Operator +Protection*: https://www.tek.com/en/documents/technical-brief/floating-oscilloscope-measurements-and-operator-protection +and *How Oscilloscope Probes Affect Your Measurement*: +https://www.tek.com/en/documents/application-note/how-oscilloscope-probes-affect-your-measurement +Keysight, *8 Tips for Better Scope Probings*: +https://www.keysight.com/us/en/assets/7018-01747/application-notes/5989-7894.pdf + +### Repeatable capture + +Use the same trigger point and timebase for a passing and failing capture. +Measure I2C rise time at the specified threshold interval, report overshoot and +low-level plateau separately, and annotate whether the probe was attached at +the controller or far end. For a rail transient, capture the rail and the event +trigger together; a DMM average cannot disprove a short brownout. State the +scope's vertical scale, offset, bandwidth limit, coupling, and sample/memory +settings so the result can be audited. + +Treat displayed digits as estimates. Include probe tolerance, scope accuracy, +noise floor, trigger jitter, and repeatability when a limit decision depends on +small margins. If the margin is smaller than the combined uncertainty, classify +the result as inconclusive and change the measurement method or improve the +test point. + +## Interpretation + +Separate instrument evidence from circuit evidence. If attaching a second probe +changes the waveform, suspect loading and repeat with a lower-capacitance +attachment. If a DMM sees a stable rail but the scope shows droop during a +radio or load event, the transient is the relevant evidence. A decoded frame +does not prove VIH/VIL, rise time, ground integrity, or supply behavior. + +## Validity, aliasing, and uncertainty + +State the quantity and bandwidth needed to answer the question. A logic +analyzer sampling too slowly can miss a narrow glitch and still decode a clean +bus; a scope bandwidth limit can hide ringing. A DMM update rate can miss a +transient, and a continuity threshold can turn a high-value path into a beep. +Record range, resolution, input impedance, bandwidth, sample rate, filtering, +and trigger settings. + +| Observation | False positive | False negative | Disambiguating test | +|---|---|---|---| +| continuity beep | threshold or parallel path | oxidized/high contact resistance | power-off ohms reading and lead subtraction | +| stable DMM rail | average hides droop | probe changes return | scope at load during event | +| clean decoded I2C | threshold/filter hides slow edge | sample misses glitch | analog SDA/SCL plus raw capture | +| zero current | open/blown current fuse | range overload | verify lead/jack/fuse and known source | +| probe improves circuit | probe adds pull/return path | probe masks intermittent fault | remove probe; alternate low-C attachment | + +Continuity is a finite-resistance, low-current test. Zero displayed ohms is not +literal zero; an open-looking semiconductor, protection device, or capacitor +may be behaving normally. If a limit decision depends on a small margin, include +probe tolerance, scope accuracy, noise floor, trigger jitter, and repeatability. +If combined uncertainty overlaps the limit, classify the result inconclusive. + +## Repeatable measurement sequence + +1. Write the predicted signature and safety boundary. +2. Announce DMM function and visually verify COM plus V/ohms or current jack. +3. Connect scope ground/reference first where the instrument requires it. +4. Capture a disabled baseline and one controlled event. +5. Save raw data and settings; repeat once unchanged. +6. If surprising, test loading, aliasing, grounding, and range before modifying + the circuit. +7. Classify confirmed, contradicted, or inconclusive and state why. + +All probe commons on a conventional benchtop scope share earth/reference. +Never remove protective earth to obtain a floating measurement. + +## Minimal diagnostic handoff + +Carry the evidence into the answer, not only the reasoning. A short diagnosis can use one row rather than a full worksheet: + +| Quantity and point | Configuration | Expected from model | Reported or measured | Interpretation | Next check | +|---|---|---|---|---|---| +| Output rail at load connector | DMM DC mode; input resistance and range still unknown | Nominal value from supplied design model | User-reported reading; no independent measurement performed | Compatible with more than one hypothesis | Capture under the triggering load with the configuration recorded | + +Replace placeholders with the actual supplied values. Preserve the distinction between evidence supplied by the user, calculations, measurements actually performed and proposed tests. If the configuration is unknown, record that explicitly instead of omitting the field. This keeps even a concise answer auditable without implying a bench test occurred. diff --git a/electronics/references/power-thermal-and-protection.md b/electronics/references/power-thermal-and-protection.md new file mode 100644 index 0000000..6b4a646 --- /dev/null +++ b/electronics/references/power-thermal-and-protection.md @@ -0,0 +1,68 @@ +# Power, thermal, and protection + +## Energy map + +Before choosing a device, draw current paths for normal operation, startup, shutdown, reversal, disconnect, short circuit, wrong polarity, and communication loss. Record source impedance and stored energy in inductors, capacitors, batteries, cables, and rotating loads. + +For a switch, estimate `Pcond = I²R` when conduction is resistive. Use `Psw ≈ 0.5 V I (tr+tf) fs` only as a screening model when a roughly linear voltage/current overlap is justified; for release, integrate measured or datasheet waveforms and add duty, gate-drive, diode, reverse-recovery, quiescent, and regulator losses. Do not use these simplified equations through saturation, current limiting, or an unknown waveform. + +For thermal screening, use `Tj = Ta + P × θJA` only when the board, airflow, copper, and steady-state conditions match the specified thermal resistance. Otherwise use the package's junction-to-board/case path and transient thermal impedance. Verify temperature with a calibrated method and identify the hottest location. + +## SOA and linear operation + +A MOSFET selected for low on-resistance may be unsuitable while it is partly enhanced. Startup ramps, e-fuses, current limiting, motor stalls, slow gates, and avalanche events can place it in linear mode. Check the exact SOA for voltage, current, pulse duration, case temperature, gate condition, duty cycle, and mounting. Infineon's [linear-mode/SOA note](https://www.infineon.com/assets/row/public/documents/24/42/infineon-applicationnote-linear-mode-operation-safe-operation-diagram-mosfets-applicationnotes-en.pdf?fileId=db3a30433e30e4bf013e3646e9381200) explains why the published SOA curve is conditional and why transient thermal impedance and thermal instability matter. Applicability: the cited MOSFET guidance; exact part data controls. + +## Protection selection + +Match protection to the fault waveform: + +| Threat | Candidate action | Required proof | +|---|---|---| +| Inductive turn-off | Flyback diode, TVS, active clamp, snubber | Peak voltage, decay time, repetition heat | +| Overcurrent/short | Fuse, current limit, foldback, e-fuse | Trip delay, I²t, restart and fault energy | +| Reverse supply | Series FET/diode, ideal-diode controller | Drop, reverse current, startup behavior | +| Surge/ESD | TVS, filtering, shielding, layout | Source waveform, clamp voltage, pulse rating | +| Thermal runaway | Derating, sensor, shutdown, foldback | Hot-case behavior and restart policy | +| Cross-domain fault | Isolation, creepage, current limiting | Withstand, leakage, fault containment | + +Protection must survive the source, not merely the nominal load. Check TVS standoff and clamp values at the actual current, diode reverse recovery, capacitor ESR, fuse interrupt rating, and repeated-fault thermal accumulation. + +## Original thermal example + +A 24 V load draws 0.65 A and a high-side switch has a guaranteed hot resistance of 120 mΩ. Conduction loss is `0.65² × 0.12 = 50.7 mW`. A 2 A, 20 ms startup pulse gives `0.48 W` during the pulse only if the switch remains in the ohmic region; linear-mode intervals require `VDS × IDS` from the waveform and SOA. If the board path were independently verified as 70 °C/W steady state and ambient is 45 °C, the steady junction rise is `0.0507 × 70 = 3.55 °C`, giving an estimated junction temperature of `48.55 °C` absolute, only when the package thermal model applies. If an overload lasts 400 ms at 2 A, the ohmic screening energy is `0.48 × 0.4 = 0.192 J`; pulse SOA and transient thermal impedance decide survival. + +## Thermal review + +| Question | Evidence | +|---|---| +| Is loss conduction, switching, magnetic, gate, or quiescent? | waveform and calculation | +| Is the rating steady or transient? | thermal model and pulse duration | +| What is the hottest junction? | thermal path plus measurement | +| Does heat change resistance or current? | hot characteristics | +| What repeats the pulse? | duty cycle and fault cycling | + +For inductive loads, record inductance or measured stored energy, current at turn-off, clamp location, clamp voltage, and decay requirement. A diode lowers voltage but may slow release; a TVS or active clamp trades voltage for loss. Measure load terminals and switch pins because wiring inductance can hide local spikes. Keep high-di/dt loops small and protection current out of sensitive returns; a schematic symbol does not prove placement, parasitics, or pulse rating. + +## MCU boundary + +An MCU GPIO is a control signal. It is not a power supply for motors, relays, solenoids, servos, high-current LEDs, or large capacitive loads. Specify the external driver, gate/base current, supply, ground or isolation, clamp path, power-up default, and reset behavior. Test with a current-limited supply, oscilloscope at the device pins, thermal measurement, and repeated fault cycles. + +## Exit evidence + +Require a measured normal waveform, startup and shutdown waveform, peak clamp voltage, current and temperature at controlling corners, and a demonstrated recovery path for each fault. If the fault waveform is unknown, the protection result is incomplete. + +## Sources + +- [Infineon MOSFET linear mode and SOA](https://www.infineon.com/assets/row/public/documents/24/42/infineon-applicationnote-linear-mode-operation-safe-operation-diagram-mosfets-applicationnotes-en.pdf?fileId=db3a30433e30e4bf013e3646e9381200) — conditional SOA and thermal analysis. +- [TI technical-document index](https://www.ti.com/technical-documents/techdoc/results?docCategoryId=1&familyId=64&litCount=all&rootFamilyId=64) — manufacturer application notes for transient thermal impedance and SOA; select the exact device family. +## MOSFET gate and resistance + +Threshold voltage is the onset of a small specified drain current, not the voltage that guarantees low resistance. Use the RDS(on) specification at the actual gate voltage and temperature. Check gate-charge, driver source/sink current, Miller plateau, turn-on/off time, and false turn-on from dV/dt. A slow or floating gate can spend damaging time in linear mode. + +## Protection rejection + +Reject a clamp that has no source waveform, a fuse with no interrupt rating, or a diode whose reverse-recovery and repetition loss are unknown. Test a shorted switch, open clamp, stuck enable, reversed supply, and repeated restart. Thermal shutdown behavior is not a complete fault strategy unless restart and energy limits are specified. + +## Verification + +Measure at the silicon pins, not only at the bench supply. Use a probe and ground connection that do not create the spike being measured. Correlate electrical waveform, current, case temperature, and reset/log evidence. diff --git a/electronics/references/schematic-to-bench.md b/electronics/references/schematic-to-bench.md new file mode 100644 index 0000000..fdbc669 --- /dev/null +++ b/electronics/references/schematic-to-bench.md @@ -0,0 +1,71 @@ +# Schematic to bench review + +Turn the design into a reviewable physical plan before applying power. + +## Review record + +For each net record: + +| Field | Required content | +|---|---| +| Net and return | signal name, source, destination, explicit return path | +| Pin identity | exact component reference, pin number, package/board revision | +| State | power-off, reset, idle, active, fault level and polarity | +| Limits | voltage, current, power, timing, absolute maximum and operating range | +| Test point | probe/meter access, reference node, expected measurement | + +Read the exact schematic, board drawing, module documentation, and datasheet. +The silkscreen or a familiar breakout is evidence of placement, not of pin +function, voltage tolerance, pull-ups, or address straps. Mark every unknown. + +## Electrical reasoning + +Calculate each intentional load. For a resistor-fed LED, evaluate the range +`I = (Vsupply - Vf) / R` across supply, forward-voltage, and resistor tolerance; +then check the LED, resistor dissipation, and source/driver current limits. A +GPIO is a control output, not a power supply. For an inductive load specify +driver rating, flyback path, external supply, shared reference or isolation, +and reset-time state. For analog inputs include source impedance, scaling, +fault voltage, ADC range, reference/calibration, and filter corner. + +For mixed voltages, identify direction and topology. A bidirectional open-drain +bus needs a translator that preserves release/high-impedance behavior; a +push-pull signal may need a different level shifter. Do not infer tolerance from +the board's supply label. + +## First-power gate + +With power removed, inspect orientation, rails, bridges, connector keying, and +unpopulated options. Check intended continuity and absence of rail-to-rail or +rail-to-signal shorts. Define a current limit and a stop condition before +powering. Apply power with the load disabled where possible; measure rail +voltage and current, reset state, and temperature. Add one signal group or +peripheral at a time. + +The review is complete when a second engineer can wire or probe from the record, +every numeric choice has a source or calculation, and unresolved facts are +visible rather than hidden in assumptions. + +Sources: component datasheet and board schematic are controlling sources. +For I2C electrical constraints use NXP UM10204 sections 3 and 7: +https://community.nxp.com/pwmxy87654/attachments/pwmxy87654/nxp-designs/931/1/UM10204.pdf + +## Worked review and stage gates + +For a 3.3 V GPIO driving an LED through 680 ohms, record GPIO4 → resistor → +anode, cathode → ground, active-high, reset-off, and the LED datasheet's Vf +range. At Vf=2.0 V, nominal current is `(3.3-2.0)/680 = 1.9 mA`; recalculate +the extremes, resistor power (`I²R`), and GPIO limits. A continuity beep does +not prove this load calculation, reset state, or driver safety. + +| Gate | Required evidence | Stop condition | +|---|---|---| +| documentation | exact schematic/BOM/board/component revisions | pin, rail, polarity unknown | +| unpowered | visual, continuity, rail-short record | unexpected conductive path | +| first power | current limit, rail/current/reset/temperature | rail collapse or excess current | +| signal | defined idle/active test-point readings | unexplained level or polarity | +| integration | identity/readback and bounded timeout | scan-only or hanging driver | +| release | reset/power-cycle and acceptance record | open electrical limit | + +Do not treat success at one gate as evidence for the next: a stable rail does +not prove correct signaling, and a functional demo does not prove recovery. diff --git a/electronics/references/sensors-and-conditioning.md b/electronics/references/sensors-and-conditioning.md new file mode 100644 index 0000000..a3045f7 --- /dev/null +++ b/electronics/references/sensors-and-conditioning.md @@ -0,0 +1,59 @@ +# Sensors and conditioning + +## Classify the output + +Before choosing an interface, identify passive resistance, analog voltage/current, binary threshold, pulse/frequency/PWM, serial stream, or register-based digital output. Confirm excitation, loading, common-mode, reference, bandwidth, response time, warm-up, supply dependence, and fault signaling. A module's advertised measurement range may not equal its conditioned output range. + +## Signal-chain failure modes + +Inspect for excessive divider loading, ADC acquisition current, insufficient excitation, input-protection leakage, common-mode violation, aliasing, ground return coupling, op-amp saturation recovery, sensor self-heating, cable pickup, connector leakage, condensation, and installation stress. Add source impedance and protection to the small-signal model. Check sensor output during power-up, disconnect, short, overrange, and saturated conditions. + +For an ADC path, establish reference accuracy/noise, sample rate, anti-alias filter, settling, grounding, and digital coupling. Microchip [AN1007, Designing with the MCP3551 Delta-Sigma ADC](https://ww1.microchip.com/downloads/en/Appnotes/01007a.pdf) emphasizes measuring and inspecting actual samples for the MCP3551 high-resolution converter; nominal bit count does not establish system performance. Applicability: the cited MCP3551 evaluation workflow, with the exact ADC taking precedence. + +## Calibration design + +Define reference standard and traceability, fixture, number and placement of points, temperature and supply corners, warm-up, fit model, residual limit, storage format, validity flag, recalibration trigger, and out-of-range behavior. Retain raw data, fitted coefficients, residuals, instrument IDs, and operator or automated-run metadata. + +Separate offset/span correction from nonlinearity, hysteresis, repeatability, drift, installation error, and random noise. A calibration curve cannot make a sensor safe outside its characterized range. Analog Devices' [MAX1464 compensation note](https://www.analog.com/en/resources/app-notes/max1464-signalconditioner-sensor-compensation-algorithm.html) demonstrates temperature compensation under an explicit constant-supply assumption; validate that assumption in the target product. Its [MAX14XX diagnostic note](https://www.analog.com/en/resources/design-notes/adding-diagnostic-capability-to-max14xx-low-cost-high-performance-signalconditioning-devices.html) illustrates retaining reference checks to detect drift. Applicability: those signal conditioners and procedures. + +## Original calibration example + +A bridge sensor is calibrated at 0, 40, and 80 input units at two temperatures. The output, with units declared, is fit to `y = a0 + a1x + a2T + a3xT`; each coefficient carries derived units and the valid fit rectangle is recorded. Before accepting it, verify fit residuals at held-out points, repeat one reference after thermal cycling, and test supply variation if excitation is not truly ratiometric. A 3-point fit can pass endpoints while leaving a bowed middle residual; report the residual envelope and repeatability, not only coefficients. + +## Sensor-specific questions + +| Family | Failure question | +|---|---| +| Resistive temperature | Is excitation causing self-heating, and is lead resistance included? | +| Thermocouple | Are cold-junction, polarity, shielding, and common-mode limits handled? | +| Accelerometer/gyro | Are bias, cross-axis sensitivity, vibration, saturation, and orientation conventions tested? | +| Current/voltage | Is isolation, burden/drop, common-mode, and fault energy valid? | +| Optical/gas | Are ambient spectrum, contamination, aging, and warm-up characterized? | +| GPS/radio | Are antenna, sky view, latency, fix validity, and privacy requirements explicit? | + +## Conditioning table + +| Output | Verify first | Failure | +|---|---|---| +| resistance | excitation, leads, self-heating | measurement changes sensor | +| voltage | source impedance, common-mode, range | loading or clipping | +| current | compliance, burden, isolation | loop cannot regulate | +| pulse/PWM | amplitude, timing, pull-up, missing state | capture/noise errors | +| serial/register | framing, scaling, validity, stale data | invalid data accepted | + +Use an independent holdout or repeat; fitting and acceptance on the same points hides model error. Test increasing and decreasing stimulus, warm-up, and supply variation separately. Define safe behavior for invalid, stale, disconnected, saturated, and implausible readings. The final enclosure, cable routing, mounting torque, airflow, optical window, and thermal path are part of the sensor. Store timestamp, stimulus, raw code, engineering value, temperature, supply, fixture state, and validity flags; plot residual against each variable before choosing a more complex fit. + +## Output criteria + +An integration recommendation is complete when the output class, signal chain, legal input region, calibration model, fault behavior, installation assumptions, and measured acceptance criteria are recorded. Otherwise produce a bounded experiment and state what remains unknown. +## Uncertainty chain + +Convert sensor datasheet terms into system output units: sensitivity, offset, gain, nonlinearity, hysteresis, repeatability, drift, ADC/reference error, noise, and installation error. Keep sign and correlation assumptions explicit. Report a residual envelope and confidence method. + +## Failure investigation + +When readings jump, compare raw output, supply, reference, temperature, timing, and physical stimulus. A firmware average can hide aliasing or intermittent saturation. Check stale digital registers and invalid flags before filtering. Disconnect and short the sensor input to distinguish sensor, wiring, conditioner, and ADC faults. + +## Calibration rejection + +Reject calibration when reference conditions are untraceable, raw data is discarded, points do not cover the operating range, or the fitted model is accepted only at training points. diff --git a/electronics/references/tolerances-and-error-budgets.md b/electronics/references/tolerances-and-error-budgets.md new file mode 100644 index 0000000..a7054bd --- /dev/null +++ b/electronics/references/tolerances-and-error-budgets.md @@ -0,0 +1,75 @@ +# Tolerances and error budgets + +## Define the claim first + +Write the output quantity, operating interval, acceptance limit, and whether the limit is guaranteed, statistical, calibrated, or measured. A value such as “one percent accurate” is incomplete without temperature, supply, load, time, bandwidth, and confidence or coverage. + +Partition error into: + +- initial offset, gain, and reference error; +- component tolerance and matching; +- temperature coefficient and thermal gradients; +- supply sensitivity, loading, and leakage; +- noise, quantization, aliasing, and EMI; +- nonlinearity, hysteresis, repeatability, drift, aging, and self-heating; +- fixture, instrument, installation, and model uncertainty. + +Label which terms calibration can remove. Calibration generally cannot remove random noise, changing hysteresis, future drift, an unmeasured installation shift, or an unbounded fault. + +## Worst-case method + +1. Express the output as a function of all bounded variables. +2. Define each variable's valid interval and correlation. +3. Evaluate nominal, all sign-relevant extrema, and temperature/supply corners. +4. Include loading and leakage in the same equation, not as a later footnote. +5. Compare the worst result with the requirement and record the controlling terms. +6. Use Monte Carlo only as a supplement to, never a replacement for, a bounded analysis. + +For `y = f(x)`, the first-order estimate is `Δy ≈ Σ |∂f/∂xi| Δxi` when variables are small and smooth. This absolute-sum form is a conservative bounded estimate; statistical combinations require an explicit independence or covariance model. Use interval evaluation or direct corner enumeration when nonlinearities, saturation, clipping, or correlations matter. + +## Original divider example + +A monitor divides a 17.6 V rail by nominal resistors 68 kΩ and 10 kΩ. The ideal output is `17.6 × 10/(68+10) = 2.256 V`. With each resistor bounded at ±0.5%, the high output occurs with the lower upper resistor and higher lower resistor: `17.6 × 10.05/(67.66+10.05) = 2.276 V`; the low output occurs with the converse limits: `17.6 × 9.95/(68.34+9.95) = 2.236 V`. The resistor-only interval is therefore about ±0.9% around nominal, before monitor input leakage, reference error, temperature coefficient, noise, and rail measurement error. This is a bounded corner calculation; physical correlation may make some corners less likely or infeasible, while statistical confidence requires a separate model. + +If the monitor input leakage is 80 nA and the Thevenin resistance is approximately `68 kΩ || 10 kΩ = 8.72 kΩ`, the added static error is about `0.70 mV` at the sense node. Whether that matters depends on ADC LSB, threshold margin, and the rail-to-output transfer. Recalculate at the actual leakage sign and temperature. + +## Matching and calibration + +Matched resistor networks may preserve ratios better than independent parts. State the matching specification, tracking temperature coefficient, and common substrate assumptions. Four equal-tolerance resistors in a difference amplifier can still create common-mode to differential conversion when ratios mismatch; use the exact topology's error expression. + +For calibration, retain raw readings and fit residuals. Do not report the fitted curve without the reference values, instrument uncertainty, temperature, supply, sample count, and out-of-range behavior. Distinguish repeatability from reproducibility and accuracy from resolution. + +## Evidence + +- [TI Precision Analog Applications Seminar — Remote System Monitor Applications](https://www.ti.com/lit/pdf/slyp160) — opposite tolerance directions in divider examples; educational and historical. +- [TI SLVA450B, IQ vs Accuracy Tradeoff In Designing Resistor Divider Input To A Voltage Supervisor](https://www.ti.com/lit/an/slva450b/slva450b.pdf) — leakage, divider selection, and total accuracy; comparator/supervisor topology-specific. +- [TI regulator-divider report](https://www.ti.com/lit/an/slva423/slva423.pdf) — resistor tolerance plus regulator accuracy and environmental drift; use the exact regulator data. +- [TI matched difference amplifier](https://www.ti.com/lit/pdf/sboa582) — matching and CMRR; circuit assumptions apply. + +## Error classes and correlations + +| Class | Behavior | Treatment | +|---|---|---| +| Offset/bias | fixed or temperature dependent | calibrate only if stable | +| Gain/reference | multiplicative | calibrate span; include drift | +| Random noise | sample dependent | characterize bandwidth | +| Hysteresis | history dependent | measure both directions | +| Nonlinearity | signal dependent | inspect residuals | +| Aging/installation | time or mounting dependent | qualify and define recalibration | + +For `Vout = Vref(1 + Rtop/Rbot)`, ratio accuracy can be good while reference drift dominates. Use partial derivatives to rank terms; sensitivity to `Vref` is `1 + Rtop/Rbot`. Do not use root-sum-square without independence evidence. Shared temperature, supply, substrate, or fixture can correlate errors; include covariance or bounded corners. Include instrument uncertainty, probe loading, fixture repeatability, gradients, and quantization before closing the budget. + +## Output criteria + +An error budget is decision-ready when every material term has a source, equation, interval or distribution, temperature/supply corner, correlation assumption, and verification method. Any missing term that could consume the margin remains `UNKNOWN` and blocks a confident pass. +## Systematic versus random + +Systematic error shifts all units or all readings in one direction; random error varies between samples. A production average cannot prove a systematic offset is absent. Repeatability describes the same setup; reproducibility changes operator, fixture, or environment. + +## Temperature and self-heating + +Use the actual component temperature, not ambient alone. For a resistor, estimate P=V2/R or I2R, then apply its temperature coefficient over the measured temperature rise. For a sensor, excitation can change the measured quantity; model self-heating as part of the transfer function. + +## Acceptance + +Choose a guard band when measurement uncertainty is not negligible. If the requirement is plus or minus 1 unit and measurement uncertainty is plus or minus 0.4 unit, a reading of 0.8 unit cannot prove compliance without a defined decision rule. diff --git a/electronics/templates/assembly-acceptance.md b/electronics/templates/assembly-acceptance.md new file mode 100644 index 0000000..45a1ecb --- /dev/null +++ b/electronics/templates/assembly-acceptance.md @@ -0,0 +1,51 @@ +# Assembly acceptance + +Assembly/BOM/schematic/layout revisions: + +Operator/date: + + +## Physical and unpowered + +- [ ] Orientation, bridges, pads, connectors, strain relief inspected +- [ ] Intended continuity checked with power removed +- [ ] Rail-to-rail and rail-to-signal shorts excluded +- [ ] Optional pull-ups, straps, and protection parts match the record + +## Controlled power and behavior + +Current limit and source: + +Measured rails/startup/steady current/temperature: + +Reset and idle-state result: + +Identity-level bus result and raw capture: + +Load/input behavior and tolerances: + +Reset/power-cycle repetitions: + +Recovery path tested: + + +Open risks, evidence links, and sign-off: + + +## Evidence separation + +Visual inspection proves: + +Unpowered electrical test proves: + +Powered functional test proves: + +Not established by these tests: + + +| Test | Setup/revision | Expected | Observed | Pass/block | +|---|---|---|---|---| +| first power | | | | | +| identity/readback | | | | | +| load behavior | | | | | +| reset/power-cycle | | | | | diff --git a/electronics/templates/bus-electrical-budget.md b/electronics/templates/bus-electrical-budget.md new file mode 100644 index 0000000..4093406 --- /dev/null +++ b/electronics/templates/bus-electrical-budget.md @@ -0,0 +1,40 @@ +# Bus electrical budget + +Bus / mode / target speed: + +Logic rail(s): + + +| Device/module | Pull-up present | Leakage/sink limit | Address/strap | Added capacitance | +|---|---|---|---|---| +| | | | | | + +Effective parallel pull-up: + +`Rp(min)` source and result: + +`Cb` estimate and contributors: + +`Rp(max) = tr(max)/(0.8473 × Cb)`: + +Selected value and speed/power rationale: + +Measured SDA/SCL rise/fall time: + +Probe model/capacitance/ground attachment: + +Scan side effects considered: + +Controller timeout and bus-clear owner: + + +## Verification rows + +| Stage | Expected | Observed | Result/inference | +|---|---|---|---| +| idle | SDA/SCL released to logic rail | | | +| scan | documented response only | | clue, not identity | +| identity | known register/bytes | | | +| recovery | bounded clear and known reset | | | + +Open unknown, owner, and next measurement: diff --git a/electronics/templates/component-contract.md b/electronics/templates/component-contract.md new file mode 100644 index 0000000..0ab1978 --- /dev/null +++ b/electronics/templates/component-contract.md @@ -0,0 +1,57 @@ +# Component contract + +## 1. Job and envelope + +- Function and observable behavior: +- Component family and why: +- Input/output quantities and units: +- Minimum / nominal / maximum / transient / fault: +- Supply rails, frequency, duty cycle, ambient, enclosure, lifetime: +- Acceptance criteria: + +## 2. Identity and evidence + +- Manufacturer and exact ordering code/package/revision: +- Datasheet and application-note URLs: +- Schematic, pinout, exposed pad, polarity, assembly constraints: +- Guaranteed values versus typical curves: +- Board/SoC schematic and firmware assumptions, if attached: +- Unknowns and evidence owner: + +## 3. Margins and calculations + +| Requirement | Equation/assumption | Corner | Result | Margin | Evidence | +|---|---|---|---|---|---| +| | | | | | | + +- Tolerance, drift, noise, leakage, loading: +- Dissipation, thermal path, SOA/transient: +- Protection energy and clamp limits: +- Guaranteed / estimated / measured classification: +- Controlling corner and model-validity range: +- Observed fact: +- Inference supported by the fact: + +### Completed example + +| Requirement | Equation/assumption | Corner | Result | Margin | Evidence | +|---|---|---|---|---|---| +| actuator conduction | `P=I²R`, hot guaranteed `RDS(on)` | 0.42 A steady, hot | 32 mW | below thermal budget | datasheet condition + measured rail | + +The example is screening evidence only; startup linear-mode SOA and clamp +waveforms remain separate requirements. + +## 4. Interface and failure contract + +- Logic thresholds, impedance, timing, power-up/down: +- Driver, pull resistor, clamp, flyback, snubber, fuse/current limit: +- Ground/isolation, creepage/clearance: +- Open, short, reversed, disconnected, brownout behavior: + +## 5. Verification + +- Instruments, fixtures, raw-data location: +- Normal, corner, reset/power-cycle, and fault tests: +- Temperature/supply/load corners: +- Calibration and diagnostic checks: +- Pass/fail evidence and unresolved risks: diff --git a/electronics/templates/design-calculation-record.md b/electronics/templates/design-calculation-record.md new file mode 100644 index 0000000..bce24be --- /dev/null +++ b/electronics/templates/design-calculation-record.md @@ -0,0 +1,51 @@ +# Design calculation record + +## Requirement and model + +- Decision supported: +- Output quantity and acceptance limit: +- Exact parts, revisions, topology, and operating modes: +- Assumptions, valid ranges, and omitted effects: +- Equation/model validity range: +- Instrument uncertainty included? Method/source: + +## Variables + +| Variable | Nominal | Bounds/distribution | Source | Correlation | +|---|---:|---|---|---| +| | | | | | + +## Calculation + +```text +Equation: +Units: +Nominal result: +Worst-case low/high: +Statistical result, if used: +``` + +Explain whether interval arithmetic, corner enumeration, sensitivity, simulation, or measurement was used. Show the controlling corner and why it is valid. + +## Margin ledger + +| Requirement | Result | Margin | Guaranteed/estimated/measured | Next check | +|---|---:|---:|---|---| +| | | | | | + +## Review gates + +- Absolute maximum and recommended-operation limits checked: +- Temperature, supply, tolerance, aging, and loading included: +- Thermal/SOA/protection calculation linked: +- Source URLs and datasheet revision retained: +- Raw simulation or measurement artifact retained: +- Unknowns blocking release: + +## Interpretation + +Observed fact from measurement or source: + +Inference made from the calculation: + +Nearest competing model or corner: diff --git a/electronics/templates/fault-ledger.md b/electronics/templates/fault-ledger.md new file mode 100644 index 0000000..bc372b4 --- /dev/null +++ b/electronics/templates/fault-ledger.md @@ -0,0 +1,33 @@ +# Fault ledger + +Symptom, first observed: + +Known-good comparison: + + +| Layer | Hypothesis | Predicted observation | Least-intrusive test | Mutation/safety effect | Result/next branch | +|---|---|---|---|---|---| +| power | | | | | | +| topology | | | | | | +| electrical | | | | | | +| timing/protocol | | | | | | +| driver/application | | | | | | + +Missing artifact or measurement: + +Recovery state and owner: + +Firmware/wiring/instrument revisions: + + +## Branch control + +What observation would contradict this hypothesis? + +What observation would merely be compatible? + +What artifact or measurement is missing? + +Mutation/rollback owner: + +Escalation after three non-converging tests: diff --git a/electronics/templates/measurement-plan.md b/electronics/templates/measurement-plan.md new file mode 100644 index 0000000..851e465 --- /dev/null +++ b/electronics/templates/measurement-plan.md @@ -0,0 +1,42 @@ +# Measurement plan + +Question and predicted observation: + +DUT state and power source: + + +| Point/signal | Instrument | Reference/return | Range/attenuation | Bandwidth/sample | Expected | +|---|---|---|---|---|---| +| | | | | | | + +## Safety and loading + +DMM lead/function check; current jack/fuse verified: + +Scope earth/common relationship: + +Differential probe required and ratings checked: + +Probe capacitance and ground lead/spring: + +Connection order and disconnect order: + + +Capture filename/settings: + +Observed result and uncertainty: + + +## Result classification + +Observed fact: + +Inference supported: + +Nearest competing explanation: + +False-positive/negative risk: + +Uncertainty or margin: + +Follow-up test if inconclusive: diff --git a/electronics/templates/schematic-review.md b/electronics/templates/schematic-review.md new file mode 100644 index 0000000..9b84659 --- /dev/null +++ b/electronics/templates/schematic-review.md @@ -0,0 +1,54 @@ +# Schematic-to-bench review + +Project / revision: + +Board / package: + +Source documents and dates: + + +## Nets and limits + +| Net | Source → destination | Return | Pin/polarity | Idle/active | V/I limits | Test point | +|---|---|---|---|---|---|---| +| | | | | | | | + +## Calculations + +Load equation and worst case: + +Driver/thermal check: + +Level translation or isolation: + +Unknown facts requiring datasheet confirmation: + + +## First power + +Current limit: + +Loads disabled: + +Power-off continuity/short checks: + +Expected rail/current/reset observations: + +Stop condition and recovery path: + + +## Stage record + +Unpowered visual result: + +Continuity/short result and meter mode: + +Current limit and first-power readings: + +Idle and active signal readings: + +Identity/readback evidence: + +Reset/power-cycle result: + +Reviewer/date: diff --git a/electronics/templates/sensor-calibration-plan.md b/electronics/templates/sensor-calibration-plan.md new file mode 100644 index 0000000..7cfcd6b --- /dev/null +++ b/electronics/templates/sensor-calibration-plan.md @@ -0,0 +1,43 @@ +# Sensor calibration plan + +## Device and signal chain + +- Exact sensor, revision, package/module, output class: +- Stimulus/input units and engineering-output units: +- Excitation, reference, conditioning, ADC, sample rate, and filters: +- Installation, fixture, orientation, cable, and environmental limits: + +## Reference conditions + +- Standards and traceability: +- Reference points and uncertainty: +- Temperature, supply, warm-up, and stabilization: +- Instrument IDs, ranges, resolution, and calibration status: + +## Procedure + +| Point | Applied reference (units) | Raw output (units) | Repeats | Temperature (units) | Supply (units) | +|---|---:|---:|---:|---:|---:| +| | | | | | | + +- Randomize or repeat order where drift could bias the fit: +- Record warm-up, settling, overrange, disconnect, and recovery: +- Preserve raw data and metadata before fitting: + +## Model and acceptance + +- Fit form and coefficient units: +- Held-out validation points: +- Residual, repeatability, hysteresis, drift, and noise limits: +- Valid range and out-of-range behavior: +- Coefficient storage, version, validity flag, and recalibration trigger: +- Valid fit range in input/temperature units: +- Invalid, disconnected, saturated, and out-of-range row: + +## Release evidence + +- Independent repeat and thermal/supply check: +- Installation-specific verification: +- Fault and diagnostic checks: +- Raw-data path and report link: +- Approver, date, and unresolved limitations: diff --git a/llms.txt b/llms.txt index 3d5ab80..4f00265 100644 --- a/llms.txt +++ b/llms.txt @@ -44,6 +44,7 @@ - [documents](documents/SKILL.md): Generate, inspect, validate, and fix PDF, Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) documents: turn structured content into render-ready artifacts, verify structural and output quality before delivery, and repair broken files. Use when a task involves creating, editing, converting, or validating office documents and PDFs. Do not use for ebook packaging (use epub), for images, video, or other media production, for API or code documentation, or for data pipelines (use data-engineering). - [dsm5](dsm5/SKILL.md): Assess and explain questions about mental health and neurocognitive conditions against DSM-5-TR diagnostic criteria, and guide evidence-based conversations for clinicians, patients, and family members. Use when someone asks about symptoms, possible conditions, differential diagnoses, diagnostic criteria, prevalence, specifiers, or wants to understand or explain a mental health or neurological condition in plain language. Do not use for formal diagnosis, treatment decisions, crisis intervention, legal or insurance determinations, or any situation that requires a licensed clinician's judgment. - [dspy](dspy/SKILL.md): Optimize and build programmatic prompt systems with Stanford DSPy. Signatures, modules (Predict, ChainOfThought, ReAct), optimizer/teleprompter selection, compilation, caching, evaluation. Use when doing programmatic prompt optimization or building compiled prompt programs. Do not use this skill for unrelated requests; route to the nearest named specialist. +- [electronics](electronics/SKILL.md): Design, review, prototype, measure, and troubleshoot electronic circuits using component evidence, worst-case calculations, interface contracts, and staged bench verification. Use for component selection, analog or digital building blocks, power and protection, sensor conditioning, schematic-to-wiring review, instrumented diagnosis, and I2C electrical integration. Do not use as a substitute for exact device documentation, ESP32 firmware operations, FPGA RTL development, named CAD-tool operation, or regulated design certification. - [email](email/SKILL.md): Send and diagnose transactional email through Twilio SendGrid from a terminal or agent: send messages, check deliverability (bounces and spam reports), and verify Signed Event Webhook signatures (ECDSA P-256) — with a bundled email-cli script that is read-only by default and gates every send behind a --dry-run/--yes confirmation. Use when an agent needs to send a transactional email, triage bounces or spam complaints, or confirm an inbound SendGrid webhook is authentic. Do not use for marketing or bulk email campaigns (that is SendGrid Marketing Campaigns), building email template systems, or other email providers (that is their own tooling). - [enterprise-architecture](enterprise-architecture/SKILL.md): Design and evolve enterprise architectures by connecting business capabilities, value streams, applications, information, technology, operating models, and transition choices. Use when mapping an enterprise portfolio, comparing current and target states, sequencing transition architectures, or defining federated architecture decision rights and stakeholder communication. Do not use for system or solution design, API or data-platform design, organizational or talent design, product roadmaps, technology adoption, or corporate strategy; route those to the named specialist skills. - [epub](epub/SKILL.md): Read, write, and edit EPUB2/EPUB3 ebooks as an EPUB file format expert. Extract text, metadata, structure, and knowledge from EPUB files for enrichment or memory. Create valid EPUBs from scratch. Validate against the EPUB specification. Use when the user mentions epub, ebook, EPUB file, ebook format, read epub, write epub, create ebook, extract from epub, epub to text, or ebook structure. Do not use this skill for unrelated requests; route to the nearest named specialist.