Skip to content

Utility Functions

The SpiNNaker2 STM interface provides several utility functions for managing the STM microcontroller and SpiNNaker2 board.

Device Management

List Available Devices

To get a list of available serial devices and their IP addresses:

from spinnaker2_stm.common import get_serial_devices

# Get devices with default 3-second timeout
devices = get_serial_devices()
for path, ip in devices.items():
    print(f"{path} (IP: {ip})")

# Get devices with custom timeout
devices = get_serial_devices(timeout=5)

The function will:

  • Detect all connected devices
  • Retrieve their IP addresses
  • Return a dictionary mapping both IP-based paths and device paths to IP addresses
  • Skip devices where IP detection fails
  • Timeout after specified seconds (default: 3s)

Connection Paths

SpiNNaker2 boards can be accessed using multiple path formats:

# Using the IP address directly (recommended)
reset_board("192.168.1.53")

# Using the IP-based device path
reset_board("/dev/ttyS2_192_168_1_53")

# Legacy approach using ACM device paths
reset_board("/dev/ttyACM0")

The library now prioritizes IP-based addressing for better reliability and device identification.

Reset Functions

Note

These functions are intended for standalone use only. If the board is being managed by other software (e.g. py-spinnaker2 or SpiNNMan), board resets must be performed using that software’s APIs. The functions in this module cannot access resources already owned by those packages and will fail.

Reset Board

To reset the entire SpiNNaker2 board:

from spinnaker2_stm.common import reset_board

# Reset using IP address (recommended)
reset_board("192.168.1.53")

# Reset using IP-based path
reset_board("/dev/ttyS2_192_168_1_53")

# Reset using default configuration (uses DEFAULT_IP)
reset_board()

The board reset operation:

  1. Checks if the board is already locked, otherwise locks it
  2. Sends a board reset command ('r')
  3. Waits for the reset to complete (2 seconds)
  4. Cleans up the serial connection

The reset will fail with a RuntimeError if the board is currently in use by another user or the validity of the lock cannot be established.

Reset STM

To reset only the STM microcontroller:

from spinnaker2_stm.common import reset_stm

# Reset using IP address (recommended)
reset_stm("192.168.1.53")

# Reset using IP-based path
reset_stm("/dev/ttyS2_192_168_1_53")

# Reset using default configuration (uses DEFAULT_IP)
reset_stm()

The STM reset operation:

  1. Checks if the board is already locked, otherwise locks it
  2. Sends an STM reset command ('rs')
  3. Waits for the reset to complete (2 seconds)
  4. Cleans up the serial connection

The reset will fail with a RuntimeError if the board is currently in use by another user or the validity of the lock cannot be established.

Help Menu

To display the STM help menu:

from spinnaker2_stm.common import show_help_menu

# Display help menu using default configuration
show_help_menu()

# Display help menu for specific board by IP
show_help_menu("192.168.1.53")

# Get help menu output as text
output = show_help_menu("192.168.1.53", return_output=True)

The help menu function can:

  • Display the help information directly (default behavior)
  • Return the output as a list of strings when return_output=True
  • Use a custom IP address or path

Note: This function checks if the board is locked before proceeding.

Board Availability Checking

The library provides a function to check if a board is available for use:

from spinnaker2_stm.common import check_board_lock

# Check if a board is available (returns True if available)
is_available = check_board_lock("192.168.1.53")

# Check if the default board is available
is_available = check_board_lock()

This function also supports an optional strict argument:

  • If strict=True, any lock that is found will be treated equally.
  • If strict=False, when the lock is held by you, it will be ignored (the board is considered available).

By default, this is set to False.

Flushing Serial Buffer

To clear the serial buffer of the STM device:

from spinnaker2_stm.common import flush_stm

# Flush serial buffer without printing content
flush_stm("192.168.1.53")

# Flush and print cleared buffer content
flush_stm("192.168.1.53", disable_print=False)

Path Normalization

The library transparently handles different path formats:

# All of these are equivalent:
reset_board("192.168.1.53")
reset_board("/dev/ttyS2_192_168_1_53")

# Legacy format (still supported but not recommended)
reset_board("/dev/ttyACM0")

Reset Commands Overview

Function Command Description
reset_board() 'r' Resets the entire SpiNNaker2 board
reset_stm() 'rs' Resets only the STM microcontroller

Interactive Board Management

The package provides an interactive interface for managing boards in Jupyter notebooks:

from spinnaker2_stm.common import get_serial_devices, reset_board, reset_stm
import ipywidgets as widgets
from IPython.display import display, clear_output

# Create and display the interface
create_board_interface()

Interactive Board Management Interface

The interface provides:

  • A dropdown menu to select available devices
  • A refresh button to update the device list
  • Reset Board button for full board reset
  • Reset STM button for STM-only reset
  • Status output area for operation feedback

Requirements:

  • ipywidgets
  • jupyter
  • IPython

Each device in the dropdown is shown with its path and IP address.