Skip to content

docs(hardware): esquemáticos eléctricos + guía de montaje#20

Open
Pablomonte wants to merge 6 commits into
mainfrom
docs/hardware-schematics
Open

docs(hardware): esquemáticos eléctricos + guía de montaje#20
Pablomonte wants to merge 6 commits into
mainfrom
docs/hardware-schematics

Conversation

@Pablomonte
Copy link
Copy Markdown
Collaborator

@Pablomonte Pablomonte commented May 27, 2026

Resumen

Documentación de hardware completa para la carpeta HardWare/, con 6 esquemáticos eléctricos generados programáticamente con schemdraw (Python → SVG) y un README con pinout, BOM, power budget y troubleshooting.

Esquemáticos

Archivo Contenido
sch_esp32_pinout.svg Pinout ESP32 S v1.1 (32 pines / 3×GND) con funciones color-coded
sch_i2c_sensors.svg Bus I2C: SCD30 (0x61) + BME280 (0x76) con pull-ups 4.7kΩ
sch_onewire.svg Bus OneWire: DS18B20 ×N con pull-up 4.7kΩ obligatorio
sch_adc_soil.svg ADC suelo: capacitivo + HD38 con doble Schottky clamp (3.3V + GND)
sch_rs485_modbus.svg RS485 Modbus: MAX485 + sensor TH + relay 2CH, con bias 560Ω y terminación 120Ω
sch_full_system.svg Diagrama de bloques del sistema completo

Documentación (README.md)

  • 📌 Tabla de pinout GPIO
  • 🔌 Conexiones por bus
  • 📦 BOM (Bill of Materials)
  • ⚡ Power budget (~340mA pico)
  • ⚠️ Known risks — sobretensión ADC en HD38 (5V → GPIO35) con circuito de protección
  • 🔧 Troubleshooting
  • 🔗 Cross-links al firmware

Tooling reproducible

  • generate_schematics.py — script canónico
  • requirements.txt — schemdraw==0.22 (pinned)
  • Makefile — make setup / schematics / clean / help
  • .gitignore — ignora HardWare/.venv/

Calidad de los diagramas

Todos los esquemáticos usan routing ortogonal (sin líneas diagonales ni superposiciones), bias resistors RS485 dibujadas explícitamente, y conexiones borde-a-borde en el diagrama de bloques. Verificados visualmente renderizando cada SVG.

Verificación

cd HardWare
make setup
make schematics   # → 6 SVG sin errores

Nota de hardware: el clamp dual Schottky en GPIO35 y las bias resistors RS485 son recomendaciones de diseño; verificar contra el montaje físico actual antes de fabricar.

🤖 Generated with Claude Code

Pablomonte and others added 3 commits May 27, 2026 17:05
@Pablomonte @claude
docs(hardware): add HardWare schematics + montaje docs
59447fd 
Documentación de hardware generada programáticamente con schemdraw:

- 6 esquemáticos SVG: pinout ESP32, I2C (SCD30+BME280), OneWire (DS18B20),
  ADC suelo (capacitivo + HD38 con doble Schottky clamp), RS485 Modbus
  (MAX485 + sensor TH + relay 2CH con bias y terminación), y diagrama
  de bloques del sistema completo
- README.md: pinout, conexiones por bus, BOM, power budget, known risks
  (sobretensión ADC HD38), troubleshooting y cross-links al firmware
- generate_schematics.py: script reproducible (make schematics)
- requirements.txt: schemdraw==0.22 (pinned)
- Makefile: targets all/setup/schematics/clean/help
- .gitignore: ignora HardWare/.venv/

Esquemáticos con routing ortogonal (sin diagonales ni superposiciones),
bias resistors RS485 dibujadas, y conexiones borde-a-borde en el diagrama
de bloques.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Pablomonte @claude
fix(hardware): pinout fiel al ESP32 DevKit V1 de 30 pines
4abd1ee 
El pinout anterior tenía el orden físico de pines inventado y conteos
incorrectos (31/32 pines, 3xGND). Corregido al layout real del DevKit V1
(board=esp32dev / WROOM-32): 30 pines, 15 por lado, 2xGND, orden físico
top->bottom verificado.

- generate_schematics.py: pinout reescrito con orden físico real; usa
  anchorname para mostrar 'GND' en ambos lados; título arriba del IC
- README.md: 30 pines / 2xGND; nota de variante de placa (30 vs 38 pines);
  BOM actualizado
- Diagrama de bloques: 'ESP32 DevKit V1 / 30 pines'

Las asignaciones GPIO<->función (I2C 21/22, OneWire 4, ADC 34/35,
RS485 16/17/18) ya eran correctas — provienen del firmware.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@Pablomonte @claude
fix(hardware): C25B (MAX485) a 5V con divisor obligatorio en RO
7db3d02 
El esquematico anterior mostraba el modulo MAX485 alimentado a 3.3V,
pero el modulo real es un C25B (MAX485 azul basico sin level-shift),
que requiere 5V y entrega RO ~5V — incompatible con el GPIO16 del
ESP32 (max 3.6V) sin proteccion.

generate_schematics.py:
- MVCC del MAX485: 3.3V -> 5V
- RX line: divisor 1kOhm serie + 2kOhm pulldown entre RO y GPIO16
  (5V x 2k/3k = 3.33V en el tap, dentro del rango del ESP32)
- Gap ESP32<->MAX485 aumentado (5 -> 7) para acomodar el divisor
- Nota inferior actualizada con la alimentacion 5V y el divisor

README.md:
- Tabla pinout GPIO16: nota del divisor obligatorio
- Conexiones RS485: filas para R1 1k y R2 2k del divisor + advertencia
- BOM: agrega 1k y 2k como **obligatorios**; renombra MAX485 -> C25B;
  segundo Schottky BAT43 (clamp HD38 a GND) ahora con cantidad 2
- Power budget: C25B se alimenta del rail 5V (VIN), no del 3.3V
- Known Risks: nueva seccion CRITICO con el circuito del divisor
- Troubleshooting: 3 entradas nuevas (C25B a 3.3V no transmite,
  falta divisor, ESP32 danado al conectar)

Las entradas DI/DE/RE del MAX485 aceptan 3.3V del ESP32 sin level
shifter (VIH=2V), solo RO necesita el divisor.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
javierbrk
javierbrk requested changes May 28, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

creo que falta madurar pero me parece una herramienta muy interesante

Comment thread HardWare/schematics/sch_adc_soil.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tenemos alguna referencia para este diseño ? es valido ?

Comment thread HardWare/schematics/sch_esp32_pinout.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

esta parece util pero quedaron lejos las etiquetas de los pines

Comment thread HardWare/schematics/sch_full_system.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tenemos un bloque grafana conectado en el diagrama en bloques, cual es el publico objetivo del diagrama. Creo que seria mas util dejarlo para el hw solamente

Comment thread HardWare/schematics/sch_i2c_sensors.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

estas resistencias no las estamos usando... deberian estar ?

Comment thread HardWare/schematics/sch_onewire.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

las vdd no estan bien conectadas

Comment thread HardWare/schematics/sch_rs485_modbus.svg
Copy link
Copy Markdown
Contributor

@javierbrk javierbrk May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

aca veo unas resistencias que tampoco usamos en Ro

@Pablomonte @claude
fix(hardware): aplicar reviews PR #20 — esquematicos fieles al HW real
3898264 
Reviews de @javierbrk (CHANGES_REQUESTED):
- I2C: pull-ups 4.7k externos no estan en el HW (los modulos los traen)
- OneWire: VDDs no estaban bien conectadas
- ADC: clamp doble Schottky no esta construido
- RS485: divisor 1k/2k en RO no esta; bias 560Ω tampoco
- Full system: bloque Grafana es software, no va en HW
- Pinout: etiquetas de funcion muy lejos del IC

Politica cero falopa: el esquematico refleja el HW real, no recomendaciones.
Si un componente no esta instalado, se elimina del schema, BOM, conexiones,
Known Risks y troubleshooting. Sin sub-tablas 'recomendado para v2'.

generate_schematics.py:
- I2C: sin pull-ups externos (los modulos SCD30/BME280 los traen)
- OneWire: rails comunes 3.3V/GND visibles, sensores con DQ arriba y power
  cableado a rails con simbolos Vdd/Ground claros
- ADC: cajas para HD38 y capacitivo con pines VCC/AOUT/GND. Sin clamp.
  Warning factual sobre AO del HD38 >3.3V. Pinspacing=6.5 para evitar
  superposiciones entre power rails de los 2 sensores
- RS485: rediseñado para reflejar el cableado real
  * Bus UTP 4 conductores: VCC (5-30V) + GND + A+ + B-, lineas paralelas
    color-coded
  * 2 borneras x4 (TH y Relay) como bloques visuales con dots en las 4
    lineas y cables al dispositivo
  * Terminacion 120Ω al final del bus (entre A+ y B-) — SÍ instalada
  * Sin divisor 1k/2k, sin bias 560Ω (no estan en este HW)
- Full system: sin Grafana/cloud, GPIO Relays conectado al ESP32 con
  rango configurable (UI 0-39, libres 13/19/23/25-27/32/33).
  Layout en 3 columnas con 5V USB centrado debajo, conexion vertical pura
- Pinout: labels de funcion acercadas (offset 4.2 -> 2.0)

README.md:
- Tabla pinout: sin 'via divisor', sin 'requiere proteccion'
- Conexiones RS485: nueva estructura ESP32↔C25B / bus UTP / nodos+borneras
- ADC: HD38 y capacitivo directos (sin 10k serie)
- BOM: removidos Schottky BAT43, R 10k clamp, R 1k/2k divisor, R 560Ω bias.
  Agregados cable UTP 4 pares y borneras x4. R 120Ω queda (sí instalado)
- Known Risks: warnings factuales, sin diagramas ASCII de mitigaciones
- Troubleshooting: removidas entradas que asumen componentes no instalados

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@Pablomonte
Copy link
Copy Markdown
Collaborator Author

Pablomonte commented May 29, 2026

Gracias por las correciones, ahí está mejorando..

Pablomonte and others added 2 commits June 1, 2026 01:23
@Pablomonte @claude
style(hardware): profesionalizar presentacion de los esquematicos
71e1aed 
Mejoras de presentacion (sin cambiar componentes ni conexiones):

- Sistema de titulo/nota por bounding box real (add_title/add_footer):
  centrados, nunca se solapan; titulo con linea separadora estilo datasheet
- Paleta de color centralizada y consistente entre los 6 esquemas
  (un color por senal: I2C, 1-Wire, ADC, RS485 TX/RX/DE, A+/B-, VCC, GND, GPIO)
- RS485: bus UTP 4 conductores (VCC/GND/A+/B-), borneras x4 por nodo,
  terminacion 120 ohm al final del bus
- Pinout: etiquetas de funcion alineadas al borde del pin (estilo datasheet);
  colores alineados a la paleta; sin doble titulo ni label central solapado
- OneWire: VDD/GND legibles sobre rails comunes coloreados
- ADC: cajas de sensor sin solape de labels; caja ESP32 compacta;
  HD38 (5V, rojo) vs capacitivo (3.3V, teal) diferenciados
- Full system: GPIO Relays conectado con rango de pines configurables;
  sin bloque Grafana (solo HW)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Pablomonte @claude
refactor(hardware): usar schemkit para paleta y helpers de esquematicos
24d6cc6 
generate_schematics.py ya no define localmente la paleta de color ni los
helpers add_title/add_footer: los importa de schemkit
(https://github.com/Pablomonte/schemkit), la utilidad dibujadora extraida
como repo independiente y reutilizable.

- requirements.txt: agrega schemkit via git URL
- generate_schematics.py: reemplaza el bloque de framework local por import

Salida SVG byte-identica a la version anterior (refactor sin cambios visuales).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@javierbrk javierbrk javierbrk requested changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Pablomonte @javierbrk