Read it. Build it.
Verify every bit.
A practical path from the source to your first board example, host tests, and a trained binary model. Commands and paths are checked against the repository snapshot.
Start with the source.
You need Git, Python with PyTorch, and gcc for host C tests. PlatformIO and pyserial are required for device builds and serial verification. TensorFlow is needed for the independent INT8 benchmarks, not for basic C library tests.
git clone https://github.com/Eden-sudo/Symbex-1.git
cd Symbex-1
# Create an isolated Python environment (Linux / macOS)
python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
# Optional: inspect the revision used by this website
git show b34f32853b1c1260109e5e193a1cab0c15a0d0e4 --statThis guide describes revision b34f328. The default Git clone tracks current upstream; check its README for subsequent changes. Website commands were verified against source; a physical board was not flashed during website development.
Make the chip agree.
The checked-in PlatformIO configuration targets esp32-s3-devkitc-1, using Arduino, a 16 MB flash layout and OPI PSRAM settings. Review it for your board before uploading; the default serial port is /dev/ttyUSB0.
cd Symbex1_PIO
pio run -t upload
pio device monitor -b 1152008/8 equal to the PC simulation: OK. This confirms the demo network matches the PC integer reference; it is not a dataset accuracy score.Inspect the minimal C++ example ↗
Test the engine first.
The library’s host suite compiles the C engine and checks bit-exact behavior with its supported test hardware layers. Run it from the repository root with Python and gcc available.
python Symbex1_PIO/lib/lib_symbex/tests/run_tests.pyKeep host correctness separate from device performance. Passing host tests cannot establish board latency or RAM consumption.
Read the test runner ↗A configuration becomes C.
The CDT takes a TOML configuration through inspect, train, export and verification stages. Read the commented example and supply your model definition, dataset and output paths. The example is a template that needs your inputs.
cd tools
cp configs/example.toml my_model.toml
# Edit my_model.toml for your data/model before running.
python cdt.py my_model.toml --show-config
python cdt.py my_model.tomlFor a complete configured boolean example, inspect the CIFAR-10 configuration. It still needs its documented data and training environment. Training does not happen on the microcontroller.
| Configuration section | What to set |
|---|---|
[model] | Model file/definition and method: boolean for the fully binary convolutional path. |
[data] | Dataset directory/format, validation_split and split_seed. |
[hardware] | ram_kb and flash_kb constraints. |
[training] | Epochs, batch size, learning rate and seed. |
[output] | Output directory and library path. |
[chip] | Board, port, counting method and weight placement. |
Run only part of the workflow
Use --from export to export a previously trained run, or --from chip to measure an existing export. Command-line flags override TOML settings. python cdt.py --help lists the available options.
The same answer, on silicon.
From tools/, replace PATH_TO_EXPORT with your actual generated output directory. The supported chip-runner selectors documented here are s3 and esp32.
python chip_test.py PATH_TO_EXPORT --board s3 --port /dev/ttyUSB0
# For a classic ESP32
python chip_test.py PATH_TO_EXPORT --board esp32 --port /dev/ttyUSB0The runner checks agreement with the PC simulation, reports task accuracy where provided, times layers and records memory. Device and PC inference must agree 100% for the exported integer model.
Inspect chip_test.py ↗Keep the evidence.
| Generated file | Purpose |
|---|---|
config_used.toml | The exact configuration used by the run. |
train.json | Training history, validation score and final test evaluation. |
model_binarized.pth | The trained binary network checkpoint. |
model_symbex.h | Generated C model data for lib_symbex. |
export.json | Model memory, layers, fidelity and C-vs-integer exactness. |
chip.json | Reported device checks and measurements. |
Know the target.
| Target / feature | Documented state |
|---|---|
| ESP32 / ESP32-S3 | Device runner support, HAL implementations and reported measured comparisons. |
| Generic C / AVR | Hardware layers in the library. Not every workload has device benchmark data. |
| Dense and binary 2D convolution | Documented inference and CDT workflows; inspect method-specific configurations. |
| 1D sensor workloads | Human activity recognition comparison in preparation. |
| RP2350 / Cortex-M33 / RISC-V | Roadmap work; no performance claim is made here. |
| Energy | Not yet measured. |
Choose a benchmark.
Start in benchmarks/README.md for environment and dataset requirements. The project recommends a TensorFlow-compatible Python environment, describes 3.11 / 3.12 examples, and documents CUDA options. CPU training is possible but slower.
Each task has its own data preparation, model training, export, INT8 baseline, device measurement and results directory. Use its source instructions rather than assuming one command covers all tasks.
Choose checkpoints and architecture variants on a held-out validation split. Record seeds, chip clock/core, model shape, weight placement and measurement definitions. Preserve the exported model’s exactness check. Current published sizing results carry the documented selection caveats.
Make the failure specific.
My serial device is not /dev/ttyUSB0.
Find your board’s actual port with pio device list, then update the PlatformIO upload port or the chip runner’s --port. The example Linux path may differ on your machine.
The board example does not match my hardware.
Inspect platformio.ini. The checked-in target assumes an ESP32-S3 board with OPI PSRAM and a 16 MB flash layout. Match those settings to your actual module and connection before uploading.
The exported C and integer simulation disagree.
Treat this as a correctness failure. Keep config_used.toml and export.json, inspect the model method and exporter, and report a minimal reproduction. Do not interpret mismatching timings as a validated benchmark.
The training or INT8 environment fails to import a package.
Check the repository’s requirements and the benchmark environment instructions. PyTorch accelerator wheels depend on your driver; TensorFlow supports specific Python versions. Keep the independent baseline environment documented.
Why does a smaller model still use substantial RAM?
Weights, activation buffers, descriptors, counting tables, tensor arenas and word alignment have different costs. Compare the same memory definition, not just raw packed weight bytes.