Every embedded project eventually accumulates “hidden math”.
Not complex algorithms.
Just hundreds of tiny engineering calculations scattered across:
- macros
- scaling constants
- ADC conversions
- timer formulas
- configuration headers
- lookup tables
- spreadsheets
- comments
- old documentation
And over time, nobody remembers where the numbers actually come from.
The Problem Isn't Complexity. It's Visibility.
A firmware project may contain code like this:
#define PWM_FREQ 20000
#define TIMER_CLK 170000000
#define PWM_PERIOD (TIMER_CLK / PWM_FREQ)
The calculation is technically simple.
But understanding it still requires mental parsing, context switching, and manual evaluation.
Now multiply that by:
- multiple abstraction layers
- chained macros
- unit conversions
- integer scaling
- safety margins
- hardware-specific constants
- formulas real-time resolver
Eventually the firmware becomes full of numeric logic that engineers can no longer see directly.
That was the frustration behind CalcDocs.
What Is CalcDocs?
CalcDocs is a VS Code extension that turns engineering calculations into live, inspectable objects directly inside the editor.
Instead of treating formulas as passive text, it evaluates and visualizes them in context.
Example:
#define PWM_PERIOD (TIMER_CLK / PWM_FREQ) // 8500
No spreadsheet.
No calculator.
No mentally simulating the preprocessor.
Just immediate feedback where the calculation actually lives.
What It Can Do
CalcDocs currently supports:
- inline formula evaluation
- C/C++ macro expansion
- live computed values
- engineering formulas in YAML
- dimensional/unit validation
- symbol dependency resolution
- inline calculations inside comments
- interactive formula visualization
- hybrid static analysis
The goal is not to replace firmware code.
The goal is to make engineering intent visible again.
Why This Matters in Embedded Systems
Embedded software often sits in a strange middle ground between:
- software engineering
- electronics
- physics
- control systems
- industrial constraints
A single incorrect scaling factor can silently propagate across an entire system.
And the worst bugs are often not algorithmic bugs.
They're interpretation bugs.
Examples:
- wrong unit assumptions
- invalid conversion factors
- outdated spreadsheet formulas
- mismatched documentation
- stale calibration constants
- copy-pasted numeric logic
Most of these issues are fundamentally visibility problems.
The Spreadsheet Problem
In many companies, engineering knowledge slowly migrates outside the firmware repository.
The code contains one version.
Excel contains another.
Documentation contains a third.
Eventually nobody fully trusts any of them.
CalcDocs started as an attempt to reduce that fragmentation.
The idea is simple:
keep formulas close to the code, but make them understandable like documentation.
Interactive Formula Exploration
One of the most interesting additions was the interactive formula viewer.
Instead of only displaying final values, formulas can now be explored dynamically inside VS Code.
This becomes extremely useful during:
- debugging
- calibration
- signal analysis
- parameter tuning
- validation activities
Especially when formulas intentionally remain symbolic during development.
Under the Hood
CalcDocs combines several layers:
- expression parsing
- AST evaluation
- macro expansion
- lightweight static analysis
- symbol tracking
- unit-aware computation
- VS Code integration
The difficult part isn't evaluating formulas.
The difficult part is matching how real firmware projects are structured.
Why I’m Exploring This Area
I work mostly on:
- embedded firmware
- Cortex-M systems
- industrial/IoT devices
- RTOS-based applications
- developer tooling
Over time I realized many embedded workflows still depend heavily on:
- tribal knowledge
- disconnected spreadsheets
- manual verification
- implicit assumptions
I think tooling around engineering visibility is still massively underexplored.
Future Directions
Some areas I’m currently exploring:
- stronger dimensional analysis
- cross-file dependency graphs
- richer interactive webviews
- symbolic computation
- tighter integration with documentation
- formula traceability
- engineering validation workflows
Final Thought
Most firmware calculations are not difficult.
They're just hidden.
CalcDocs is an attempt to make embedded engineering knowledge visible directly where it matters most: inside the code.
If you work on embedded systems, I’d genuinely be interested in how your team handles:
- formulas
- scaling factors
- engineering constants
- unit conversions
- spreadsheet dependencies
because every company seems to reinvent this differently.
