LitexCNC: een open-source controller voor LinuxCNC

[Tolp2]

Zoals beloofd op de CNCzone dag 2023 ga ik in deze serie beschrijven hoe je van een goedkope LED-kaart kan komen tot een complete CNC-besturing. Dit project gaat uit van open source software, open source hardware en open source toolchain. Om met dit project aan de slag te gaan heb je de volgende zaken nodig:

• Een PC of Raspberry Pi met LinuxCNC;
• Een vaste hand om SMD componenten te solderen (of iemand die dit voor je wilt doen);

[Tolp2]

DEEL1: LED-kaart
De LED-kaarten hebben zogenoemde HUB75 connectoren en worden normaliter gebruikt om billboards aan te sturen. Iedere connector heeft 6 individuele aanstuurbare pinnen en 8 gedeelde pinnen. LitexCNC ondersteund meerdere typen LED-kaarten:

• 5A-75B: deze kaart heeft 8 connectoren en heeft daarmee maximale 56 GPIO;
• 5A-75E: deze kaart heeft 16 connectoren en heeft daarmee maximale 104 GPIO;

Voor dit stappenplan gebruik ik de 5A-75B. Deze kun je bijvoorbeeld hier worden aangeschaft. De laagste prijs ligt ongeveer op 12 Euro, met daarboven nog verzendkosten. De reden dat ik de 5A-75B gebruik is omdat dit board de ruimte biedt om een HAT (waarover later meer) er op te plaatsen.

Aanpassen LED-kaart
De LED-kaart is standaard geconfigureerd om alleen outputs te hebben. Wil je de kaart hebben om juist een heleboel outputs te hebben (PWM, Stepgen, digital out), dan kun je deze stap overslaan. Wil je ook inputs hebben, zoals home switches, encoders, noodstop, e.d., dan moeten de buffers worden verwijderd en vervangen worden door draadbruggen.

De 5A-75B bevat in totaal 12 buffer IC's. De afbeelding hieronder geeft de locaties van de buffers weer, maar afhankelijk van de versie van je kaart kan de locatie van de buffers anders zijn. De markering van de buffers is in alle gevallen 74VHC245.



De makkelijkste manier om de buffers te verwijderen is om met een klein tangetje de pootjes door te knippen. Als de chip weg is, dan kan vervolgens met een soldeerbout de pootjes gemakkelijk en zonder schade van de pads worden geveegd. Voor het netjes de-solderen van de chips is meer ervaring nodig, en ik had vaak last van pads die kapot gingen. Het losknippen gaat eigenlijk altijd goed.

Vervolgens kunnen twee keuzes worden gemaakt:

• Soldeer 8 draadbruggen per chip (mijn voorkeur)
• Gebruik een speciaal PCB die hiervoor is ontwikkeld

De soldeerbruggen verbinden de volgende pinnen:

• pin2 <-> pin 18
• pin3 <-> pin 17
• pin4 <-> pin 16
• pin5 <-> pin 15
• pin6 <-> pin 14
• pin7 <-> pin 13
• pin8 <-> pin 12
• pin9 <-> pin 11

Naast het vervangen van de buffers, moeten er ook nog twee pin-headers worden aangebracht voor het programmeren van de board. In de afbeelding zijn deze weergegeven met JTAG en GND/3.3V

LET OP: na deze aanpassing zijn de HUB75 connectoren niet geschikt voor 5V.

[hainjedaf]

Was een leuke en interessante voordracht!

[Tolp2]

DEEL2: Voorbereiden software
Terwijl de LED-kaart in bestelling is (duurt ongeveer twee weken voordat deze arriveert), kunnen we alvast de software voorbereiden. Hieronder vind je een beschrijving om LinuxCNC op een RaspberryPi te installeren. Daarna volgen de stappen om LitexCNC te installeren en de toolchain voor te bereiden. Eventueel kan een hier een image worden gedownload waarmee LinuxCNC direct kan worden geflasht op de RaspberryPi.

Installeren LinuxCNC
Originele versie van onderstaand recept kan worden gevonden op het LinuxCNC-forum. De code in onderstaande blokken kan één-op-één worden gekopieerd in de terminal van de RapsberryPi.

• Download het image (Buster) en flash deze op de SD kaart met de Raspberry Pi Imager.
• Update van het OS

  Code: Selecteer alles

  sudo apt update
  sudo apt upgrade
  

• Installeer de real-time kernel

  Code: Selecteer alles

  sudo su     
  cd /tmp     
  wget https://github.com/kdoren/linux/releases/download/rpi_5.15.65-rt49/linux-image-5.15.65-rt49-v7l+_5.15.65-1_armhf.deb     
  apt install ./linux-image-5.15.65-rt49-v7l+_5.15.65-1_armhf.deb     
  KERN=5.15.65-rt49-v7l+      
  mkdir -p /boot/$KERN/o/     
  cp -d /usr/lib/linux-image-$KERN/overlays/* /boot/$KERN/o/     
  cp -dr /usr/lib/linux-image-$KERN/* /boot/$KERN/     
  [[ -d /usr/lib/linux-image-$KERN/broadcom ]] && cp -d /usr/lib/linux-image-$KERN/broadcom/* /boot/$KERN/     
  touch /boot/$KERN/o/README     
  mv /boot/vmlinuz-$KERN /boot/$KERN/     
  mv /boot/initrd.img-$KERN /boot/$KERN/     
  mv /boot/System.map-$KERN /boot/$KERN/     
  cp /boot/config-$KERN /boot/$KERN/     
  cp /boot/cmdline.txt /boot/$KERN/     
  cat >> /boot/config.txt << EOF     
  
  [all]     
  kernel=vmlinuz-$KERN     
  # initramfs initrd.img-$KERN     
  os_prefix=$KERN/     
  overlay_prefix=o/$(if [[ "$KERN" =~ 'v8' ]]; then echo -e "\narm_64bit=1"; fi)     
  [all]     
  EOF
  

• Optimaliseer de kernel. Twee van de 4 processoren worden gereserveerd voor LinuxCNC

  Code: Selecteer alles

  sudo sed -i -e '$s/$/ isolcpus=1,2,3 idle=poll/' /boot/$KERN/cmdline.txt
  

• Herstart de RaspberryPi om de wijzigingen door te voeren
• Installeer LinuxCNC

  Code: Selecteer alles

  sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com --recv-key 3cb9fd148f374fef
  echo deb http://linuxcnc.org/ buster base 2.8-rtpreempt | sudo tee /etc/apt/sources.list.d/linuxcnc.list
  echo deb-src http://linuxcnc.org/ buster base 2.8-rtpreempt | sudo tee -a /etc/apt/sources.list.d/linuxcnc.list
  sudo apt-get update
  sudo apt-get install linuxcnc-uspace linuxcnc-uspace-dev
  

Opmerking: Link naar image is gewijzigd op 8 november 2023. De nieuwe link verwijst naar de laatste versie van Debian Buster die beshcikbaar is. Het is een oude versie van Linux, maar is geschikt om LinuxCNC 2.8.4 op te draaien. Eventueel kan LinuxCNC ook op Debian Bookworm worden gezet. Dit zal ik later behandelen in een eigen onderwerp.

Installeren LitexCNC en voorbereiden toolchain
LitexCNC is een Python-pakket dat er voor zorgt dat de toolchain en driver geïnstalleerd worden op het systeem en dat de firmware kan worden gebouwd. Het is als pakket makkelijk te installeren vanaf pypi.org:

Code: Selecteer alles

pip3 install litexcnc[cli] --user

Hierna kunnen de volgende commando's worden uitgevoerd om de toolchain en driver te installeren:

• Toolchain (Litex, open-oss-cad, OpenOCD):

  Code: Selecteer alles

  litexcnc install_toolchain --user
  

• Driver voor LinuxCNC

  Code: Selecteer alles

  sudo env "PATH=$PATH" litexcnc install_driver
  

[Tolp2]

DEEL 3: Een LED laten knipperen
In dit deel gaan we een simpel firmware schrijven en de LED-kaart aansturen door middel van halrun. We gaan dus nog niet aan de slag met LinuxCNC en de HAL-bestanden die daarbij horen. Het aansturen wordt gedaan door middel van Ethernet. Dit heeft twee redenen: 1) dit voorbeeld werkt op zowel een RaspberryPi als een PC en 2) dit voorbeeld heeft geen input-pinnen nodig, dus solderen is nog niet nodig.

Compileren firmware
Onderstaand is de firmware voor het voorbeeld, noem het bestand 'blink.json'.

Code: Selecteer alles

{
    "board_name": "blink",
    "board_type": "5A-75E v6.0",
    "clock_frequency": 35000000,
    "connection": {
        "connection_type": "etherbone",
        "tx_delay": 0,
        "ip_address": "10.0.0.10",
        "mac_address": "0x10e2d5000000"
    },
    "modules": [
        {
            "module_type": "gpio",
            "instances": [ 
                {"direction": "out", "pin":"j1:2"},
            ]
        }
    ]
}

De velden die hier worden gebruikt zijn:

• board_name: de naam van de LED-kaart zoals deze wordt weergegeven in LinuxCNC/HAL
• board_type: het type board. Ondersteunde types zijn '5A-75B v6.1', '5A-75B v7.0', '5A-75B v8.0', '5A-75E v6.0', en '5A-75E v7.1'. Van de 5A-75E is ook nog een versie 8.X in omloop; voor deze kaart kan de versie `5A-75E v6.0`worden gebruikt
• clock_frequency: de snelheid van de LED-kaart. De snelheid is afhankelijk van met name de hoeveelheid modules die gebruikt worden en het type verbinding (ethernet is zwaarder dan SPI). Een goede eerste inschatting is circa 35 MHz. Tijdens het compileren van de firmware kan een waarschuwing worden gegeven dat de 'constraints' niet worden gehaald; in dat geval is het noodzakelijk om een lagere kloksnelheid te kiezen.
• connection: definitie van de verbinding. In dit voorbeeld krijgt de kaart het ip-adres 10.0.0.10 toegewezen.
• modules. Een lijst van modules, hier wordt in een volgende editie verder op ingegaan. In dit geval gebruiken we alleen 1 pin GPIO, waar direct een LED op kan worden aangesloten.

De firmware kan nu gebouwd worden met het volgende commando:

Code: Selecteer alles

litexcnc build_firmware blink.json --build

Flashen firmware
Na het bouwen van de firmware is de gecompileerde firmware the vinden in de map /blink/gateware (relatief gezien vanaf de plaats waar de configuratie staat). Om de firmware te gebruiken we de GPIO van de Raspberry Pi. De volgende links moeten worden gelegd, dit kan met jumper wires:

• GPIO header pin 36 -> J27 (TCK)
• GPIO header pin 31 -> J31 (TMS)
• GPIO header pin 35 -> J32 (TDI)
• GPIO header pin 37 -> J30 (TDO)
• GPIO GND naar GND van de LED kaart

Bovenstaande indeling is gelijk aan de verbindingen op de HU75HAT!

Wanneer de verbinding is gelegd kan de firmware worden geflasht met het volgende commando:

Code: Selecteer alles

litexcnc flash_firmware /blink/gateware/colorlight.svf

De volgende output zal worden gegenereerd wanneer het flashen goed gaat:

Code: Selecteer alles

Open On-Chip Debugger 0.12.0+dev-00290-g2e60e2eca (2023-08-21-22:34)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
SysfsGPIO nums: swclk = 11, swdio = 25
jtag
Info : SysfsGPIO JTAG/SWD bitbang driver
Info : JTAG tap: ecp5.tap tap/device found: 0x41111043 (mfg: 0x021 (Lattice Semi.), part: 0x1111, ver: 0x4)
Warn : gdb services need one or more targets defined
svf processing file: "/home/emco5/git/emco5/firmware/emco5_spi/gateware/colorlight.svf"
95%

Ethernet instellingen
We maken gebruiken een ethernet verbinding met een vast IP-adres (10.0.0.10). Dit betekent dat de ethernet-poort hiervoor geconfigureerd moet worden. Vervang eventuele bestaande configuratie in /etc/dhcp.conf door om een statisch IP-adres te krijgen (voorbeeld specifiek voor een Raspberry Pi):

Code: Selecteer alles

interface eth0
nogateway
static ip_address=10.0.0.1/24
static routers=10.0.0.1
static domain_name_servers=10.0.0.1

Afhankelijk van de PC en de ethernet poort die wordt gebruikt, kan het noodzakelijk zijn om een andere interface te selecteren.

LED aansturen met halrun
Met halrun kunnen HAL-commando's worden uitgetest en kan worden opgestart met:

Code: Selecteer alles

halrun

In de terminal die vervolgens verschijnt kunnen vervolgens commando's worden ingegeven. Om de LED aan te sturen, maken we eerst verbinding met de LED-kaart en zorgen dat deze in het proces van de HAL komt te hangen. Hierbij is het van belang dat de status LED-kaart eerst wordt gelezen, daarna kan de HAL met deze informatie de nieuwe gewenste staat berekenen, waarna deze wordt weggeschreven naar de LED-kaart.

Code: Selecteer alles

loadrt litexcnc connections="eth:10.0.0.10"
loadrt threads name1=test-thread period1=1000000

# Add litexcnc to the thread
addf blink.read test-thread
addf blink.write test-thread

start

Vervolgens kan de LED worden aangezet met het volgende commando:

Code: Selecteer alles

setp blink.gpio.00.out 1

En weer worden uitgezet met:

Code: Selecteer alles

setp blink.gpio.00.out 0

Type exit om halrun weer te verlaten.

LED laten knipperen
In bovenstaand voorbeeld stuurden we de LED handmatig aan. We kunnen ook een signaal generator gebruiken om de LED te laten knipperen

Code: Selecteer alles

loadrt litexcnc connections="eth:10.0.0.10"
loadrt siggen
loadrt threads name1=test-thread period1=1000000

# Add litexcnc to the thread
addf blink.read test-thread
addf siggen.0.update test-thread
addf blink.write test-thread

# Verbind de uitvoer van de siggen aan de LED
net blink siggen.0.clock => blink.gpio.00.out

start

Meer informatie over het aanpassen van de signaal generator is beschikbaar in de LinuxCNC documentatie.

[André-R]

Was een leuke en interessante voordracht!

Inderdaad !!

[jand]

Leuk dat je hier een tutorial plaatst. Ik ga het lekker op mijn gemak uitproberen. Als eerste maar met een vers geïnstalleerde pi beginnen. Het modificeren en bestukken van de print komt t.z.t wel.

[jand]

Het image voor de pi die je opgeeft is bullseye (11) en de rest van de tutorial gaat over buster (10). Dit geeft een hele rits 'unmet dependencies'.
Is "LinuxCNC 2.9.1 Raspberry Pi OS based on Debian 12 Bookworm" niet een betere keuze? (https://www.linuxcnc.org/iso/linuxcnc-2 ... pi4.img.xz)

Is litexcnc compatible met LinuxCNC 2.9? Of moet ik op zoek naar een raspbian 10 (Buster) image?

[Tolp2]

Het image voor de pi die je opgeeft is bullseye (11) en de rest van de tutorial gaat over buster (10). Dit geeft een hele rits 'unmet dependencies'.
Is "LinuxCNC 2.9.1 Raspberry Pi OS based on Debian 12 Bookworm" niet een betere keuze? (https://www.linuxcnc.org/iso/linuxcnc-2 ... pi4.img.xz)

Is litexcnc compatible met LinuxCNC 2.9? Of moet ik op zoek naar een raspbian 10 (Buster) image?

In principe heb je voor LinuxCNC 2.8.4 een image nodig van Buster. Er zijn ook mensen die het op Bookworm hebben draaien met LinuxCNC 2.9, maar proces is moeilijker. Als je hier een recept voor hebt: wees welkom om deze hier te delen!

Ik zal de links nalopen in deze thread nalopen zodat deze naar Buster verwijzen. Edit: wijziging heb ik doorgevoerd.

Buster of Bookworm, dat maak niet uit: LitexCNC ondersteund beide!

[jand]

Er mist wat in de sed regel om de cmdline.txt file aan te passen. Op deze manier wordt de file wel aangepast:

Code: Selecteer alles

sudo sed -i -e '$s/$/ isolcpus=1,2,3 idle=poll/' /boot/$KERN/cmdline.txt

[Tolp2]

Er mist wat in de sed regel om de cmdline.txt file aan te passen. Op deze manier wordt de file wel aangepast:

Code: Selecteer alles

sudo sed -i -e '$s/$/ isolcpus=1,2,3 idle=poll/' /boot/$KERN/cmdline.txt

Bedankt! Ik heb het aangepast. Het originele 'recept' had de toevoeging in een regel tekst staan. Had deze omgezet met sed, maar niet afdoende getest dus.

[Tolp2]

Ik heb zojuist versie 1.1.0 gepubliceerd. Deze versie geeft ondersteuning voor SPI, wat nodig is voor de HUB75HAT die ik zaterdag heb laten zien. Daarnaast heb ik een aantal commando's aangepast, waarmee het makkelijk wordt. Je kan updaten naar de nieuwste versie met:

Code: Selecteer alles

pip install -U litexcnc

De tutorial hierboven heb ik aangepast naar deze nieuwe versie.

[pep]

Wat leuk! En tof dat je er een tutorial van maakt. Dit ga ik met belangstelling volgen... Eerste vraagje alvast: je hebt het over 8 buffer IC's, maar ik denk dat ik er 12 zie zitten op het plaatje in de oranje vakjes. Moeten die er alle 12 aan geloven? Of kijk ik verkeerd?

[Tolp2]

Wat leuk! En tof dat je er een tutorial van maakt. Dit ga ik met belangstelling volgen... Eerste vraagje alvast: je hebt het over 8 buffer IC's, maar ik denk dat ik er 12 zie zitten op het plaatje in de oranje vakjes. Moeten die er alle 12 aan geloven? Of kijk ik verkeerd?

Het zijn er inderdaad 12 (ondertussen aangepast). Ik zou adviseren om deze allemaal te verwijderen, in ieder geval als je ook gebruik wil maken van de HUB75HAT. Niet alle IC's hoeven overbrugd te worden, maar welke je moet overbruggen hangt helaas af van de versie van de LED-kaart. Als je een versie 8.2 van de 5A-75B hebt, dan kan ik een foto maken met de minimaal benodigde draadbruggen.