Jumperless V5

https://docs.jumperless.org
Admin
Jumperless V5 is a software-defined breadboard and integrated hardware development environment for...
Tokens:113,117
Snippets:898
Trust Score:5.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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
```

--------------------------------

### 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()

```

--------------------------------

### 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)
```

--------------------------------

### 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
```

--------------------------------

### 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')"

```

--------------------------------

### 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

```

--------------------------------

### 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://..."}
      ]
    }
  ]
}

```

--------------------------------

### 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
```
```

--------------------------------

### 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
```

--------------------------------

### 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

```

--------------------------------

### main.py dunder manifest

Source: https://docs.jumperless.org/badge-api-reference

Place at the top of /apps/<slug>/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 ...

```

--------------------------------

### 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])

```

--------------------------------

### 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()

```

--------------------------------

### 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
```

--------------------------------

### ~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

```

--------------------------------

### 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
```

--------------------------------

### 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

```

--------------------------------

### 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
```

--------------------------------

### 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

```
Tokens:
Raw