MechaLeveling: autonivelación y fresado de PCB para CNC 3018

Sondea el cobre con el probe de tu CNC, compensa el G-code y fresa placas de circuito impreso parejas. Funciona con FluidNC o GRBL y usa pcb2gcode como motor CAM.

KiCad → Gerber → MechaLeveling → CNC 3018

Descargar · Instalar desde el código · Flujo de trabajo · Conectar por WiFi · Hardware · Problemas conocidos · English

---

Qué problema resuelve

Una placa de cobre nunca es plana: entre 0,3 y 0,6 mm de alabeo es lo normal, y un corte de aislación tiene apenas 0,07 mm de profundidad. Por eso en una CNC chica las pistas salen cortadas de un lado y sin tocar del otro.

MechaLeveling sondea el cobre con el probe de la propia máquina (G38.2), arma un modelo de la superficie y reescribe tu G-code para que el V-bit siga la altura real en cada punto. Además hace el paso CAM completo desde una pestaña: le entregas los Gerber de KiCad y te devuelve el G-code listo.

Qué hace

• Escaneo de superficie sobre una grilla configurable (15x12 por defecto), interpolación RBF (SciPy), guardado automático por fila, reescaneo de puntos sueltos, detección de outliers.
• Compensación en Z de cualquier G-code (pcb2gcode, FlatCAM, KiCad, Fusion): los movimientos largos se parten en segmentos de 0,5 mm y cada uno recibe su propia Z.
• Pestaña PCB: eliges el Gerber de cobre y el Excellon de taladros, un perfil, y aprietas Generar. Salen la aislación, los taladros (un archivo por broca), el NPTH y el contorno, validados y listos para la cola de nivelación.
• Envío por USB o WiFi con pausa, reanudar, detener, parada de emergencia, override de avance, husillo y Z en vivo, reinicio desde una línea.
• Ejecución autónoma desde la SD (solo FluidNC): subes el archivo y la máquina lo fresa sola, sin computador conectado.
• Dos modos de placa: S (una placa de 200x150) y L (300x200, dos placas pegadas, necesita un eje X de 305 mm).
• Health check antes de cada trabajo, estimación de tiempo, historial de trabajos, repaso por zonas pintadas.

Pestaña Nivelar	Pestaña PCB (pcb2gcode)
Grilla, parámetros del probe, escaneo, aplicar un mapa guardado	Gerber y Excellon de entrada, G-code nivelado de salida

Descargar para Mac

En Releases hay un .dmg listo para usar (macOS 12 o superior, Apple Silicon e Intel):

1. Abre el .dmg y arrastra MechaLeveling.app a Aplicaciones.
2. La primera vez, clic derecho sobre la app y Abrir (la app no está firmada con Apple, así que macOS pide confirmación solo esa vez).
3. Para la pestaña PCB instala pcb2gcode con Homebrew: brew install pcb2gcode. Todo lo demás (escaneo, nivelación, fresado) funciona sin él.

Tus datos (configuración, mapas, historial, logs, G-code generado) quedan en ~/Library/Application Support/MechaLeveling.

En Linux y Windows se corre desde el código fuente: ver INSTALL.md.

Compatibilidad

Función	GRBL 1.1 (USB)	FluidNC (USB o WiFi)
Escaneo con probe, mapa de alturas, compensación Z	sí	sí
Envío de G-code, overrides, parada de emergencia	sí	sí
Conexión WiFi (telnet) y búsqueda en la red	no	sí
Subir a SD y ejecutar sin computador	no	sí
Cambiar la red WiFi desde la app (cambiar_wifi.py)	no	sí

Desarrollado y usado a diario en una TwoTrees 3018 con placa MKS DLC32 y FluidNC. Cualquier placa ESP32 con FluidNC debería comportarse igual. Las placas con GRBL 1.1 funcionan por USB para todo menos WiFi y SD.

Flujo de trabajo

1. Conectar. USB: elige el puerto serial. WiFi: escribe host:23 o aprieta Escanear para encontrar FluidNC en tu red (ver la sección siguiente). El health check te dice si la máquina está en Idle, si el probe lee bien y si el mapa cargado coincide con el modo de placa.
2. Pestaña PCB (opcional, necesita pcb2gcode). Selecciona el Gerber de cobre, el drill PTH y, si los tienes, el contorno y el NPTH. Elige los perfiles de aislación, taladro y corte. Generar. Los .nc quedan en pcb_output/ y se mandan a la cola de nivelación con un clic.
3. Cero. Lleva la máquina al origen de la placa, toca el cobre con la fresa y fija el cero de X, Y y Z (o usa Probe Z con el clip en el cobre).
4. Escanear. Pestaña Nivelar, Escanear superficie. El probe visita cada punto de la grilla y el mapa se guarda después de cada fila. El escaneo puede pausarse a la mitad para que muevas el clip del probe.
5. Nivelar. Nivelar archivos crea una copia _NIVELADO.nc de cada archivo de la cola con la compensación aplicada. Revisa el preview.
6. Fresar. Iniciar cola envía los archivos en orden (aislación, taladros, contorno) y pide el cambio de broca entre uno y otro. Con FluidNC puedes en cambio subir a la SD y dejar que la máquina trabaje sola.

El orden de herramientas y las profundidades salen de cinco perfiles de material (V-bit de 60° y 45°, brocas de 0,8 y 1,0 mm, contorno). Son diccionarios simples al inicio de app.py y en profiles.py: ajústalos a tus fresas y placas.

Conectar la CNC por WiFi

FluidNC tiene WiFi propio, pero hay que decirle a qué red conectarse. El computador y la CNC tienen que estar en la misma red (si mueves la máquina a otro lugar, hay que repetir esto con la red nueva).

Opción A, desde la app (recomendada). Conecta la CNC por USB y corre en la Terminal, dentro de la carpeta del código:

python3 cambiar_wifi.py

Te pide el nombre de la red, la clave (no se muestra mientras la escribes ni se guarda en ningún archivo) y un nombre para la máquina. Reinicia el ESP32 y te muestra la IP que le tocó.

Opción B, desde el punto de acceso de FluidNC. Recién instalado, FluidNC levanta su propia red WiFi (nombre FluidNC, IP 192.168.4.1). Conéctate a ella desde el computador, abre http://192.168.4.1 en el navegador, y en la pestaña WiFi de la WebUI escribe el nombre y la clave de tu red, modo STA. Guarda y reinicia.

Después, en MechaLeveling: en la pestaña Conexión elige WiFi TCP. El host por defecto es fluidnc.local:23. Si tu red no resuelve nombres .local, aprieta Escanear: la app prueba tu subred (puertos 23, 8080 y 81) y te muestra las máquinas que responden como FluidNC. Aprieta Guardar IP para que la recuerde. Las IP guardadas quedan en config_user.json, en tu computador, nunca en el repositorio.

Si la máquina cambia de IP (DHCP), Escanear la vuelve a encontrar. Si dejó de conectarse después de cambiar la clave del WiFi, repite la opción A.

Hardware necesario

• CNC 3018 (o cualquier router chico) con entrada de probe. Se usa el pin de probe del firmware: gpio.22 en la MKS DLC32, A5 en un Arduino Uno con GRBL.
• Cableado del probe: una pinza al cobre de la placa y la otra a la fresa. G38.2 se detiene en el instante en que se tocan.
• V-bits con punta de 0,1 mm, brocas de 0,8 y 1,0 mm, una fresa de 1 a 3,2 mm para el contorno. Todo esto, y la 3018 misma, lo encuentras en mechatronicstore.cl.

Hay una configuración de ejemplo de FluidNC para la MKS DLC32 en examples/fluidnc/. El detalle del cableado y cómo verificar la polaridad del probe está en docs/hardware.md.

Seguridad

MechaLeveling mueve una fresa girando. Lee docs/KNOWN_ISSUES.md antes de confiarle una placa que te importe. Ten la parada de emergencia física a mano, no dejes sola una ejecución desde SD en su primer corte, y configura tú mismo $20/$21 (límites): la app nunca los cambia.

La app no guarda claves de WiFi ni credenciales de ningún tipo. Lo único que persiste en tu computador es la lista de IP de confianza y tus mapas.

Estructura del proyecto

app.py                interfaz y orquestación (CustomTkinter)
grbl_serial.py        conexión FluidNC / GRBL (serial y telnet), búsqueda en la red
probe.py              grilla de sondeo, escaneo en zigzag, guardar/cargar JSON
heightmap.py          modelo de superficie (RBF thin plate spline)
gcode_modifier.py     compensación Z, segmentación, pie de seguridad
gcode_sender.py       envío con pausa / reanudar / detener / overrides
sd_manager.py         subida a SD y ejecución autónoma (FluidNC)
zone_filter.py        repaso por zonas pintadas
health_check.py       chequeos previos al trabajo
pcb_integration.py    pipeline de la pestaña PCB: validar, explorar offset, correr, publicar
pcb2gcode_runner.py   subproceso pcb2gcode (búsqueda del binario, versión, vigilante)
pcb_profiles.py       traducción perfil -> .millproject
pcb_validate.py       validación de Gerber y Excellon
excellon_parser.py    parser de taladros para el resumen de la UI
paths.py              carpetas de datos y utilidades por plataforma
cambiar_wifi.py       cambiar la red WiFi del ESP32 por USB
packaging/            script para armar el .app y el .dmg de macOS
tests/                432 tests, sin hardware

Desarrollo

pip install -r requirements-dev.txt
python -m pytest tests/ -q      # 432 tests, unos 15 s
ruff check .

Los tests marcados slow corren el binario real de pcb2gcode sobre la placa demo sintética de tests/fixtures/ y se saltan solos si no está instalado. Nada de la suite abre un puerto serial. Ver CONTRIBUTING.md.

Licencia y créditos

Código bajo licencia MIT, copyright 2026 MechatronicStore.

• pcb2gcode (GPLv3) hace la geometría CAM. Se invoca como programa aparte y no viene incluido: lo instalas tú.
• FluidNC, GRBL, CustomTkinter, NumPy, SciPy, Pillow, pySerial.

Hecho en Curicó, Chile, por MechatronicStore, tienda de electrónica, Arduino, impresión 3D y robótica educativa. Si tienes dudas del proyecto, abre un issue.

---

English

PCB autoleveling and milling for the CNC 3018, with FluidNC or GRBL, and pcb2gcode as the CAM engine.

A copper-clad board is never flat: 0.3 to 0.6 mm of warp is normal and an isolation cut is only 0.07 mm deep. MechaLeveling probes the copper with the machine's own Z probe, builds a surface model and rewrites your G-code so the V-bit follows the real surface. It also runs the whole CAM step from a tab by driving pcb2gcode for you.

Features

• Surface scan with G38.2 over a configurable grid, RBF interpolation, autosave after every row, re-scan of single points.
• Z compensation of any G-code (pcb2gcode, FlatCAM, KiCad, Fusion).
• PCB tab: Gerber and Excellon in, profile, Generate. Isolation, drills (one file per bit), NPTH and cutout come out ready for the leveling queue.
• Streaming over USB or WiFi with pause, resume, stop, emergency stop, feed, spindle and live Z override, restart from a line.
• Autonomous run from SD (FluidNC only).
• Two board modes: S (one 200x150 board) and L (300x200, two boards side by side, needs a 305 mm X axis).
• Pre-job health check, time estimate, job history, per-zone repaint pass.

Download (macOS): a ready to use .dmg is in Releases. Drag the app to Applications, right click and Open the first time (it is not signed with Apple), and brew install pcb2gcode for the PCB tab.

Run from source (macOS, Linux, Windows)

git clone https://github.com/MechatronicStore/MechaLeveling.git
cd MechaLeveling
pip install -r requirements.txt
python app.py

You need pcb2gcode 3.x for the PCB tab (brew install pcb2gcode, apt install pcb2gcode) and python3-tk on Linux. Full guide in INSTALL.md (Spanish, with the commands in every platform).

Workflow: connect (USB, or WiFi with the Escanear button to find FluidNC on your LAN) → PCB tab: pick Gerbers, generate → set XYZ zero on the board → Leveling tab: scan the surface → level the files → Milling tab: stream the queue or upload to SD.

WiFi: FluidNC must join your network first. Run python3 cambiar_wifi.py with the CNC on USB (asks SSID and password, never stores them), or connect to the FluidNC access point and set your network in the WebUI at 192.168.4.1. Then use fluidnc.local:23 or Escanear in the app.

Compatibility: GRBL 1.1 over USB does everything except WiFi and SD; FluidNC does everything. Developed and used daily on a TwoTrees 3018 with an MKS DLC32 board.

Safety: this moves a spinning cutter. Read docs/KNOWN_ISSUES.md first and keep the physical E-stop within reach. The app never stores WiFi passwords or credentials.

License: MIT. pcb2gcode (GPLv3) is invoked as a separate program and not bundled. Made in Curicó, Chile, by MechatronicStore.