### led_start_animation() and led_stop_animation() example
Source: https://docs.jumperless.org/badge-api-reference
Example of starting the pulse heart animation, waiting 5 seconds, then stopping it.
```python
led_start_animation(ANIM_PULSE_HEART)
import time
time.sleep(5)
led_stop_animation()
```
--------------------------------
### List and run examples from the MicroPython filesystem
Source: https://docs.jumperless.org/scripts
After flashing firmware, use os.listdir('/python_scripts/examples') to list available example files and exec(open(...).read()) to run one. The output shows the example's printed banner and test messages.
```python
>>> import os
>>> os.listdir('/python_scripts/examples')
['adc_basics.py', 'dac_basics.py', 'gpio_basics.py', ...]
>>> exec(open('/python_scripts/examples/gpio_basics.py').read())
GPIO Basics Demo
Testing GPIO pin 1
...
```
--------------------------------
### Example structure template
Source: https://docs.jumperless.org/scripts
Template for each MicroPython example, including a docstring with title, description, and hardware setup, followed by imports and main loop.
```python
"""
Example Title
Brief description of what this example demonstrates.
Hardware Setup:
1. Connection instructions
2. Required components
3. Expected behavior
"""
import jumperless as j
import time
# Your example code here
print("Example Demo")
# Main loop or demonstration
while True:
# Do something interesting
time.sleep(0.1)
```
--------------------------------
### led_show_image() example
Source: https://docs.jumperless.org/badge-api-reference
Example of displaying a builtin image, waiting 2 seconds, then displaying another image using a string name.
```python
led_show_image(IMG_HEART)
import time
time.sleep(2)
led_show_image("smiley") # string name works too
```
--------------------------------
### Install Jumperless with uv or pipx
Source: https://docs.jumperless.org/03-app
Installs the Jumperless app in an isolated environment using uv or pipx. This is the recommended way to get started.
```bash
uv tool install jumperless
# or: pipx install jumperless
```
--------------------------------
### led_screenshot() example with modes
Source: https://docs.jumperless.org/badge-api-reference
Example of setting two pixels and taking screenshots with various modes. The comments show the rendering size for each mode.
```python
led_set_pixel(0, 0, 255)
led_set_pixel(7, 7, 255)
led_screenshot() # int 1 — 2W × 2W square per LED
led_screenshot(0.5) # float — quarter-block compact (4×4 chars)
led_screenshot(0) # int 0 — half-block compact (8×4 chars)
led_screenshot(2, False) # int 2 — bigger square, no ANSI colour
led_screenshot(1.5) # float — 1 char × 1 char-row per LED (tall)
```
--------------------------------
### led_clear() and led_set_pixel() example
Source: https://docs.jumperless.org/badge-api-reference
Example of clearing the matrix and setting two pixels with brightness 100.
```python
led_clear()
led_set_pixel(3, 3, 100)
led_set_pixel(4, 4, 100)
```
--------------------------------
### Create a new Jumperless MicroPython example template
Source: https://docs.jumperless.org/scripts
Use this template when adding a .py file to pythonStuff/ex/. It requires a docstring describing the example and hardware setup, plus imports for jumperless as j and time. After writing, run the generator script and rebuild the firmware.
```python
"""
My New Example
Description of what this demonstrates.
Hardware Setup:
- List any required connections
"""
import jumperless as j
import time
print("My New Example")
# Your code here
```
--------------------------------
### Initialize and install jumperless-mcp submodule
Source: https://docs.jumperless.org/jumperless-agent-skill
Use when setting up the jumperless-mcp server from the mcp/ git submodule. First initialize the submodule if the repo was not cloned with --recurse-submodules, then build and install the server with cargo. A release binary can be used instead of the cargo install step.
```shell
git submodule update --init --recursive # if not cloned with --recurse-submodules
cd mcp && cargo install --path . # or use a release binary
```
--------------------------------
### Hello World example
Source: https://docs.jumperless.org/badge-developer-guide
Clears the OLED, prints 'Hello Badge!', shows a heart on the LED matrix for 3 seconds, then exits to the menu.
```python
import time
oled_clear()
oled_set_cursor(32, 28)
oled_print("Hello Badge!")
oled_show()
led_show_image(IMG_HEART)
time.sleep_ms(3000)
led_clear()
exit()
```
--------------------------------
### Install and run JumperlessWokwiBridge.py
Source: https://docs.jumperless.org/03-app
For the Python bridge: first install the required libraries, then run the app. The app will update firmware if a newer version is available.
```bash
pip install -r requirements.txt
```
```bash
python3 JumperlessWokwiBridge.py
```
--------------------------------
### Toggle individual example inclusion in src/micropythonExamples.h
Source: https://docs.jumperless.org/scripts
Comment out a generated #define to exclude a specific example at compile time. The example shows INCLUDE_STYLOPHONE commented out and INCLUDE_GPIO_BASICS kept.
```c
// In src/micropythonExamples.h
// #define INCLUDE_STYLOPHONE // Comment out to exclude
#define INCLUDE_GPIO_BASICS // Keep to include
```
--------------------------------
### List directory contents with jfs.listdir
Source: https://docs.jumperless.org/09.6-jfs
Lists the contents of the root directory and a subdirectory. The example first creates a subdirectory with jfs.mkdir, then lists its contents. Use jfs.listdir to get a list of entry names for a given path.
```python
# List contents of the root directory
print(jfs.listdir('/'))
# List contents of a subdirectory
jfs.mkdir('/my_dir')
print(jfs.listdir('/my_dir'))
```
--------------------------------
### Disable example categories with convenience macros
Source: https://docs.jumperless.org/scripts
Use these macros to disable entire categories of examples at compile time. DISABLE_ALL_EXAMPLES turns everything off; the other macros disable demo, hardware, or machine examples.
```c
#define DISABLE_DEMO_EXAMPLES // Disables LED, Voltage, Stylophone
#define DISABLE_HARDWARE_EXAMPLES // Disables DAC, ADC, GPIO, Node
#define DISABLE_MACHINE_EXAMPLES // Disables UART examples
#define DISABLE_ALL_EXAMPLES // Disables everything
```
--------------------------------
### Run Jumperless
Source: https://docs.jumperless.org/03-app
Runs the Jumperless app after installation.
```bash
jumperless
```
--------------------------------
### Quick Start: Display and Clear Text
Source: https://docs.jumperless.org/04-oled
Connects to the OLED and displays a basic text message with size 2, then clears the display after a 2-second pause. Use this as the minimal starting point for any OLED script.
```python
import jumperless as j
import time
# Basic text display
j.oled_connect()
j.oled_print("Hello!", 2)
time.sleep(2)
j.oled_clear()
```
--------------------------------
### led_start_animation(name, [interval_ms])
Source: https://docs.jumperless.org/badge-api-reference
Starts a builtin animation on the LED matrix, optionally with a custom interval.
```APIDOC
## led_start_animation(name, [interval_ms])
### Description
Start a builtin animation.
### Method
Function
### Parameters
- **name** (string) - Required - Animation name
- **interval_ms** (int) - Optional - Interval in milliseconds
### Returns
None
```
--------------------------------
### Setting a tile order with __order__
Source: https://docs.jumperless.org/badge-developer-guide
Examples of using __order__ to control menu position: negative for before curated tiles, small positive for between, large for near end.
```python
__order__ = -10 # before BOOP
__order__ = 25 # between MAP (30) and SCHEDULE (40)
__order__ = 9999 # nearly last
```
--------------------------------
### Run the generator script
Source: https://docs.jumperless.org/scripts
Command to run the generator script that converts Python examples to C string literals and generates the firmware header.
```bash
python3 scripts/generate_micropython_examples.py
```
--------------------------------
### ir_start()
Source: https://docs.jumperless.org/badge-api-reference
Bring the IR hardware up and start receiving in Python mode. Incoming frames are queued in an 8-slot ring buffer for retrieval with `ir_read()` or `ir_read_words()`. Blocks up to ~500 ms while Core 0 powers the RMT channel, and drains any stale frames left over from the Boop screen.
```APIDOC
## ir_start()
### Description
Bring the IR hardware up and start receiving in Python mode. Incoming frames are queued in an 8-slot ring buffer for retrieval with `ir_read()` or `ir_read_words()`. Blocks up to ~500 ms while Core 0 powers the RMT channel, and drains any stale frames left over from the Boop screen.
### Method
Function call
### Endpoint
`ir_start()`
### Parameters
None
### Returns
None
### Example
```python
ir_start()
```
```
--------------------------------
### led_set_frame() example with bitmasks
Source: https://docs.jumperless.org/badge-api-reference
Example of drawing a smiley face and an X using led_set_frame() with row bitmasks. The second call passes brightness 50 to dim the X.
```python
# Draw a smiley face
led_set_frame([
0b00111100,
0b01000010,
0b10100101,
0b10000001,
0b10100101,
0b10011001,
0b01000010,
0b00111100,
])
# Draw an X with explicit brightness
led_set_frame([
0b10000001,
0b01000010,
0b00100100,
0b00011000,
0b00011000,
0b00100100,
0b01000010,
0b10000001,
], 50) # dim
```
--------------------------------
### Direct execution with `>` commands
Source: https://docs.jumperless.org/08-micropython
Direct execution from the main Jumperless menu: type a command with the `>` prompt and use `print()` to see a value. Example commands set a GPIO, read an ADC value, and connect nodes.
```python
> gpio_set(1, True)
> print(adc_get(0))
> connect(1, 5)
```
--------------------------------
### Read and write files on the badge VFS with os
Source: https://docs.jumperless.org/badge-api-reference
Use this to access the badge's VFS through the standard os module. The example lists the /apps directory and the root, then writes a JSON file to /apps/my_app/save.json and reads it back. Available os operations include listdir, mkdir, remove, rename, stat, getcwd, chdir, ilistdir, and statvfs; standard open/read/write/close work as expected.
```python
import os
os.listdir("/apps")
os.listdir("/")
with open("/apps/my_app/save.json", "w") as f:
f.write('{"score": 42}')
with open("/apps/my_app/save.json", "r") as f:
data = f.read()
```
--------------------------------
### Clone and install the Jumperless MCP server
Source: https://docs.jumperless.org/07.5-automation
Clones the canonical automation repository with submodules and installs the MCP server binary. The MCP server holds the USB serial port exclusively while running, so do not run jumperless.py concurrently.
```bash
git clone --recurse-submodules https://github.com/Architeuthis-Flux/Large-Breadboard-Model.git
cd Large-Breadboard-Model/mcp
cargo install --path . # or use a release binary
```
--------------------------------
### Install Jumperless V5 Agent Skill
Source: https://docs.jumperless.org/07.5-automation
Clones the Jumperless V5 Agent Skill into the appropriate skills directory (e.g., ~/.cursor/skills or ~/.claude/skills). The skill drives the device via scripts/jumperless.py over the Raw REPL.
```bash
mkdir -p ~/.cursor/skills # or ~/.claude/skills
cd ~/.cursor/skills
git clone --recurse-submodules \
https://github.com/Architeuthis-Flux/Large-Breadboard-Model.git jumperless-v5
```
--------------------------------
### settings.txt [ota] keys: manifest_url and community_apps_url
Source: https://docs.jumperless.org/badge-developer-guide
Example settings.txt [ota] section. manifest_url overrides the default GitHub Releases endpoint; leave empty for the build-baked default. community_apps_url points to the Community Apps registry JSON; empty disables the tile, and the legacy asset_registry_url key still works.
```ini
[ota]
# Override the default GitHub Releases endpoint (advanced; usually
# leave empty to use the build-baked default).
manifest_url =
# URL of the Community Apps registry JSON. Empty disables the
# Community Apps tile. The legacy `asset_registry_url` key still
# works for backwards compatibility.
community_apps_url = https://raw.githubusercontent.com/Architeuthis-Flux/Temporal-Replay-26-Badge/main/registry/community_apps.json
```
--------------------------------
### Upgrade Jumperless
Source: https://docs.jumperless.org/03-app
Upgrades the Jumperless app using the command that matches your installation method. Use `which jumperless` to verify which install you're running if the version still looks old.
```bash
uv tool upgrade jumperless
pipx upgrade jumperless
pip install --upgrade jumperless
```
--------------------------------
### Verify connectivity with detect and exec
Source: https://docs.jumperless.org/jumperless-agent-skill
Install the pyserial dependency, detect the Jumperless device, and run a quick inline command to verify connectivity. If `detect` succeeds, the port is cached in `.jumperless_port` for subsequent calls.
```shell
pip install pyserial
python scripts/jumperless.py detect
python scripts/jumperless.py exec "print('ok from jumperless')"
```
--------------------------------
### nets section example entry
Source: https://docs.jumperless.org/07.5-automation
Shows an example net entry in the nets section. The special field can be "none", "RAIL", "DAC", "ADC", "GPIO", "UART_TX", "UART_RX", or "FAKE_GPIO_IN". The voltage field is present on ADC, DAC, RAIL, and FAKE_GPIO_IN nets.
```json
{
"index": 4,
"name": "DAC 0",
"nodes": ["DAC_0", "BUF_IN"],
"special": "DAC",
"voltage": 3.25
}
```
--------------------------------
### Control IR TX power with ir_tx_power
Source: https://docs.jumperless.org/badge-developer-guide
Starts IR, prints the default TX power (50 percent of 38kHz carrier), then throttles it down to 10 percent for close-range testing.
```python
ir_start()
print(ir_tx_power()) # Default: 50 (percent of 38kHz carrier)
ir_tx_power(10) # Throttle down for close-range testing
```
--------------------------------
### Run Jumperless code in a notebook cell with # %%micropython
Source: https://docs.jumperless.org/08-micropython
Start a notebook cell with `# %%micropython` to run it on the Jumperless. The `#` is intentional so Pylance skips the unknown magic and treats it as plain Python, while micropython-magic converts it back to the real magic when the cell runs. The `%load_ext` cell must be run first; otherwise the cell executes locally and raises `NameError: name 'adc_get' is not defined`.
```python
# %%micropython
for i in range(5):
print(adc_get(0))
print(gpio_get(1))
oled_print("hi from a notebook")
```
--------------------------------
### Directory structure of pythonStuff folder
Source: https://docs.jumperless.org/scripts
Shows the layout of the pythonStuff directory, including the ex/ folder with example scripts and the jumperless module files.
```text
pythonStuff/
├── ex/ # Example scripts (this directory)
│ ├── adc_basics.py
│ ├── dac_basics.py
│ ├── gpio_basics.py
│ ├── interaction_demo.py
│ ├── led_brightness_control.py
│ ├── node_connections.py
│ ├── stylophone.py
│ ├── uart_basics.py
│ ├── uart_loopback.py
│ └── voltage_monitor.py
├── jumperless_module.py # Main jumperless module wrapper
└── jumperless.pyi # Type stub for IDE autocomplete
```
--------------------------------
### Example slot file in YAML format
Source: https://docs.jumperless.org/08-file-manager
Shows the YAML structure of a Jumperless slot file, including bridges, power, and config sections. Use this as a template when editing slot files directly. Note that named nodes like NANO_D5 and GP_1 are valid, but MicroPython-style constants such as GPIO_1 are not.
```yaml
version: 2
sourceOfTruth: bridges
bridges:
- {n1: 1, n2: 10, dup: 2, color: red}
- {n1: NANO_D5, n2: GP_1, dup: 2}
- {n1: TOP_RAIL, n2: 5, dup: 2}
power:
topRail: 3.30
bottomRail: 2.50
dac0: 3.33
dac1: 0.00
```
--------------------------------
### Direct Wokwi link import in Jumperless app
Source: https://docs.jumperless.org/03-app
Shows the Jumperless app menu and the result of pasting a Wokwi project link. The app prompts for a project name, saves it to the library, assigns it to active slot 0, and starts live updating automatically.
```text
Menu
~~~~~
x = clear all connections
+ = add connections
- = remove connections
https://wokwi.com/projects/424432011346848769
Enter a name for this new project: cool project zone
✓ Saved 'cool project zone' to project library
✓ 'cool project zone' assigned to active slot 0
URL: https://wokwi.com/projects/424432011346848769
The project will start updating automatically
```
--------------------------------
### Full ADC scanning example
Source: https://docs.jumperless.org/05-arduino
This full Arduino sketch scans ADC0 across breadboard rows 1-60, connecting to each node, reading the voltage, and printing the response. It uses the same OPENJCOMMAND/CLOSEJCOMMAND macros and includes a 1500 ms boot delay. The LED_BUILTIN toggles to indicate activity, and the response buffer is limited to 30 characters.
```arduino
#define OPENJCOMMAND Serial.print("");
#define CLOSEJCOMMAND Serial.println("
");
void setup() {
pinMode(LED_BUILTIN, OUTPUT);
Serial.begin(115200);
delay(1500);
}
int lastNode = 8;
int node = 8;
unsigned long delayTime = 60;
void loop() {
digitalWrite(LED_BUILTIN, HIGH);
delay(delayTime);
node++;
if (node > 60) {
node = 1;
}
// Disconnect from previous node
OPENJCOMMAND
Serial.print("disconnect( ADC0," + String(lastNode) + ")");
CLOSEJCOMMAND
delay(delayTime);
// Connect to new node
OPENJCOMMAND
Serial.print("connect(ADC0 ," + String(node) + ")");
CLOSEJCOMMAND
delay(delayTime);
// Read the voltage
OPENJCOMMAND
Serial.print("print(adc_get(0))");
CLOSEJCOMMAND
delay(delayTime);
// Read response from Jumperless
char response[30] = {0};
int idx = 0;
while(Serial.available() > 0 && idx < 29) {
response[idx++] = Serial.read();
delay(5);
}
Serial.println(response);
Serial.print("num chars read = ");
Serial.println(idx);
Serial.flush();
lastNode = node;
digitalWrite(LED_BUILTIN, LOW);
}
```
--------------------------------
### community_apps.json v2 schema with file and app entries
Source: https://docs.jumperless.org/badge-developer-guide
Example community_apps.json v2 schema with two asset kinds: a single file (doom1-shareware) and a multi-file app bundle (tardigotchi). File lists are inlined directly; there is no per-app manifest.json. The registry is auto-generated by firmware/scripts/generate_startup_files.py from firmware/initial_filesystem/.
```json
{
"schema_version": 2,
"assets": [
{
"id": "doom1-shareware",
"kind": "file",
"name": "DOOM 1 Shareware WAD",
"version": "1.9",
"url": "https://...doom1.wad",
"sha256": "<64 hex>",
"size": 4196020,
"dest_path": "/doom1.wad",
"min_free_bytes": 4500000,
"description": "..."
},
{
"id": "tardigotchi",
"kind": "app",
"name": "Tardigotchi",
"version": "8b139b84ef0b",
"dest_dir": "/apps/tardigotchi",
"size": 33744,
"description": "Hatch and care for a tiny tardigrade.",
"files": [
{"path": "/main.py", "size": 187, "sha256": "...", "url": "https://..."},
{"path": "/engine.py", "size": 24006, "sha256": "...", "url": "https://..."},
{"path": "/icon.py", "size": 9551, "sha256": "...", "url": "https://..."}
]
}
]
}
```
--------------------------------
### Get filesystem info with jfs.info()
Source: https://docs.jumperless.org/09.6-jfs
Retrieves filesystem statistics using jfs.info() and prints total, used, and free space in kilobytes. The tuple unpacking assigns the three returned values to variables.
```python
total, used, free = jfs.info()
print("Filesystem Size: " + str(total / 1024) + " KB")
print("Used: " + str(used / 1024) + " KB")
print("Free: " + str(free / 1024) + " KB")
```
--------------------------------
### Basic tag command example
Source: https://docs.jumperless.org/05-arduino
Use this minimal Arduino sketch to send a single MicroPython command to the Jumperless via the serial port. It defines the OPENJCOMMAND and CLOSEJCOMMAND macros that wrap commands in
tags, waits 1500 ms for the Jumperless to boot, then reads the ADC0 voltage and processes the response. The delay(100) after sending the command gives the Jumperless time to respond.
```arduino
#define OPENJCOMMAND Serial.print("
");
#define CLOSEJCOMMAND Serial.println("
");
void setup() {
Serial.begin(115200);
delay(1500); // Give Jumperless time to boot
}
void loop() {
// Read voltage on ADC channel 0
OPENJCOMMAND
Serial.print("print(adc_get(0))");
CLOSEJCOMMAND
delay(100);
// Read the response
while(Serial.available() > 0) {
char c = Serial.read();
// Process the voltage reading...
}
}
```
--------------------------------
### Jumperless REPL auto-indent blink example
Source: https://docs.jumperless.org/08-micropython
Example of automatic multiline detection in the Jumperless REPL. After a colon, the REPL indents automatically, so you type without leading spaces. The function blinks an LED on GPIO 1 five times with 0.5-second delays.
```python
>>> def blink_led():
... for i in range(5):
... gpio_set(1, True)
... time.sleep(0.5)
... gpio_set(1, False)
... time.sleep(0.5)
...
>>> blink_led()
```
--------------------------------
### Open, read, and append files with jfs.open()
Source: https://docs.jumperless.org/09.6-jfs
Demonstrates basic file operations with jfs.open(): reading a file manually and closing it, then appending to a file using the 'with' statement for automatic resource management. The example shows both explicit close and context manager usage.
```python
# Open a file for reading
f = jfs.open('config.txt', 'r')
content = f.read()
f.close()
# Use 'with' for automatic closing
with jfs.open('data.log', 'a') as log_file:
log_file.write('New log entry.\n')
```
--------------------------------
### LED background callback with matrix_app_start and matrix_app_stop
Source: https://docs.jumperless.org/badge-developer-guide
Registers a Python callback that the firmware calls periodically to animate the matrix while the main loop does other things. The callback clears the matrix, draws a vertical line at x = phase % 8, and increments phase. Start with matrix_app_start(spinner, 80, 30) and stop with matrix_app_stop().
```python
phase = 0
def spinner(now_ms):
global phase
led_clear()
x = phase % 8
for y in range(8):
led_set_pixel(x, y, 80)
phase += 1
matrix_app_start(spinner, 80, 30)
# ... main loop handles OLED and input ...
# The spinner runs in the background via the service pump
matrix_app_stop() # When done
```
--------------------------------
### MicroPython Raw REPL loop
Source: https://docs.jumperless.org/07.5-automation
Canonical transport for full scripts and loops on the 3rd port. Example prints ADC value every 0.5 seconds for 10 iterations.
```python
import time
for i in range(10):
print(i, adc_get(0))
time.sleep(0.5)
```
--------------------------------
### haptic_strength() - Get or set default motor strength
Source: https://docs.jumperless.org/badge-api-reference
Get or set the default motor strength used by haptic_pulse(). If value is omitted, returns the current strength (0–255).
```python
print(haptic_strength()) # Read current
haptic_strength(200) # Set to 200
```
--------------------------------
### screenshot() mode and ANSI examples
Source: https://docs.jumperless.org/badge-api-reference
Call screenshot() with no arguments for the default half-block OLED and small square LED rendering. Pass a mode to change the OLED and LED sizes: 0.5 gives a quarter-block OLED with tiny tall LEDs, 1 gives 2W squares, 2 gives 4W squares, and 1.5 gives a tall OLED with tall LEDs. Pass False as the second argument to disable ANSI bright-red colouring for lit LED pixels.
```python
screenshot() # default — half-block OLED + small square LED
screenshot(0.5) # quarter-block OLED + tiny tall LED
screenshot(1) # OLED 2W square, LED 4W square
screenshot(2) # OLED 4W square, LED 6W square
screenshot(1.5) # tall OLED (1 char/pixel) + tall LED (3 chars/LED)
screenshot(0, False) # default, no ANSI colour
```
--------------------------------
### Send and receive simple IR frame with ir_send/ir_read
Source: https://docs.jumperless.org/badge-developer-guide
Starts IR mode, sends a simple frame with address 0x42 and command 0x01, waits 200ms, reads a received frame if available, prints the address and command in hex, then stops IR. Must call ir_start() before using any IR functions.
```python
ir_start()
# Send
ir_send(0x42, 0x01)
# Receive
time.sleep_ms(200)
if ir_available():
frame = ir_read()
if frame:
addr, cmd = frame
oled_println("Got: " + hex(addr) + " " + hex(cmd))
ir_stop()
```
--------------------------------
### haptic_strength([value])
Source: https://docs.jumperless.org/badge-api-reference
Get or set the default motor strength used by haptic_pulse().
```APIDOC
## haptic_strength([value])
### Description
Get or set the default motor strength used by `haptic_pulse()`. If `value` is omitted, returns the current strength.
### Method
Function call
### Parameters
#### Optional Parameters
- **value** (integer) - Optional - New strength (0–255). If omitted, just returns current.
### Request Example
```
print(haptic_strength()) # Read current
haptic_strength(200) # Set to 200
```
### Response
Returns the current strength (0–255).
```
--------------------------------
### Adding input with button_pressed example
Source: https://docs.jumperless.org/badge-developer-guide
Loops until BACK is pressed, incrementing a counter on CONFIRM presses, with haptic pulse and smiley LED feedback. Note: button_pressed() is edge-triggered, button() is level-triggered, and a sleep of 20-30ms is required in the loop.
```python
import time
count = 0
while True:
oled_clear()
oled_set_cursor(0, 0)
oled_print("Press buttons!")
oled_set_cursor(0, 20)
oled_print("Count: " + str(count))
oled_show()
if button_pressed(BTN_CONFIRM):
count += 1
haptic_pulse()
led_show_image(IMG_SMILEY)
if button_pressed(BTN_BACK):
break
time.sleep_ms(30)
led_clear()
exit()
```
--------------------------------
### LED built-in images and animations: led_show_image, led_start_animation, led_stop_animation
Source: https://docs.jumperless.org/badge-developer-guide
Shows a built-in heart image for 1 second, then starts a pulsing heart animation at 100 ms per frame for 3 seconds and stops it.
```python
led_show_image(IMG_HEART)
time.sleep_ms(1000)
led_start_animation(ANIM_PULSE_HEART, 100)
time.sleep_ms(3000)
led_stop_animation()
```
--------------------------------
### Get and set IR TX duty with ir_tx_power()
Source: https://docs.jumperless.org/badge-api-reference
Reads the default IR TX duty (50) and then lowers it to 10 percent to reduce LED stress during self-loopback. ir_tx_power() accepts an optional percent in 1–50 and returns the current duty; it raises ValueError if out of range.
```python
ir_start()
print("Default duty:", ir_tx_power()) # 50
ir_tx_power(10) # throttle down for self-loopback
```
--------------------------------
### ir_tx_power([percent])
Source: https://docs.jumperless.org/badge-api-reference
Get or set the IR carrier duty cycle. A higher duty drives the IR LED harder and extends range at the cost of current and LED stress.
```APIDOC
## ir_tx_power([percent])
### Description
Get or set the IR carrier duty cycle. A higher duty drives the IR LED harder and extends range at the cost of current and LED stress.
### Method
Function call
### Endpoint
`ir_tx_power([percent])`
### Parameters
- **percent** (int) - Optional - New duty cycle in the range **1–50** (percent of the 38 kHz carrier period). Call with no argument to just read the current value. Power-on default is **50**.
### Returns
- The current duty as an integer percent after the (optional) set.
### Raises
- `ValueError` if `percent` is outside 1–50.
### Example
```python
ir_start()
print("Default duty:", ir_tx_power()) # 50
ir_tx_power(10) # throttle down for self-loopback
```
```
--------------------------------
### matrix_app_start(callback, [interval_ms], [brightness])
Source: https://docs.jumperless.org/badge-api-reference
Registers a Python callback for background LED matrix rendering.
```APIDOC
## matrix_app_start(callback, [interval_ms], [brightness])
### Description
Register a Python callback for background LED matrix rendering.
### Method
Function
### Parameters
- **callback** (callable) - Required - Callback function
- **interval_ms** (int) - Optional - Tick interval in milliseconds
- **brightness** (int) - Optional - LED brightness (0-255)
### Returns
None
```
--------------------------------
### Detect long press with button_held_ms(BTN_DOWN)
Source: https://docs.jumperless.org/badge-api-reference
Reads how long the down button has been continuously held. Returns milliseconds held, or 0 if not pressed. The example prints a message when the hold exceeds 1000 ms.
```python
ms = button_held_ms(BTN_DOWN)
if ms > 1000:
oled_println("Long press!")
```
--------------------------------
### ~help command output
Source: https://docs.jumperless.org/06-config
Output of the ~help command, which lists all configuration commands. Note that ~? currently shows a shorter one-line command card instead.
```text
~help
Read config
~ = show current config
~names = show names for settings
~numbers = show numbers for settings
~[section] = show specific section (e.g. ~[routing])
Write config
`[section] setting = value; = enter config settings (pro tip: copy/paste setting from ~ output and just change the value)
` = open the interactive config menu (arrow keys)
Reset config
`reset = reset to defaults (keeps calibration and hardware version)
`reset_hardware = reset hardware settings (keeps calibration)
`reset_calibration = reset calibration settings (keeps hardware version)
`reset_all = reset to defaults and clear all settings
`force_first_start = clears everything to factory settings and runs first startup calibration
`self_test = run the hardware self test (non-destructive)
`self_test_report = re-print the stored self test report
Help
~? = show this help
```
--------------------------------
### Jumperless UART command tag examples
Source: https://docs.jumperless.org/05-arduino
These are the supported command tag formats for sending commands to the Jumperless from an Arduino or other device connected to the routable UART. Use matching opening and closing tags. The tag runs raw menu commands, while the tag runs MicroPython commands and automatically prepends the '>' prompt.
```xml
f 1-30
```
```xml
x
```
```xml
n
```
```xml
print(adc_get(0))
```
--------------------------------
### main.py dunder manifest
Source: https://docs.jumperless.org/badge-api-reference
Place at the top of /apps//main.py. The scanner reads the first ~2 KB as text and parses these dunder assignments without executing code, so they must use simple string literals. The slug must match [A-Za-z0-9_-]+ and not start with a dot; otherwise the app is silently skipped.
```python
"""My Game — Tamagotchi-style desk pet."""
__title__ = "My Game"
__description__ = "A tiny pet that lives in your pocket."
__icon__ = "icon.py"
__matrix_title__ = "Pet"
# ... rest of main.py ...
```
--------------------------------
### Removal overlay with overlay_set() and oled_print()
Source: https://docs.jumperless.org/jumperless-agent-skill
Use to mark a wire or component for removal with a red overlay (0xFF2020) and print the removal instruction. The example marks overlay col 3, row 1, 5 holes tall, and tells the user to remove the wire at row 3.
```python
# Use a different color (e.g. red) to mark what to remove
# Breadboard row 3 is overlay col 3, 5 holes tall
overlay_set("remove_wire", 3, 1, 5, 1, [0xFF2020] * 5)
oled_clear()
oled_print("Remove wire at row 3")
```
--------------------------------
### Send multi-word NEC frame with ir_send_words()
Source: https://docs.jumperless.org/badge-api-reference
Starts the IR hardware and transmits a multi-word NEC frame with three payload words. The encoder appends a CRC32 automatically; ir_send_words() raises ValueError for empty or >64-word sequences and OSError(1) if the hardware is not up.
```python
ir_start()
ir_send_words([0xB0, 0xDEADBEEF, 0x12345678])
```
--------------------------------
### IC body and pin 1 overlay with overlay_set()
Source: https://docs.jumperless.org/jumperless-agent-skill
Use for ICs spanning multiple rows: mark the body with overlay_set() using one pixel per pin, then add a pin 1 marker. The example places a 555 timer with body at overlay col 5, row 1, 1 high, 8 wide, and pin 1 at row 5.
```python
# IC body across breadboard rows 5-12 (top half → overlay cols 5-12)
overlay_set("ic_body", 5, 1, 1, 8, [0x203030] * 8) # col 5, row 1, 1 high, 8 wide
# Pin 1 marker
overlay_set("ic_pin1", 5, 2, 1, 1, [0xFF2020])
oled_clear()
oled_print("Place 555 timer")
oled_print("Pin 1 at row 5")
```
--------------------------------
### Read and display boops() JSON data
Source: https://docs.jumperless.org/badge-api-reference
Use this to read the on-flash boops.json document and display each peer badge UID on the OLED. The boops() function returns a JSON string, and the example iterates over the "pairings" list, printing the peer_badge_uid field (or "?" if missing) for each entry, then refreshes the display with oled_show().
```python
import json
data = json.loads(boops())
for p in data.get("pairings", []):
oled_println(p.get("peer_badge_uid", "?"))
oled_show()
```
--------------------------------
### init()
Source: https://docs.jumperless.org/badge-api-reference
Initializes the badge hardware bridge. This is called automatically and does not need to be invoked manually.
```APIDOC
## init()
### Description
Initialize the badge hardware bridge. Called automatically.
### Method
Function
### Parameters
None
### Returns
None
```
--------------------------------
### Multi-file app folder structure
Source: https://docs.jumperless.org/badge-developer-guide
Shows the recommended folder structure for a multi-file app with main.py as the entry point.
```text
/apps/my_game/
main.py # Entry point (tiny — just imports and calls main)
engine.py # Game loop and logic
data.py # Constants, level data
screens.py # OLED rendering functions
icon.py # Optional: app icon bitmap for the menu
```
--------------------------------
### Print Jumperless configuration with ~ command
Source: https://docs.jumperless.org/06-config
Enter the tilde (~) character in the main menu to print the entire configuration file. The output is shown below, and any line can be copied, edited, or pasted back into the main menu to change a setting.
```text
~
```
```text
Jumperless Config:
`[config] firmware_version = 5.7.11.0;
`[hardware] generation = 5;
`[hardware] revision = 7;
`[hardware] probe_revision = 5;
`[hardware] psram_installed = false;
`[hardware] psram_app_size_kb = 2048;
`[probe] auto_connect = on;
`[probe] power_source = dac0_first;
`[probe] use_pio_button = true;
`[probe] led_on_button_pin = true;
`[probe] led_refresh_us = 0;
`[probe] pad_max = 4056;
`[probe] pad_min = 15;
`[probe] pad_max_measure = 4111;
`[probe] pad_max_measure_gpio = 4110;
`[probe] pad_min_measure = 10;
`[probe] switch_threshold_high = 1.2000;
`[probe] switch_threshold_low = 0.9000;
`[probe] switch_select_max_ma = 0.0000;
`[probe] switch_blink_hold_pct = 50;
`[probe] measure_voltage = 3.3671;
`[probe] current_zero = 2.1667;
`[probe] min_valid_reading = 85;
`[probe] droop_v0 = 3.3500;
`[probe] droop_ohms = 169.6479;
`[probe] pad_ohms = 5.0000;
`[clickwheel] encoder_pio = auto;
`[clickwheel] rail_click_adjust = oled_only;
`[clickwheel] part_walk = z;
`[clickwheel] fx_type = glow;
`[clickwheel] fx_duration_ms = 160;
`[clickwheel] fx_tint = 0x00;
`[clickwheel] fx_density = 128;
`[measurement] net_currents = 1;
`[measurement] current_flow = conventional;
`[measurement] show_probe_current = 0;
`[measurement] crosspoint_resistance = 40.0000;
`[terminal] colors = true;
`[terminal] line_buffering = true;
`[undo] persist = true;
`[undo] max_saved_actions = 256;
`[dacs] limit_max = 8.00;
`[dacs] limit_min = -8.00;
`[debug] file_parsing = false;
`[debug] net_manager = false;
`[debug] nets_to_chips = false;
`[debug] nets_to_chips_alt = false;
`[debug] probing = false;
`[debug] arduino = 0;
`[debug] show_node_errors = true;
`[debug] probe_switch_stats = false;
`[debug] probe_switch_agree = false;
`[debug] net_voltage_scan = false;
`[debug] net_scan_pair_taps = 1;
`[routing] stack_paths = 2;
`[routing] stack_rails = 3;
`[routing] stack_dacs = 0;
`[routing] stack_gpio = 0;
`[routing] stack_adcs = 0;
`[routing] part_safety = off;
`[slots] boot_mode = last_active;
`[slots] boot_slot = 0;
`[calibration] top_rail_zero = 1655;
`[calibration] top_rail_spread = 18.4000;
`[calibration] bottom_rail_zero = 1639;
`[calibration] bottom_rail_spread = 19.0000;
`[calibration] dac_0_zero = 1655;
`[calibration] dac_0_spread = 18.2300;
`[calibration] dac_1_zero = 1629;
`[calibration] dac_1_spread = 19.0300;
`[calibration] adc_0_zero = 8.9969;
`[calibration] adc_0_spread = 18.0563;
`[calibration] adc_1_zero = 8.9903;
`[calibration] adc_1_spread = 18.0659;
`[calibration] adc_2_zero = 8.9993;
`[calibration] adc_2_spread = 18.0637;
`[calibration] adc_3_zero = 8.9826;
`[calibration] adc_3_spread = 18.0345;
`[calibration] adc_4_zero = 0.0000;
`[calibration] adc_4_spread = 4.9151;
`[calibration] adc_7_zero = 8.8184;
`[calibration] adc_7_spread = 17.7676;
`[logo_pads] top_guy = uart_tx;
`[logo_pads] bottom_guy = uart_rx;
`[logo_pads] building_pad_top = isense_pos;
`[logo_pads] building_pad_bottom = isense_neg;
`[logo_pads] top_guy_idle = off;
`[logo_pads] bottom_guy_idle = off;
`[logo_pads] building_pad_top_idle = off;
`[logo_pads] building_pad_bottom_idle = off;
`[display] lines_wires = wires;
`[display] menu_brightness = -10;
`[display] led_brightness = 10;
`[display] rail_brightness = 55;
`[display] special_net_brightness = 20;
`[display] net_color_mode = rainbow;
`[serial_1] function = passthrough;
`[serial_1] baud_rate = 115200;
`[serial_1] print_passthrough = 0;
`[serial_1] connect_on_boot = 0;
`[serial_1] lock_connection = 0;
`[serial_1] autoconnect_flashing = 1;
`[serial_1] async_passthrough = true;
`[serial_1] tag_parsing = enabled;
`[serial_1] flash_reset_type = avr;
`[serial_2] function = micropython;
`[serial_2] baud_rate = 115200;
`[serial_2] print_passthrough = 0;
`[serial_2] connect_on_boot = 0;
`[serial_2] lock_connection = 0;
`[top_oled] enabled = 1;
`[top_oled] i2c_address = 0x3C;
`[top_oled] width = 128;
`[top_oled] height = 32;
`[top_oled] rotation = 0;
`[top_oled] connection_type = i2c0;
`[top_oled] sda_pin = 4;
`[top_oled] scl_pin = 5;
`[top_oled] gpio_sda = 134;
`[top_oled] gpio_scl = 135;
`[top_oled] sda_row = -1;
`[top_oled] scl_row = -1;
`[top_oled] connect_on_boot = 1;
`[top_oled] lock_connection = 0;
`[top_oled] show_in_terminal = off;
`[top_oled] font = Eurostl;
`[top_oled] startup_message = images/bubbleJumpThin.bin;
`[usb_cdc] ignore_dtr = false;
`[usb_audio] enabled = false;
`[usb_audio] left = 0;
`[usb_audio] right = 1;
`[usb_audio] rate = 16000;
`[usb_audio] full_scale = 8.00;
`[usb_audio] dc_block = true;
```
--------------------------------
### Set custom OLED startup bitmap with [top_oled] startup_message
Source: https://docs.jumperless.org/04-oled
Displays a custom bitmap image at startup by providing a path on the filesystem. The image must be a .bin bitmap file (with 4-byte header recommended or raw at 512, 1024, 256, or 496 bytes), recommended size 128×32 pixels, stored in /images/ on the Jumperless filesystem.
```text
`[top_oled] startup_message = /images/mylogo.bin;
```
--------------------------------
### Register a matrix app with badge.matrix_app_start
Source: https://docs.jumperless.org/badge-developer-guide
Registers a matrix app callback with badge.matrix_app_start. The callback runs from the firmware's matrix service pump; keep it fast, don't block, and avoid while True loops. The firmware stops the callback automatically when switching modes.
```python
"""Slow drifting dot."""
__matrix_title__ = "Drift"
import badge
_phase = 0
def _tick(now_ms):
global _phase
_phase = (_phase + 1) & 7
frame = [0] * 8
frame[7] = 0x80 >> _phase
badge.led_set_frame(frame)
badge.matrix_app_start(_tick, 250, 24)
```
--------------------------------
### main.py entry point for multi-file app
Source: https://docs.jumperless.org/badge-developer-guide
A minimal main.py that adds the app directory to sys.path and calls main() from engine. Uses triple-quoted docstring as the module's first line.
```python
"""My Game app entry point."""
import sys
APP_DIR = "/apps/my_game"
if APP_DIR not in sys.path:
sys.path.insert(0, APP_DIR)
from engine import main
main()
```
--------------------------------
### Importing badge and standard library in other modules
Source: https://docs.jumperless.org/badge-developer-guide
Shows how other modules in a multi-file app should import from badge and standard libraries explicitly.
```python
from badge import *
import time
import gc
```