Why I Built CalcDocs: Making Firmware Calculations Visible Inside VS Code
Inline calculations • Macro value expansion • Engineering formulas • Unit conversions
Embedded firmware projects are full of hidden numeric logic.
A simple value often depends on:
- chained macros
- scaling factors
- unit conversions
- lookup tables
- configuration headers
- external spreadsheets
Understanding what a single constant actually means often requires jumping across multiple files and reconstructing the computation in your head.
After dealing with this repeatedly in industrial and IoT firmware projects, I started building a VS Code extension to make these relationships visible directly inside the editor.
That project became CalcDocs.
The problem: hidden computation in plain sight
In many embedded projects, formulas live in different places at the same time:
- firmware code (C/C++)
- configuration headers
- spreadsheets
- documentation
- sometimes only in engineers’ heads
Over time, these sources tend to diverge.
A value might look simple in code:
#define SPEED (RPM * 0.10472)
But in reality it depends on implicit assumptions, scaling factors, and domain knowledge that is not immediately visible.
To understand it, you often need to:
- search for related macros
- follow indirect definitions
- check external documentation
- manually evaluate expressions
- rebuild the mental model of the system
The real issue is not computation complexity.
The issue is visibility.
What I wanted to change
I wanted formulas in firmware to behave less like hidden implementation details and more like live engineering objects.
Something that you can:
- read directly in context
- evaluate inline
- understand without leaving the code
This is where CalcDocs started.
What CalcDocs does
CalcDocs is a VS Code extension designed to make engineering calculations visible directly inside your codebase.
- inline evaluation of expressions
- macro expansion
- C/C++ constants support
- YAML-based formulas
- unit and dimensional checks
- detection of invalid expressions
- inline computation in comments
- hybrid symbol resolution
The goal is simple: reduce the need to mentally simulate the code.
Example
Instead of:
#define RPM 1000
#define SPEED (RPM * 0.10472)
You see:
#define SPEED (RPM * 0.10472) // 104.72
The idea is not to replace the code, but to augment it with immediate engineering visibility.
Under the hood
CalcDocs combines:
- expression parsing and AST evaluation
- macro expansion
- lightweight static analysis
- symbol resolution
- integration with language tooling
The challenge is consistency with real firmware code structures, not just computation.
Why this matters in embedded systems
Embedded and industrial software often suffers from a disconnect between:
- what the code says
- what the system actually computes
- what engineers assume it does
This becomes critical when:
- systems grow in complexity
- multiple engineers contribute
- documentation is outdated
- values are reused across subsystems
Small mismatches can lead to:
- debugging time loss
- integration issues
- calibration errors
- system-level bugs
The real problem is not computation.
The problem is visibility.
Engineering workflows
CalcDocs is part of a broader exploration of embedded engineering workflows:
- live documentation in code
- unit-aware computation
- tighter firmware/model coupling
- reducing spreadsheet dependency
- improving traceability
What’s next
- stronger unit system integration
- deeper static analysis
- cross-file dependency handling
- performance improvements
- better VS Code integration
Final thoughts
CalcDocs started as a personal attempt to reduce friction in firmware development.
It is now evolving into a broader investigation of engineering tooling for embedded and industrial software.
If you work in this space, I’d be interested in how you manage:
- constants
- formulas
- scaling factors
