🧮 CalcDocs — Instantly See What Your Firmware REALLY Computes [0.3.4-prerelease]

Reveal hidden firmware values directly inside VS Code.
Inline calculations • Macro value expansion • Engineering formulas • Unit conversions

Live engineering knowledge embedded directly into firmware.
Stop rebuilding firmware formulas in Excel ➡️ Reuse the originals directly.

Firmware logic is often invisible.

Values are buried behind:

• chained macros
• scaling constants
• unit conversions
• spreadsheet calculations
• scattered documentation

👉 CalcDocs makes those values visible instantly.

⚡ What CalcDocs does

CalcDocs transforms VS Code into a live firmware calculation explorer.

Instead of manually expanding macros, opening Excel files, or mentally resolving formulas:

✅ Hover a value
✅ See the final computed result
✅ Understand firmware logic instantly

No build. No flashing. No debugger.

⚡ 5-second demo

1️⃣ Coding Evaluator

Write this:

#define RPM 1000
#define SPEED (RPM * 0.10472)

CalcDocs instantly shows:

#define SPEED (RPM * 0.10472)   ← 104.72

✅ Real-time evaluation
✅ Inline resolved values
✅ No manual calculations

2️⃣ Realtime Engineering Notes

Write this directly inside your firmware comments:

// @rpm = 3000 rpm
// = @rpm -> rad/s
// = 13 N * 1 m * @rpm -> W

CalcDocs evaluates everything live:

// @rpm = 3000 rpm
// = @rpm -> rad/s <- 314.1592653589793 rad/s
// = 13 N * 1 m * @rpm -> W <- 4084.0704496667313 W

• Realtime calculations directly in comments
• Unit conversion (rpm -> rad/s, atm -> Pa, etc.)
• Keep formulas near the actual firmware logic
• Eliminate scattered Excel and text notes

Keep engineering calculations close to the firmware logic instead of:

• Excel sheets
• random .txt files
• disconnected documentation

Your firmware becomes self-documented.

3️⃣ Interactive Formula Explorer

Explore firmware formulas as a live dependency graph directly inside VS Code.

CalcDocs keeps formulas and firmware intrinsically synchronized.

The same engineering logic can now:

✅ live next to production code
✅ be evaluated in real time
✅ be reused during debugging
✅ propagate through dependencies automatically
✅ stay permanently aligned with the firmware implementation
✅ can also propagate tolerances (e.g. tol, min/max) through your YAML formula dependency graph to compute final min/max ranges.

No duplicated engineering logic.
No spreadsheet drift.
No parallel maintenance.

4️⃣ Macro Chain Revelation

File	Preview
Inside C code
Inside formulas*.yaml

👀 Firmware Blindness — Before vs After

Before	After

⚡ Quick Actions & Header Generation

Header generation

Quick menu

🔥 Why this matters

Firmware development is rarely difficult because of syntax.

It becomes difficult because:

• values are hidden
• formulas are fragmented
• scaling is implicit
• engineering decisions live outside the codebase

Understanding a single value may require:

• opening multiple headers
• expanding macro chains
• checking documentation
• validating unit conversions
• searching old spreadsheets

Most firmware projects suffer from:

• duplicated formulas
• stale spreadsheets
• undocumented scaling
• hidden assumptions

These issues create real bugs.

CalcDocs removes that friction.

Instead of navigating half the project:

👉 you immediately see what the firmware computes.

🔗 YAML ↔ C Synchronization

Define formulas once:

power:
  formula: vin * current
  unit: W

Use them everywhere.

CalcDocs:

✅ evaluates formulas
✅ syncs YAML with C/C++
✅ prevents formula drift
✅ shows results inline

⚖️ Built-In Validation

Detect issues early:

• Unit mismatches
• Overflow risks
• Invalid conversions
• YAML/C inconsistencies

CalcDocs is designed for real embedded firmware workflows.

👀 What it looks like in real code

#define VIN 24
#define CURRENT 2
#define POWER (VIN * CURRENT)

CalcDocs shows:

#define POWER (VIN * CURRENT)   ← 48W

💡 Real use cases

🔍 Understand code instantly

No more jumping across headers to resolve macros

⚠️ Catch bugs early

See wrong values before flashing your MCU

🔄 Eliminate Excel drift

Formulas stay aligned with firmware

🧪 Debug faster

Know values before runtime

📚 Create Self-Documenting Firmware

Engineering decisions stay inside the source code.

❗ What CalcDocs Is NOT

CalcDocs is intentionally focused.

It is:

❌ NOT a compiler
❌ NOT a debugger
❌ NOT a full static analyzer

CalcDocs focuses on one thing:

making firmware numeric logic visible.

⚙️ Recommended setup (optional)

CalcDocs works standalone.

For best results, combine it with:

• clangd (recommended)
• ms-vscode.cpptools
• CMake Tools

CalcDocs integrates without conflicts.

CalcDocs supports engineering prefixes automatically:

mV, uV, nV, kV, MHz, mA, etc.

❤️ Support

If CalcDocs saves you time:

• ⭐ Leave a review (this helps a lot)
  https://marketplace.visualstudio.com/items?itemName=convergo-dev.calcdocs-vscode-extension

• 💖 Support development
  

📚 Documentation

Full documentation available on GitHub:

• 👉 Getting Started
• 👉 Formula YAML Guide
• 👉 Real Use Cases
• 👉 Features Overview
• 👉 Configuration
• 👉 Architecture
• 👉 Limitations
• 👉 Contributing
• 👉 Inline Calculations
• 👉 Interactive Formula Viewer
• 👉 Tolerance propagation & formula ranges

🧠 Final thought

Spreadsheets hide logic. Code hides values.

CalcDocs reveals both.