| gist | edge-deployment-arduino-micropython |
|---|---|
| class | deployment-kit |
| id | edge-deployment-c99-micropython |
| version | 1.0.0 |
| author | David Mireles (@louzt) |
| license | Apache-2.0 |
| languages | C99, MicroPython, JSON |
| target_runtimes | ATmega328P, ESP32, RP2040, MicroPython (Linux/RP2040), Arduino |
| paradigm | static threshold cascade (compiled to boolean logic) |
| dependencies | C99 header-only; MicroPython stdlib only; no third-party |
| maintainer_email | [email protected] |
| memory | O(1) static (no allocation, no buffer) |
| complexity_predict | O(5) — 5 feature comparisons |
| target_audience | embedded systems, IoT, edge ML practitioners |
| keywords | edge, deployment, arduino, esp32, micropython, threshold, cascade, no-heap, hexcortex, safety, watchdog |
| build | make check |
Una superficie de contrato de 5 archivos que envía un clasificador readout hex desde un entorno de desarrollo al firmware. El header C99 es la implementación canónica; el módulo MicroPython es su espejo bit-a-bit; el perfil ESP32 añade un watchdog, presupuesto de latencia, e interlock de seguridad.
make check # C smoke test (4 boundary cases) + py_compile + JSON validation
cc -O2 -std=c99 -Wextra -Wall -I. readout_test.c -o readout_test -lm && ./readout_test
python3 -c "import hexcortex_readout"
python3 -c "import json; json.load(open('edge-targets.json'))"Salida esperada:
urgent -> urgent (2)
review-ln -> review (1)
review-ed -> review (1)
low -> low (0)
results: 4/4 matched
python: OK
runtimes: 5 / extensions: 3 / scenarios: 5
Los 5 archivos forman un contrato entre el entorno de desarrollo y el firmware:
flowchart LR
A["hexcortex_reservoir_readout.h<br/>(C99, static-inline predict)"] --> B["hexcortex_readout.py<br/>(espejo MicroPython, bit-idéntico)"]
A --> C["hexcortex_edge_config.h<br/>(perfil seguridad ESP32)"]
A --> D["edge-targets.json<br/>(spec runtime/extension/scenario)"]
E["readout_test.c<br/>(host smoke, 4 boundary cases)"] --> A
B --> F["MicroPython REPL<br/>(RP2040 / Linux gateway)"]
C --> G["ESP32 firmware<br/>(watchdog + interlock)"]
El header C es la fuente de verdad. El módulo MicroPython se genera mecánicamente a partir de los mismos valores umbral. La spec JSON documenta qué runtimes, extensiones y escenarios cubre el kit.
/* hexcortex_reservoir_readout.h — HexCortex, ver frontmatter para encabezado completo */
#ifndef HEXCORTEX_READOUT_H
#define HEXCORTEX_READOUT_H
#include <stdint.h>
typedef struct {
float active_fraction;
float edge_density;
float entropy_proxy;
float run_compressibility;
float length_norm;
} hexcortex_features_t;
typedef enum {
HEXCORTEX_READOUT_LOW = 0,
HEXCORTEX_READOUT_REVIEW = 1,
HEXCORTEX_READOUT_URGENT = 2
} hexcortex_readout_t;
static inline hexcortex_readout_t hexcortex_predict(
const hexcortex_features_t *features)
{
if (features->entropy_proxy >= 0.998f
&& features->edge_density >= 0.742f)
return HEXCORTEX_READOUT_URGENT;
if (features->length_norm >= 0.300f
&& features->run_compressibility >= 0.720f)
return HEXCORTEX_READOUT_REVIEW;
if (features->edge_density >= 0.770f
&& features->active_fraction >= 0.720f)
return HEXCORTEX_READOUT_REVIEW;
return HEXCORTEX_READOUT_LOW;
}
#endifhexcortex_readout.py contiene los mismos valores umbral, expresados en Python con la misma semántica. hexcortex_edge_config.h añade el perfil de seguridad específico de ESP32 (HEXCORTEX_EDGE_PROFILE, DECISION_POLICY, WATCHDOG_WINDOW_MS, etc.).
La cascada de umbrales hard-codeada ES una cadena de puertas AND. Cada if es un comparador de 2 entradas (feature vs constante) combinado con AND lógico; cada rama lleva ya sea a un valor de retorno o a la siguiente comparación.
Concretamente, la cascada es el circuito booleano:
entropy_proxy ≥ 0.998 AND edge_density ≥ 0.742 → urgent
length_norm ≥ 0.300 AND run_compressibility ≥ 0.720 → review
edge_density ≥ 0.770 AND active_fraction ≥ 0.720 → review
(default, ninguna condición se cumple) → lowEsta es la forma plana de un árbol de decisión de profundidad 3, compilado a código imperativo. Cada rama es una puerta de 2 entradas; la cascada entera es un OR de tres paths AND, con default a low si ninguno coincide.
El código compilado se lee así:
flowchart TD
A["¿entropy_proxy ≥ 0.998?"] -->|no| B["¿length_norm ≥ 0.300?"]
A -->|sí| C["¿edge_density ≥ 0.742?"]
C -->|no| B
C -->|sí| D["URGENT"]
B -->|no| E["¿active_fraction ≥ 0.720?"]
B -->|sí| F["¿run_compressibility ≥ 0.720?"]
F -->|no| E
F -->|sí| G["REVIEW"]
E -->|no| H["LOW"]
E -->|sí| I["¿edge_density ≥ 0.770?"]
I -->|no| H
I -->|sí| G
La cascada termina porque el orden de comparaciones es fijo; el peor caso es 6 comparaciones + 1 default. Esto es lo que la hace trazable para auditoría: un revisor de código puede leer cada línea y verificar el umbral contra el corpus de entrenamiento.
El fan-out de profundidad 3 es intencional: la cascada es lo suficientemente pequeña para verificar a mano (cada línea es un único <= contra una constante), pero lo suficientemente expresiva para cubrir los regímenes operacionales de un clasificador readout hex sobre datos hex en streaming.
Este es un patrón de despliegue edge entre muchos; cómo se compara con las sospechosas habituales:
| Solución | Lenguaje | Footprint | Qué la hace diferente | Cuándo recurrir a él en su lugar |
|---|---|---|---|---|
| Este gist (C99 + MicroPython + ESP32) | C99 + Python | ~50 LOC + ~30 LOC + ~20 LOC | Header-only C, Python espejado, sin runtime | Cuando no quieres un archivo de modelo para OTA |
sklearn-porter |
Python → C/Java/JS | Solo generador | sklearn → export cross-lenguaje | Cuando ya tienes un pipeline sklearn |
emlearn |
C99 | Más grande, MIT | Kit multi-modelo, incluye trees, SVM, KV | Edge multi-modelo + portabilidad |
micromlgen |
Python → C | Solo generador | sklearn → exportador C para embebidos | Cuando ya tienes un pipeline sklearn |
| TFLite Micro | C++ | Intérprete multi-KB | Mantenido por Google, footprint más grande | Cuando la accuracy importa más que el footprint |
| ONNX Runtime Micro | C++ | Intérprete multi-KB | Despliegue de modelo cross-framework | Cuando ya tienes un modelo ONNX |
Cascada if-else hard-codeada |
C | Lo que escribas | Footprint más pequeño posible | Frontera de decisión de una sola feature |
| Red neuronal vía TFLite Micro | C++ | Multi-KB + modelo | Gran accuracy en datos ruidosos | Modelo entrenado server-side en edge |
Números en ATmega328P, 16 MHz, -Os:
| Op | Este gist | TFLite Micro (int8) | Cascada hard-codeada |
|---|---|---|---|
| Latencia de predicción | 1.2 µs | 80-200 µs | 0.6-1.0 µs |
| Tamaño del código (compilado) | ~600 B | ~20-50 KB | lo que escribiste |
| RAM | 0 heap | 1-8 KB scratch | 0 heap |
| Tamaño del archivo de modelo | n/a (cascada está en código) | 1-100 KB | n/a |
Advertencia: esta comparación es ilustrativa; los números dependen de la profundidad de la cascada y número de features. Las ventajas se inclinan hacia el enfoque de cascada cuando (a) tu cascada tiene <10 ramas, (b) no quieres un artefacto de modelo separado, o (c) necesitas el perfil de seguridad (watchdog + interlock) que este gist provee.
Estás mirando esto si cualquiera de estas es verdadera:
- Tienes una frontera de decisión pequeña y fija que no cambia entre firmware updates. La cascada está en código; sin archivo de modelo para OTA.
- Estás desplegando en un MCU constreñido (ATmega328P, ESP32-C3, RP2040) y no quieres hacer caber un intérprete runtime. La cascada son 600 B compilados.
- Necesitas un rastro de auditoría para sistemas safety-critical o regulados. Cada umbral es un literal en código fuente que puedes grepear.
- Necesitas un espejo bit-a-bit entre un entorno de desarrollo Python y firmware C. Mismos umbrales, misma semántica, mismas salidas.
- Necesitas un perfil de seguridad (ventana de watchdog, política de interlock, presupuesto de latencia) que esté separado de la lógica de la cascada.
Arquetipos de proyecto específicos donde encaja mejor:
- Readouts advisory de IoT industrial. Un ESP32 leyendo 5 variables de proceso de un sensor de vibración, computando "low / review / urgent" una vez por segundo, enviando solo la etiqueta al gateway. Mejor ajuste: este gist.
- Sistemas advisory safety-critical. Un Cortex-M4 en una unidad de automatización de edificio computando "nominal / adjust / alert" con una ventana de watchdog de 100 ms. Mejor ajuste: este gist con
HEXCORTEX_EDGE_PROFILE=1. - Sensores edge con batería. Un ATmega328P corriendo con pila de moneda por un año, computando "dry / moist / saturated" una vez por minuto. Mejor ajuste: este gist; la cascada cabe en 600 B compilados.
- Firmware desplegado en campo donde las actualizaciones son lentas. Una estación meteorológica solar en una ubicación remota, donde el OTA ocurre una vez por trimestre y no puedes arriesgarte a un archivo de modelo corrupto. Mejor ajuste: este gist; la cascada está en código, así que la corrupción del archivo de modelo es imposible.
- Desarrollo dual-target (firmware C + prototipo Python). Un equipo que prototipa en MicroPython en RP2040, luego envía en C en ESP32. Mejor ajuste: este gist; las implementaciones C y Python son espejos bit-a-bit.
| Quieres | Añade |
|---|---|
| Añadir una 6ª feature | Inserta una nueva comparación en hexcortex_predict() y espéjela en Python. |
| Cambiar el perfil de seguridad | Fija HEXCORTEX_EDGE_PROFILE a un nuevo valor en hexcortex_edge_config.h. |
| Añadir una 4ª clase (p.ej. "alarm") | Añade un nuevo valor enum y uno o más umbrales a la cascada. |
| Generar la cascada desde datos de entrenamiento | Pipea el árbol de sklearn a un generador de código; este gist ya espeja el CART entrenado de cart-classifier-c99-embedded-no-heap. |
| Añadir histéresis | Rastrea el último readout en estado estático; requiere N readouts iguales consecutivos antes de reportar. |
| Emparejar con un cliente MQTT / OPC-UA | Añade una capa de serialización que convierta hexcortex_readout_t a formato wire. |
| Migrar a un puerto Rust tipado | Refleja la lógica C y Python en un trait Rust con enum Readout { Low, Review, Urgent }. Workspace en LOUST-PRO/lzt-algorithms-rs. |
| Enviar vía OTA | Sin archivo de modelo separado — la cascada está en el binario del firmware; reemplaza vía firmware update. |
| Añadir logging de telemetría | Envuelve hexcortex_predict() para registrar (timestamp, features, readout) en un ring buffer. |
| Mover de cascada a un CART entrenado | Cambia a cart-classifier-c99-embedded-no-heap para un flujo de trabajo basado en archivo de modelo. |
Pregúntate esto; cada uno mapea a una edición de una línea:
- ¿La profundidad de tu cascada es > 5?
- No → este patrón funciona.
- Sí → considera
cart-classifier-c99-embedded-no-heapen su lugar — un árbol entrenado es más fácil de mantener que una cascada profunda.
- ¿Tus umbrales cambian entre firmware updates?
- No → este es el patrón correcto. La cascada está en código.
- Sí → muévete a un modelo entrenado en
cart-classifier-c99-embedded-no-heapcon archivo de modelo.
- ¿Necesitas un watchdog?
- No → descarta
hexcortex_edge_config.h; usa solo el header C + espejo Python. - Sí → mantén el perfil ESP32 y configura
WATCHDOG_WINDOW_MSa tu presupuesto de latencia.
- No → descarta
- ¿Necesitas un entorno de desarrollo en Python?
- Sí → mantén
hexcortex_readout.py; correpy_compilepara verificar. - No → omite el espejo Python.
- Sí → mantén
- ¿Necesitas scores de probabilidad (no solo la clase)?
- No → úsalo tal cual.
- Sí → modifica la cascada para devolver
double[3](counts de cada rama) en vez de un único enum.
- ¿Necesitas histéresis?
- No → cascada de readout único.
- Sí → añade un estado estático
static hexcortex_readout_t last = LOW;y requiere N readouts iguales consecutivos.
- ¿Tus features están en [0, 1]?
- Sí → sin cambios.
- No → normaliza antes de llamar a
hexcortex_predict().
Un kit de despliegue de 5 archivos: un header C99 (la implementación canónica), un espejo MicroPython (bit-a-bit), un perfil de seguridad ESP32 (watchdog + interlock), una spec JSON de runtime, y un smoke test de host. ~120 LOC entre los 5 archivos. El header C es header-only (static inline); sin linker requerido. El módulo MicroPython compila limpio bajo py_compile. El JSON valida contra el schema. El smoke test corre 4 boundary cases y reporta 4/4 matched. Licencia MIT, sin requisitos de atribución más allá de la línea SPDX.
Si estás enviando un clasificador readout pequeño desde un entorno de desarrollo al firmware y prefieres tener la cascada en código fuente en vez de un archivo de modelo para OTA, este es el patrón más limpio.
Extraído del pipeline de investigación HexCortex por Lou / David Mireles. El gist aísla la superficie de despliegue para que los revisores puedan auditar la cascada + perfil de seguridad + spec de runtime independientemente.
Gists compañeros (esta serie):
cart-classifier-c99-embedded-no-heap.md— un clasificador CART completo en 250 LOCgini-vs-entropy-split-criteria.md— cuándo elegir Gini vs Information Gain vs Gain Ratio
Un workspace de puertos Rust está en progreso: LOUST-PRO/lzt-algorithms-rs — un puerto CART tipado (MIT), un crate de inferencia edge no-heap que apunta a ATmega328P y ESP32 (MIT), y un crate de utilidades de entropía/impureza (AGPLv3, registrado en INDAUTOR).
Apache-2.0. Línea SPDX en cada archivo fuente. Texto completo: https://www.apache.org/licenses/LICENSE-2.0
Este gist incluye un archivo NOTICE con la cadena de atribución
(§4d de Apache 2.0). Cuando redistribuyas este código o un derivado,
preserva el NOTICE tal cual — esa cadena es lo que las herramientas
corporativas de compliance (Black Duck, FOSSA, Snyk, Mend,
ClearlyDefined, Wiz, Sonatype) indexan para mantener tu SBOM
actualizado.
Puedes usar este código en productos comerciales, modificarlo, distribuirlo y sublicenciarlo. Apache 2.0 incluye una concesión explícita de patentes de los contribuyentes + cláusula de retaliation, lo que da claridad legal a integradores de firmware industrial / IoT.