Choose the right tool

PulsePins exposes the same hardware through several different surfaces:

  • small command-line tools (ppfg, ppdelay, ppplay, ppread, ...)
  • the C++ API
  • Python bindings
  • the SCPI server (ppscpi)
  • the browser UI (ppwebgui)

This page is a task-oriented guide for choosing the right entry point.

Start here

If you want to...

  • generate a quick digital signal without writing a sequence file: use ppfg or ppdelay
  • run or replay a saved sequence file: use ppplay
  • capture what PulsePins produced and save it for inspection or replay: use ppread
  • verify board health or run built-in streaming tests: use pptest
  • inspect external clock or PPS timing: use ppfreq or ppts
  • troubleshoot trigger routing and trigger sources: use pptrig
  • inspect or change combiner routing manually: use ppqout
  • drive a workflow from scripts or notebooks: use the Python API
  • build custom sequence-generation logic or hardware wrappers: use the C++ API
  • control the device remotely from automation software: use ppscpi
  • interact with the device from a browser: use ppwebgui

By task

I want to generate a simple digital output now

Use:

  • ppfg for periodic patterns, PWM-style outputs, bursts, and gated square-wave generation
  • ppdelay for one-shot delayed pulses after a trigger
  • pphelloworld for the most minimal output-toggle smoke test

These are the best first tools when you want a signal quickly and do not need a saved sequence artifact.

I want to play back a sequence file

Use:

Choose the file format by goal:

  • text (.seq, .txt) when you want human-editable sequences
  • binary (.ppbin) when you want exact replay of the full internal representation
  • VCD when the source waveform came from a waveform-oriented tool

I want to capture and inspect what happened

Use:

Typical outputs:

  • VCD for waveform viewers
  • text for manual inspection/editing
  • binary for exact replay/regression workflows

If you want a simple digital-logic-analyzer workflow, ppread is usually the right first stop.

I want to validate clocks, PPS, or timing sources

Use:

  • ppfreq for external/internal/streamer clock measurements
  • ppts for PPS and timestamp stream inspection

These tools are especially useful during board bring-up, synchronization work, and external-reference troubleshooting.

I want to debug triggers and routing

Use:

  • pptrig to inspect trigger source selection, masks, and inversion
  • ppqout to inspect or force combiner/output routing behavior

These are lower-level troubleshooting tools rather than general sequence-generation commands.

I want to verify the device itself

Use:

  • pptest for built-in streaming, trigger, preprocessor, and readback verification
  • ppcounter for the integrated counter subsystem

If you just brought up a board or changed low-level behavior, start here before building bigger workflows.

I want to read board peripherals

Use:

  • pptemp for the onboard temperature sensor path
  • ppaux for AUX input sampling

For PP_PMOD-specific hardware context, also see pp_pmod.md and pp_pmod_reference.md.

Choose the right interface layer

CLI tools

Best when:

  • you want immediate interaction from a shell
  • you want copy-pasteable lab commands
  • you want the fastest path to trying a built-in feature

Start with the CLI if the job already maps to an existing tool page.

Python API

Best when:

  • you want scripting, notebooks, or quick automation
  • you want to generate or transform sequences programmatically without building a C++ binary
  • you want to integrate PulsePins into a larger measurement script

See: Python API.

C++ API

Best when:

  • you are extending the project itself
  • you need new tool behavior, new wrappers, or tighter control over host-side execution paths
  • performance and direct integration with the existing C++ runtime matter

See: C++ API.

SCPI server

Best when:

  • you want remote instrument-style control from other software
  • your lab already has SCPI-oriented orchestration

Use: ppscpi.

Web GUI

Best when:

  • you want a quick browser-based control surface
  • you want to inspect live status and adjust trigger/combiner settings interactively
  • you want to stream PulsePins text sequences without writing a custom client

Use: ppwebgui.

Typical user journeys

First hardware bring-up

Suggested order:

  1. pphelloworld
  2. pptest
  3. ppfreq or ppts if timing inputs matter
  4. ppfg or ppdelay for your first real output

Build a repeatable waveform workflow

Suggested order:

  1. prototype with ppfg or pptest
  2. capture with ppread
  3. replay with ppplay
  4. move to Python or C++ if you need generated sequences

Bring up a peripheral device from qout pins

Suggested order:

  1. validate base outputs with pptest
  2. validate routing with ppqout if needed
  3. prototype the transaction with helper tools under tools/
  4. replay the generated sequence with ppplay or pptest -f

When to move beyond the CLI

Move from CLI tools to Python or C++ when:

  • you are repeating the same command patterns in scripts
  • you need programmatic sequence generation
  • you want richer error handling than shell pipelines provide
  • you are adding a new capability instead of just using an existing one