Scrutiny Debugger reads target variables from debug symbols and moves their values through a client/server data path for live dashboards, scripts, graphs, and hardware-in-the-loop testing. The number that matters is requested bytes per update multiplied by update frequency: when that demand approaches the capacity of the transport or target instrumentation, samples arrive late and control-loop observations lose timing fidelity. Configure only the variables needed at each rate, verify target timing under load, and reduce acquisition demand before treating delayed data as a control-logic defect.
Runtime data path
Scrutiny is more than a visualization layer. It interprets compiler debug symbols, identifies variable locations and types, acquires target memory, and exposes the results to both a GUI and a Python SDK. The client/server architecture allows an operator dashboard and a HIL test script to use the same server-side target connection.
Acquisition can use a small portable instrumentation library when extracting data through a debug probe is impractical. The instrumentation layer can also catch target events. Available communication paths include CAN bus, J-Link RTT, and a user-built bridge that presents another physical link through a UDP socket.
Symbol interpretation is part of the measurement chain. Compiler support therefore has two dimensions: whether the instrumentation library builds for the target, and whether the server correctly interprets the compiler's debug-symbol representation. A successful target build does not prove that structures, pointers, or addresses will decode correctly.
Symptom quantities and limits
Start with acquisition rate, payload size, transport capacity, and target execution time. This is load and timing, not dashboard logic. Read actual refresh behavior in the client, communication statistics in the transport, and execution-time measurements in the target rather than assigning an unsupported numerical limit.
| Quantity | Why it matters | Where to read or measure it |
|---|---|---|
| Requested update frequency | Raises transactions and processing demand as it increases | Per-variable refresh-rate configuration |
| Bytes requested per update | Arrays and expanded structures can dominate each acquisition cycle | Debug type information and selected variable list |
| Approximate payload rate | Provides a first-pass load estimate: selected bytes per update × updates per second | Calculate from the two rows above; add protocol overhead separately |
| Transport utilization | High utilization produces queueing, latency, and irregular delivery | CAN, RTT, or UDP bridge diagnostics |
| Instrumentation execution time | Consumes target CPU time and can disturb time-sensitive control work | Target trace, execution timer, or task-runtime measurement |
| Symbol-to-memory mapping | An incorrect address or type yields implausible values despite a healthy link | Compiler map/debug data and a known test variable |
A stale gauge, uneven graph spacing, or slow script response points first to acquisition scheduling and transport queueing. A stable but impossible value points instead to symbol interpretation, address units, type layout, pointer validity, or stale firmware metadata.
Acquisition load mechanism
Each selected variable creates work at several layers: the client requests an update, the server resolves its type and address, the target or probe reads memory, the transport carries the response, and the clients process it. Large arrays and fully expanded structures increase payload. Fast refresh rates increase transaction count even when each value is small.
Use separate rates according to signal dynamics. Fast-changing control variables may justify frequent acquisition; configuration values, state labels, and PID gains generally change less often. Scrutiny provides fine-grained refresh control for individual variables, so low-priority values need not consume the same bandwidth as a waveform under investigation.
Pointer dereferencing adds another failure mode. A variable declared as MyStruct* can be displayed as an expandable structure and its members can be edited, but the pointer value must reference valid, accessible memory at the instant of access. Initialization, object lifetime, and concurrent updates remain properties of the target application.
TI C2000 targets require special attention because their architecture uses a 16-bit byte. Address units and type sizes must follow the target architecture rather than the conventional assumption that one byte contains eight bits. Validate a known scalar, an array element, and a structure member before trusting bulk acquisition on that architecture.
Configuration procedure
Build the exact target firmware with debug information from a supported compiler configuration. Preserve the matching firmware image and symbols as one revision-controlled pair.
Select the acquisition path. Use the instrumentation library when direct probe extraction is unsuitable, CAN where it matches the target integration, J-Link RTT when available, or bridge another link to a UDP socket.
Load the matching firmware metadata into the server. Firmware can be managed through the GUI, but the selected metadata still has to correspond to the code running on the target.
Add one known scalar variable at a conservative refresh rate. Change it through a controlled target action and confirm that both value and timing are plausible.
Add arrays, structures, and pointers progressively. For
MyStruct*, confirm the pointer address before editing internal members.Assign refresh rates by diagnostic value and signal bandwidth. Keep slow configuration values below the acquisition priority of fast control signals.
Bind validated variables to gauges, sliders, light switches, buttons, or graphs. Treat writable widgets as commands that can change live target memory.
Connect the Python SDK for automated HIL work, then define expected values, tolerances, event conditions, and test sequencing in the test script.
Export a known value set when the setup is stable. Reimporting value sets can restore items such as PID gains for a specific setup, so verify the active firmware and machine state before applying them.
Verification under operating load
Repeat verification with the same variable count, refresh rates, GUI widgets, graphs, and HIL scripts intended for normal use. A one-variable bench check proves address resolution; it does not prove that the final acquisition load preserves control timing.
Compare a known target variable against an independent observation or an internal target calculation.
Exercise minimum, nominal, and maximum expected values and check signedness, scaling, array indexing, and structure-member placement.
Measure the target task or control-loop execution time with acquisition disabled and enabled. Any unacceptable increase is an instrumentation-load problem.
Increase requested variables in stages while watching latency, missed updates, transport errors, and graph timing.
Run the GUI and Python HIL client concurrently to validate the client/server operating case.
After importing a saved value set, read every safety-relevant or motion-relevant value back from the target before enabling operation.
Differential graph cursors and editable axes help compare transitions and measure intervals, but the graph cannot restore timing information lost before the sample reached the server. Use a target-side event capture when the event is shorter than the effective acquisition interval.
Recurring integration pitfalls
| Symptom | Likely mechanism | Corrective action |
|---|---|---|
| Values decode incorrectly after a firmware change | Running code and debug symbols no longer match | Select the firmware metadata produced by the deployed build |
| Graphs update irregularly | Requested traffic exceeds transport or processing capacity | Reduce variable count or individual refresh rates, then retest |
| Pointer members disappear or become implausible | Null, stale, or changing pointer value | Validate pointer lifetime and address before dereferencing |
| TI C2000 addresses appear offset | Eight-bit-byte assumptions entered the integration | Validate address units and type sizes against the compiler output |
| Saved tuning values produce unexpected behavior | Value set belongs to another firmware or setup | Check revision compatibility and read values back after import |
| Existing OpenOCD/SWD connection cannot be selected directly | Native OpenOCD support was planned rather than identified as ready | Use an available path or implement a UDP bridge |
Writable dashboards deserve the same access discipline as any commissioning interface. A slider or button can alter live memory immediately; separate observation-only screens from tuning controls and apply changes only when the equipment state permits them.
Frequently asked questions
What happens if I refresh every Scrutiny variable at the fastest rate?
Transaction count, payload, target work, and queueing rise together. Reduce low-priority variables individually until measured latency and target execution time remain acceptable.
What happens if the firmware and debug symbols do not match?
Scrutiny may read valid memory through obsolete addresses or type layouts, producing stable but incorrect values. Load the metadata generated with the firmware currently running on the target.
What happens if Scrutiny dereferences an invalid MyStruct pointer?
The displayed members may be unavailable or implausible, and writes may target unintended memory if the transport permits them. Confirm the MyStruct* address and object lifetime before expanding or editing members.
What happens if I use saved PID gains with another build?
Names, addresses, permissible ranges, or control behavior may differ. Verify firmware compatibility, import only in a controlled equipment state, and read each applied value back from the target.
When should I stop troubleshooting Scrutiny and contact official support?
Stop when a repeatable symbol-decoding, transport, or firmware-management fault remains after validating the build pair, a known scalar, and acquisition load. Record the compiler, target architecture, transport, minimal variable set, and reproduction sequence. Escalate through the project's official support channel with those diagnostics.