🧮 CalcDocs — Instantly See What Your Firmware REALLY Computes [0.2.8 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.

---

Important

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

---

Tip

Keep engineering calculations close to the firmware logic instead of:

• Excel sheets
• random .txt files
• disconnected documentation

Your firmware becomes self-documented.

---

3️⃣ Macro Chain Revelation

File	Preview
Inside C code
Inside formulas*.yaml

---

👀 Firmware Blindness — Before vs After

Before	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

---

Warning

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

---

Important

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

---

Note

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.

---

Tip

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

---

🧠 Final thought

Spreadsheets hide logic. Code hides values.

CalcDocs reveals both.