Silinx · User's guideTry Silinx

Getting started with Silinx (step by step)

User's guide · English · Português

New Project: starting from the traffic example

No programming tools or git needed. Way 1, in the browser, does it all: Way 2 is another way of running the same Silinx, on your own computer.

I want to…Use
write VHDL/Verilog, draw schematics and state machines, wire digital circuits on a breadboard (74xx and 4000 ICs, tried live), simulate, synthesize and program a Basys2 / Nexys2 boardWay 1: in the browser, nothing to install
work offline, keep the projects as folders with any browser, program with the installed tools (Adept, openFPGALoader…), or use Xilinx ISE 14.7 or AMD Vivado for other boardsWay 2: run Silinx locally (installs Node.js once)

Way 1: in the browser (simplest)

The quickest: open https://pmnmalo.github.io/Silinx/ in your browser (the latest release; your projects are kept in that browser. The development version, with the changes not released yet, is at https://pmnmalo.github.io/Silinx/dev/, its projects kept apart) and go to step 4. Or download it, to work offline:

  1. Open the latest release.
  2. Under Assets, click Silinx.html to download it.
  3. Double-click the downloaded file. It opens in your browser (Chrome, Edge, Firefox or Safari).
  4. On the Start page click New Project…: its first page asks the project's kind, Digital Logic (schematics, truth tables, state machines and circuits on a breadboard, drawn and simulated: nothing of HDL, board or FPGA flow shown), FPGA (the default, a board and a device: what follows) or Co-design (FPGA and microcontroller nodes: not available yet). Then choose in Start from Example: gates (logic gates drawn as a schematic: a good first example), Example: breadboard (74LS chips wired on a breadboard, counting a button's presses: a digital circuit, see circuits.md), Example: traffic (a pedestrian crossing: a state diagram and a Boolean algebra), Example: blinky (or pong, a game for two, stopwatch, clock, vga, a picture on a VGA monitor, isqrt, a C function made into hardware, uart, an echo over the serial port to a terminal, or micro80, an 8080-compatible microprocessor running a program) or Empty project. After the examples come the Test design: … entries: designs Silinx itself is tested with (schematics, state diagrams, C programs for Silinx HLS), each with its test (a test bench, or the C program's main()), to see what Silinx does with each kind of source. An empty project asks one thing more, on the next page: its Top-Level Source Type (HDL, Schematic, a state machine (FSM or ASM), Boolean Algebra, Petri Net, Circuit, or a C or C++ function for Silinx HLS): the project starts with that top. The kind and the top can be changed later in Design Properties (its Project Kind).

That's all. Things to know:

Programming the board from the browser on Windows

Chrome and Edge reach a USB board only through Windows' WinUSB driver. Digilent Adept (installed with Adept, Xilinx ISE or Vivado, as on most lab computers) gives the Basys2 / Nexys2 its own driver, and FTDI's driver takes the FTDI boards (Basys 3, Nexys A7, iCEBreaker, ULX3S, Tang Nano 9K): the browser then lists the board but cannot open it. The console says so: the board cannot be opened (Access denied.)….

  1. Close Digilent Adept, iMPACT, Vivado's Hardware Manager and the Silinx application: one program at a time can use the board.
  2. Download Zadig and run it, with the board connected and switched on.
  3. Options ▸ List All Devices, choose the board (Digilent USB Device, Basys2, Nexys2, or Dual RS232-HS (Interface 0) for an FTDI board), choose WinUSB as the driver and click Replace Driver (or Install Driver).
  4. Unplug the board and plug it in again, then click Program FPGA: the browser shows its list of USB devices; choose the board (only the first time).

Adept, iMPACT and Vivado no longer see the board while it has WinUSB: to use them again, put Digilent's (or FTDI's) driver back in Windows' Device Manager (the board ▸ Update driver ▸ Let me pick).

The browser shows its list only right after a click: if the console says the browser did not show its list of USB devices, click the button again. If it says no board chosen, the list was closed with no board: check the cable and that the board is switched on (a board missing from the list on Windows: its driver, as above).


Way 2: run Silinx locally (Node.js)

The same Silinx, running on your computer instead of the site: projects as folders in Silinx-projects with any browser, synthesis offline, the board programmed with the installed tools too (Digilent Adept, openFPGALoader, xc3sprog, adepttool) or from Firefox and Safari, and Xilinx ISE 14.7 or AMD Vivado for the boards the Silinx toolchain does not support yet.

Step 1: install Node.js (once)

Silinx runs on Node.js, a free program.

  1. Go to https://nodejs.org and download the version marked LTS.
  2. Run the installer and accept the defaults (Next, Next, Install). - Windows: keep the option Add to PATH ticked (it is by default). You do not need the extra "Tools for native modules". - macOS: open the downloaded .pkg and follow the steps. - Linux: use your package manager (Ubuntu/Debian: sudo apt install nodejs npm) or the installer from nodejs.org. Version 18 or newer is needed.

Step 2: download Silinx

  1. Open the latest release.
  2. Under Assets, download silinx-<version>.zip (for example silinx-15.22.1.zip). - Don't use the green Code ▸ Download ZIP button or "Source code": that version does not include everything Silinx needs (it still works, but the first start needs Internet to download the missing parts).
  3. Unzip it (extract it) to a folder you will find again, e.g. Documents: - Windows: right-click the zip ▸ Extract All… ▸ Extract. Don't run it from inside the zip. - macOS: double-click the zip. - You get a folder called silinx.

Optional, to make sure the file is the release's (for example one you got from a course page): the release lists each file's SHA-256 checksum in its notes and in the file SHA256SUMS. Download SHA256SUMS into the same folder and, in a terminal there, run sha256sum -c SHA256SUMS --ignore-missing (Linux) or shasum -a 256 -c SHA256SUMS --ignore-missing (macOS): the file must say OK. On Windows, Get-FileHash silinx-<version>.zip in PowerShell prints the checksum to compare with the notes'. Each file also has GitHub's build provenance attestation (it was built by the repository's Release workflow from the version's tag): with the GitHub CLI, gh attestation verify silinx-<version>.zip --repo pmnmalo/Silinx.

Step 3: start Silinx

Open the silinx folder and double-click the launcher for your system:

SystemDouble-click
WindowsStart Silinx.bat
macOSStart Silinx.command
Linuxstart-silinx.sh (or run ./start-silinx.sh in a terminal)

A black window (the Silinx server) opens and then your browser shows Silinx at http://127.0.0.1:8642.

First time only, you may see:

Step 4: use it

Updating Silinx

Download the new silinx-<version>.zip, unzip it and use the new folder (you can delete the old one). Your projects are not inside that folder, so they are kept.


Synthesis and programming a board with Silinx running locally (optional)

In the browser (Way 1) nothing more is needed for the Basys2 and Nexys2. Running Silinx locally (Way 2), these need up to two more things. Your teacher may provide them already set up.

  1. For the Basys2 and Nexys2 boards, nothing: the Silinx toolchain, the default mode, synthesizes and generates the bitstream with no Xilinx tool. The Spartan-6 boards, the Nexys3 and the Atlys, too, in the browser and with Silinx running locally; the Atlys has no seven-segment display or VGA of its own, so Silinx puts them on its VHDCI connector (as a Digilent VmodBB wires them). For the other boards (or the processes that need ISE), Xilinx ISE 14.7 (free WebPACK licence); on any computer it runs inside Docker, then choose an ISE mode in Settings (⚙) ▸ Toolchain Settings (ISE / Programmers)… (ISE style: Tools ▸ …): - install Docker Desktop (on Apple Silicon Macs, OrbStack is a faster alternative); - download silinx-docker-kit-<version>.zip from the release and follow its ise/README.md: you download the ISE installer and licence with your own free AMD account and run one script (it takes 20–60 minutes, once). ISE cannot be shared, so everyone builds their own copy.
    The 7-series boards, the Basys 3 and the Nexys A7 (Artix-7), the Arty S7 (Spartan-7) and the Zybo Z7 (Zynq-7000), are built by AMD Vivado ML Standard (free for these parts) with Silinx running locally, its Synthesis Tool Vivado; the Basys 3 and the Nexys A7 by the Silinx toolchain too, in the browser as well (the README, The Artix-7 boards with AMD Vivado).
  2. The board's USB driver to program it: - Windows: install Digilent Adept 2 (Runtime + Utilities) from digilent.com. - macOS (Basys2): in a Terminal, inside the silinx folder, run brew install libusb python and ./scripts/install-adepttool.sh (needs Homebrew). - Linux: Digilent Adept, or openFPGALoader from your package manager.

In Silinx, Settings (⚙) ▸ Toolchain Settings (ISE / Programmers)… (ISE style: Tools ▸ …) shows what was found.


Problems?

What you seeWhat to do
The launcher says Node.js is not installedInstall it (Step 1). Then close the window and double-click the launcher again.
Browser: "This site can't be reached"The Silinx window was closed: double-click the launcher again.
"Port 8642 is used by another program"Another program uses that port. Open a terminal in the silinx folder and run node bin/silinx.js serve --port 8643 --open.
Console: "the Silinx server is not running"Same as above: start Silinx again. Your unsaved changes are saved as soon as it is back.
macOS: the .command file opens in a text editorRight-click it ▸ Open With ▸ Terminal.
The window flashes and closesOpen a terminal in the silinx folder and run node bin/silinx.js serve --open to read the message.

Opening a terminal in a folder: Windows: open the folder, click the address bar, type cmd and press Enter. macOS: right-click the folder ▸ New Terminal at Folder (or open Terminal, type cd , drag the folder into the window and press Enter).


For those who use git

git clone https://github.com/pmnmalo/Silinx.git
cd Silinx
npm install
npm start            # prints the address to open: http://127.0.0.1:8642/#token=…