# NeoCalculator **Repository Path**: flymotte/NeoCalculator ## Basic Information - **Project Name**: NeoCalculator - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-30 - **Last Updated**: 2026-03-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ο»Ώ

# πŸ”’ NumOS ### Open-Source Scientific Graphing Calculator OS **ESP32-S3 N16R8 Β· ILI9341 IPS 320Γ—240 Β· LVGL 9.x Β· Pro-CAS Engine Β· Natural Display V.P.A.M.**
[![PlatformIO](https://img.shields.io/badge/PlatformIO-espressif32_6.12-orange?logo=platformio&logoColor=white)](https://platformio.org/) [![LVGL](https://img.shields.io/badge/LVGL-9.5.0-blue?logo=c&logoColor=white)](https://lvgl.io/) [![ESP32-S3](https://img.shields.io/badge/ESP32--S3-N16R8-red?logo=espressif&logoColor=white)](https://www.espressif.com/en/products/socs/esp32-s3) [![Website](https://img.shields.io/badge/Website-neocalculator.tech-purple?logo=google-chrome&logoColor=white)](https://neocalculator.tech) [![Framework](https://img.shields.io/badge/Framework-Arduino-teal?logo=arduino&logoColor=white)](https://www.arduino.cc/) [![Language](https://img.shields.io/badge/Language-C%2B%2B17-blue?logo=cplusplus&logoColor=white)](https://en.cppreference.com/) [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE) [![Status](https://img.shields.io/badge/Status-Pro--CAS%20Production-brightgreen)](#project-status) [![RAM](https://img.shields.io/badge/RAM-29.7%25%20%E2%80%94%2097.2%20KB-informational)](#build-stats) [![Flash](https://img.shields.io/badge/Flash-23.2%25%20%E2%80%94%201.52%20MB-informational)](#build-stats) [![GitHub Stars](https://img.shields.io/github/stars/El-EnderJ/NeoCalculator?style=social)](https://github.com/El-EnderJ/NeoCalculator) [![GitHub Forks](https://img.shields.io/github/forks/El-EnderJ/NeoCalculator?style=social)](https://github.com/El-EnderJ/NeoCalculator)
> *A real open-source alternative to commercial scientific calculators.* > *Inspired by NumWorks Β· TI-84 Plus Β· HP Prime G2, built from scratch in C++17.*
--- ![Image](https://github.com/user-attachments/assets/e1b1df29-362b-4f5c-b824-bacb8e9a28f4) ## Table of Contents 0. [Webpage](https://neocalculator.tech/) 1. [What is NumOS?](#what-is-numos) 2. [Key Features](#key-features) 3. [System Architecture](#system-architecture) 4. [Pro-CAS Engine](#pro-cas-engine) 5. [Hardware](#hardware) 6. [Quick Start](#quick-start) 7. [User Manual β€” EquationsApp](#user-manual--equationsapp) 8. [Project Structure](#project-structure) 9. [Build Stats](#build-stats) 10. [Critical Hardware Fixes](#critical-hardware-fixes) 11. [Project Status](#project-status) 12. [Technology Stack](#technology-stack) 13. [Comparison with Commercial Calculators](#comparison-with-commercial-calculators) 14. [Documentation](#documentation) 15. [Contributing](#contributing) --- ## What is NumOS? **NumOS** is an open-source scientific and graphing calculator operating system built on the **ESP32-S3 N16R8** microcontroller (16 MB Flash QIO + 8 MB PSRAM OPI). The project aims to become the best open-source calculator in the world, rivalling the Casio fx-991EX ClassWiz, the NumWorks, the TI-84 Plus CE, and the HP Prime G2. **NumOS delivers:** - **Full Pro-CAS Engine** β€” Advanced symbolic algebra: immutable DAG with hash-consing (`ConsTable`), overflow-safe bignum arithmetic (`CASInt`/`CASRational`), multi-pass fixed-point simplifier, symbolic differentiation (17 rules), symbolic integration (Slagle heuristic), and non-linear equation/system solving via Sylvester resultant. All memory managed in PSRAM with an STL-compatible allocator. - **Natural Display V.P.A.M.** β€” Formulae rendered as they appear on paper: real stacked fractions, radical symbols (√), genuine superscripts, 2D navigation with a structural smart cursor. - **Modern LVGL 9.x Interface** β€” Smooth transitions, animated splash screen, NumWorks-style launcher. Recent launcher refactor: the launcher now uses LVGL Flex `ROW_WRAP` (dynamic rows) with fixed card sizing instead of a static grid descriptor. See `docs/UI_CHANGES.md` for developer migration notes and `docs/fluid2d_plan.md` for an example app (Fluid2D) integrated into the new APPS[] schema. - **Custom Math Engine** β€” Complete pipeline: Tokenizer β†’ Shunting-Yard Parser β†’ RPN Evaluator + Visual AST, implemented from scratch in C++17. - **Modular App Architecture** β€” Each application is a self-contained module with explicit lifecycle (`begin/end/load/handleKey`), orchestrated by `SystemApp`. --- ## Key Features | Feature | Description | |:--------|:------------| | **CAS-S3-ULTRA Engine** | Sylvester Resultant solver (3Γ—3 NL systems), 16-seed Newton-Raphson, BigInt precision (`CASInt` + `CASRational`), hash-consed DAG, 8-pass fixed-point simplifier, PSRAM-backed step logger | | **Unified Calculus App** | Symbolic $d/dx$ differentiation (17 rules) and numerical/symbolic $\int dx$ integration (Slagle heuristic: table lookup, linearity, u-substitution, integration by parts/LIATE), tab-based mode switching, automatic simplification, and detailed step-by-step output | | **EquationsApp** | Solves linear, quadratic, and 2Γ—2 systems (linear + non-linear via Sylvester resultant) with full step-by-step display | | **Bridge Designer** | Real-time structural bridge simulator with Verlet integration physics, stress analysis (greenβ†’red beam visualisation), snap-to-grid editor, wood/steel/cable materials, and truck/car load testing β€” PSRAM-backed, 60 Hz fixed timestep | | **Particle Lab** | Powder-Toy-class sandbox: 30+ materials (Sand, Water, Lava, LN2, Wire, Iron, Titan, C4, Clone), spark electronics with Joule heating, phase transitions, reaction matrix (Water+Lava=Stone+Steam), Bresenham line tool, material palette overlay, LittleFS save/load | | **Settings App** | System-wide toggles for complex number output (ON/OFF), decimal precision selector (6/8/10/12 digits), and angle-mode display | | **Natural Display** | Real fractions, radicals, exponents, 2D cursors β€” mathematical rendering as it appears on paper | | **Graphing: y=f(x)** | Real-time function plotter with zoom, pan, and value table | | **85+ CAS Unit Tests** | Comprehensive test suite for the Pro-CAS, enable/disable via compile-time flag | | **PSRAMAllocator** | CAS uses `PSRAMAllocator` to isolate memory usage in the 8 MB PSRAM OPI | | **Variables A–Z + Ans** | Persistent storage via LittleFS β€” 216 bytes in `/vars.dat` | | **SerialBridge** | Full calculator control from PC via Serial Monitor without physical hardware | | **SerialBridge Debug** | Immediate byte echo, 5-second heartbeat, 8-event circular buffer | --- ## Photo gallery ### Neural Network Simulator: ![Image](https://github.com/user-attachments/assets/353db3e3-6f3f-4bd1-973f-55b6798b57e0) ### Fluid 2D Simulator: ![Image](https://github.com/user-attachments/assets/546cebc5-3288-4c1d-a7f1-1fc079083cf7) ### Periodic Table (Chemistry App): ![Image](https://github.com/user-attachments/assets/2ad74661-2b3d-48fb-b313-ff48e37727f3) ### Grapher App: ![Image](https://github.com/user-attachments/assets/db788a6a-9ee3-4d40-b86a-607843d3a1fe) ### Steps (Equations App) (WIP, still in development, Alpha): ![Image](https://github.com/user-attachments/assets/5b67651e-b090-468e-997e-c5894b59595b) ![Image](https://github.com/user-attachments/assets/c6120c05-4c0b-4e52-a65c-d122f5b54889) ### Calculus App: ![Image](https://github.com/user-attachments/assets/01923e6d-5380-42ab-9213-f927f385aef8) ### Probability (Gaussian Distribution): ![Image](https://github.com/user-attachments/assets/f6041c0a-8423-43fa-84e7-f53bad07441b) ### Python App: ![Image](https://github.com/user-attachments/assets/243ce6a3-a6f5-4a73-a87f-6522058f042a) ![Image](https://github.com/user-attachments/assets/22360608-7e25-44a7-854b-9e1070cfb15b) ### Bridge Designer: ![Image](https://github.com/user-attachments/assets/87218d20-1495-4da7-9d3b-032125e37097) ### Circuit Simulator (Circuit Core, Alpha): ![Image](https://github.com/user-attachments/assets/3e6163c9-f592-4f3c-a7ed-a07b21c2d6ae) ### Particle Lab (Powder Toy like): ![Image](https://github.com/user-attachments/assets/452ea202-4b8f-46ff-b989-685c42d53914) ### Optics Lab: ![Image](https://github.com/user-attachments/assets/dfff1cf6-4905-45e8-a151-1c2b52fff67e) --- ## System Architecture ```mermaid flowchart TB subgraph esp[ESP32-S3 N16R8] main["main.cpp: setup() β†’ PSRAM, TFT, LVGL, Splash, SystemApp; loop(): lv_timer_handler(), app.update(), serial.poll()"] system["SystemApp (Dispatcher)"] main --> system end subgraph apps[Applications] mm["MainMenu (LVGL)"] calc["CalculationApp (Natural VPAM, History)"] grapher["GrapherApp (y=f(x), Zoom & Pan)"] eq["EquationsApp (Pro-CAS)"] calculus["CalculusApp (d/dx, ∫dx)"] settings["SettingsApp"] end system --> mm system --> calc system --> grapher system --> eq system --> calculus system --> settings math["Math Engine: Tokenizer Β· Parser Β· Evaluator Β· ExprNode Β· VariableContext Β· EquationSolver"] procas["Pro-CAS Engine: CASInt Β· CASRational Β· SymExpr DAG Β· SymSimplify Β· SymDiff Β· SymIntegrate"] system --> math math --> procas display["Display Layer: DisplayDriver Β· LVGL flush DMA Β· ILI9341 @ 10 MHz"] input["Input Layer: KeyMatrix 5x10 Β· SerialBridge Β· LvglKeypad Β· LittleFS"] system --> display system --> input display -->|SPI @ 10 MHz| ili["ILI9341 IPS 3.2 in β€” 320x240 Β· 16 bpp"] ili -.-> esp ``` --- ## Pro-CAS Engine The **Pro-CAS** (Computer Algebra System) is NumOS's complete symbolic-algebra engine. Evolved from the original CAS-Lite, it implements an immutable DAG with hash-consing, overflow-safe bignum arithmetic, multi-pass fixed-point simplification, symbolic differentiation, symbolic integration (Slagle), and non-linear system solving via Sylvester resultant. All CAS memory resides in PSRAM. ### CAS Pipeline (Derivatives) ```mermaid flowchart TB user["User input (CalculusApp): x^3 + sin(x)"] user --> me["Math Engine: Parser + Tokenizer"] me --> af["ASTFlattener: MathAST β†’ SymExpr DAG"] af --> sd["SymDiff β†’ d/dx: 3x^2 + cos(x)"] sd --> ss["SymSimplify (8-pass fixed-point)"] ss --> sea["SymExprToAST: SymExpr β†’ MathAST (Natural Display)"] sea --> canvas["MathCanvas renders: 3x^2 + cos(x)"] ``` ### CAS Pipeline (Integrals) ```mermaid flowchart TB userInt["User input (CalculusApp, ∫dx mode): x Β· cos(x)"] userInt --> af2["ASTFlattener β†’ SymExpr DAG"] af2 --> sint["SymIntegrate (Slagle): table β†’ linearity β†’ u-sub β†’ parts (LIATE)"] sint --> ss2["SymSimplify"] ss2 --> conv["SymExprToAST::convertIntegral()"] conv --> canvas2["MathCanvas renders: xΒ·sin(x) + cos(x) + C"] ``` ### Pro-CAS Components | Module | File | Responsibility | |:-------|:-----|:---------------| | `CASInt` | `cas/CASInt.h` | Hybrid BigInt: `int64_t` fast-path + `mbedtls_mpi` on overflow | | `CASRational` | `cas/CASRational.h/.cpp` | Overflow-safe exact fraction (num/den with auto-GCD) | | `PSRAMAllocator` | `cas/PSRAMAllocator.h` | STL allocator β†’ `ps_malloc`/`ps_free` for PSRAM | | `SymExpr` DAG | `cas/SymExpr.h/.cpp` | Immutable symbolic tree with hash (`_hash`) and weight (`_weight`) | | `ConsTable` | `cas/ConsTable.h` | PSRAM hash-consing table: deduplication of identical nodes | | `SymExprArena` | `cas/SymExprArena.h` | PSRAM bump allocator (16 blocks Γ— 64 KB) + integrated ConsTable | | `ASTFlattener` | `cas/ASTFlattener.h/.cpp` | MathAST (VPAM) β†’ SymExpr DAG with hash-consing | | `SymDiff` | `cas/SymDiff.h/.cpp` | Symbolic differentiation: 17 rules (chain, product, quotient, trig, exp, log) | | `SymIntegrate` | `cas/SymIntegrate.h/.cpp` | Slagle integration: table, linearity, u-substitution, parts (LIATE) | | `SymSimplify` | `cas/SymSimplify.h/.cpp` | Multi-pass simplifier (8 iterations, fixed-point, trig/log/exp) | | `SymPoly` | `cas/SymPoly.h/.cpp` | Univariable symbolic polynomial with `CASRational` coefficients | | `SymPolyMulti` | `cas/SymPolyMulti.h/.cpp` | Multivariable polynomial + Sylvester resultant | | `SingleSolver` | `cas/SingleSolver.h/.cpp` | Single-variable equation: linear / quadratic / Newton-Raphson | | `SystemSolver` | `cas/SystemSolver.h/.cpp` | 2Γ—2 system: Gaussian elimination + non-linear (resultant) | | `OmniSolver` | `cas/OmniSolver.h/.cpp` | Analytic variable isolation: inverses, roots, trig | | `HybridNewton` | `cas/HybridNewton.h/.cpp` | Newton-Raphson with symbolic Jacobian and 16-seed multi-start | | `CASStepLogger` | `cas/CASStepLogger.h/.cpp` | `StepVec` in PSRAM β€” detailed steps (INFO/FORMULA/RESULT/ERROR) | | `SymToAST` | `cas/SymToAST.h/.cpp` | Bridge: `SolveResult` β†’ MathAST Natural Display | | `SymExprToAST` | `cas/SymExprToAST.h/.cpp` | Bridge: `SymExpr` β†’ MathAST. Includes `convertIntegral()` (+C) | ### CAS Tests β€” 53 Unit Tests | Phase | Tests | Coverage | |:------|:-----:|:---------| | **A β€” Foundations** | 1–18 | `Rational`: add, subtract, multiply, divide, simplification. `SymPoly`: arithmetic, derivation, normalisation. | | **B β€” ASTFlattener** | 19–32 | ASTβ†’SymPoly conversion for simple polynomials, constants, trig functions, powers. | | **C β€” SingleSolver** | 33–44 | Linear (single solution), quadratic (2 real roots, repeated root, negative discriminant), steps. | | **D β€” SystemSolver** | 45–53 | 2Γ—2 determined system, indeterminate (infinite solutions), incompatible system. | ```ini # platformio.ini β€” enable tests: build_flags = ... -DCAS_RUN_TESTS build_src_filter = +<*> +<../tests/CASTest.cpp> ``` --- ## Hardware | Component | Specification | |:----------|:-------------| | **MCU** | ESP32-S3 N16R8 CAM β€” Dual-core Xtensa LX7 @ 240 MHz | | **Flash** | 16 MB QIO (`default_16MB.csv`) | | **PSRAM** | 8 MB OPI (`qio_opi` β€” critical to prevent boot panic) | | **Display** | ILI9341 IPS TFT 3.2" β€” 320Γ—240 px β€” SPI @ 10 MHz (verified) | | **SPI Bus** | FSPI (SPI2): MOSI=13, SCLK=12, CS=10, DC=4, RST=5 | | **Backlight** | GPIO 45 β€” hardwired to 3.3V (`pinMode(45, INPUT)`) | | **Keyboard** | 5Γ—10 matrix (Phase 7) β€” Rows OUTPUT: GPIO 1,2,41,42,40 Β· Cols INPUT_PULLUP: GPIO 6,7,8… | | **Storage** | LittleFS on dedicated partition β€” persistent A–Z variables | | **USB** | Native USB-CDC on S3 β€” 115 200 baud | ### Full Pinout #### ILI9341 Display | Signal | GPIO | Notes | |:-------|:----:|:------| | MOSI | 13 | FSPI Data In | | SCLK | 12 | FSPI Clock | | CS | 10 | Chip Select (active LOW) | | DC | **4** | Data/Command | | RST | **5** | Reset | | BL | 45 | Hardwired to 3.3V β€” always INPUT | #### 5Γ—10 Keyboard Matrix (driver `Keyboard`, Phase 7) | Row | GPIO | Role | Column | GPIO | Role | |:----|:----:|:-----|:-------|:----:|:-----| | ROW 0 | 1 | OUTPUT | COL 0 | 6 | INPUT_PULLUP | | ROW 1 | 2 | OUTPUT | COL 1 | 7 | INPUT_PULLUP | | ROW 2 | 41 | OUTPUT | COL 2 | 8 | INPUT_PULLUP | | ROW 3 | 42 | OUTPUT | COL 3–9 | 3,15,16,17,18,21,47 | not yet wired | | ROW 4 | 40 | OUTPUT | β€” | β€” | β€” | > βœ… **GPIO 4/5 conflict resolved (2026-03-02)**: Keyboard columns C0 and C1 reassigned from GPIO 4/5 (`TFT_DC`/`TFT_RST`) to GPIO 6/7. The three currently wired columns use GPIO 6, 7, and 8 β€” no display conflict. --- ## Quick Start ### Requirements - [PlatformIO IDE](https://platformio.org/install/ide?install=vscode) (VS Code extension) - USB drivers for ESP32-S3 (no external driver needed on Windows 11+) - Python 3.x (PlatformIO installs it automatically) ### Build and Flash ```bash git clone https://github.com/your-user/numOS.git cd numOS # Build only pio run -e esp32s3_n16r8 # Build and flash to ESP32-S3 pio run -e esp32s3_n16r8 --target upload # Open serial monitor (115 200 baud) pio device monitor ``` ### Serial Keyboard Control (SerialBridge) With the Serial Monitor open, type characters to control the calculator: | Key | Action | | Key | Action | |:---:|:-------|-|:---:|:-------| | `w` | ↑ Up | | `z` | ENTER / Confirm | | `s` | ↓ Down | | `x` | DEL / Delete | | `a` | ← Left | | `c` | AC / Clear | | `d` | β†’ Right | | `h` | MODE / Return to menu | | `0`–`9` | Digits | | `+-*/^.()` | Operators | | `S` | SHIFT | | `r` | √ SQRT | | `t` | sin | | `g` | GRAPH | | `e` | `=` (equation) | | `R` | SHOW STEPS | > **Note**: lowercase `s` = DOWN; uppercase `S` = SHIFT. Disable CapsLock before use. --- ## User Manual β€” EquationsApp The **EquationsApp** solves single-variable polynomial equations and 2Γ—2 systems (linear and non-linear), displaying complete solution steps via the Pro-CAS engine. ### Access 1. From the Launcher, select **Equations** with ↑↓ and press ENTER. 2. The mode-selection screen appears. ### Mode 1: Single-Variable Equation 1. Select **Equation (1 var)** with ↑↓ and press ENTER. 2. The editor opens. Type your equation with the `=` sign: - `x^2 - 5x + 6 = 0` β†’ x₁=2, xβ‚‚=3 - `2x + 3 = 7` β†’ x=2 - `x^2 = -1` β†’ no real solution (Ξ” < 0) 3. Press **ENTER** to solve. 4. The result screen shows: - **Linear**: a single solution `x = value` - **Quadratic**: discriminant Ξ” and up to 2 solutions `x₁`, `xβ‚‚` - **No real solution**: negative discriminant message 5. Press **SHOW STEPS** (`R`) to view detailed steps: - Normalised equation - Discriminant value Ξ” = bΒ² βˆ’ 4ac - Quadratic formula applied - Computed roots 6. Press **MODE** (`h`) to return to the main menu. ### Mode 2: 2Γ—2 System 1. Select **System (2Γ—2)** and press ENTER. 2. Two fields appear: **Eq 1** and **Eq 2**. - Type the first equation in `x` and `y`, press ENTER. - Type the second equation, press ENTER. - Example: `2x + y = 5` / `x - y = 1` β†’ x=2, y=1 3. Press **ENTER** to solve. Displays `x = value, y = value`. 4. Press **SHOW STEPS** to view the full Gaussian elimination. 5. Press **MODE** to return. ### EquationsApp Keys | Key | Action | |:----|:-------| | ↑ ↓ ← β†’ | Navigate selection / cursor in editor | | ENTER | Confirm mode / Solve equation | | DEL | Delete character | | AC | Clear field | | SHOW STEPS | View detailed steps (from result screen) | | MODE | Return to main menu | --- ## Project Structure ``` numOS/ β”œβ”€β”€ src/ β”‚ β”œβ”€β”€ main.cpp # Arduino entry point (setup/loop) β”‚ β”œβ”€β”€ SystemApp.cpp/.h # Central orchestrator and LVGL launcher β”‚ β”œβ”€β”€ Config.h # Global ESP32-S3 pinout β”‚ β”œβ”€β”€ lv_conf.h # LVGL 9.x configuration β”‚ β”œβ”€β”€ HardwareTest.cpp # Interactive keyboard test (inline) β”‚ β”œβ”€β”€ apps/ β”‚ β”‚ β”œβ”€β”€ CalculationApp.cpp/.h # Natural V.P.A.M. calculator β”‚ β”‚ β”œβ”€β”€ GrapherApp.cpp/.h # y=f(x) graphing plotter β”‚ β”‚ β”œβ”€β”€ EquationsApp.cpp/.h # Pro-CAS β€” Equation solver β”‚ β”‚ β”œβ”€β”€ CalculusApp.cpp/.h # Pro-CAS β€” Unified symbolic derivatives + integrals β”‚ β”‚ β”œβ”€β”€ BridgeDesignerApp.cpp/.h # Bridge structural simulator (Verlet physics) β”‚ β”‚ β”œβ”€β”€ CircuitCoreApp.cpp/.h # Circuit simulator (MNA, 30 components) β”‚ β”‚ β”œβ”€β”€ Fluid2DApp.cpp/.h # 2D fluid dynamics (Navier-Stokes) β”‚ β”‚ β”œβ”€β”€ ParticleLabApp.cpp/.h # Powder-Toy sandbox (30+ materials, electronics) β”‚ β”‚ β”œβ”€β”€ ParticleEngine.cpp/.h # Cellular automata engine (LUT, spark cycle) β”‚ β”‚ └── SettingsApp.cpp/.h # Settings: complex roots, precision, angle mode β”‚ β”œβ”€β”€ display/ β”‚ β”‚ └── DisplayDriver.cpp/.h # TFT_eSPI FSPI + LVGL init + DMA flush β”‚ β”œβ”€β”€ input/ β”‚ β”‚ β”œβ”€β”€ KeyCodes.h # KeyCode enum (48 keys) β”‚ β”‚ β”œβ”€β”€ KeyMatrix.cpp/.h # 5Γ—10 hardware driver with debounce β”‚ β”‚ β”œβ”€β”€ SerialBridge.cpp/.h # Virtual keyboard via Serial β”‚ β”‚ └── LvglKeypad.cpp/.h # LVGL indev keypad adapter β”‚ β”œβ”€β”€ math/ β”‚ β”‚ β”œβ”€β”€ Tokenizer.cpp/.h # Lexical analyser β”‚ β”‚ β”œβ”€β”€ Parser.cpp/.h # Shunting-Yard β†’ RPN / Visual AST β”‚ β”‚ β”œβ”€β”€ Evaluator.cpp/.h # Numerical RPN evaluator β”‚ β”‚ β”œβ”€β”€ ExprNode.h # Expression tree (Natural Display) β”‚ β”‚ β”œβ”€β”€ MathAST.h # V.P.A.M. tree: NodeRow/NodeFrac/NodePow… β”‚ β”‚ β”œβ”€β”€ CursorController.h/.cpp # MathAST editing cursor β”‚ β”‚ β”œβ”€β”€ EquationSolver.cpp/.h # Numerical Newton-Raphson β”‚ β”‚ β”œβ”€β”€ VariableContext.cpp/.h # Variables A–Z + Ans β”‚ β”‚ β”œβ”€β”€ VariableManager.h/.cpp # Persistent ExactVal storage β”‚ β”‚ β”œβ”€β”€ StepLogger.cpp/.h # Parser step logger β”‚ β”‚ └── cas/ # β˜… Complete Pro-CAS Engine β”‚ β”‚ β”œβ”€β”€ CASInt.h # Hybrid BigInt (int64 + mbedtls_mpi) β”‚ β”‚ β”œβ”€β”€ CASRational.h/.cpp # Overflow-safe exact fraction β”‚ β”‚ β”œβ”€β”€ ConsTable.h # Hash-consing PSRAM (dedup) β”‚ β”‚ β”œβ”€β”€ PSRAMAllocator.h # STL allocator for PSRAM OPI β”‚ β”‚ β”œβ”€β”€ SymExpr.h/.cpp # Immutable DAG with hash + weight β”‚ β”‚ β”œβ”€β”€ SymExprArena.h # Bump allocator + ConsTable β”‚ β”‚ β”œβ”€β”€ SymDiff.h/.cpp # Symbolic differentiation (17 rules) β”‚ β”‚ β”œβ”€β”€ SymIntegrate.h/.cpp # Slagle integration (table/u-sub/parts) β”‚ β”‚ β”œβ”€β”€ SymSimplify.h/.cpp # Fixed-point simplifier (8 passes) β”‚ β”‚ β”œβ”€β”€ SymPoly.h/.cpp # Univariable symbolic polynomial β”‚ β”‚ β”œβ”€β”€ SymPolyMulti.h/.cpp # Multivariable polynomial + resultant β”‚ β”‚ β”œβ”€β”€ ASTFlattener.h/.cpp # MathAST β†’ SymExpr DAG β”‚ β”‚ β”œβ”€β”€ SingleSolver.h/.cpp # Analytic linear + quadratic solver β”‚ β”‚ β”œβ”€β”€ SystemSolver.h/.cpp # 2Γ—2 system (linear + NL resultant) β”‚ β”‚ β”œβ”€β”€ OmniSolver.h/.cpp # Analytic variable isolation β”‚ β”‚ β”œβ”€β”€ HybridNewton.h/.cpp # Newton-Raphson with symbolic Jacobian β”‚ β”‚ β”œβ”€β”€ CASStepLogger.h/.cpp # Steps in PSRAM (StepVec) β”‚ β”‚ β”œβ”€β”€ SymToAST.h/.cpp # SolveResult β†’ visual MathAST β”‚ β”‚ └── SymExprToAST.h/.cpp # SymExpr β†’ MathAST (+C, ∫) β”‚ └── ui/ β”‚ β”œβ”€β”€ MainMenu.cpp/.h # LVGL launcher grid 3Γ—N β”‚ β”œβ”€β”€ MathRenderer.h/.cpp # 2D MathCanvas renderer β”‚ β”œβ”€β”€ StatusBar.h/.cpp # LVGL status bar β”‚ β”œβ”€β”€ GraphView.cpp/.h # Graph widget β”‚ β”œβ”€β”€ Icons.h # App icon bitmaps β”‚ └── Theme.h # Colour palette and UI constants β”œβ”€β”€ tests/ β”‚ β”œβ”€β”€ CASTest.h/.cpp # CAS unit tests β”‚ β”œβ”€β”€ HardwareTest.cpp # TFT + physical keyboard test β”‚ └── TokenizerTest_temp.cpp # Tokenizer test β”œβ”€β”€ docs/ β”‚ β”œβ”€β”€ CAS_UPGRADE_ROADMAP.md # β˜… CAS Elite roadmap (6 phases, complete) β”‚ β”œβ”€β”€ ROADMAP.md # Phase history + future plan β”‚ β”œβ”€β”€ PROJECT_BIBLE.md # Master software architecture β”‚ β”œβ”€β”€ MATH_ENGINE.md # Math engine + Pro-CAS in detail β”‚ β”œβ”€β”€ HARDWARE.md # ESP32-S3 pinout, wiring, and bring-up β”‚ β”œβ”€β”€ CONSTRUCCION.md # Physical assembly guide β”‚ └── DIMENSIONES_DISEΓ‘O.md # 3D chassis specifications β”œβ”€β”€ platformio.ini # PlatformIO configuration β”œβ”€β”€ wokwi.toml # Wokwi simulator (optional) └── diagram.json # Wokwi circuit diagram ``` --- ## Build Stats > Compiled with `pio run -e esp32s3_n16r8` in **production** mode (CAS tests disabled) | Resource | Used | Total | Percentage | |:---------|-----:|------:|:----------:| | **RAM** (data + bss) | 97 192 B | 327 680 B | **29.7 %** | | **Flash** (program storage) | 1 518 269 B | 6 553 600 B | **23.2 %** | **Flash saved vs test mode:** βˆ’39 444 B when deactivating `-DCAS_RUN_TESTS`. To enable or disable CAS tests, edit `platformio.ini`: ```ini ; ---- Production mode (default) ---- ; -DCAS_RUN_TESTS ← commented out ; ---- Test mode β€” uncomment these two lines ---- ; -DCAS_RUN_TESTS ; +<../tests/CASTest.cpp> ← in build_src_filter ``` --- ## Critical Hardware Fixes Issues discovered and resolved during bring-up. **Essential** for any fork or new build: | # | Problem | Symptom | Solution | |:-:|:--------|:--------|:---------| | **β‘ ** | Flash OPI Panic | Boot β†’ `Guru Meditation: Illegal instruction` | `memory_type = qio_opi` + `flash_mode = qio` | | **β‘‘** | SPI StoreProhibited | Crash in `TFT_eSPI::begin()` at address `0x10` | `-DUSE_FSPI_PORT` β†’ `SPI_PORT=2` β†’ `REG_SPI_BASE(2)=0x60024000` | | **β‘’** | Display noise | Horizontal lines and visual artefacts | Reduce SPI to 10 MHz: `-DSPI_FREQUENCY=10000000` | | **β‘£** | LVGL black screen | `lv_timer_handler()` invokes flush but no image appears | Buffers via `heap_caps_malloc(MALLOC_CAP_DMA\|MALLOC_CAP_8BIT)` β€” **never** `ps_malloc` | | **β‘€** | GPIO 45 BL short | Display stops responding on backlight init | `pinMode(45, INPUT)` β€” the pin is hardwired to 3.3V | | **β‘₯** | Serial CDC lost | Output invisible in Serial Monitor on connect | `while(!Serial && millis()-t0 < 3000)` + `monitor_rts=0` in platformio.ini | --- ## Project Status | Phase | Description | Status | |:------|:------------|:------:| | **Phase 1** | Math Engine β€” Tokenizer, Shunting-Yard Parser, RPN Evaluator, ExprNode, VariableContext | βœ… Complete | | **Phase 2** | Natural Display V.P.A.M. β€” fractions, radicals, exponents, smart 2D cursor | βœ… Complete | | **Phase 3** | Launcher 3.0, SerialBridge, CalculationApp history, GrapherApp zoom/pan | βœ… Complete | | **Phase 4** | LVGL 9.x β€” ESP32-S3 HW bring-up, DMA, animated splash screen, icon launcher | βœ… Complete | | **Phase 5** | CAS-Lite Engine (SymPoly, SingleSolver, SystemSolver, 53 tests) + EquationsApp UI | βœ… Complete | | **CAS Elite** | CAS-S3-ULTRA: BigNum, hash-consed DAG, SymDiff 17 rules, SymIntegrate Slagle, SymSimplify 8-pass, OmniSolver, Unified CalculusApp (d/dx + ∫dx), SettingsApp | βœ… **Complete** | | **Phase 6** | Statistics, Regression, Sequences, Probability, Matrices, Bridge Designer | βœ… **Complete** | | **Simulations** | ParticleLab (30+ materials, electronics), CircuitCore (SPICE), Fluid2D (Navier-Stokes) | βœ… **Complete** | | **Phase 7** | Complex numbers, base conversions | πŸ”² Planned | | **Phase 8** | Physical keyboard, custom PCB, rechargeable battery, 3D enclosure, WiFi OTA | πŸ”² Planned | --- ## Technology Stack | Layer | Technology | Version | |:------|:-----------|:-------:| | **MCU Framework** | Arduino on ESP-IDF 5.x | PlatformIO espressif32 6.12.0 | | **UI / Graphics** | LVGL | 9.5.0 | | **TFT Driver** | TFT_eSPI | 2.5.43 | | **Filesystem** | LittleFS | ESP-IDF built-in | | **Language** | C++17 | lambdas, `std::function`, `std::unique_ptr` | | **CAS Memory** | PSRAMAllocator STL custom | PSRAM OPI 8 MB | | **Build System** | PlatformIO | 6.12.0 | | **Simulation** | Wokwi | wokwi.toml | --- ## Comparison with Commercial Calculators | Feature | **NumOS** | NumWorks | TI-84 Plus CE | HP Prime G2 | |:--------|:---------:|:--------:|:-------------:|:-----------:| | Open Source | βœ… MIT | βœ… MIT | ❌ | ❌ | | Natural Display | βœ… | βœ… | βœ… | βœ… | | Symbolic CAS | βœ… Pro | βœ… SymPy | ❌ | βœ… | | Symbolic derivatives | βœ… | βœ… | ❌ | βœ… | | Symbolic integrals | βœ… | βœ… | ❌ | βœ… | | Solution steps | βœ… | ❌ | ❌ | βœ… | | Colour graphing | βœ… | βœ… | βœ… | βœ… | | Multi-function graphing | πŸ”² | βœ… | βœ… | βœ… | | Statistics & Regression | βœ… | βœ… | βœ… | βœ… | | Matrices | πŸ”² | βœ… | βœ… | βœ… | | Complex numbers | πŸ”² | βœ… | βœ… | βœ… | | Scripting / Python | βœ… NeoLanguage + Python | βœ… | βœ… TI-BASIC | βœ… HP PPL | | WiFi / Connectivity | πŸ”² | βœ… | ❌ | ❌ | | Rechargeable battery | πŸ”² | βœ… | ❌ | βœ… | | Estimated HW cost | **~€15-20** | €79 | €149 | €179 | | Platform | ESP32-S3 | STM32F730 | Zilog eZ80 | ARM Cortex-A7 | > πŸ† NumOS already surpasses the TI-84 in CAS capability and cost, and is on track to match the NumWorks. --- ## Documentation | Document | Description | |:---------|:------------| | [ROADMAP.md](docs/ROADMAP.md) | Complete phase history, milestones, and detailed future plan | | [PROJECT_BIBLE.md](docs/PROJECT_BIBLE.md) | Master architecture, modules, code conventions, and development guides | | [CAS_UPGRADE_ROADMAP.md](docs/CAS_UPGRADE_ROADMAP.md) | Full roadmap for the 6-phase CAS Elite upgrade | | [MATH_ENGINE.md](docs/MATH_ENGINE.md) | Math engine + Pro-CAS: design, algorithms, pipeline, and examples | | [HARDWARE.md](docs/HARDWARE.md) | ESP32-S3 pinout, complete wiring, critical bugs, and bring-up notes | | [CONSTRUCCION.md](docs/CONSTRUCCION.md) | Physical assembly guide, 3D printing, and hardware testing | | [DIMENSIONES_DISEΓ‘O.md](docs/DIMENSIONES_DISEΓ‘O.md) | Dimensional specifications for the 3D chassis | --- ## Contributing NumOS is an open-source project that aspires to grow with a community. Contributions are welcome! 1. **Fork** the repository. 2. Create a branch: `git checkout -b feature/descriptive-name` 3. Follow the [code conventions](docs/PROJECT_BIBLE.md#guia-de-estilo) of the project. 4. Verify the build passes: `pio run -e esp32s3_n16r8` 5. If you add math logic, include tests in `tests/`. 6. Open a **Pull Request** with a clear description of your changes. ### Areas Where Help Is Most Needed | Module | Description | |:-------|:------------| | **Sequences App** | Arithmetic and geometric sequences, Nth term, partial sums | | **Settings App** | ~~Angle mode DEG/RAD/GRA, brightness, factory reset~~ βœ… Done, remaining: brightness PWM, factory reset | | **Advanced CAS** | ~~Symbolic derivatives and integrals~~ βœ… Done, remaining: definite integrals, series | | **Better UI/UX** | General improvement on UI and UX for real product release | | **Matrices** | Matrix editor, determinant, inverse, multiplication | | **Physical keyboard** | βœ… GPIO 4/5 conflict resolved β€” `Keyboard` driver 5Γ—10 implemented (Phase 7) | | **Custom PCB** | KiCad schematic with integrated ESP32-S3 + TP4056 charger | --- *This project was developed with AI assistance (Claude/Copilot) for code generation, guided by the author's systems architecture decisions. All design choices like DAG structure, memory management, parser design, were made and validated by the author.* ## Licence This project is licensed under the **MIT** licence. See [LICENSE](LICENSE) for details. ---
*Built with ❀️ and a lot of C++17* **NumOS, The best open-source scientific calculator for ESP32-S3** *Last updated: March 2026*