# HP 3457A

Reverse-engineered GPIB command reference for the HP 3457A digital
multimeter, built toward a Python control library. The instrument
predates SCPI/IEEE-488.2, so it doesn't understand `*IDN?` and friends —
it has its own compact command language, documented only in the PDF
manuals below.

## Contents

- **`commands.json`** — the deliverable. A complete, hand-verified,
  structured extraction of every command in Chapter 4 ("Command
  Reference") of `HP 3457A Operating.pdf`: 97 documented commands,
  expanded to 120 JSON entries (the `F10`–`F58` family is 24 independent
  zero-parameter commands crammed onto one manual page — modeled here as
  24 separate entries, not one command with 24 parameter choices). Each
  entry has description, syntax, structured parameters (typed value
  tables with power-on/default flags where the manual provides them),
  important points, and worked examples, plus two classification fields
  not in the manual (see below). Read the `_meta` block at the top of the
  file first — it documents the schema and a dozen cross-cutting findings
  that took real digging to establish, not just page-by-page
  transcription.
- **`cmdformat.txt`** — the schema outline `commands.json` follows.
- **`HP 3457A Operating.pdf`** — the real command/operating reference.
  Chapter 4 is the source for `commands.json`; Chapter 1 has the
  abbreviated specifications (accuracy, reading rates, memory); Chapter 3
  has the conceptual explanations (triggering, math operations, buffers)
  Chapter 4 assumes you've already read.
- **`HP 3457A Service.pdf`** — board-level theory of operation and
  schematics. Poor OCR/scan quality throughout (don't expect a clean
  full-text read), but worth a targeted search when a specific mechanism
  needs explaining — e.g. it's what revealed the opto-isolated
  master/slave-processor link that explains why `F10`–`F58` execute
  faster than `DCV`/`OHM`/`OHMF`.
- **`GPIBProgrammingReferenceManual.pdf`** — despite the filename, this is
  a *generic* Advantech GPIB interface-card primer (bus concepts,
  IEEE-488 basics), not HP 3457A-specific. Useful for general GPIB
  background, not command syntax.

## `commands.json` at a glance

Every entry carries two classification fields beyond what the manual
documents, meant to guide what a Python library should actually expose:

- **`tier`** — does a typical automated measurement workflow need this?
  `core` (40 — measurement functions plus the setup/trigger/timing/status
  commands a controller genuinely can't replicate host-side), `protocol`
  (3 — `ADDRESS`/`END`/`INBUF`, bus/transport housekeeping), `extended`
  (77 — real and documented, but not needed for typical use: plug-in-card
  commands, on-instrument program/state storage a host script replaces,
  calibration/diagnostics/service, front-panel UI, legacy speed-optimized
  aliases).
- **`rationale`** — *why* does this exist / why is it fast? Distinguishes
  genuine hardware advantages that remain relevant today
  (`measurement_hardware`, `acquisition_timing`) from things that only
  mattered because 1980s host controllers were slow or limited
  (`era_computer_workaround`), plus a few narrower buckets
  (`wire_efficiency`, `plugin_card_dependent`, `diagnostic_calibration`,
  `status_error_readback`, `ui_frontpanel_only`, `bus_protocol`).

`tier` and `rationale` are independent axes and are allowed to disagree —
e.g. the `MEM` reading-memory family is `extended` tier (most workflows
don't need it) but `acquisition_timing` rationale (genuinely valuable
*if* burst throughput matters).

### Notable findings baked into `_meta`

- **Only `ADDRESS` is Remote-unchecked** across all 120 entries — you
  can't remotely reassign the instrument's own bus address. Everything
  else is fully GPIB-controllable. `POWER` isn't a documented command at
  all (pure physical switch).
- **The Front Panel checkbox is unreliable** as a "what's physically
  possible" signal — `DCV`/`ACV`/`ACI`/`ACDCV`/`DCI` are all marked
  unchecked despite having real dedicated/shifted panel keys; `ACDCI` is
  checked despite Chapter 3 describing it in word-for-word parallel terms
  to its siblings (almost certainly a manual erratum on the `ACDCI` page).
- **The output buffer holds exactly one reading** and silently overwrites
  it if not drained in time — there is no GPIB streaming mode. The
  documented high-throughput pattern is `NRDGS <count>` + a single
  `TRIG SGL`, which runs the whole burst to completion *inside* the
  instrument (bus held throughout) before you pay any transfer cost.
  `MATH STAT`/`PFAIL` are the two math operations that don't alter the
  reading, so they accumulate accurate aggregates across a burst even
  when individual readings never make it off the bus — genuinely useful
  for a burst that outruns the transfer channel, not a 1980s-era
  workaround.
- **CR/LF bus-hold gotcha**: with the input buffer off (its power-on
  default), the instrument holds the HP-IB bus until a command finishes
  executing, because it processes `<CR>` immediately but not `<LF>` until
  done. Explains earlier confusing "dropped command" symptoms seen live
  on this project's hardware.
- **Memory/timing math**: 2208 bytes total (reading/subprogram/state,
  via `MSIZE`); reading-memory format (`MFORMAT`) determines bytes/sample
  (2–16); the empirical reading-rate table tops out at 1350 readings/sec
  (`DCV`, 3.5 digits, autozero off) — filling the ~1053-sample max buffer
  at that rate takes ~0.78s. `ACV`/`ACI` cap out ~140x slower (~9.5
  rdg/s) since AC measurement is internally-aggregated, not instantaneous
  sampling — so `DCV` burst mode is the only realistic way to approximate
  an oscilloscope-style capture with this instrument.

Full detail, sourcing, and page references for all of the above are in
`commands.json`'s `_meta` block.

## Related work reviewed

- [sigrok's `hp-3457a` driver](https://github.com/sigrokproject/libsigrok/tree/master/src/hardware/hp-3457a) —
  thin coverage: measurement-mode selection, NPLC, terminal switching,
  autorange query, `RMATH HIRES`, rear-card scan-list plumbing. No
  `PER`, no explicit range/resolution, no `FSOURCE` (flagged `TODO` in
  their own code), nothing for math/calibration/display/subprograms.
- [MikeDombo/HP3457A-GPIB](https://github.com/MikeDombo/HP3457A-GPIB) —
  a wxPython measurement GUI. Confirmed real-world use of the `F10`-`F58`
  shorthand family and the `TERM 1`/`TERM 2` numeric equivalents.

## Status / next steps

`commands.json` is complete and is the ground-truth spec for the planned
Python control library, which hasn't been started yet. The transport
layer (Prologix GPIB-ETHERNET controller) already exists in the sibling
repo `progpib` — the plan is to build HP 3457A-specific command wrappers
on top of that rather than reimplementing GPIB transport here. One
documented gap remains: the separate "HP-IB Commands" section (manual
pages 4-167–4-174, generic IEEE-488 bus messages like `CLEAR`/`LOCAL`/
`REMOTE`) hasn't been extracted into `commands.json` yet, since it likely
maps to functionality `progpib` already exposes at the transport layer
rather than needing instrument-specific wrappers.
