spinner-wiring-guide

Interactively guides the user through the process of wiring up a SpiNNaker machine and correcting wiring errors.

usage: spinner-wiring-guide [-h] [--version] [--no-tts] [--no-auto-advance]
                            [--fix] [--log LOGFILE]
                            (--num-boards N | --triads W H)
                            [--transformation {shear,slice}]
                            [--uncrinkle-direction {columns,rows}]
                            [--folds X Y] [--board-dimensions W H D]
                            [--board-wire-offset-south-west X Y Z]
                            [--board-wire-offset-north-east X Y Z]
                            [--board-wire-offset-east X Y Z]
                            [--board-wire-offset-west X Y Z]
                            [--board-wire-offset-north X Y Z]
                            [--board-wire-offset-south X Y Z]
                            [--inter-board-spacing S]
                            [--boards-per-frame BOARDS_PER_FRAME]
                            [--frame-dimensions W H D]
                            [--frame-board-offset X Y Z]
                            [--inter-frame-spacing S]
                            [--frames-per-cabinet FRAMES_PER_CABINET]
                            [--cabinet-dimensions W H D]
                            [--cabinet-frame-offset X Y Z]
                            [--inter-cabinet-spacing S] [--num-cabinets N]
                            [--num-frames N] [--wire-length L [L ...]]
                            [--minimum-slack H] [--bmp CABINET FRAME HOSTNAME]
                            [--proxy HOSTNAME] [--proxy-port PORT]
                            [--subset SUBSET [SUBSET ...]]

Interactively guide the user through the process of wiring up a SpiNNaker
machine.

optional arguments:
  -h, --help            show this help message and exit
  --version, -V         show program's version number and exit
  --no-tts              disable text-to-speech announcements of wiring steps
  --no-auto-advance     disable auto-advancing through wiring steps
  --fix                 detect errors in existing wiring and just show
                        corrective steps
  --log LOGFILE         record the times at which each cable is installed

machine topology dimensions:
  --num-boards N, -n N  build the 'squarest' system with this many boards
  --triads W H, -t W H  build a system with the specified number of triads of
                        boards in each dimension (yielding 3*W*H boards)

topology folding options:
  --transformation {shear,slice}, -T {shear,slice}
                        the transformation function to use from hexagonal
                        torus to rectangular Cartesian grid (selected
                        automatically if omitted)
  --uncrinkle-direction {columns,rows}
                        direction in which to uncrinkle the hexagonal mesh to
                        form a regular grid (default: rows)
  --folds X Y, -F X Y   the number of pieces to fold into in each dimension
                        (default: (2, 2)) ignored if --transformation is not
                        given

board physical dimensions:
  --board-dimensions W H D
                        physical board dimensions in meters (default: (0.014,
                        0.233, 0.24))
  --board-wire-offset-south-west X Y Z
                        physical offset of the south-west connector from board
                        left-top-front corner in meters (default: (0.008,
                        0.013, 0.0))
  --board-wire-offset-north-east X Y Z
                        physical offset of the north-east connector from board
                        left-top-front corner in meters (default: (0.008,
                        0.031, 0.0))
  --board-wire-offset-east X Y Z
                        physical offset of the east connector from board left-
                        top-front corner in meters (default: (0.008, 0.049,
                        0.0))
  --board-wire-offset-west X Y Z
                        physical offset of the west connector from board left-
                        top-front corner in meters (default: (0.008, 0.067,
                        0.0))
  --board-wire-offset-north X Y Z
                        physical offset of the north connector from board
                        left-top-front corner in meters (default: (0.008,
                        0.085, 0.0))
  --board-wire-offset-south X Y Z
                        physical offset of the south connector from board
                        left-top-front corner in meters (default: (0.008,
                        0.103, 0.0))
  --inter-board-spacing S
                        physical spacing between each board in a frame in
                        meters (default: 0.00124)

frame physical dimensions:
  --boards-per-frame BOARDS_PER_FRAME
                        number of boards per frame (default: 24)
  --frame-dimensions W H D
                        frame physical dimensions in meters (default: (0.43,
                        0.266, 0.25))
  --frame-board-offset X Y Z
                        physical offset of the left-top-front corner of the
                        left-most board from the left-top-front corner of a
                        frame in meters (default: (0.06, 0.017, 0.0))
  --inter-frame-spacing S
                        physical spacing between frames in a cabinet in meters
                        (default: 0.133)

cabinet physical dimensions:
  --frames-per-cabinet FRAMES_PER_CABINET
                        number of frames per cabinet (default: 5)
  --cabinet-dimensions W H D
                        cabinet physical dimensions in meters (default: (0.6,
                        2.0, 0.25))
  --cabinet-frame-offset X Y Z
                        physical offset of the left-top-front corner of the
                        top frame from the left-top-front corner of a cabinet
                        in meters (default: (0.085, 0.047, 0.0))
  --inter-cabinet-spacing S
                        physical spacing between each cabinet in meters
                        (default: 0.0)
  --num-cabinets N, -c N
                        specify how many cabinets to spread the system over
                        (default: the minimum possible)
  --num-frames N, -f N  when only one cabinet is required, specifies how many
                        frames within that cabinet the system should be spread
                        across (default: the minimum possible)

available wire lengths:
  --wire-length L [L ...], -l L [L ...]
                        specify one or more available wire lengths in meters
  --minimum-slack H     the minimum slack to allow in a wire connecting two
                        boards in meters

SpiNNaker BMP connection details:
  --bmp CABINET FRAME HOSTNAME
                        specify the hostname of a BMP to use to communicate
                        with SpiNNaker boards in the given frame

SpiNNaker proxy connection details:
  --proxy HOSTNAME      specify the hostname of a spinner-proxy-server
                        instance to use to communicate with the SpiNNaker
                        system
  --proxy-port PORT     specify the port to connect to spinner-proxy-server
                        with (default: 6512)

wire subset selection:
  These arguments allow the specificiation of subsets of wires to install,
  for example, selecting only particular wires within a particular cabinet
  or frame. If no subsets are specified, all wires will be included,
  otherwise the union of all specified subsets are included. Use '1.2.*' to
  select all wires between boards in cabinet 1, frame 2. Use '1.*.*' to
  select all wires between boards in cabinet 1. Use '1-2.*.*' to select all
  wires which cross between cabinets 1 and 2.

  --subset SUBSET [SUBSET ...]
                        specify the subset of wires to include

User Interface

_images/wiring_guide_screenshot.png

The screen shot above shows the wiring guide being used to wire up a 600 board system.

The centre of the display shows an overview of the whole machine and indicates wires that have already been installed and are coloured based on the length of the cable used. The boards and sockets to be connected are highlighted and a close-up view of the two endpoints is shown on the left- and right-hand side of the display.

Underneath the diagrams, the central caption indicates the length of wire to use for the current connection and the current progress through the whole job. The left and right captions indicate the positions of the specific boards to be connected (in terms of their cabinet, frame and board numbers).

When each wire is installed, SpiNNer verbally announces the next connection to be made using text-to-speech (TTS). Additionally, when appropriate command-line options are given, SpiNNer also illuminates a red LED on the pair of boards which are to be connected. Further, SpiNNer can automatically check for the correct installation of each wire and automatically advance to the next wire when a successful connection is made.

The length of each wire to be installed is selected by the same method as the spinner-wiring-stats tool. The order of wire installation proceeds in three broad phases:

  • Within frames
  • Between frames
  • Between cabinets

Additionally, the tightest wires are installed first such that newly inserted wires can be installed over the top of existing wires.

The following keys are used to interact with the wiring guide:

Purpose Key
Move to next wire Left-click, Down, Space
Skip forward multiple wires Page-Down
Move to previous wire Right-click, Up, Backspace
Skip backward multiple wires Page-Up
Go to first wire Home
Go to last wire End
Toggle Text-to-Speech t
Toggle Auto-Advance a
Pause logging p

See the spinner-proxy-server documentation to see how this tool may be used by multiple people at once to share the task of installing cables in large machines.

Standalone Usage

To run the wiring tool stand-alone without connecting to the SpiNNaker machine being assembled, simply supply a system size and a set of available wire lengths:

$ spinner-wiring-guide -n 1200 -l 0.15 0.30 0.50 1.00

Illuminating LEDs and On-the-Fly Wire Checking

spinner-wiring-guide can illuminate a red LED on boards whose wires are to be connected and also check wires are inserted on-the-fly. To enable this feature, ensure all boards are powered on (e.g. using rig-power BMP_HOSTNAME on -b 0-23 for each frame) and then use:

$ spinner-wiring-guide -n 24 -l 0.15 0.30 0.50 1.00 --bmp 0 0 BMP_HOSTNAME

Note that the --bmp argument must be given once for each frame in the system.

Parallel, multi-person cable installation

Several instances of spinner-wiring-guide can be used in parallel along with --proxy argument and the spinner-proxy-server tool to share the work of installing cables in very large SpiNNaker machines between multiple people. See the proxy server documentation for a complete example of how to do this.

Just Illuminating LEDs

If you do not wish to power-up the system while wiring it up, LEDs can still be illuminated while disabling the wire-checking feature using the --no-auto-advance argument:

$ spinner-wiring-guide -n 24 -l 0.15 0.30 0.50 1.00 --bmp 0 0 BMP_HOSTNAME --no-auto-advance

Repairing wiring errors

Adding the --fix option will check all installed wires in the machine and guide you through any corrections which must be made:

$ spinner-wiring-guide -n 24 -l 0.15 0.30 0.50 1.00 --bmp 0 0 BMP_HOSTNAME --fix

Installing subsets of machines

If installation is to be split into multiple phases focusing on one subsection at a time, the --subset argument may be used to filter the wires displayed or repaired by the wiring guide.

The --subset argument takes a set of arguments in the form c.f.b where c, f, and b are described below and specify a range of cabinets, frames or boards. The three parts must be in one of the following formats:

  • A number (e.g. 3) specifying a specific cabinet, frame or board.
  • A pair (e.g. 1-2) specifying a specific pair of cabinets, frames or boards.
  • A wildcard (*).

For example:

  • Subset 0.1.* would select wires going between any boards within cabinet 0, frame 1.
  • Subset 0-1.*.* would select any cable which connects between cabinet 0 and cabinet 1.

If multiple subsets are defined, cables matched by at least one of the subsets will be selected. For example, the screenshot below was produced by the following command-line which defines two subsets:

$ spinner-wiring-guide -n 360 -l 0.15 0.3 0.5 0.9 --subset 0.*.* 0-1.*.*
_images/wiring_guide_subset_screenshot.png

Logging

The --log FILENAME argument causes the wiring guide to log (into a CSV file) how long it took to install each ceable. This may be useful for research comparing ease of installation and maintainance of a SpiNNaker system. Note that this system does not currently log cables being removed.

The CSV file contains the set of columns defined below. Various types of events are recorded in the log and not every event has a sensible value for every column. Columns without a sensible value are set to NA.

event_type:The type of event being logged (see list below).
realtime:The real time and date the event occurred.
time:Time that the event occurred, in seconds since the start of logging and excluding any time spent paused.
sc, sf, sb, sd, dc, df, db, dd:
 Source and destination cabinet, frame, board and direction of a cable being installed.
duration:Overall time, in seconds, to connect a cable correctly (or time spent paused for pause events).
attempt_duration:
 Time since last attempt to connect the cable, in seconds.
num_attempts:Number of attempts made to install the current cable.

The following event types are defined:

logging_started:
 This event is produced when a new wiring session begins. All relative times are measured in seconds from this point.
logging_stopped:
 Produced when logging ceases.
connection_started:
 Produced when a new cable to install is displayed on the screen.
connection_error:
 Produced each time a cable is connected incorrectly according the the wiring probe.
connection_complete:
 Produced when the wiring probe detects that the cable has been installed correctly.
pause:Produced after logging has been paused for some period of time. Relative timings reported by other events will not include any time spent paused.