logic-notes/docs/practical-field-manual.md

Practical Field Manual

This manual is written for real use, not for theory.

Use it when you need to:

• prepare a Linux machine for a sharing session
• verify a logic-analyzer software stack quickly
• run a demo without hardware
• perform a first capture with real hardware
• decode UART, I2C, or SPI with the least amount of guesswork

The examples assume Arch Linux, but the workflow itself is generic.

1. Prepare the machine

Install the default stack

sudo pacman -S pulseview sigrok-cli sigrok-firmware-fx2lafw

What each package is for:

• pulseview: GUI capture and decoder workflow
• sigrok-cli: command-line verification and scripted demos
• sigrok-firmware-fx2lafw: support for common FX2-based analyzers

Verify that the binaries exist

command -v pulseview
command -v sigrok-cli

If either command prints nothing, the install is not complete.

2. Verify the stack without hardware

This is the safest first check.

Scan devices

sigrok-cli --scan

A healthy software-only result should still show the built-in demo device.

Inspect the demo driver

sigrok-cli --driver demo --show

This confirms that:

• the backend loads
• the driver is visible
• the channel groups are available

Run a small capture

sigrok-cli -d demo -c samplerate=1000 -C D0,D1,D2,D3 --samples 32 -O ascii

If you want a more compact output:

sigrok-cli -d demo -c samplerate=1000 -C D0,D1,D2,D3 --samples 32 -O bits

If these commands work, the software stack is already usable for a live walkthrough.

3. Open the GUI before hardware arrives

Start the GUI even if no analyzer is connected yet.

pulseview

Check the following:

• the application starts normally
• the decode UI is reachable
• adding protocol decoders does not crash
• session save and export menus are present

This matters because workshop failures are often GUI failures, not device failures.

4. First capture with real hardware

Once hardware is available, use this sequence.

Step 1: Detect the device

sigrok-cli --scan

If no device appears:

• reconnect USB
• try a different cable
• try a different port
• re-run the scan

Step 2: Open PulseView

Choose the detected device and set:

• active channels
• sample rate
• capture depth or capture time
• threshold or trigger settings if the device supports them

Step 3: Keep the first capture simple

For the first run:

• enable only the channels you need
• use a moderate sample rate
• avoid complicated trigger rules
• verify that the waveform looks electrically plausible before adding decoders

Step 4: Decode only after the waveform looks correct

Do not start by tuning decoder settings blindly.

First confirm:

• idle level looks correct
• edges are stable
• the clock actually toggles
• chip select or start condition is visible

Then add protocol decoders.

5. UART recipe

Use this when debugging boot logs, MCU shells, or sensor modules with TX/RX.

Wiring checklist

• connect analyzer ground to target ground
• probe at least one data line: TX or RX
• probe both if you want duplex visibility

Capture checklist

• start with a sample rate comfortably above the baud rate
• verify the idle level
• identify start bits and stop bits visually

Decoder settings

Typical values to check:

• baud rate
• data bits
• parity
• stop bits
• bit order
• inverted or non-inverted line

Common failure patterns

If the decoded text is nonsense:

• wrong baud rate
• inverted logic level
• wrong probe point
• insufficient sample rate

6. I2C recipe

Use this for sensors, PMICs, EEPROMs, and board bring-up.

Wiring checklist

• connect ground
• probe SCL
• probe SDA

What to verify in the raw waveform

• both lines idle high
• SDA changes while SCL is low, except for start and stop
• start and stop conditions are clearly visible

Decoder settings

The basic decoder setup is usually enough if the waveform is clean.

If decoding fails:

• check whether the line is actually I2C and not a GPIO imitation
• confirm pull-ups exist
• reduce the number of enabled channels
• increase sample rate

Common failure patterns

• no pull-up, so the lines never return high
• noise or ringing causes false transitions
• probing on the wrong side of level shifters

7. SPI recipe

Use this for flash, displays, radios, and many digital peripherals.

Wiring checklist

• connect ground
• probe CLK
• probe MOSI
• probe MISO if needed
• probe CS# whenever possible

What to verify in the raw waveform

• clock is present and stable
• data transitions match clock edges
• chip select brackets each transaction

Decoder settings

The important settings are:

• clock polarity
• clock phase
• bit order
• word size
• chip-select polarity

Fast diagnosis

If the bytes look shifted or wrong:

• try the other SPI mode
• verify whether the device is MSB-first or LSB-first
• check whether CS# is active-low or active-high

8. Minimal workshop flow

If you need a short live session, use this order:

1. Show the package install command
2. Run sigrok-cli --scan
3. Run the built-in demo capture
4. Open PulseView
5. Explain how a real analyzer would replace the demo source
6. Show one decoder workflow, not three

For a 10 to 15 minute slot, this is usually enough.

9. Chinese-friendly fallback

If the audience benefits from Chinese UI or Chinese-facing materials, keep DSView as a backup plan.

Use it only if:

• it was built and verified beforehand
• decoder resources are confirmed to load
• startup logs are clean

Do not rely on a first-time DSView build during a live session on a modern rolling-release Linux system.

10. Troubleshooting checklist

When the setup does not work, check in this order.

Software layer

• does sigrok-cli --scan run at all
• does the demo driver work
• does pulseview start cleanly

USB layer

• cable quality
• port quality
• hub vs direct connection
• insufficient power

Signal layer

• shared ground
• correct voltage domain
• correct probe point
• enough sample rate

Decoder layer

• correct protocol choice
• correct channel mapping
• correct polarity or inversion
• correct timing parameters

11. Cleanup after the share

If the machine was only used for preparation or a one-off workshop, remove everything cleanly.

Example package cleanup on Arch:

sudo pacman -Rns pulseview sigrok-cli libsigrok libsigrokdecode sigrok-firmware-fx2lafw boost

If local tools or builds were added, also remove:

• user-local binaries
• desktop entries
• temporary source archives
• temporary session files
• user-local decoder directories

12. Final advice

For most Linux-based embedded work:

• use PulseView + sigrok-cli as the default recommendation
• keep the first live demo hardware-free if necessary
• treat raw waveforms as the truth and decoders as helpers
• prepare a fallback path before every public session