Começar a usar o Silinx (passo a passo)
Guia do utilizador · English · Português

Não precisa de ferramentas de programação nem de git. A Forma 1, no browser, faz tudo: a Forma 2 é outra maneira de correr o mesmo Silinx, no seu computador.
| Quero… | Use |
|---|---|
| escrever VHDL/Verilog, desenhar esquemáticos e máquinas de estados, ligar circuitos digitais numa breadboard (CIs 74xx e 4000, experimentados ao vivo), simular, sintetizar e programar uma placa Basys2 / Nexys2 | Forma 1: no browser, nada a instalar |
| trabalhar sem Internet, guardar os projetos em pastas com qualquer browser, programar com as ferramentas instaladas (Adept, openFPGALoader…), ou usar o Xilinx ISE 14.7 ou o AMD Vivado para outras placas | Forma 2: correr o Silinx localmente (instala o Node.js uma vez) |
Forma 1: no browser (a mais simples)
O mais rápido: abra https://pmnmalo.github.io/Silinx/ no browser (a última versão lançada; os seus projetos ficam nesse browser. A versão em desenvolvimento, com as alterações ainda não lançadas, está em https://pmnmalo.github.io/Silinx/dev/, com os projetos à parte) e passe ao passo 4. Ou descarregue-o, para trabalhar sem Internet:
- Abra a última versão.
- Em Assets, clique em
Silinx.htmlpara o descarregar. - Faça duplo clique no ficheiro descarregado. Abre no browser (Chrome, Edge, Firefox ou Safari).
- Na página inicial clique em Novo Projeto… (New Project…): a primeira página pergunta o tipo de projeto, Lógica Digital (Digital Logic: esquemáticos, tabelas de verdade, máquinas de estados e circuitos numa breadboard, desenhados e simulados: sem HDL, placa nem fluxo da FPGA à vista), FPGA (por omissão, uma placa e um dispositivo: o que se segue) ou Co-design (nós de FPGA e de microcontrolador: ainda não disponível). Depois escolha em Começar a partir de (Start from) Exemplo: gates (portas lógicas desenhadas num esquemático: um bom primeiro exemplo), Exemplo: breadboard (chips 74LS ligados numa breadboard, a contar as vezes que se carrega num botão: um circuito digital, ver circuits.md), Exemplo: traffic (uma passadeira para peões: um diagrama de estados e uma álgebra booleana), Exemplo: blinky (ou pong, um jogo para dois, stopwatch, clock, vga, uma imagem num monitor VGA, isqrt, uma função em C feita em hardware, uart, um eco pela porta série para um terminal, ou micro80, um microprocessador compatível com o 8080 a correr um programa) ou Projeto vazio (Empty project). Depois dos exemplos vêm os Projeto de teste: … (Test design: …): projetos com que o próprio Silinx é testado (esquemáticos, diagramas de estados, programas em C para o Silinx HLS), cada um com o seu teste (uma bancada de teste, ou o
main()do programa em C), para ver o que o Silinx faz com cada tipo de fonte. Um projeto vazio pergunta mais uma coisa, na página seguinte: o seu Tipo de Fonte de Topo (Top-Level Source Type: HDL, Esquemático, uma máquina de estados (FSM ou ASM), Álgebra Booleana, Rede de Petri, Circuito, ou uma função C ou C++ para o Silinx HLS): o projeto começa com esse topo. O tipo e o topo podem mudar-se depois nas Propriedades do Projeto (Design Properties: o seu Tipo de Projeto).
É tudo. A saber:
- Os menus indicados a seguir (File ▸ …, Tools ▸ …) são os da interface Estilo ISE; na interface Silinx (a por omissão) os mesmos comandos estão na página inicial, nas Definições (⚙) do cabeçalho e na paleta de comandos (Ctrl+K: escreva o nome do comando).
- Os projetos ficam guardados dentro deste browser, neste computador. Para guardar uma cópia ou passar para outro computador use File ▸ Export Project (.zip)… (e File ▸ Import Project (.zip)… para o voltar a abrir, a partir do zip ou da pasta do projeto, a que tem o seu silinx.json; também abre um pacote de projeto
.silinx.jsonde uma versão anterior). Apagar os dados do browser apaga os projetos. - Ou guarde-os numa pasta do seu disco (Chrome ou Edge): File ▸ Open Workspace Folder… (também na página inicial) e escolha uma pasta, por exemplo uma nova pasta
Silinx-projectsnos Documentos. Cada projeto passa a ser uma pasta normal lá dentro (silinx.json,src/,sim/,constraints/, ebuild/com o bitstream), igual às do Silinx a correr localmente (Forma 2): a pasta também abre lá, e a pasta de um projeto pode ser comprimida em zip e entregue. O browser lembra-se da pasta; quando voltar a pedir autorização, clique em Reopen Silinx-projects na página inicial. File ▸ Copy Browser Projects to the Folder copia os projetos que já tinha no browser, e File ▸ Use Browser Storage volta ao browser. A barra de estado mostra onde ficam os projetos. Da primeira vez que o Silinx abre no Chrome ou no Edge, a consola propõe Choose a Workspace Folder… ou Keep in This Browser; escolhida uma pasta, os projetos que já estavam no browser podem ser copiados ou movidos para lá (mover pergunta antes de os apagar do browser). O Firefox e o Safari não abrem pastas: aí os projetos ficam no browser. Um projeto guardado só no browser e sem cópia há 7 dias (exportado como projeto Silinx, ou enviado para o GitHub) é dito uma vez na consola quando abre, com os botões Export Project (.zip) e Store Project in a GitHub Repository…. - Implement Design e Generate Programming File correm a cadeia de ferramentas Silinx no browser (placas Basys2, Nexys2, Nexys3, Atlys e iCEBreaker; a primeira vez descarrega as ferramentas do site, cerca de 100 MB, que o browser guarda; também no
Silinx.htmldescarregado): o bitstream (<módulo de topo>.bit, por exemploblinky.bit) é descarregado. - Programar a placa a partir do browser (Chrome ou Edge, ou o Chrome num tablet Android; o Firefox e o Safari não acedem a dispositivos USB; com a página aberta a partir do endereço do site, não a partir do ficheiro descarregado): ligue o cabo USB da placa, ligue-a, e depois Configure Target Device ▸ Program FPGA e escolha a placa na lista que o browser mostra (só na primeira vez). No Windows, se o Digilent Adept estiver instalado, o controlador dele ocupa a placa: dê-lhe o controlador WinUSB com o Zadig para a usar a partir do browser. No Linux, permita o acesso à placa com uma regra udev (
SUBSYSTEM=="usb", ATTR{idVendor}=="1443", MODE="0666"). Para guardar o desenho na flash da placa (PROM), para que arranque ao ligar, selecione a PROM (XCF02S / XCF04S) na cadeia e clique em Program PROM, com o jumper de modo em ROM (Basys2: JP3). - Num iPad ou num tablet (Safari, ou o browser do tablet): editar, desenhar, simular e Generate Programming File funcionam. O Chrome num tablet Android também programa a placa, como num computador (verificado num tablet Samsung; a placa na porta USB do tablet); o Safari num iPad não acede a dispositivos USB (programe o
.bitdescarregado a partir de um computador ou de um tablet Android). Os projetos ficam no browser, que o iPadOS pode apagar ao fim de algumas semanas sem uso: guarde uma cópia com File ▸ Export Project (.zip)…. Um tablet tem menos memória, por isso um desenho grande pode falhar na síntese. Os menus do botão direito abrem com um toque longo (o dedo parado meio segundo); dois dedos movem um desenho e o gesto de pinça faz zoom. Na vertical o painel lateral (Projeto) mostra-se ou esconde-se com o botão do painel lateral no cabeçalho (na interface Estilo ISE é uma gaveta, o botão à esquerda do cabeçalho) e as propriedades dos editores abrem por cima do desenho (Propriedades). - Uma ligação para os diapositivos: clique com o botão direito no projeto, no painel Projeto, Partilhar Projeto… (uma cópia), e depois Gerar (a ligação feita, e depois Copiar, Mostrar ou Mostrar o Código QR): a ligação abre o Silinx no projeto, em Experimentar, na simulação ou no emulador da placa, com o projeto inteiro lá dentro (ver o README, A design in a link).
- A interface abre em português quando o browser está em português; muda-se em Definições (⚙) ▸ Idioma (na interface Estilo ISE, View ▸ Language).
Programar a placa a partir do browser no Windows
O Chrome e o Edge só chegam a uma placa USB através do controlador WinUSB do Windows. O Digilent Adept (instalado com o Adept, o Xilinx ISE ou o Vivado, como na maioria dos computadores dos laboratórios) dá à Basys2 / Nexys2 o seu próprio controlador, e o controlador da FTDI fica com as placas FTDI (Basys 3, Nexys A7, iCEBreaker, ULX3S, Tang Nano 9K): o browser mostra então a placa na lista, mas não a consegue abrir. A consola diz isso: the board cannot be opened (Access denied.)….
- Feche o Digilent Adept, o iMPACT, o Hardware Manager do Vivado e a aplicação Silinx: só um programa de cada vez pode usar a placa.
- Descarregue o Zadig e execute-o, com a placa ligada ao computador e ligada.
- Options ▸ List All Devices, escolha a placa (Digilent USB Device, Basys2, Nexys2, ou Dual RS232-HS (Interface 0) numa placa FTDI), escolha WinUSB como controlador e clique em Replace Driver (ou Install Driver).
- Desligue o cabo da placa e volte a ligá-lo, e depois clique em Program FPGA: o browser mostra a sua lista de dispositivos USB; escolha a placa (só na primeira vez).
O Adept, o iMPACT e o Vivado deixam de ver a placa enquanto ela tiver o WinUSB: para os voltar a usar, reponha o controlador da Digilent (ou da FTDI) no Gestor de Dispositivos do Windows (a placa ▸ Atualizar controlador ▸ Escolher).
O browser só mostra a sua lista logo a seguir a um clique: se a consola disser the browser did not show its list of USB devices, clique de novo no botão. Se disser no board chosen, a lista foi fechada sem placa: verifique o cabo e se a placa está ligada (uma placa que não aparece na lista no Windows: o seu controlador, como acima).
Forma 2: correr o Silinx localmente (Node.js)
O mesmo Silinx, a correr no seu computador em vez do site: os projetos como pastas em Silinx-projects com qualquer browser, a síntese sem Internet, a placa programada também com as ferramentas instaladas (Digilent Adept, openFPGALoader, xc3sprog, adepttool) ou a partir do Firefox e do Safari, e o Xilinx ISE 14.7 ou o AMD Vivado para as placas que a cadeia de ferramentas Silinx ainda não suporta.
Passo 1: instalar o Node.js (uma vez)
O Silinx corre no Node.js, um programa gratuito.
- Vá a https://nodejs.org e descarregue a versão marcada LTS.
- Execute o instalador e aceite as opções por omissão (Next, Next, Install). - Windows: mantenha a opção Add to PATH selecionada (já vem assim). Não precisa das "Tools for native modules". - macOS: abra o
.pkgdescarregado e siga os passos. - Linux: use o gestor de pacotes (Ubuntu/Debian:sudo apt install nodejs npm) ou o instalador do nodejs.org. É preciso a versão 18 ou mais recente.
Passo 2: descarregar o Silinx
- Abra a última versão.
- Em Assets, descarregue
silinx-<versão>.zip(por exemplosilinx-15.22.1.zip). - Não use o botão verde Code ▸ Download ZIP nem o "Source code": essa versão não traz tudo o que o Silinx precisa (funciona na mesma, mas o primeiro arranque precisa de Internet para descarregar o que falta). - Descompacte-o (extraia-o) para uma pasta que volte a encontrar, por exemplo Documentos: - Windows: botão direito no zip ▸ Extrair Tudo… ▸ Extrair. Não o execute de dentro do zip. - macOS: duplo clique no zip. - Fica com uma pasta chamada
silinx.
Opcional, para confirmar que o ficheiro é o da versão (por exemplo um que veio da página de uma cadeira): a versão lista o checksum SHA-256 de cada ficheiro nas suas notas e no ficheiro SHA256SUMS. Descarregue o SHA256SUMS para a mesma pasta e, num terminal aí, corra sha256sum -c SHA256SUMS --ignore-missing (Linux) ou shasum -a 256 -c SHA256SUMS --ignore-missing (macOS): o ficheiro tem de dizer OK. No Windows, Get-FileHash silinx-<versão>.zip no PowerShell mostra o checksum, a comparar com o das notas. Cada ficheiro tem também a atestação de proveniência do GitHub (foi construído pelo workflow Release do repositório a partir da tag da versão): com o GitHub CLI, gh attestation verify silinx-<versão>.zip --repo pmnmalo/Silinx.
Passo 3: arrancar o Silinx
Abra a pasta silinx e faça duplo clique no ficheiro do seu sistema:
| Sistema | Duplo clique em |
|---|---|
| Windows | Start Silinx.bat |
| macOS | Start Silinx.command |
| Linux | start-silinx.sh (ou ./start-silinx.sh num terminal) |
Abre-se uma janela preta (o servidor do Silinx) e depois o browser mostra o Silinx em http://127.0.0.1:8642.
- Mantenha a janela preta aberta enquanto trabalha. Fechá-la desliga o Silinx.
- Fechou o separador do browser sem querer? Volte a http://127.0.0.1:8642, no mesmo browser, enquanto a janela está aberta (ou faça duplo clique outra vez no ficheiro).
- Fazer duplo clique no ficheiro com o Silinx já a correr só volta a abrir o browser.
Só da primeira vez pode aparecer:
- Windows: "O Windows protegeu o seu PC": clique em Mais informações ▸ Executar mesmo assim.
- Firewall do Windows pergunta pelo Node.js: clique em Permitir (o Silinx só aceita ligações do próprio computador).
- macOS: "não pode ser aberto porque é de um programador não identificado": botão direito (ou Ctrl-clique) em
Start Silinx.command▸ Abrir ▸ Abrir. Das vezes seguintes basta o duplo clique.
Passo 4: usar
- Página inicial ▸ Novo Projeto… (New Project…), Começar a partir de Exemplo: gates para começar (portas AND, OR, NOT e NAND num esquemático: um detetor de números primos de 4 bits nos interruptores e em dois LEDs), Exemplo: traffic a seguir (uma passadeira para peões: o controlador é um diagrama de estados, as luzes uma álgebra booleana), Exemplo: blinky para explorar um projeto completo, ou Projeto vazio (Empty project).
- Os projetos ficam em pastas normais em
Silinx-projects, na sua pasta de utilizador (Windows:C:\Users\<você>\Silinx-projects, macOS:/Users/<você>/Silinx-projects). Pode copiá-los, fazer cópias de segurança, ou comprimi-los para entregar. - Mudar o Nome do Projeto… (Rename Project…; menu Ficheiro, menu do botão direito do projeto no painel Projeto, o de um projeto recente na página Início) muda o nome de um projeto: a pasta muda de nome (a de um repositório git com o
.git, mantendo o repositório no GitHub), e o projeto continua aberto com os separadores. Não enquanto corre uma implementação nem enquanto o projeto é partilhado em direto. - Abrir no VS Code (Open in VS Code; o editor que o Silinx encontra neste computador: VS Code, VSCodium ou Cursor): botão direito num ficheiro de texto (HDL, C, restrições) no painel Projeto ou no seu separador para o ficheiro, no projeto para a sua pasta (Abrir a Pasta no VS Code); cada gravação lá aparece no Silinx.
- O separador Colaboração (Collaboration, o último do painel lateral; sem projeto aberto, ao lado de Início: o início de sessão no GitHub, Abrir do Repositório GitHub…): um projeto num repositório do GitHub (também o de um trabalho do GitHub Classroom), Registar (Commit)…, Enviar (Push), Receber (Pull), Alterações… (os ficheiros alterados, numa janela), Histórico… e as verificações do GitHub; Guardar o Projeto num Repositório GitHub… ou Abrir do Repositório GitHub… para um que não tenha (README, "A project on GitHub"); e a partilha em direto: Partilhar em Direto…, quem está no projeto, Parar de Partilhar.
- File ▸ Export Project (.zip)… começa pelo software de destino: Xilinx ISE cria um zip que abre no Xilinx ISE 14.7; Silinx guarda o projeto Silinx completo (com os diagramas ASM e esquemáticos), que se reabre com File ▸ Import Project… (que reconhece o software do zip); a pasta de um projeto Silinx (a que tem o seu silinx.json) também se importa aí, como a de um projeto ISE. AMD Vivado e Intel Quartus aparecem desativados: o Silinx ainda não lê nem escreve os seus projetos. Um projeto importado veio de fora: só corre o Xilinx ISE e só programa uma placa depois de carregar em Confiar no Projeto (Trust Project) na consola, que o diz quando o projeto abre. Um projeto só de desenho e simulação (sem FPGA) não tem software a escolher: é exportado como projeto Silinx.
- A interface abre em português quando o browser está em português; muda-se em Definições (⚙) ▸ Idioma (na interface Estilo ISE, View ▸ Language).
Atualizar o Silinx
Descarregue o novo silinx-<versão>.zip, descompacte-o e use a nova pasta (pode apagar a antiga). Os seus projetos não estão dentro dessa pasta, por isso mantêm-se.
Síntese e programação de uma placa com o Silinx a correr localmente (opcional)
No browser (Forma 1) não é preciso mais nada para as Basys2 e Nexys2. Com o Silinx a correr localmente (Forma 2), precisam de até mais duas coisas. O seu professor pode já as ter preparadas.
- Para as placas Basys2 e Nexys2, nada: a toolchain Silinx, o modo por omissão, sintetiza e gera o bitstream sem nenhuma ferramenta Xilinx. As placas Spartan-6, a Nexys3 e a Atlys, também, no browser e com o Silinx a correr localmente; a Atlys não tem display de sete segmentos nem VGA próprios, e o Silinx põe-nos no seu conector VHDCI (como os liga uma Digilent VmodBB). Para as outras placas (ou os processos que precisam do ISE), o Xilinx ISE 14.7 (licença WebPACK gratuita); em qualquer computador corre dentro do Docker, e depois escolha um modo ISE em Definições (⚙) ▸ Definições da Toolchain (ISE / Programadores)… (Estilo ISE: Tools ▸ …): - instale o Docker Desktop (nos Mac com Apple Silicon, o OrbStack é uma alternativa mais rápida); - descarregue
silinx-docker-kit-<versão>.zipda mesma página e siga o seuise/README.md: descarrega o instalador do ISE e a licença com a sua conta AMD gratuita e corre um script (demora 20–60 minutos, uma vez). O ISE não pode ser partilhado, por isso cada pessoa cria a sua cópia.
As placas da série 7, a Basys 3 e a Nexys A7 (Artix-7), a Arty S7 (Spartan-7) e a Zybo Z7 (Zynq-7000), são construídas pelo AMD Vivado ML Standard (gratuito para estes dispositivos) com o Silinx a correr localmente, com o Vivado como ferramenta de síntese (Synthesis Tool); a Basys 3 e a Nexys A7 também pela cadeia de ferramentas Silinx, também no browser (ver o README, The Artix-7 boards with AMD Vivado). - O controlador USB da placa para a programar: - Windows: instale o Digilent Adept 2 (Runtime + Utilities) a partir de digilent.com. - macOS (Basys2): num Terminal, dentro da pasta
silinx, executebrew install libusb pythone./scripts/install-adepttool.sh(precisa do Homebrew). - Linux: Digilent Adept, ou o openFPGALoader do gestor de pacotes.
No Silinx, Definições (⚙) ▸ Definições da Toolchain (ISE / Programadores)… (Estilo ISE: Tools ▸ …) mostra o que foi encontrado.
Problemas?
| O que aparece | O que fazer |
|---|---|
| O arranque diz Node.js is not installed | Instale-o (Passo 1). Feche a janela e faça duplo clique outra vez. |
| Browser: "Não é possível aceder a este site" | A janela do Silinx foi fechada: faça duplo clique outra vez no ficheiro de arranque. |
| "Port 8642 is used by another program" | Outro programa usa essa porta. Abra um terminal na pasta silinx e execute node bin/silinx.js serve --port 8643 --open. |
| Consola: "the Silinx server is not running" | O mesmo: volte a arrancar o Silinx. As alterações por guardar são guardadas assim que ele voltar. |
macOS: o ficheiro .command abre num editor de texto | Botão direito ▸ Abrir com ▸ Terminal. |
| A janela abre e fecha logo | Abra um terminal na pasta silinx e execute node bin/silinx.js serve --open para ler a mensagem. |
Abrir um terminal numa pasta: Windows: abra a pasta, clique na barra de endereço, escreva cmd e carregue em Enter. macOS: botão direito na pasta ▸ Novo Terminal na Pasta (ou abra o Terminal, escreva cd , arraste a pasta para a janela e carregue em Enter).
Para quem usa git
git clone https://github.com/pmnmalo/Silinx.git
cd Silinx
npm install
npm start # mostra o endereço a abrir: http://127.0.0.1:8642/#token=…