Table of Contents

0. Webpage
1. What is NumOS?
2. Key Features
3. System Architecture
4. CAS Engine
5. Hardware
6. Quick Start
7. User Manual — EquationsApp
8. Project Structure
9. Build Stats
10. Critical Hardware Fixes
11. Project Status
12. Technology Stack
13. Comparison with Commercial Calculators
14. Documentation
15. 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:

• Giac-backed CAS Engine — Symbolic math now runs through Giac C++ via src/math/giac/GiacBridge.cpp (The Big Switch). Legacy CAS-S3 modules remain documented as historical milestones and optional local tooling.
• 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 Numeric 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

Photo gallery

Neural Network Simulator:

Fluid 2D Simulator:

Periodic Table (Chemistry App):

Grapher App:

Steps (Equations App) (WIP, still in development, Alpha):

Calculus App:

Probability (Gaussian Distribution):

Python App:

Bridge Designer:

Circuit Simulator (Circuit Core, Alpha):

Particle Lab (Powder Toy like):

Optics Lab:

System Architecture

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 (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["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

CAS Engine

The CAS (Computer Algebra System) now uses Giac C++ as the canonical symbolic backend. The migration is routed through src/math/giac/GiacBridge.cpp and consumed by the UART command path in src/input/SerialBridge.cpp.

Legacy CAS-S3 internals documented below remain as historical milestones and optional local components, but symbolic truth for current backend flows comes from Giac.

Giac Migration Milestones

• Big Switch complete: custom symbolic backend replaced by Giac as canonical CAS.
• Embedded numeric stabilization complete with -DDOUBLEVAL.
• Stack stabilization complete with -DARDUINO_LOOP_STACK_SIZE=65536.
• Real-style defaults complete: complex_mode(false) and preserved imaginary unit behavior (i^2 = -1).
• UART command path certified on hardware for sum, int, solve, and simplify.

CAS Pipeline (Derivatives)

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)

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"]

CAS Components

CAS Tests — 53 Unit Tests

# platformio.ini — enable tests:
build_flags    = ... -DCAS_RUN_TESTS
build_src_filter = +<*> +<../tests/CASTest.cpp>

Hardware

Full Pinout

ILI9341 Display

5×10 Keyboard Matrix (driver Keyboard, Phase 7)

✅ 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 (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

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:

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 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

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       # CAS — Equation solver
│   │   ├── CalculusApp.cpp/.h        # 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 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 roadmap (6 phases, complete)
│   ├── ROADMAP.md                    # Phase history + future plan
│   ├── PROJECT_BIBLE.md              # Master software architecture
│   ├── MATH_ENGINE.md                # Math engine + 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)

Flash saved vs test mode: −39 444 B when deactivating -DCAS_RUN_TESTS.

To enable or disable CAS tests, edit platformio.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:

Project Status

Technology Stack

Comparison with Commercial Calculators

🏆 NumOS already surpasses the TI-84 in CAS capability and cost, and is on track to match the NumWorks.

Documentation

Support the Project ☕

The EV grant graciously covers the core hardware prototyping. However, I have set a €500 goal on Ko-fi to fund the crucial "invisible" infrastructure of NumOS.

Your support directly funds:

1. ** AI & Dev Tools:** Subscriptions for Claude/Copilot to accelerate C++ optimization and the Giac engine porting.
2. Digital Presence: Domain hosting (neocalculator.tech / numos.org) and backend web services.
3. Beta Shipping: Sending physical beta units to expert contributors globally to accelerate community development.

Every contribution keeps me focused on the mission and ensures NumOS stays independent and open-source.

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 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

_{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.}

License & Intellectual Property

Software (Firmware)

The NeoCalculator firmware (NumOS) is licensed under the GNU GPL v3. We are proud to build upon the Giac engine by Bernard Parisse. In accordance with the GPL v3, all software source code in this repository is open for study, modification, and redistribution.

Hardware & Industrial Design

All rights reserved. The hardware design, including but not limited to:

• PCB Schematics and Layouts (KiCad files, Gerbers).
• Industrial Design and 3D Models (STL, STEP, CAD files).
• The "Exam Key" security architecture.

Are proprietary and the intellectual property of Juan Ramón. No commercial use or reproduction of the hardware is permitted without express authorization.

Note on Hardware IP: This proprietary status is a necessary measure for now. Our primary goal is to maintain the strict hardware control required to eventually achieve official "Exam Legal" certification and to protect the project's integrity from low-quality, unauthorized clones. Once the ecosystem is mature and certified, we plan to evaluate open-hardware licensing models.