User Guide

Placing Parts

Circuits are created by selecting parts from the Parts List panel which get placed near the top left of the schematic area.

The parts are then selected with the left mouse button and dragged into position. Selected parts become brighter. Multiple parts may be selected by rubber-band selecting them with the mouse. Clicking in blank space deselects the part(s).

Pressing the delete key, deletes the selected parts.

Ctrl + Left click allows for selecting multiple parts one by one.

Ctrl + D duplicates the selected parts at the current position of the mouse based off the first-selected part position.

Wires and Busses

Connection lines may be added between pins of the same type. These are designated by color coding. Wires carry bit data of logic 1 or 0. These are by default: white. Bus lines carry integer numbers between bus pins which are yellow by default.

Wire and Bus

Connections are made by clicking on a pin and dragging a line out to snap to another pin of the same type. To disconnect a line, drag away from the right-side connection.

Pins on the right side of parts may fan out to multiple end points, but pins on the left side only accept one input.

In general, pins on the left side of a part are inputs, and pins on the right side of a part are outputs. But IO and some others (to be decided) are bidirectional, however the signal input does not go back along other wires connected to the same pin.

To hold a pin high or low, there are parts for V+ and Gnd available. These may also be used to feed a bus with all ones or zeros.

Plus minus

To colorize lines, there are the WireColor and BusColor parts that may be wired up to any output pin of that type. Right-clicking on the part opens a color selection panel. The chosen color affects the net of lines that the part is attached to.

colors

The IO part has a control panel that pops up when right-clicked on. This allows for setting of its wire and bus colors i.e. all the pins of the part. The panel also allows for setting up how many pins it has, and a tool to edit the pin names. The pin names may be generated with an optional prefix and suffix character or string. Or the pin names may be individually edited. Then the names may be applied by clicking the Application button.

Another color customization feature is for the logic level indication. This is available via the Settings menu. By default, red is used for logic 1 and blue for logic 0. Another setting is for whether to indicate the logic levels from the output and/or to the input pins. When stimulating the circuit with inputs from the IO part, the wires change color if set to do so to indicate the logic level. The bus lines do not change color.

To remove logic level coloring of the wires during use, there is a colored button that may be pressed in the menu bar.

Circuit Blocks

Previously saved circuits may be loaded as blocks. This causes them to appear as a part with pins mapped to unconnected IO pins of the circuit with the same pin names as those IO pins. Also, the circuit that was loaded as a block is added to the Part List under the Blocks list with the title of the Circuit or its file name if the Circuit was unnamed. Right-click on block part entry in the part list to remove it.

IO parts are required in order to obtain IO pins for block parts. One side of each of these parts should be fully unconnected for it to be deemed an input or output of the circuit when loaded as a block. Inside a block, the IO Manager panel is no longer available. The internal IO parts of the block have their pins assigned to block pins in relation to their positions in the schematic diagram.

Circuits containing blocks that have been saved may also be loaded as blocks to nest or encapsulate their functionality into ever more complex circuits. This will impact speed since there will be exponential growth in the number of parts to be processed, but blocks do not involve coloring wires and visual elements.

Chips encapsulate complex functionality in the most efficient manner since they directly implement their functionality rather than being comprised of basic parts.

IO Parts

The IO part may be used to set the bus value and pin levels to stimulate the circuit. The current hex value is displayed on the part. This value may be edited by entering a decimal or hex number (0xff style) to set the value.

IO Part

The value is output from both sides of the part affecting whatever parts are connected to the IO part and that accept inputs in the direction of the value or level propagation. The value is applied after the enter key is pressed and the color of the text changes from orange to green.

Right-clicking on the IO part opens a panel that contains controls for entering the value, adjusting the value with a slider, or stepping the value up or down. The step buttons act like on a keyboard with a repeating action if held down. The panel may be moved so as not to obscure parts.

IO parts also capture and display values that they receive. The bus and wires of the IO part keep in sync as if wired in parallel, but the number of wires limit the range of numbers supported via the wired output pins. So a data input of 0xff may be clipped to 0xf if there were only 4 output wires used to connect the output.

It is best practice to only use the bus input or wire inputs for an IO part to avoid them fighting over what is the input value. When manually entering values with the slider or buttons, the Range setting limits the maximum value.

There are also single-pin parts to use for a bus or a wire input or output. These may be used for the IO pins of circuits that will be loaded as blocks or tested by the circuit testing feature.

Part Numbering

When parts are added, they are given an internal part number that is displayed when hovering the mouse over a part. This is the number displayed in any error message or saved with the circuit. But, there is a Tool available to automatically number parts in a more normal way, and it also sets the part tags with these numbers. Or the user may label the parts by editing the tag text labels.

User Interface

The overall schematic diagram area may be panned and zoomed. Also, the grid can be turned on/off and snapping enabled or disabled. A mini-map is also provided for visualizing and panning around a large diagram.

The circuit has an editable Title label which is saved with the circuit and used as a name for an associated block.

The New button erases the circuit, Save saves to the current file or initiates the SaveAs dialog, and Load is used to open a saved circuit. Load as block inserts a block part into the current circuit. The Tools menu is available for tasks such as numbering parts. Settings are saved and loaded with the software. Circuits are saved with the schematic settings, part settings, connections, and data such as colors.

Quit the App. by pressing the Esc key. Unsaved changes are indicated by a red color of the file name.

Keyboard Shortcuts

Esc - Quit the program

Ctrl + N - New circuit (wipe the current circuit and start a new one)

Ctrl + S - Save the circuit or open the SaveAs popup panel

Ctrl + O or Ctrl + L - Open the panel for Loading circuits

Ctrl + P or Ctrl + Space - open the Part selection panel

Ctrl + T - open the Tool menu

Ctrl + H - open the Help panel

DEL - delete selected parts

Crtl + D - duplicate selected parts

Crtl + R - remove connections between selected parts

Internal Operation

Internally, the value is propagated as an integer on the bus lines and as bits on wires. 8 bits take 8 steps to fully apply to 8 wires connected to a part, so this may cause up to 8 changes of a parts' output until it is stable. This affect is not seen by the user since it should be between frame updates of the display. It is like the propagation delay in real circuits but much more delayed.

There is also detection for unstable circuits where the output is continually cycling and not stabilizing. This condition stops propagation of signals and an alert message is shown to the user with information as to what part and pin the problem was detected at. Hovering the mouse over a part reveals its part number.

A speed optimization that is used is to not propagate a level if there is no change to an input. An affect of this may be to not update a downstream wire color if its color has been changed by the user. The speed of simulation will depend on circuit complexity and the speed of the computer being used, and what settings are applied to the circuit such as viewing logic levels and probing/displaying values.

Circuits are saved as text-based JSON data with a .circ file extension. So it’s possible to edit and view the files in external text editors. Also, external tools could be used to generate or process these files.

Tools

Number parts

This is a utility to add part numbers to the Tags of the parts.

The part number index is based off the distance of the part from the top left corner of the schematic diagram.

The name prefix is taken from the name of the part.

This is just a quick way to get started with assigning part labels to your circuit.

Test circuit

This uses the Title of your circuit to search for a test script (see the Nand2Tetris tab) under the directory that is specified in the settings for the Test Directory.

A warning is displayed if the test file cannot be found.

Load HDL circuit

This generates the Input and Output pins for a circuit from the data contained in an HDL specification file (see the Nand2Tetris tab).

It’s up to you to create the internal circuit to connect the inputs to the outputs to fulfill the function of the circuit, and then test it.

Disassembler

This tool is used to load .hack files that contain words of machine code, and converts these into Assembly language to help you to understand the code that it represents.

Nand2Tetris Integration

This Digital Logic Simulation software is designed to be very flexible, but at the same time it is useful to support widely-adopted standards. One of these is Nand2Tetris which offers a platform for learning how digital systems work from the ground up (a NAND gate to a working computer).

So an attempt has been made to support the .hdl (hardware description file format), .tst (circuit test specification), and .cmp (the output result comparison file format) of the Nand2Tetris platform. The relevant files are in a tests directory.

In order to process these files, the path to their base directory needs to be set in the Test file directory setting in Settings.

These files are also shipped with the Nand2tetris Software Suite from the Nand2tetris Software website.

Once this is set up, you should be able to make use of them in the Tools menu.

A set of IO pins may be automatically produced by loading an HDL file from the Tools menu. Then, you may construct a circuit to fulfill the requirements of the specification in the HDL file which may be displayed by clicking of the TextView part that is produced. Then run the tests on your circuit to see if it passes with the Test runner panel which is opened via the Tools menu.

Some circuits require a clock such as the CPU, so you need to use a Wire input named clk for this.

When testing the Memory, please ignore this message: "Before running this script, select the ‘Screen’ option from the ‘View’ menu".

When testing the CPU, the OutM pin has a high impedance state, so to simulate this a TriState output part needs to be used. Some circuit templates are provided with the required IO pins to help.

Remember to set the Title of your circuit to the name of the Part that you will test against. The software uses the Title text to search for the required test files.