doc/guide/install.rst: added note about plugdev/dialout, introduces new 70-openfpgaloader.rules (without GROUP) file

70-openfpgaloader.rules

@@ -0,0 +1,72 @@
+# Copy this file to /etc/udev/rules.d/
+
+ACTION!="add|change", GOTO="openfpgaloader_rules_end"
+
+# gpiochip subsystem
+SUBSYSTEM=="gpio", MODE="0664", TAG+="uaccess"
+
+SUBSYSTEM!="usb|tty|hidraw", GOTO="openfpgaloader_rules_end"
+
+# Original FT232/FT245 VID:PID
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="664", TAG+="uaccess"
+
+# Original FT2232 VID:PID
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="664", TAG+="uaccess"
+
+# Original FT4232 VID:PID
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6011", MODE="664", TAG+="uaccess"
+
+# Original FT232H VID:PID
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6014", MODE="664", TAG+="uaccess"
+
+# Original FT231X VID:PID
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6015", MODE="664", TAG+="uaccess"
+
+# anlogic cable
+ATTRS{idVendor}=="0547", ATTRS{idProduct}=="1002", MODE="664", TAG+="uaccess"
+ATTRS{idVendor}=="336c", ATTRS{idProduct}=="1002", MODE="664", TAG+="uaccess"
+
+# altera usb-blaster
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6001", MODE="664", TAG+="uaccess"
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6002", MODE="664", TAG+="uaccess"
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6003", MODE="664", TAG+="uaccess"
+
+# altera usb-blasterII - uninitialized
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6810", MODE="664", TAG+="uaccess"
+# altera usb-blasterII - initialized
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6010", MODE="664", TAG+="uaccess"
+
+# altera usb-blasterIII
+ATTRS{idVendor}=="09fb", ATTRS{idProduct}=="6022", MODE="664", TAG+="uaccess"
+
+# dirtyJTAG
+ATTRS{idVendor}=="1209", ATTRS{idProduct}=="c0ca", MODE="664", TAG+="uaccess"
+
+# Jlink
+ATTRS{idVendor}=="1366", ATTRS{idProduct}=="0105", MODE="664", TAG+="uaccess"
+
+# NXP LPC-Link2
+ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="0090", MODE="664", TAG+="uaccess"
+
+# NXP ARM mbed
+ATTRS{idVendor}=="0d28", ATTRS{idProduct}=="0204", MODE="664", TAG+="uaccess"
+
+# icebreaker bitsy
+ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="6146", MODE="664", TAG+="uaccess"
+
+# Radiona ULX3S/ULX4M (DFU)
+ATTRS{idVendor}=="1d50", ATTRS{idProduct}=="614b", MODE="664", TAG+="uaccess"
+
+# numato systems
+ATTRS{idVendor}=="2a19", ATTRS{idProduct}=="1009", MODE="644", TAG+="uaccess"
+
+# orbtrace-mini dfu
+ATTRS{idVendor}=="1209", ATTRS{idProduct}=="3442", MODE="664", TAG+="uaccess"
+
+# QinHeng Electronics USB To UART+JTAG (ch347)
+ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="55dd", MODE="664", TAG+="uaccess"
+
+# ESP32-S3 (usb-jtag bridge)
+ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", MODE="664", TAG+="uaccess"
+
+LABEL="openfpgaloader_rules_end"

doc/guide/install.rst

@@ -149,25 +149,49 @@ Udev rules
 ----------
 
 By default, users have no access to converters.
-A rule file (:ghsrc:`99-openfpgaloader.rules <99-openfpgaloader.rules>`) for ``udev`` is provided at the root directory
-of this repository.
-These rules set access right and group (``plugdev``) when a converter is plugged.
+Two rule files are provided at the root directory of this repository:
+
+- :ghsrc:`99-openfpgaloader.rules <99-openfpgaloader.rules>` sets the group with ``GROUP="plugdev"``.
+- :ghsrc:`70-openfpgaloader.rules <70-openfpgaloader.rules>` does not set ``GROUP="plugdev"``.
+
+First, check if ``plugdev`` exists:
 
 .. code-block:: bash
 
+    grep -w plugdev /etc/group
+
+Option 1 (recommended): create system group ``plugdev`` (if required) and use ``99-openfpgaloader.rules``:
+
+.. code-block:: bash
+
+    sudo groupadd --system plugdev # only required if plugdev is absent
     sudo cp 99-openfpgaloader.rules /etc/udev/rules.d/
     sudo udevadm control --reload-rules && sudo udevadm trigger # force udev to take new rule
     sudo usermod -a $USER -G plugdev # add user to plugdev group
 
+Option 2: if ``plugdev`` does not exist (or you do not want to create it), use
+``70-openfpgaloader.rules`` and ensure your user is in ``dialout``:
+
+.. code-block:: bash
+
+    sudo cp 70-openfpgaloader.rules /etc/udev/rules.d/
+    sudo udevadm control --reload-rules && sudo udevadm trigger # force udev to take new rule
+    sudo usermod -a $USER -G dialout # add user to dialout group
+
 After that you need to unplug and replug your device.
 
 .. HINT::
-   ``usermod`` is used to add ``$USER`` as a member of ``plugdev`` group.
-   However this update is not taken into account immediately: it's required to
-   logout from current session and login again.
-   Check, by using ``id $USER``, if ``plugdev`` is mentioned after ``groups=``.
-   An alternate (and temporary) solution is to use ``sudo - $USER`` to have
-   your user seen as a member of ``plugdev`` group (works only for the current terminal).
+   ``usermod`` is used to add ``$USER`` as a member of ``plugdev``, or
+   ``dialout`` group. However this update is not taken into account immediately:
+   it's required to logout from current session and login again.
+   Check, by using ``id $USER``, if ``plugdev``, ord ``dialout`` is mentioned after
+   ``groups=``. An alternate (and temporary) solution is to use ``sudo - $USER``
+   to have your user seen as a member of the expected group (works only for the
+   current terminal).
+
+   If the converter still cannot be opened, check access rights on the device
+   node (for example ``ls -l /dev/ttyUSB* /dev/ttyACM*``) and verify
+   the associated group (``plugdev`` or ``dialout``).
 
 macOS
 =====