ALICE instruction manual

Both the tool and the manual are currently/permanently under construction! Click here to open on a separate page.

Index

Basics

ALICE is a tool is to build some logic circuits and have fun with them. It is an open-source project by Aubery Lis, available for free to run locally from gitea. In ALICE, you build a logic circuit on a gridded board. Like with real circuit boards, the two main things you're going to use are Devices (think microchips, transistors, diodes...) and Wires that connect the devices. Like real-life ICs have small metallic pins that are used to expose the circuit hidden inside to the outside world, each Device has one or more Pins. When Devices are placed on the circuit, their Pins are connected with Wires. The collection of directly interconnected Wires and Pins is called a Net. When the circuit is ran, first all input Pins register the state of the Net they're on (True/False/Unknown), then the logic inside the Devices is ran, and finally, the output pins update the Nets they are on.

ALICE is a big nasty abstraction tailored for binary logic, so it will not emulalte exact voltages and real transistors that you may find inside real-life logic chips. Instead, it works only with binary True/False logic, however, a third Undefined state happens if no Pin outputs a signal to a Net. Like in real life, two or more output Pins driving the same net leads to a short citcuit and an undefined logic state! In reality, this may destroy the integrated circuits. In ALICE, you will simply receive an error.

Exercise: your first ALICE circuit

Access ALICE in your web browser. You will be presentedd with an empty circuit Cir0. Let's place our first Device by pressing the little plus icon next to "Gates" in the Devices folder in the explorer on the left. A drop-down menu appears, revealing the choices available in this Device group. Let's pick an AND gate by clicking on "And".

Notice how at the bottom of the screen, the Tool window now shows gates.and instead of pointer, and your cursor is a folded hand when hovered over the circuit; this means that currently you are "holding" the AND gate in your digital hand. Click once to invoke the AND gate, then choose a suitable position for it (anywhere on the circuit in this case) and click again. The gate was placed! You can add more gates like this if you keep clicking, but for now, hit "escape" to stop the action and set your tool back to Pointer.

The AND gate has two input pins on the left, and one output on the right. And as expected, its output produces True only if both of its inputs receive True. Right now nothing is going into the input pins, though. The Interfaces Device group has basic input and output elements. But for simplicity, picking the most basic Devices has been mapped to the keyboard as shortcuts. To add a Source, press "S" on the keyboard. You will notice the Tool line change to interfaces.source. Place two sources to the left of the AND gate. These are basic on-off buttons that produce a True or a False and can be interacted with using the Pointer tool. In a similar fashion, press "L" to invoke a Light - a basic LED-like indicator - and place it somewhere to the right of the AND gate.

Final step: the devices are there but the pins are all disconnected! Press "W" on your keyboard to switch to the wire tool. You will notice the cursor became a crosshair. Now simply click on the Source's pin, then start moving your mouse away. A Wire appears! Bring it over to one of the AND gate's inputs and click again to finish the wire. Do the same with the other source, connect AND's output pin to the light's input pin and hit "escape" to exit the wiring tool.

The circuit is finished! In the top bar, press the "Run" button. The Status line in the bottom changed from "Idle" to "Running", signifying that the circuit is now being actively processed. While the circuit is running, the only available tool is Pointer; you cannot add or remove elements while it is turned on. However, you can interact with whatever is interactable; in this case, try clicking on the Sources' buttons and see how the circuit reacts. Which combination of the Sources being on or off lights up the Light?

Project Hierarchy

The top level unit in ALICE is a Project. A Project's contents can be seen in the explorer tree in the screen's top-left, under "Project Tree". An ALICE project contains:

One project can contain many circuits at once, like a notebook with many pages. It is only possible to load and run one circuit at a time, so there is no way to pass signals between two circuits as parts of one whole. However, ALICE is hierarchic, and each circuit can be made into an Integrated Circuit, which can be used as a construction part of other circuits.

The Notes subfolder is to create and store bits of text, like a description of your project, circuit notes, and whatnot. It comes pre-packed with ALICE manual - there is no need to delete it, since it is stored in ALICE's own files and takes no space in your project's memory.

Project Settings govern the most basic rules that apply to all circuits, including their integrated circuit forms. Project's name can be changed, as well as runtime timings. Less frames per second with more ticks per frame is advised for complex builds.

Exercise: add another circuit

Let's say you want to work on a new bit of circuitry, but want to keep the current one in direct proximity. Best choice in such case is keeping them as separate circuits in the same project.

Right-click on the "Circuits" subfolder and click "Create New" - a blank circuit opens up. You will notice that a new entry appeared in the "Circuits" subfolder. It should get the name "cir1" under normal conditions. Right-click it to explore the options: you can rename it to something fancier than an order number, delete it, save as separate circuit, or even create an integrated circuit out of it!

Saving and Loading

The top-level unit of ALICE, Project, is associated with the .alice file extension. A Project contains one or more Circuits, as well as the emulation settings and other important stuff. It is possible to save the project by hitting Save Project at the Explorer's bottom. ALICE does not use cookies or site storage, so the moment you refresh the page, everything's gone! Loading the entire project back up is done by opening up a new ALICE tab and hitting Load Project in the Explorer.

It is possible to save and load circuits separately from the project, e.g. to move them from one project to another. To save a circuit, right-click on its name in the Explorer and select Download Circuit. Circuit files are associated with .acirc (ALICE Circuit) extension and can be loaded by right-clicking the Circuits folder and picking Upload existing .acirc and locating the local file. Circuit files contain information on their integration as well. Do note that if a circuit uses integrated circuits from some projects, those have to be downloaded as circuits as well and uploaded to the other project before uploading the circuit that uses them; otherwise, a dependency error occurs.

Integrated Circuits

One of the reasons for creating ALICE is fascination with how one gets from puny logic gates to entire CPUs through the power of large-scale integration. In real world, an integrated circuit is a pre-fabricated chip that one uses in their circuitboard to perform a task it is designed for. In ALICE, Integrated Circuits are more abstract, and are merely circuits with some nodes exposed to the outside world via IC Pins. Once a circuit's integrated version is configured, in can be used as an ordinary device in other circuits, which, in turn, can be integrated as well.

To integrate a circuit, right-click on its name in the Project Tree and select "Create IC". Bear in mind that an IC can only be created if a circuit has one or more IC Pins - a special device available under Primitives, or by hitting "I". An IC Pin exposes a node from the circuit to the outside world. Bear in mind that when an IC is used as a device, its pins change direction based on what happens inside and outside of the IC. If there is a signal source both behind the pin inside the IC and going to the pin from the outside, a short circuit error will happen.

After "Create IC" is clicked, a new screen appears, where integration settings are adjusted. Up top are the settings of the resulting device's size. It is picked automatically to fit all the pins, but can be adjusted to the user's liking. Below is an entry for each IC pin in the circuit. Clicking "Offset" cycles through possible offsets on the side the pin is at. Clicking "Side" cycles through the IC's four sides the pin can be on. Once you are happy with how your IC looks, hit "Save" on the toolbar. This will commit the integration details for this circuit, which you can now confirm by looking in the Details window at bottom left and noting "Integration: present" showing up instead of "Integration: absent".

Now you can use your circuit as a device in other circuits. It is available from the "Integrated Circuits" subfolder in "Devices". Integration details are saved along with the project, so when you reopen your project, all the circuits with integration will be loaded as ICs automatically. Do note that there are rules of using ICs enforced by ALICE's code:

  1. An IC cannot be used inside itself (single-step infinite recursion)
  2. An IC cannot be used inside any IC it uses down the dependency line (multiple-step infinite recursion)
  3. Once used in a circuit, an IC cannot be deleted
  4. Changing a circuit will change every instance of its integrated version in other circuits

Tools & Actions List

Actions

Device shortcuts

Bug Reporting

ALICE is admittedly explosive at the present moment. Although it works, it still misbehaves sometimes. Most of the bugs are related not to the logic, but to the GUI, in particular the graphic wire routing system. If you encounter a bug, please, write to auby [at] auberylis.moe with details. Please, include the following:

Each bug report is greatly appreciated and taken into account! ALICE is a one-girl operation, so it may take time for everything to get resolved. Cheers!