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
This commit is contained in:
Fábio Cunha
parent
746d66309b
commit
31c9baede3
6 changed files with 405 additions and 0 deletions
57
.aurelio/README.md
Normal file
57
.aurelio/README.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
# Aurelio Workspace — savearth Flow Meter PCB
|
||||
|
||||
## WHY
|
||||
|
||||
This hardware repository needs the same context, memory, and MCP tooling as the rest of the savearth engineering stack. Keeping a local `.aurelio/` workspace inside the repo means agents and contributors can connect to the central `savearth-workspace` and `savearth-mcp` services, access electrical-analysis MCPs, and sync memory without relying on an external Git submodule.
|
||||
|
||||
## HOW
|
||||
|
||||
The workspace is defined by `.aurelio/config.toml` and `.aurelio/mcp_config.json`. `config.toml` sets the realm (`flow-meter-pcb`), display name, sync endpoint, and default models. `mcp_config.json` declares the MCP servers the local IDE/agent should launch, scoped to hardware work: project/workspace servers, electrical EDA/sourcing servers, knowledge/memory servers, Atlassian, and sequential thinking. `.aurelio/sync.py` pushes and pulls the `brain/` directory to/from the central Proxmox container (CT 208) that hosts the Aurelio brain.
|
||||
|
||||
## WHAT
|
||||
|
||||
### Realm
|
||||
|
||||
- **Name:** `savearth Flow Meter PCB`
|
||||
- **Realm:** `flow-meter-pcb`
|
||||
- **Version:** `2.8.0`
|
||||
|
||||
### Tracked workspace files
|
||||
|
||||
These files are version-controlled and bootstrapped on clone:
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `.aurelio/config.toml` | Workspace identity, sync endpoint, model defaults |
|
||||
| `.aurelio/mcp_config.json` | MCP server declarations for this realm |
|
||||
| `.aurelio/sync.py` | Push/pull `brain/` to the central Aurelio host |
|
||||
| `.aurelio/README.md` | This file |
|
||||
| `.aurelio/realm/AGENTS.md` | Realm-specific agent guide |
|
||||
| `.aurelio/realm/memory/index.md` | Starter memory index |
|
||||
|
||||
### MCP servers
|
||||
|
||||
| Server | Purpose |
|
||||
|---|---|
|
||||
| `savearth-mcp` | Project-specific device and telemetry tools |
|
||||
| `savearth-workspace` | Workspace orchestration and realm lookup |
|
||||
| `electrical-eda-mcp` | Schematic parsing, ERC, power-rail analysis, SPICE |
|
||||
| `electrical-sourcing-mcp` | JLCPCB/LCSC component search, alternates, BOM optimization |
|
||||
| `knowledge-mcp` | General knowledge retrieval |
|
||||
| `codebase-memory-mcp` | Codebase-aware memory and search |
|
||||
| `atlassian-mcp-server` | Jira/Confluence integration |
|
||||
| `sequential-thinking` | Structured reasoning helper |
|
||||
|
||||
### Sync commands
|
||||
|
||||
```bash
|
||||
# Pull the latest central brain into the local workspace
|
||||
python3 .aurelio/sync.py --pull
|
||||
|
||||
# Push local brain changes to the central workspace
|
||||
python3 .aurelio/sync.py --push
|
||||
```
|
||||
|
||||
### Ignored state
|
||||
|
||||
Runtime brain artifacts, session memory, and auto-generated logs live under `.aurelio/brain/` and `.aurelio/memory/` and are ignored by Git. Only the bootstrap files listed above are tracked.
|
||||
19
.aurelio/config.toml
Normal file
19
.aurelio/config.toml
Normal file
|
|
@ -0,0 +1,19 @@
|
|||
[identity]
|
||||
name = "savearth Flow Meter PCB"
|
||||
realm = "flow-meter-pcb"
|
||||
version = "2.8.0"
|
||||
|
||||
[sync]
|
||||
enabled = true
|
||||
endpoint = "https://mcp.portugalfuturista.org"
|
||||
interval_seconds = 300
|
||||
auto_push = true
|
||||
|
||||
[models]
|
||||
default_local = "qwen2.5-coder:14b"
|
||||
default_cloud = "gemini-2.5-pro"
|
||||
ollama_url = "http://127.0.0.1:11434"
|
||||
|
||||
[brain]
|
||||
auto_save = true
|
||||
artifact_types = ["task", "implementation_plan", "walkthrough", "analysis"]
|
||||
81
.aurelio/mcp_config.json
Normal file
81
.aurelio/mcp_config.json
Normal file
|
|
@ -0,0 +1,81 @@
|
|||
{
|
||||
"mcpServers": {
|
||||
"savearth-mcp": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://savearth-mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false,
|
||||
"disabledTools": []
|
||||
},
|
||||
"savearth-workspace": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://savearth-workspace.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false,
|
||||
"disabledTools": []
|
||||
},
|
||||
"electrical-eda-mcp": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://electrical-eda-mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false,
|
||||
"disabledTools": []
|
||||
},
|
||||
"electrical-sourcing-mcp": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://electrical-sourcing-mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"env": {},
|
||||
"_disabled": false,
|
||||
"disabledTools": []
|
||||
},
|
||||
"knowledge-mcp": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://knowledge-mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false
|
||||
},
|
||||
"codebase-memory-mcp": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://codebase-memory-mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false
|
||||
},
|
||||
"sequential-thinking": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-sequential-thinking"
|
||||
],
|
||||
"type": "npx",
|
||||
"_disabled": false
|
||||
},
|
||||
"atlassian-mcp-server": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"mcp-remote",
|
||||
"https://atlassian.mcp.portugalfuturista.org/sse"
|
||||
],
|
||||
"_disabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
154
.aurelio/realm/AGENTS.md
Normal file
154
.aurelio/realm/AGENTS.md
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
<!-- This realm corresponds to the `savearth-hw-project` repository. -->
|
||||
<!-- The canonical central brain project/realm name is `flow-meter-pcb`. -->
|
||||
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
30
.aurelio/realm/memory/index.md
Normal file
30
.aurelio/realm/memory/index.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
# Realm Memory Index — flow-meter-pcb
|
||||
|
||||
## Purpose
|
||||
|
||||
This index anchors the local Aurelio workspace for the savearth Flow Meter PCB realm. It points agents to the canonical directories, conventions, and related repositories so hardware changes stay aligned with firmware, manufacturing, and cloud teams.
|
||||
|
||||
## Key directories
|
||||
|
||||
| Directory | Purpose |
|
||||
|---|---|
|
||||
| `hardware/v2.8/` | Active EasyEDA Pro production design, BOM, manufacturing outputs, parsed data |
|
||||
| `hardware/v2.9/` | Placeholder for next mitigation spin |
|
||||
| `hardware/common/` | Shared KiCad/EasyEDA libraries and automation scripts |
|
||||
| `docs/` | Analysis, guides, meeting notes, and reports |
|
||||
| `hardware/common/scripts/` | BOM extraction, JLCPCB CSV generation, KiCad conversion |
|
||||
|
||||
## Important conventions
|
||||
|
||||
- Active production design is **v2.8**; next spin is **v2.9**.
|
||||
- Use scripts in `hardware/common/scripts/` for repeatable BOM extraction and library conversion; do not hand-edit generated JSON/CSV files unless the source EDA project has changed.
|
||||
- Maintain parity between markdown docs in `docs/` and Confluence pages in the Hardware space.
|
||||
- Branch names use the `HW-<number>-<description>` prefix to match the firmware repo's `FW-` prefix.
|
||||
|
||||
## Related repositories
|
||||
|
||||
| Repository | Local path | Role |
|
||||
|---|---|---|
|
||||
| `aws-iot-core-poc` | `../aws-iot-core-poc` | Firmware and BSP |
|
||||
| `savearth-iot-infrastructure` | `../savearth-iot-infrastructure` | Cloud backend |
|
||||
| `hardware-devicesFirmwareTest` | `../hardware-devicesFirmwareTest` | Assembly-house test station |
|
||||
64
.aurelio/sync.py
Executable file
64
.aurelio/sync.py
Executable file
|
|
@ -0,0 +1,64 @@
|
|||
#!/usr/bin/env python3
|
||||
import os
|
||||
import argparse
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# Config
|
||||
VM_IP = "192.168.0.38"
|
||||
CONTAINER_ID = 208
|
||||
TARGET_DIR = "/opt/pf-services-208/gabinete/.aurelio/brain"
|
||||
LOCAL_BRAIN = Path(__file__).parent / "brain"
|
||||
|
||||
def run_cmd(cmd: str):
|
||||
print(f"Running: {cmd}")
|
||||
result = subprocess.run(cmd, shell=True)
|
||||
if result.returncode != 0:
|
||||
print(f"Error executing: {cmd}")
|
||||
sys.exit(result.returncode)
|
||||
|
||||
def push():
|
||||
print("Pushing local brain to CT 208 Gabinete...")
|
||||
# Tar local brain
|
||||
if not LOCAL_BRAIN.exists():
|
||||
print("Local brain does not exist. Nothing to push.")
|
||||
return
|
||||
|
||||
run_cmd(f"tar czf /tmp/local_brain.tar.gz -C {LOCAL_BRAIN.parent} brain")
|
||||
run_cmd(f"scp /tmp/local_brain.tar.gz root@{VM_IP}:/tmp/")
|
||||
|
||||
# Copy archive into container and extract inside the container
|
||||
run_cmd(f"ssh root@{VM_IP} 'pct push {CONTAINER_ID} /tmp/local_brain.tar.gz /tmp/local_brain.tar.gz'")
|
||||
run_cmd(f"ssh root@{VM_IP} 'pct exec {CONTAINER_ID} -- bash -c \"mkdir -p {TARGET_DIR} && tar xzf /tmp/local_brain.tar.gz -C /opt/pf-services-208/gabinete/.aurelio/\"'")
|
||||
print("Push complete.")
|
||||
|
||||
def pull():
|
||||
print("Pulling central brain from CT 208 Gabinete to local workspace...")
|
||||
# Tar remote brain
|
||||
run_cmd(f"ssh root@{VM_IP} 'pct exec {CONTAINER_ID} -- bash -c \"mkdir -p {TARGET_DIR} && tar czf /tmp/remote_brain.tar.gz -C /opt/pf-services-208/gabinete/.aurelio/ brain\"'")
|
||||
run_cmd(f"ssh root@{VM_IP} 'pct pull {CONTAINER_ID} /tmp/remote_brain.tar.gz /tmp/remote_brain.tar.gz'")
|
||||
run_cmd(f"scp root@{VM_IP}:/tmp/remote_brain.tar.gz /tmp/")
|
||||
|
||||
# Extract locally
|
||||
if not LOCAL_BRAIN.exists():
|
||||
LOCAL_BRAIN.mkdir(parents=True)
|
||||
run_cmd(f"tar xzf /tmp/remote_brain.tar.gz -C {LOCAL_BRAIN.parent}")
|
||||
print("Pull complete.")
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Aurelio Sync Utility")
|
||||
parser.add_argument("--push", action="store_true", help="Push local brain to central server")
|
||||
parser.add_argument("--pull", action="store_true", help="Pull central brain to local workspace")
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.push:
|
||||
push()
|
||||
elif args.pull:
|
||||
pull()
|
||||
else:
|
||||
parser.print_help()
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Loading…
Reference in a new issue