28 Virtual Hardware: Test Harnesses

28.1 Start With the Decision

A virtual board can prove state order before real parts arrive. It cannot prove heat, voltage, or radio timing by itself.

28.2 Route Overview

This is part 1 of 2. Continue with Virtual Hardware: Evidence Transfer.

28.3 Part Objectives

• Build a repeatable virtual circuit and firmware test.
• Inject faults while keeping model limits explicit.

28.4 Chapter Roadmap

• Begin With One Risky Line of Code
• Start With the Firmware Risk
• Phoebe’s Field Notes: The Rise Time A Zero-Ohm Virtual Wire Cannot Show You
• Simulate, Then Prove Firmware
• Build Virtual Circuit Test Harness
• Ideal Models Hide Gaps
• In 60 Seconds
• Prerequisites
• What This Chapter Adds
• Use Virtual Hardware as Evidence
• Choose the Simulator Role

28.5 Begin With One Risky Line of Code

Firmware is the code that runs on a device. Picture a board that should sound an alarm when a level switch changes. A virtual board can run the code before the real parts arrive. Start with one claim the test can support, such as the order of states or the response to a missing reading. Keep claims about real voltage, heat, timing, and power for the bench.

Build the smallest repeatable circuit. Fix the part types, starting state, and input steps. Save the code and tool version. Run the normal case. Then force a stuck input, a slow reply, a reset, and a lost link. Record the state, output, log, and expected safe action. A green run is useful only when another person can repeat it.

Fast virtual tests can cover many code paths, but ideal parts may hide rise time, noise, pull-up, and current faults. A detailed model can help, but it is still a model. This first pass does not release the product. Use the Practitioner layer to build the test harness, inject faults, and plan the handoff. Use the Under the Hood layer to inspect model limits, signal facts, timing gaps, and physical proof. The deeper route tells you which claims must wait for real hardware.

Keep a two-part claim list. Put code order, state change, and error paths on the virtual side. Put real heat, current, noise, edge shape, range, and part spread on the bench side. Some claims need both. Mark them that way. This stops a fast test from being read as full proof.

Run the same short case after each change. Start. Read. Act. Lose the input. Recover. Save the log. A small repeat test finds many simple breaks. Add a fixed seed when chance is used. Fix the clock when time drives the code. Check the result, not just the lack of a crash. Make the safe state visible.

Before the bench test, print the open claim list. Use the same input steps where you can. Measure what the model could not show. Note each part and wire. If the real board acts in a new way, add that case to the fast test when the tool can model it. The two test paths should teach each other.

Close each run with three marks. Pass means the named claim held. Fail means it did not. Open means the tool could not show it. Do not turn open into pass. Save the run with the code change. A short honest result is more useful than a long demo with no claim.

28.6 Start With the Firmware Risk

Imagine firmware that passes on a desk but fails when a sensor is noisy, an interrupt arrives early, a bus stalls, or a peripheral resets. Virtual hardware is useful when it exposes that risk before physical boards are scarce or unsafe to modify. The simulation should name the behavior being tested and the evidence needed before code moves to real hardware.

Phoebe’s Field Notes: The Rise Time A Zero-Ohm Virtual Wire Cannot Show You

The mathematical gist. An 80 pF I2C bus with a 10 kΩ pull-up rises in 678 ns because $t_r=0.847R_{pu}C_{bus}$. That is 2.26 times the 300 ns Fast-mode limit and even longer than its 600 ns minimum high phase; the same resistor remains within Standard-mode’s 1,000 ns limit.

Math Bridge · guided foundationsWhy can a pull-up pass at 100 kHz and fail at 400 kHz?Let Blueprint Bina turn resistance and bus capacitance into the rise time an ideal simulator cannot show. Learn the maths

28.7 Learning Objectives

By the end of this chapter, you will be able to:

• Define which hardware-programming claims a simulator can support and which claims require physical hardware.
• Build a repeatable virtual circuit that links firmware, pin maps, virtual peripherals, test inputs, and expected observations.
• Use simulated boards and peripherals to exercise firmware logic, state transitions, error handling, and interface assumptions.
• Capture simulation evidence without overclaiming timing, analog, radio, power, or environmental behavior.
• Plan a controlled transfer from simulation to bench hardware and record what must be revalidated.

28.8 Simulate, Then Prove Firmware

Virtual hardware is useful when the team is clear about the claim. It can run firmware against a modeled board, sensor, display, bus, timer, interrupt, or user input before the physical prototype is available. It cannot prove the real board’s electrical margin, analog accuracy, radio range, enclosure behavior, thermal behavior, or battery life. A useful Wokwi, Tinkercad Circuits, Renode, QEMU, Proteus, or custom harness run therefore answers a scoped question such as whether a fault branch executes, whether a pin map matches the intended schematic, or whether a parser survives malformed input.

A strong simulation pass names three things before anyone celebrates a green run: the firmware behavior being exercised, the model boundary, and the bench check that will replace the virtual assumption. That keeps a simulator from becoming a shortcut around hardware truth. For an ESP32 or Arduino-style node, the model may cover GPIO, serial logs, button state, virtual DHT22/BME280 values, and an MQTT mock, while omitting Wi-Fi coexistence, regulator behavior, antenna placement, and sleep current. For an RP2040 or Zephyr target, it may cover I2C/SPI/UART sequencing and reset logic while omitting actual pullups, timing margin, and board variant constraints.

The Simulate, Then Prove Firmware argument uses Figure 28.1 to compare Design Claim. Look next for Model Scope before accepting Hardware simulation is useful when every run starts with a claim and ends with evidence plus a hardware-transfer action as a design claim.

Trace Figure 28.1 through Design Claim, Model Scope, and Virtual Build. At the first stop, the diagram uses Design Claim to state a required condition; at the second it uses Model Scope to test technical feasibility; at the third it highlights Virtual Build. Those hand-offs make Hardware simulation is useful when every run starts with a claim and ends with evidence plus a hardware-transfer action actionable within Simulate, Then Prove Firmware.

The loop is deliberately conservative. It starts with a design claim, records model scope, builds a reproducible virtual setup, applies normal and fault stimuli, captures observed evidence, and sends unresolved physical claims to hardware transfer. That means a passing simulator run is allowed to move firmware work forward, create reviewable logs, and uncover missing error handling. It is not allowed to replace logic-analyzer traces, oscilloscope measurements, current profiling, sensor calibration, RF testing, or environmental checks when those are the claims under review.

• Good simulation claim: The firmware handles missing sensor data, invalid messages, reset during alarm, or a full command buffer.
• Model boundary: Virtual pins, ideal sensors, simplified bus timing, deterministic inputs, and omitted power/RF/thermal effects.
• Hardware transfer: Repeat the scenario on a real board with serial logs, logic analyzer traces, power measurements, and sensor checks.

28.9 Build Virtual Circuit Test Harness

Treat the virtual circuit as versioned engineering material. For a Wokwi project, keep diagram.json, firmware source, board target, library versions, serial output, and scenario instructions together. For Renode or QEMU, keep the platform description, machine configuration, firmware image, startup script, UART log, and CI command. For Arduino CLI, PlatformIO, or Zephyr builds, keep the board identifier, compile flags, dependency lock state, and simulator-specific setup. The review artifact should be runnable by someone who did not build the demo.

Name the actual interfaces the firmware depends on. A Raspberry Pi Pico or RP2040 simulation may exercise GPIO, PWM, I2C, SPI, UART, timers, and interrupt handling. An ESP32 or Arduino-style node may exercise Wi-Fi/MQTT mock paths, OLED updates, button state, LED state, DHT22/BME280/DS18B20-style sensor values, and serial diagnostics. A useful run includes normal, boundary, missing-device, invalid-value, reset, and rapid-input cases. Each case should state the expected serial line, display state, LED state, message count, timeout branch, or assertion result.

Carry simulator evidence into the same workflow used for physical verification. If the simulation checks an I2C sensor branch, the handoff should name the bench counterpart: pullup values, bus speed, address scan, logic-analyzer capture, and sensor-read timing. If it checks a sleep or watchdog path, the handoff should name current measurement, wake source, reset reason, brownout threshold, and battery-load test. If it checks a gateway service image in QEMU or Renode, the handoff should name boot timing, peripheral availability, network path, log correlation, and target-board rerun. This keeps the virtual circuit from becoming a separate truth source.

1. Freeze the pin map. Match virtual pins to the schematic, datasheet pin names, voltage domains, pullups, and connector plan.
2. Drive failure paths deliberately. Use absent sensors, wrong I2C address, malformed UART input, full buffers, watchdog reset, and repeated button events.
3. Carry the same scenario to the bench. Use a logic analyzer, oscilloscope, current probe, serial logger, RF tool, or calibrated sensor as the physical counterpart.

28.10 Ideal Models Hide Gaps

Most virtual hardware models are intentionally simplified. They may not model pullup resistance, bus capacitance, rise/fall time, ADC noise, oscillator drift, brownout, regulator dropout, interrupt jitter, DMA timing, flash wear, boot strap pins, ESD damage, connector tolerance, or sensor calibration. A clean simulated I2C transaction does not prove a real cable, board layout, or pullup value will survive the bench. A clean UART parser run does not prove level shifting, framing under noise, or connector strain. A successful simulated Wi-Fi publish does not prove antenna placement, roaming, coexistence, or access-point recovery.

This is why the under-the-hood result is a set of transfer questions, not a release claim. If a simulated SPI waveform has the right command order, the bench still needs chip-select timing, voltage level, setup/hold margin, real peripheral response, and noise check. If a simulated sleep path reaches low-power mode, the bench still needs current draw, wake latency, watchdog behavior, and battery-load measurement. If a simulator runs a Zephyr or embedded-Linux image, the target board still needs driver availability, device-tree accuracy, bootloader behavior, peripheral timing, flash partition, and recovery-path checks.

The practical reason to write these limits down is that simulator failures and bench failures have different root-cause classes. A simulator mismatch may be firmware logic, fixture data, library version, build target, or model coverage. A bench mismatch may be schematic, assembly, power integrity, tolerance, environmental condition, instrument setup, or firmware timing. Good evidence separates those categories, updates the model when the bench exposes a wrong assumption, and keeps the simulator useful for regression tests without pretending it measures physical reality.

• Digital state: State machine branch, message parser, debounce behavior, timeout path, reset recovery, and watchdog path.
• Physical state: Voltage, current, timing margin, thermal condition, analog tolerance, RF path, and mechanical access.
• Transfer gap: The exact physical measurement or bench scenario that must follow the simulator run.

28.11 Prerequisites

You should already be comfortable with:

• Specification Sheet Fundamentals: turning part documents into design assumptions and validation actions.
• Hardware prototyping: breadboards, wiring, pullups, decoupling, and basic bench checks.
• Prototyping software: firmware sketches, libraries, serial logs, and build configuration.
• End-to-End Test Strategy: evidence records, test limits, and the difference between development checks and release validation.

28.12 What This Chapter Adds

The testing-validation chapters discuss simulation tools and validation methods in more detail. This chapter focuses on the design-methodology question: how do you use simulated hardware programming without letting simulation claims drift beyond what the model can prove?

28.13 Use Virtual Hardware as Evidence

Virtual hardware is useful when it answers a narrow firmware or integration question. The team names the claim, states what the model includes, builds a repeatable virtual circuit, applies normal and fault stimuli, captures the observed behavior, and carries the same scenario to physical hardware when the claim depends on electrical, timing, analog, RF, power, or environmental reality.

Use the loop introduced in the overview when the firmware depends on board pins, sensors, bus devices, displays, actuators, timers, interrupts, or user interaction. The loop makes simulation a disciplined development activity instead of a quick demo that becomes unreviewable later.

28.14 Choose the Simulator Role

Do not rank simulators in the abstract. Choose the role that matches the evidence you need.

28.15 Continue to the Next Part

Carry this evidence into Virtual Hardware: Evidence Transfer, which begins with Tool Names Are Not Evidence.