jumperless-boardboard-v5/RP23V50firmware/CodeDocs/Jumperless_API_Reference.md

Jumperless MicroPython API Reference

This document provides a comprehensive reference for the jumperless MicroPython module, which allows for direct control over the Jumperless hardware.

A Note on Usage

All functions and constants from the jumperless module are automatically imported into the global namespace. This means you can call them directly (e.g., connect(1, 5)) without needing the jumperless. prefix.

There are three primary ways to specify nodes in functions:

1. By Number: Use the integer corresponding to the breadboard row (1-60).
2. By String Name: Use a case-insensitive string for any named node (e.g., "d13", "TOP_RAIL").
3. By Constant: Use the predefined, case-sensitive constant for a node (e.g., D13, TOP_RAIL).

---

Node Connections

These functions manage the connections between nodes on the breadboard and special function pins.

connect(node1, node2, [save=True])

Creates a bridge between two nodes.

• node1, node2: The nodes to connect. Can be integers, strings, or constants.
• save (optional): If True (default), the connection is saved to the current slot's node file. If False, it's a temporary connection for the current session.

Example:

# Connect breadboard row 1 to row 30
connect(1, 30)

# Connect Arduino D13 to the top power rail
connect(D13, TOP_RAIL)

# Connect GPIO 1 to ADC 0 using strings
connect("GPIO_1", "ADC0")

disconnect(node1, node2)

Removes a specific bridge between two nodes.

• node1, node2: The two nodes to disconnect.
• To remove all connections from a single node, set node2 to -1.

Example:

# Remove the bridge between rows 1 and 30
disconnect(1, 30)

# Remove all connections from GPIO_1
disconnect(GPIO_1, -1)

is_connected(node1, node2)

Checks if a direct or indirect connection exists between two nodes.

• Returns a custom ConnectionState object which evaluates to True if connected (CONNECTED) and False if not (DISCONNECTED).

Example:

if is_connected(D13, TOP_RAIL):
    print("D13 is connected to the top rail.")

state = is_connected(1, 2)
print(state)  # Prints "CONNECTED" or "DISCONNECTED"

nodes_clear()

Removes all connections from the board.

Example:

nodes_clear()
print("All connections cleared.")

node(name_or_id)

Creates a node object from a string name or integer ID. This is useful for storing a node reference in a variable.

Example:

my_pin = node("D7")
led_pin = node(15)

connect(my_pin, led_pin)
oled_print(my_pin) # Displays 'D7' on the OLED

---

DAC (Digital-to-Analog Converter)

Functions for controlling the analog voltage outputs.

dac_set(channel, voltage, [save=True])

Sets the output voltage for a specific DAC channel.

• channel: The DAC channel to set. Can be an integer (0-3) or a node constant (DAC0, DAC1, TOP_RAIL, BOTTOM_RAIL).
• voltage: The desired voltage (from -8.0V to 8.0V).
• save (optional): If True (default), the setting is saved to the config file.
• Aliases: set_dac()

Channels:

• 0 or DAC0: The 5V tolerant DAC output.
• 1 or DAC1: The 8V tolerant DAC output.
• 2 or TOP_RAIL: The top power rail.
• 3 or BOTTOM_RAIL: The bottom power rail.

Example:

# Set the top rail to 5V
dac_set(TOP_RAIL, 5.0)

# Set DAC0 to 1.25V
set_dac(DAC0, 1.25)

dac_get(channel)

Reads the currently set voltage for a DAC channel.

• channel: The DAC channel to read.
• Returns a float.
• Aliases: get_dac()

Example:

voltage = dac_get(TOP_RAIL)
print("Top Rail voltage: " + str(voltage))

---

ADC (Analog-to-Digital Converter)

Functions for measuring analog voltages.

adc_get(channel)

Reads the voltage from a specific ADC channel.

• channel: The ADC channel to read (0-4).
• Returns a float.
• Aliases: get_adc()

Channels:

• 0-3: 8V tolerant ADC inputs.
• 4: 5V tolerant ADC input.

Example:

voltage = adc_get(0)
print("ADC0 voltage: " + str(voltage))

---

GPIO (General Purpose Input/Output)

Functions for controlling the digital I/O pins.

gpio_set(pin, value)

Sets the output state of a GPIO pin.

• pin: The GPIO pin number (1-10).
• value: True for HIGH, False for LOW.
• Aliases: set_gpio()

gpio_get(pin)

Reads the state of a GPIO pin.

• pin: The GPIO pin number (1-10).
• Returns a GPIOState object (HIGH, LOW, or FLOATING).
• Aliases: get_gpio()

gpio_set_dir(pin, direction)

Sets the direction of a GPIO pin.

• pin: The GPIO pin number (1-10).
• direction: True for OUTPUT, False for INPUT.
• Aliases: set_gpio_dir()

gpio_get_dir(pin)

Reads the direction of a GPIO pin.

• pin: The GPIO pin number (1-10).
• Returns a GPIODirection object (INPUT or OUTPUT).
• Aliases: get_gpio_dir()

gpio_set_pull(pin, pull)

Configures the internal pull resistor for a GPIO pin.

• pin: The GPIO pin number (1-10).
• pull: 1 for PULLUP, -1 for PULLDOWN, 0 for NONE.
• Aliases: set_gpio_pull()

gpio_get_pull(pin)

Reads the pull resistor configuration of a GPIO pin.

• pin: The GPIO pin number (1-10).
• Returns a GPIOPull object (PULLUP, PULLDOWN, or NONE).
• Aliases: get_gpio_pull()

Pinout:

• 1-8: Routable GPIO pins GPIO_1 to GPIO_8.
• 9: UART_TX.
• 10: UART_RX.

Example:

# Set GPIO 1 as an output and turn it on
gpio_set_dir(1, True)
gpio_set(1, True)

# Set GPIO 2 as an input with a pull-up
gpio_set_dir(2, False)
gpio_set_pull(2, 1)

# Read the state of GPIO 2
state = gpio_get(2)
if state == HIGH:
    print("GPIO 2 is HIGH")

---

PWM (Pulse-Width Modulation)

Functions for generating PWM signals on GPIO pins.

pwm(pin, [frequency], [duty_cycle])

Sets up and starts a PWM signal on a GPIO pin.

• pin: The GPIO pin to use (1-8).
• frequency (optional): The PWM frequency in Hz (10.0 to 62,500,000.0). Defaults to 1000.
• duty_cycle (optional): The duty cycle from 0.0 to 1.0. Defaults to 0.5.
• Aliases: set_pwm()

pwm_set_duty_cycle(pin, duty_cycle)

Changes the duty cycle of an existing PWM signal.

• pin: The GPIO pin number (1-8).
• duty_cycle: The new duty cycle (0.0 to 1.0).
• Aliases: set_pwm_duty_cycle()

pwm_set_frequency(pin, frequency)

Changes the frequency of an existing PWM signal.

• pin: The GPIO pin number (1-8).
• frequency: The new frequency in Hz.
• Aliases: set_pwm_frequency()

pwm_stop(pin)

Stops the PWM signal on a GPIO pin.

• pin: The GPIO pin number (1-8).
• Aliases: stop_pwm()

Example:

# Start a 1kHz, 25% duty cycle PWM on GPIO_1
pwm(GPIO_1, 1000, 0.25)

# Change the duty cycle to 75%
pwm_set_duty_cycle(GPIO_1, 0.75)

# Stop the PWM signal
pwm_stop(GPIO_1)

---

INA (Current/Power Monitor)

Functions for reading data from the INA219 current sensors.

ina_get_current(sensor)

Reads the current in Amps.

• sensor: The sensor to read (0 or 1).
• Aliases: get_current()

ina_get_voltage(sensor)

Reads the shunt voltage in Volts.

• sensor: The sensor to read (0 or 1).
• Aliases: get_voltage()

ina_get_bus_voltage(sensor)

Reads the bus voltage in Volts.

• sensor: The sensor to read (0 or 1).
• Aliases: get_bus_voltage()

ina_get_power(sensor)

Reads the power in Watts.

• sensor: The sensor to read (0 or 1).
• Aliases: get_power()

Example:

current_mA = ina_get_current(0) * 1000
print("Current: " + str(current_mA) + " mA")

---

OLED Display

Functions for controlling the onboard OLED display.

oled_print(text, [size=2])

Displays text on the OLED screen. It can print strings, numbers, and custom Jumperless types.

• text: The content to display.
• size (optional): The font size (1 or 2). Defaults to 2.

oled_clear()

Clears the OLED display.

oled_show()

Refreshes the OLED display to show the latest changes. (Note: Often not needed as oled_print handles this).

oled_connect()

Connects the I2C lines to the OLED display.

oled_disconnect()

Disconnects the I2C lines from the OLED display.

Example:

oled_connect()
oled_print("Hello!")
time.sleep(2)
oled_clear()
oled_disconnect()

---

Probe

Functions for interacting with the physical probe.

probe_read([blocking=True])

Reads the pad currently being touched by the probe.

• blocking (optional): If True (default), the function will wait until a pad is touched. If False, it returns immediately.
• Returns a ProbePad object (e.g., 25, D13_PAD, NO_PAD).
• Aliases: read_probe(), probe_read_blocking(), probe_read_nonblocking(), probe_wait(), wait_probe(), probe_touch(), wait_touch()

probe_button([blocking=True])

Reads the state of the buttons on the probe.

• blocking (optional): If True (default), waits for a button press. If False, returns the current state immediately.
• Returns a ProbeButton object (CONNECT_BUTTON, REMOVE_BUTTON, or BUTTON_NONE).
• Aliases: get_button(), button_read(), read_button(), probe_button_blocking(), probe_button_nonblocking(), check_button(), button_check()

Example:

print("Touch a pad...")
pad = probe_read()
print("You touched: " + str(pad))

if pad == D13_PAD:
    print("That's the Arduino LED pin!")

print("Press a probe button...")
button = get_button()
if button == CONNECT_BUTTON:
    print("Connect button pressed.")

---

System Functions

arduino_reset()

Resets the connected Arduino Nano.

run_app(appName)

Launches a built-in Jumperless application.

• appName: The name of the app to run (e.g., "File Manager", "I2C Scan").

---

Status Functions

These functions print detailed status information to the serial console.

• print_bridges(): Prints all active bridges.
• print_paths(): Prints all resolved paths between nodes.
• print_crossbars(): Prints the raw state of the crossbar matrix.
• print_nets(): Prints the current net list.
• print_chip_status(): Prints the status of the CH446Q chips.

---

Help Functions

help()

Displays a comprehensive list of all available functions and constants in the jumperless module.

nodes_help()

Displays a detailed reference for all available node names and their aliases.