Firmware Calculations Are Invisible — So I Built CalcDocs for VS Code

Gian Michele Pasinelli — Wed, 27 May 2026 11:33:41 +0000

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.

DEV Community: Gian Michele Pasinelli