Setting up the bench

What you need

• A computer with a keyboard: a laptop, a desktop or a Chromebook. A phone is too small, and a tablet is hard work without a keyboard.
• A web browser. Chrome, Chromium, Edge or Brave is best, because they can keep your work in a folder on the computer (step 2). Firefox and Safari work too, and keep your work inside the browser instead.
• A notebook and a pencil, and some graph paper. Every chip starts on paper.
• Nothing else. No account, no password, no download to install, no money.

Step 1 · Open the workshop

1. Go to nand2tetris.github.io/web-ide and bookmark it. This is the IDE (the “integrated development environment”): every tool you need for the whole year, in one web page.
2. A notice at the bottom asks about analytics, which only counts visits. Click Reject. Everything works the same.
3. You are now in the Hardware Simulator, where you will build most of your chips. The row of small icons along the top switches between the tools. The ones you will use this year are the Hardware Simulator, the CPU Emulator (Project 4) and the Assembler (Project 6). Hover over an icon to see its name.

Step 2 · Decide where your work is kept

The IDE saves as you type. The question is where. Open Settings (the gear icon near the top right) and look under Project files.

The better way: a folder on the computer

For Chrome, Chromium, Edge or Brave. Your chips are ordinary files you can see, copy and back up, and clearing the browser cannot lose them.

1. In Settings, choose Use Desktop Storage.
2. Click Download the projects folder. Save the file, then unzip it into a folder you will remember, for example a folder called nand2tetris in your Documents.
3. Click Select Projects Folder and choose that folder. Your browser asks whether this page may see and save files there. Say yes. If it asks again on another day, say yes again.

The simple way: inside the browser

For any browser, and what the IDE does if you change nothing. Your chips live inside the browser on this computer.

• Never click Reset browser storage files in Settings. It wipes your work.
• If anyone clears this browser’s history and site data, your work goes with it. Tell the family.
• Every Friday, make a backup: in the Hardware Simulator, use the download button beside the chip list (it says Download all files in this folder into a zip) and keep the zip.

Step 3 · Look around

Open the Hardware Simulator, choose Project 1 from the list at the top, and then And from the list beside it. Don’t build anything yet. Just find these four things:

1. The HDL editor, at the top. HDL is the language you describe a chip in. The grey lines starting with // are comments for people, and the computer ignores them. Your work goes where the file says to put your code.
2. The pins, in the middle: the chip’s inputs and outputs. Click an input to switch it between 0 and 1.
3. The test, at the bottom. Every chip comes with a test script and a compare file, which holds the right answers. The arrow buttons step through the test one line at a time, or run it all. When it finishes, the IDE says whether your chip’s output matched, and the Diff Table shows any row that did not.
4. The Builtin switch, beside “HDL”. It swaps your chip for the course’s own ready-made one. That is handy for seeing what a chip should do, but turn it off before you test yours, or you are testing theirs.

The line at the very bottom tells you if your HDL has a mistake in it. Read it slowly; it usually says which line.

Step 4 · The lectures

Each project page lists its lectures in the order to watch them, with their lengths. They are the course’s own, by Professors Nisan and Schocken, and they were filmed with an older version of the tools. The buttons look different from the IDE you have, but the ideas are exactly the same. Watch with your parent, one or two at a sitting, and stop the video whenever you want to try something on paper.

Step 5 · Your notebook

Before each chip, write its truth table in your notebook and work out on paper how to build it. Only then type it in. When a chip will not pass, go back to the paper, not to the internet. Keep everything: the wrong tries too. They are part of how you got there.

The rules of the bench

1. Don’t look up answers. Every answer to every chip is online somewhere. Building the chip is the point, and a copied chip teaches nothing. If you land on a page of answers by accident, close it and tell your parent. Saying so is worth more than the chip.
2. Being stuck is part of the work. Most chips take more than one try, and Mux takes almost everyone a while. Ask a person. Sleep on it.
3. Your work stays at home. Don’t post your chips anywhere public. The course’s authors ask everyone not to, so that the next person can build them too.
4. A pass is a pass. The test cannot be argued with, and neither can a fail. That is what makes it fair.

If something goes wrong

• My work disappeared. Open Settings and check which storage is chosen. If you use a folder, make sure it is the same folder as before.
• The test fails and I don’t know why. Open the Diff Table, find the first row that is wrong, and work that row out by hand on paper.
• The page looks broken. Reload it. Your work is saved.
• Something else. Ask your parent before you search for it.

For the parent

Next: Project 0, the workbench →