portugalfuturista/sistemas-cibernetico-fisicos
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sistemas-cibernetico-fisicos/.aurelio/realm/AGENTS.md
Fábio Cunha 31c9baede3 feat(aurelio): bootstrap flow-meter-pcb realm workspace 
- Add .aurelio/config.toml, mcp_config.json, sync.py, README.md

- Seed .aurelio/realm/AGENTS.md and memory/index.md
2026-07-05 20:24:26 +01:00

7.6 KiB
Raw Blame History

Agent Guide: savearth — Flow Meter PCB Repository

Current Status

Last Updated: 2026-07-04
Status: Realm refreshed and formally onboarded into the Hybrid Memory Engine. Active production design is v2.8 in EasyEDA Pro. Next revision v2.9 is in planning.
Repository: SavearthTech/savearth-hw-project
Workspace identity: savearth Flow Meter PCB (flow-meter-pcb)

Recent additions (last 8 weeks):

  • v2.9 placeholder structure + mitigation plan (docs/v2.9_mitigation_plan.md).
  • v2.8 hardware analysis and flashing-fix documentation.
  • Hardware meeting agenda capturing v2.8 field issues and v2.9 decisions.
  • Version-agnostic extraction scripts (hardware/common/scripts/).
  • KiCad library export pipeline (hardware/common/kicad_libs/).

Repository Purpose

This repository houses the PCB design files for the savearth smart shower water-monitoring device. It tracks the complete hardware evolution from Altium Designer (v1.0–v2.7) through EasyEDA Pro (v2.8+), including schematics, PCB layouts, BOMs, Gerber manufacturing files, and 3D models.

Architecture Overview

Active Design Tool: EasyEDA Pro (v2.8 onwards)

  • Primary project file: hardware/v2.8/easyeda/Savearth GBT.eprj
  • Schematics: Savearth SCH ESP32 v2_8.epro, Savearth SCH Power v2_8.epro
  • Integrated with JLCPCB manufacturing pipeline
  • Component library: hardware/common/easyeda_libs/
  • Backups stored in hardware/v2.8/easyeda/Savearth GBT_backup/

Legacy Design Tool: Altium Designer (v1.0–v2.7)

  • v2.7 schematics: hardware/v2.7/altium/Savearth_v2_7/*.schdoc
  • v2.7 PCB layout: hardware/v2.7/altium/Savearth_v2_7/Savearth_v2_7.pcbdoc
  • Older versions in hardware/v{xx}/altium/

Component Knowledge Base

  • Aggregated cross-version data: hardware/savearth_hw_knowledge.json
  • Per-version BOMs: hardware/v{xx}/bom/bom_v{xx}.json
  • JLCPCB CSVs: hardware/v{xx}/bom/bom_v{xx}_jlcpcb.csv

Key Subsystems (v2.8)

Subsystem Components Firmware Driver
ESP32-S3 MCU ESP32-S3-WROOM-1-N8R8, USB-C, flash, antenna main/ FSM core
Power Management BQ25895RTWR charger, AP2112K-3.3 LDO, DW01 battery protection, MIC94073 load switch components/bq25895/, power_manager.c
IO Expansion PCAL9538ABSHP I2C GPIO expander components/bsp/, components/pcal9538a/
Flow Sensor 59170-1-S-00-D hall-effect pulse sensor flow_meter_task.c
Audio / ML ICS-43434 I2S digital MEMS microphone I2S audio pipeline / TFLite Micro
Motion Detection PIR sensor (GPIO44) FSM state_sleep_entry()
User Interface LEDs, slide switch SS12D00G3, push-button LED/button tasks
Display 40-pin FPC connector HC-FPC-0.5-40P-FH20 for ST7701S LCD components/lcd_driver/ST7701S.c, main/tasks/lcd_task.c
USB HYCW396-USBC16-712B USB-C connector Native USB Serial/JTAG
Debug/Factory 1×6 1.27 mm header HX PZ1.27-1x6P WZ CON header

Agent Operational Directives

File Handling

  • Binary files dominate. Most design files (.eprj, .epro, .schdoc, .pcbdoc, .step, .elibz, .xlsx, Gerber .zip) cannot be diffed or parsed as text.
  • Use the extracted JSON in hardware/v{xx}/parsed_data/ for automated analysis:
    • bom_extended.json — structured BOM
    • netlist.json — netlist
    • schematic_raw.json — raw schematic data
  • Use the aggregated knowledge base hardware/savearth_hw_knowledge.json for cross-version component lookups.

Component Sourcing

  • The electrical-sourcing-mcp server (CT 208, port 8081) can search the JLCPCB 2.5M+ component catalog against BOM entries.
  • Use search_local_library, get_component_details, and find_alternates for sourcing and cost optimization.
  • Current limitation (2026-07-04): The local JLCPCB database appears unpopulated and Octopart API calls are failing with HTTPStatusError. Component lookups return zero results. See realms/flow-meter-pcb/.aurelio/memory/mcp-electrical-validation.md for the full test report.

Schematic / EDA Analysis

  • The electrical-eda-mcp server (CT 208, port 8082) provides parse_schematic, extract_bom, analyze_power_rails, run_erc, and SPICE conversion/simulation tools.
  • These tools expect native schematic files (KiCad, EasyEDA, Altium, EAGLE, PSIM). Binary .eprj/.schdoc must be exported to a supported format first.
  • KiCad export pipeline: hardware/common/scripts/convert_to_kicad.py.

Cross-Repository Coordination

  • Hardware version changes in this repo must be reflected in firmware main/hardware_config.c and main/hardware_config.h.
  • New sensor additions require corresponding firmware driver implementations in aws-iot-core-poc.
  • Pin assignment changes affect GPIO mapping in firmware.

Branch Naming Convention

  • Feature branches use Jira ticket prefix: HW-<number>-<description>
  • This aligns with the FW- prefix used in the firmware repo.

Available MCP Tools for This Realm

Tool Server Use Case
search_local_library electrical-sourcing-mcp Find JLCPCB component alternatives
get_component_details electrical-sourcing-mcp Get specs/pricing/stock by C-number or MPN
search_components electrical-sourcing-mcp Multi-source distributor search
find_alternates electrical-sourcing-mcp Form-fit-function alternatives
generate_optimized_bom electrical-sourcing-mcp Cost-optimized BOM generation
analyze_component_alternatives electrical-sourcing-mcp Formalized alternative analysis
parse_schematic electrical-eda-mcp Parse schematic files
extract_bom electrical-eda-mcp Extract BOM from schematic
analyze_power_rails electrical-eda-mcp Analyze power rails and decoupling
run_erc electrical-eda-mcp Electrical rule checks
convert_schematic_to_spice electrical-eda-mcp Convert schematic to SPICE netlist
run_spice_simulation electrical-eda-mcp Run SPICE simulation

Important Notes

  • .gitignore is correct at the top level. The old .giignore typo noted in earlier realm memory has been fixed.
  • .gitattributes marks EasyEDA binaries, manufacturing outputs as binary, and KiCad files as text.
  • Altium project references external paths: hardware/v2.0/altium/flow_meter.PrjPcb points to ..\..\Savearth2\Savearth_v2_6\ outside the repository. This file is legacy and not operationally relevant.
  • KiCad export: A generated KiCad library exists under hardware/common/kicad_libs/, but the full KiCad project is not yet committed.
  • Supply-chain risks: ICS-43434 EOL, Si2302 NRFND, USB-C connector alternatives — all documented under docs/reports/.

Terminal Output Capture Rule

MANDATORY: Follow the same .agentlog pattern as other savearth repositories.

# CORRECT:
git status --short > /tmp/fmpcb_status.agentlog 2>&1
# Then read with view_file

Git Commit Rules

Use conventional commit format with hardware scope:

feat(hw): add v2.9 schematic with improved power path
fix(bom): correct R12 value from 10k to 4.7k
docs(gerber): export v2.8 rev2 manufacturing files
chore(cleanup): remove duplicate documentation folder

Related Realms

  • smart-device-firmware — ESP32-S3 firmware that implements drivers for every subsystem in this PCB.
  • iot-backend — AWS IoT backend that receives telemetry from devices built with this PCB.
  • nervura-electrica — Hosts the electrical MCP servers used to analyze this realm's BOMs and schematics.