Add structured GPIB command reference (commands.json) and docs

Complete extraction of all 97 commands in HP 3457A Operating.pdf
Chapter 4, expanded to 120 JSON entries (F10-F58 modeled as 24
independent commands rather than one parameterized command). Each
entry includes description, syntax, structured parameters, important
points, worked examples, and tier/rationale classification to guide
which commands a Python control library actually needs.

Documents several findings not obvious from the manual alone: the
output buffer's single-reading data-loss behavior and the correct
burst-acquisition pattern, the CR/LF bus-hold gotcha, the Front Panel
checkbox's unreliability, the isolation-link mechanism behind F10-F58's
speed, and memory/timing capacity math for burst captures.

Updates README.md (was empty) and cmdformat.txt to document the
schema and key findings.
This commit is contained in:
2026-08-24 22:50:36 -05:00
parent 300a9f1492
commit a5ee5781de
3 changed files with 6263 additions and 14 deletions

View File

@@ -1,15 +1,53 @@
command name
local y/n
remote y/n
description
syntax
parameters
>> parameter name
>> parameter description
>> parameter values
>>>> value description
>>>> power-on value y/n
>>>> default value y/n
Important points
example
Schema for entries in commands.json (the "commands" array).
Read commands.json's own "_meta" block for the full rationale behind each
field below and for cross-cutting findings that don't belong to any one
command.
command name -> "name"
manual page(s) -> "manual_pages" (array of printed page numbers, e.g. ["4-7","4-8"])
local y/n -> "local" (Front Panel checkbox; see _meta.front_panel_caveat before trusting this)
remote y/n -> "remote" (Remote checkbox; only ADDRESS is false)
description -> "description"
syntax -> "syntax" (null for the four service-only commands)
parameters -> "parameters" (array, empty [] if the command takes none)
>> parameter name -> parameters[i].name
>> parameter description -> parameters[i].description
>> parameter values -> parameters[i].values (array of choice/range rows; empty [] for free-form numeric parameters)
>>>> value description -> values[j].description
>>>> power-on value y/n -> values[j].power_on (bool, only present for discrete enumerated choices)
>>>> default value y/n -> values[j].default (bool, only present for discrete enumerated choices)
>> (free-form parameters instead carry parameters[i].power_on_raw / .default_raw as plain text)
Important points -> "important_points" (array of strings)
example -> "examples" (array of {code, comment, note?})
Fields added beyond the original sketch, once the actual manual data made
clear they were needed:
tier -> "core" | "protocol" | "extended" -- does a typical
automated workflow need this command? See
_meta.tiering.
tier_reason -> free text explaining the tier call for this
specific command.
rationale -> "measurement_hardware" | "acquisition_timing" |
"wire_efficiency" | "era_computer_workaround" |
"plugin_card_dependent" | "diagnostic_calibration" |
"status_error_readback" | "ui_frontpanel_only" |
"bus_protocol" -- WHY the command exists / is fast,
independent of whether a library needs it. See
_meta.rationale_taxonomy.
service_command -> true for the 4 commands (CAL, DIAGNOSTIC, SECURE,
REV?) the manual defers entirely to the Service
manual, with no documented syntax here.
see_also -> present on R and T, the bare-syntax aliases of
RANGE and TRIG -- points to the real command
instead of duplicating its content.
family -> "F10-F58" on each of that family's 24 entries,
linking them together (see _meta.f10_f58_split
for why they're split into 24 entries instead of
one parameterized command).
selects_function / selects_range -> present only on the F10-F58 family entries;
what that specific zero-parameter command
configures.
prerequisites -> present only on "?" (the standalone trigger
shorthand); the TARM/NRDGS/TRIG state it requires
before it will work.