Jumperless V5

Full capabilities at a glance

Always keep these in mind — even in the middle of a specific task, a different peripheral may be the better tool:

Think creatively: If measuring resistance, consider whether INA-based, ADC-based, or mixed approaches suit the range best. If debugging a circuit, you can probe multiple nodes with different ADC channels simultaneously. If a user needs a clock signal, reach for PWM instead of bit-banging GPIO.

Getting connected

Before any hardware interaction, ensure connectivity:

pip install pyserial
python scripts/jumperless.py detect
python scripts/jumperless.py exec "print('ok from jumperless')"

If detect succeeds, the port is cached in .jumperless_port for subsequent calls.

Execution modes

Prefer these modes in order:

1. Inline command (short, single-purpose):

python scripts/jumperless.py exec "connect(1, D4)"

2. Script file (multi-line logic — preferred for anything beyond a one-liner):

python scripts/jumperless.py exec --file scripts/session.py

3. Piped script (dynamically generated scripts):

python scripts/jumperless.py exec --stdin <<'PYEOF'
import time
connect(ADC0, 5)
time.sleep(0.05)
v = adc_get(0)
disconnect(ADC0, -1)
print(v)
PYEOF

For complex logic, write a temporary .py file and use --file. Do not cram long multi-line logic into shell-quoted one-liners.

Use --timeout N when scripts take longer than the default 8 seconds (e.g. continuous monitors, guided flows).

Updating a running script

Loop scripts run on the device in MicroPython. The host exec process exits as soon as it finishes sending the script — the serial port is already free. The MicroPython loop keeps running on the Jumperless itself.

To stop it and send a new version:

1. Write the updated script to the file.

2. Run exec with the updated file.
enter_raw_repl() automatically sends a double Ctrl-C (\x03\x03) to the device before sending any new code, interrupting whatever MicroPython loop is currently running.

python scripts/jumperless.py exec --file scripts/my_loop.py --timeout 300

That's it — no process killing needed.

3. Start every loop script with a cleanup header.
The interrupted script may have left connections, overlays, or OLED content mid-run. Always reset to a known state at the top:

import time
nodes_clear()
overlay_clear_all()
oled_clear()
time.sleep(0.05)   # let crossbar settle after clear

Background long-running loops with block_until_ms: 0 so the shell doesn't block waiting for them to finish.

Settling time patterns

Build these into every script. The crossbar routing fabric and DAC output stages need time to stabilize.

import time

# After making connections
connect(ADC0, 5)
connect(DAC1, ISENSE_PLUS)
time.sleep(0.05)  # 50ms settle

# After changing DAC/rail voltage
dac_set(TOP_RAIL, 3.3)
time.sleep(0.02)  # 20ms for DAC to reach setpoint

# After bulk state changes
set_state(new_state)
time.sleep(0.1)   # 100ms for full state application

# For multi-sample measurements, small inter-sample delay
for _ in range(16):
    v = adc_get(0)
    samples.append(v)
    time.sleep(0.01)  # 10ms between samples

Visual placement guidance

Whenever the user needs to place, move, or remove something physical, run an overlay script before asking. The board shows them exactly where to go; OLED echoes the instruction in text.

Overlay coordinate system

The LED canvas is rows 1–10, cols 1–30:

• Rows 1–5 = top breadboard half (breadboard rows 1–30)
• Rows 6–10 = bottom breadboard half (breadboard rows 31–60)
• Col 1–30 = the 30 columns of holes within each half

Breadboard row N → overlay col N (top half, N 1–30) or col N−30 (bottom half, N 31–60). The 5 holes A–E in each strip correspond to overlay rows 1–5 (top) or 6–10 (bottom).

Placement patterns

Single component / pin — use place_here() + oled_print():

import time

# Mark a single hole bright red, tell user on OLED
overlay_set_pixel(3, 10, 0xFF2020)          # direct: row 3, col 10
# — or using animations helper if loaded —
place_here("target_pin", 3, 10, 0xFF2020)

oled_clear()
oled_print("Place R1 pin 1")
oled_print("Row 10, top half")

IC spanning multiple rows — use highlight_range() for the body, place_here() per pin:

# IC body across breadboard rows 5-12 (top half → overlay cols 5-12)
highlight_range("ic_body", 1, 1, 0x203030)   # single overlay row, cols 5-12
# Pin 1 marker
place_here("ic_pin1", 2, 5, 0xFF2020)

oled_clear()
oled_print("Place 555 timer")
oled_print("Pin 1 at row 5")

Span of rows (e.g. resistor leg to leg):

# Highlight rows 5 and 15 where resistor legs go
place_here("r1_a", 1, 5, 0xFF8000)
place_here("r1_b", 1, 15, 0xFF8000)

oled_clear()
oled_print("Place R1: row 5 to 15")

Removal / "move this wire":

# Use a different color (e.g. red pulsing) to mark what to remove
highlight_row("remove_wire", 3, 0xFF2020)

oled_clear()
oled_print("Remove wire at row 3")

Always clear overlays after confirmation

After the user confirms placement (probe button, clickwheel, or verbal confirmation), clear the guidance overlays so they don't obscure net colors:

overlay_clear("target_pin")
overlay_clear("ic_body")
# — or wipe everything —
overlay_clear_all()
oled_clear()

In guided step flows, pair each step with an overlay

When using jumperless.py guide, run a matching overlay script immediately before each button-wait so the board lights up with the current step's target location. Use overlay_clear_all() at the start of each step to remove the previous step's marks.

Workflow selection

Choose based on the task, then read only the files needed. But stay aware of the full capabilities table above — better solutions may combine peripherals across workflows.

1. Connectivity / rewiring

   • Read: reference/node-map.md → reference/api/connections-routing.md
   • Use fast_connect() / fast_disconnect() for batch operations (skips LED updates)

2. Measurement (V/I/R, sweeps)

   • Read: reference/api/measurements-power.md
   • For reusable patterns: scripts/measurements.py, measureR.py
   • Always account for crossbar series resistance (20–40Ω default connect(), ~80Ω with duplicates=0) and 2Ω ISENSE shunt

3. Visual guidance (LEDs, OLED) — mandatory any time you ask for physical action

   • See "Visual placement guidance" section above for patterns
   • Read: reference/api/ui-interaction-system.md → scripts/animations.py
   • Use reduced-brightness saturated colors (e.g. 0x2020FF, not 0x0000FF)
   • 0x000000 = transparent in overlays; always overlay_clear_all() after step completes

4. State surgery / batch edits

   • Read: reference/state-format.md → reference/api/state-nets-filesystem.md

5. Guided human-in-the-loop flows

   • python scripts/jumperless.py guide --file steps.txt
   • One step per line; device shows on OLED and waits for probe button / clickwheel

Only load reference/api-reference.md when a task spans multiple API domains. For transport/hanging issues, load reference/repl-runtime-playbook.md.

Core command patterns

# Snapshot full state
python scripts/jumperless.py state

# Execute a script file
python scripts/jumperless.py exec --file scripts/session.py

# List device filesystem
python scripts/jumperless.py fs

# Longer timeout for continuous scripts
python scripts/jumperless.py exec --file scripts/measureR.py --timeout 60

Measurement best practices

Always settle, always sample multiple times

import time

connect(ADC0, 5)
time.sleep(0.05)

samples = [adc_get(0) for _ in range(8)]
v_avg = sum(samples) / len(samples)
print("V at row 5:", v_avg)

disconnect(ADC0, -1)

Resistance: choose method by expected range

• Low R (<500Ω): Use lower DAC voltage (0.5–1.5V) to avoid high current. INA-based is most accurate.
• Medium R (500Ω–10kΩ): DAC at 2–3V. Mixed ADC+INA gives best results.
• High R (>10kΩ): Use higher DAC voltage (3–5V). Baseline-corrected method recommended (measure leakage current with load floating, then subtract).

Adaptive DAC voltage ladder (from measureR.py)

if R_prev is None:     v_set = 2.0
elif R_prev < 200:     v_set = 0.5
elif R_prev < 1000:    v_set = 1.5
elif R_prev < 5000:    v_set = 2.5