Installation Documentation Update for Debian 12 & Python 3.11 with venv.

[GTCLive]

Hi Peter. I like your project quite a lot and getting ready to get familiar and give it a try. Hopefully this can retire my 4 years old LPT card and so I've put a 5A-75E V.8.0 (like yours?), a FT232H programmer and a dozen SN74LVC245A buffers on order.

Challenge I'm facing now is installing LiteX-CNC's dependencies/toolchain ect. Debian 12 and Python 3.11 (pip3) forces a virtual environment and this creates a whole lot of impediments at the permission & user levels. Practically impossible to install anything without failures. e.g. Driver perms fails (sudo does not work), LiteX throws an error (--user does not work), to name a few.

Can I recommend for this to be investigated at your end (I'm nowhere a linux expert!) and documentation updated to support this environment?

Let me know if you need any trace logs etc. Happy to help despite my limited abilities and knowledge.

Thanks. Alex.

[Peter-van-Tol]

Great to hear that you are willing to try Litex-CNC. The setup I currently work with is indeed the 5A-75E, but for my Raspberry Pi based setup I'm switching to the 5A-75B in combination with a hat and running on SPI.

Issues installing driver
Concerning the driver: does sudo not work at all on your setup, or does install_driver throw errors at you when using sudo?

Most likely you require privileges to modify the contents of your LinuxCNC installation, so sudo is required. When running sudo however, you also get all environment settings of that super user, which breaks things. You can solve this with the following command:

sudo -E env PATH=$PATH litexcnc install_driver

This is an issue with the documentation. I can see this command is in the repo, however it is not listed (yet) at the documentation.

Could you let me know whether this resolves your issue concerning the driver?

Issue concerning installing Litex
The --user-tag is not working at this moment, see also #47. This has been resolved, but that version is not officially released yet on PyPi. I will make a release this evening, so you can test whether this resolves your problem.

[Peter-van-Tol]

'too name a few' suggests you experience more issues, can you also list your other issues here ?

[GTCLive]

Hi Peter. Too cool, thanks so much for the tweaked sudo tip, this worked and installed the driver flawlessly!

Among other installation failures are $ litexcnc install_litex and $ litexcnc install_toolchain. Below are my install steps on a stock Debian 12 with Python 3.11. Pretty sure this will all makes sense to you once you've seen the attached screengrabs. Let me know if you need me to test anything at my end, all up for making this work for 'novice gurus'.

---

$ sudo apt install python3-pip python3.11-venv
$ python3 -m venv /home/cnc/LiteX-CNC
$ source /home/cnc/LiteX-CNC/bin/activate
$ cd /home/cnc/LiteX-CNC

$ pip install litexcnc[cli]
$ sudo -E env PATH=$PATH litexcnc install_driver

$ litexcnc install_litex (comment about "Issue concerning installing Litex" noted though, I'll try again tomorrow)

$ litexcnc install_toolchain

[Peter-van-Tol]

For install_toolchain there are options too!

litexcnc install_toolchain --help 

gives

Usage: litexcnc install_toolchain [OPTIONS]

  Installs the Toolchain for ECP5 (oss-cad-suite)

Options:
  --user
  -a, --architecture [arm|arm64|x64]
  -os, --os [darwin|linux|windows]
  --help                          Show this message and exit.

For your system the correct command for installing the toolchain will be:

• for a desktop: litexcnc install_toolchain --user --architecture x64 --os linux
• for a Raspberry Pi on Debian 12 (Bookworm): litexcnc install_toolchain --user --architecture arm64 --os linux
• for a Raspberry Pi on Debian 10 (Buster): litexcnc install_toolchain --user --architecture arm --os linux

With the upcoming release (working on it), you don't necessarily have to provide --architecture and --os, as this is derived from the system itself.

NOTE
You might have to restart your system to put the toolchain on path correctly.

[Peter-van-Tol]

Version 1.0.3 has been released. You can install it with:

pip3 install -U litexcnc[cli]

Let me know whether it works, then I will close this issue. For more support on drafting your configuration for the card, you can always ask in the discussions.

[GTCLive]

Hi Peter. Sweet, the toolchain installs with the given options, thanks for highlighting this for us. However the LiteX dependency still fails with the following errors:

$ litexcnc install_litex
PermissionError: [Errno 13] Permission denied: '/opt/litex'

$ litexcnc install_litex --user
ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

The workaround is to install it manually, for now, however I have no idea if this is the way you anticipated it and/or want to document it:

$ mkdir LiteX
$ cd LiteX
$ wget https://raw.githubusercontent.com/enjoy-digital/litex/master/litex_setup.py
$ python3 litex_setup.py --init --install
$ cd ..

[GTCLive]

Regardless of what appears as a successful dependencies install, it is still impossible to build a bin file. See steps and error below:

$ git clone https://github.com/Peter-van-Tol/LiteX-CNC.git
$ cd LiteX-CNC
$ litexcnc build_firmware examples/5a-75e.json --build

raise ValueError("Field board_type is requierd.")
ValueError: Field board_type is requierd.

Note: I've edited the examples/5a-75e.json and added at the top: "board_type": "5A-75E v7.1",
and now this error shows up:

for index in range(len(kwargs['modules'])):
~~~~~~^^^^^^^^^^^
KeyError: 'modules'

And so I'm completely lost. Certainly not working at my end obviously because my abilities as a user and knowledge doesn't help me too much. I'll see if I can find time to browse through those 60'ish pages of the linuxcnc forum and see if I can find hints as to what's going on. In a meantime if you know what's happening I'd love to hear what I'm doing wrong.

I appreciate the help and support so far. Too kind already.

[GTCLive]

Quick update:

Peter, I've managed to build a *.json example taken from member "deroj" on the forum.
https://forum.linuxcnc.org/27-driver-boards/44422-colorcnc-colorlight-5a-75e-5a-75b-as-fpga-controller-board?start=610#281360

And that's good news! However not so much for new 'users' (aka non-linux experts like myself). As a suggestion, I certainly see additional details to be put into the documentation "installation" section. And of course updating the /examples/ with some that works to prevent any confusions as to why nothing works.

Apart from that, I am super excited about your project! One of the coolest out there I had the chance to take on, and so I'd like to pass my gratitude for what you've done for us. Top notch!! I look forward getting these buffers desoldered and in/out signals scoped (not really haha). All good fun nonetheless, thank you Peter.

[Peter-van-Tol]

The examples in the repo are not up-to-date, however those in the documentation are. I will remove the examples from the repo (except one or two) and make sure they work. For a full list of configurations, see the examples section.

For the install_litex error: you've found a nice caveat. The problem is that the files have to be cloned in your user folder, but you cannot install it with the --user option from pip. Will resolve it by adding another option --venv, which will do your manual steps. Also, I will add documentation on how to install manually.

[Peter-van-Tol]

The examples have been resolved.

For the install_litex I don't think we need an extra option; the option has been there the whole time. In your case the command would have been:

litexcnc install_litex --directory ~

Which installs it in your HOME-directory, thus circumventing any permissions. And it installs it without the --user as required for venv. I do agree, the documentation has to be better.

[Peter-van-Tol]

I've improved the documentation. Could you check whether you would have found the information you needed to install the driver, Litex, and toolchain when looking at the latest documentation?

[GTCLive]

Hi Peter, don't know what to say... a simple thank you ain't enough to express how grateful I am for your support, let alone this cool project you've impressively facilitate for the community. The Documentation was already beyond amazing, just needed a 'linux illiterates' tweak, which you've kindly done I've seen! Cheers man 👍😎

Below are my notes for an ootb Debian 12 & Python 3.11 having Linuxcnc 2.9. Following those lines will get you a bit file in less than 10min zero complaints/perms/fuss/sweat.

$ sudo apt install python3-pip python3.11-venv
$ python3 -m venv /home/cnc/LiteX-CNC
$ source /home/cnc/LiteX-CNC/bin/activate
$ cd /home/cnc/LiteX-CNC

$ pip3 install -U litexcnc[cli]
$ litexcnc install_litex --directory ~
$ litexcnc install_toolchain --user --architecture x64 --os linux
$ sudo -E env PATH=$PATH litexcnc install_driver

# To force OSS-Cad-Suite PATH, a reboot is required:
$ sudo reboot

$ source /home/cnc/LiteX-CNC/bin/activate
$ cd /home/cnc/LiteX-CNC
$ git clone https://github.com/Peter-van-Tol/LiteX-CNC.git
$ cd LiteX-CNC

# Change board_type in 5a-75e_simple.json from "5A-75E v8.0" -to- "5A-75E v6.0"
$ sudo nano examples/5a-75e_simple.json

# Test build:
$ litexcnc build_firmware examples/5a-75e_simple.json --build

# Ping Test 192.168.0.50. Download bit file with openFPGAloader:
$ sudo ~/oss-cad-suite/bin/openFPGALoader --unprotect-flash -c ft232 -f examples/5a-75e_simple/gateware/colorlight_5a_75e.bit

Success!

[Peter-van-Tol]

Cool! I will add this as a tutorial!

[GTCLive]

(ColorLight) cnc@debian-i7:~/ColorLight/LiteX-CNC$ halrun
halcmd: loadrt litexcnc connections="eth:192.168.10.101"
Note: Using POSIX realtime
litexcnc: Loading Litex CNC driver version 1.1.0
litexcnc: Loading and registering default modules:
litexcnc: Registered module gpio
litexcnc: Registered module pwm
litexcnc: Registered module encoder
litexcnc: Registered module step
litexcnc: Setting up board drivers:
litexcnc: Registered driver eth
LitexCNC-eth: connected to board on '192.168.10.101:1234'
litexcnc: Setting up modules...
litexcnc: Reading 8 bytes
litexcnc: - Watchdog
litexcnc: - Wallclock
litexcnc: - gpio ... done!
litexcnc: Creating read and write buffers...
litexcnc: Base addresses: init: 00000000, reset: 00000028, config: 0000002C, write: 0000002C, read: 00000034
litexcnc: - Write buffer: 8 bytes
litexcnc: - Read buffer: 16 bytes
litexcnc: Exporting functions...
halcmd: exit
litexcnc: LitexCNC driver unloaded
Note: Using POSIX realtime

F'ing EPIC!! Let's play this. Thanks, Peter. Happy for you to close this. I'll catch you in the Discussion Section or forum when I'll struggle (lol) to get the hal & ini sorted. Aiming for a closed loop (3 glass scales + 2 ABZ encoders) for a 4-axis mill.