diff --git a/docs/requirements/drivers.rst b/docs/requirements/drivers.rst index 5c16473..d82b6c0 100644 --- a/docs/requirements/drivers.rst +++ b/docs/requirements/drivers.rst @@ -3,32 +3,26 @@ Required Drivers ================ -On most systems the Fomu board does **not** need any special drivers. +On most systems (such as Windows 10 or newer, or MacOS X), the Fomu board does **not** need any special drivers. -* On Windows 10 or newer you do not need to install anything. -* On Windows systems **earlier** than Windows 10 you will need to - :ref:`windows-zadig`. -* On MacOS X you do not need to install any drivers. -* On Linux you do not need to install any drivers, **however** you may need - ``sudo`` access unless you :ref:`linux-udev` to grant permission to use the +* On GNU/Linux, you do not need to install any drivers, **however**, you may need + ``sudo`` access unless you :ref:`linux-udev` to grant permission for using the USB device from a non-privileged account. - +* Windows systems **earlier** than Windows 10: you will need to + :ref:`install Zadig drivers `. .. _linux-udev: Setup udev rules ---------------- -.. warning:: +.. WARNING:: + This set up is for GNU/Linux **only**. Setting up these udev rules grants + permissions for using the USB device from a non-privileged account. - This set up is for Linux **only**. - - Setting up these udev rules grant permissions to use the USB device from a - non-privileged account. - -In Linux, try running ``dfu-util -l``, and if you get an error message like the -following you should add a ``udev`` rule as to give your user permission to the -usb device. +On GNU/Linux, try running ``dfu-util -l``. If you get an error message like the +following, you should add a ``udev`` rule as to give your user permission to the +USB device. .. session:: shell-session :emphasize-lines: 9 @@ -45,43 +39,37 @@ usb device. $ Steps to set up udev rule -------------------------- +######################### -#. Add your user to the plugdev group +#. Add your user to group ``plugdev``: .. session:: shell-session $ sudo groupadd plugdev $ sudo usermod -a -G plugdev $USER -#. Check you are in the ``plugdev`` group with ``id $USER`` + .. WARNING:: + You **must** log out and then log in again for the addition to group ``plugdev`` to take affect. + +#. Use ``id $USER`` and/or ``groups`` to check you are in group ``plugdev``: .. session:: shell-session $ id $USER uid=1000(tim) gid=1000(tim) groups=500(plugdev),997(admin) - $ - -#. You **will** need to log out and log in again in order to be a member of the ``plugdev`` group. - - .. warning:: - - You **must** log out and then log in again for the group addition to take affect. - -#. Check you are in the ``plugdev`` group with ``groups`` - - .. session:: shell-session $ groups | grep plugdev tim plugdev admin - $ -#. Create a file named ``/etc/udev/rules.d/99-fomu.rules`` and add the following: +#. Create a file named ``/etc/udev/rules.d/99-fomu.rules`` and add the following. .. code:: udev SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="5bf0", MODE="0664", GROUP="plugdev" + .. NOTE:: + You need ``sudo`` privileges for creating this file. + #. Reload the udev-rules using the following: .. session:: shell-session @@ -101,9 +89,12 @@ Installing Zadig Drivers #. Download `Zadig `__. #. Open Zadig. -#. Under Options, select "List All Devices". -#. In the dropdown, select your Fomu and in the field right of the green arrow - choose the `WinUSB` driver and hit Upgrade Driver. +#. Under ``Options``, select ``List All Devices``. +#. In the dropdown, select your Fomu; in the field right of the green arrow, + choose the ``WinUSB`` driver; and hit ``Upgrade Driver``. - .. image:: ../_static/Zadig-Setup.png - :alt: Setup of Zadig for Updating USBport driver on WIN7 \ No newline at end of file + .. figure:: ../_static/Zadig-Setup.png + :align: center + :alt: Setup of Zadig for updating USB port driver on Windows earlier than 10 + + Setup of Zadig for updating USB port driver on Windows earlier than 10. diff --git a/docs/requirements/files.rst b/docs/requirements/files.rst index 03cac63..8a283c5 100644 --- a/docs/requirements/files.rst +++ b/docs/requirements/files.rst @@ -3,16 +3,15 @@ Required Files -------------- -.. note:: - +.. NOTE:: If you’re attending a workshop that provides USB drives, these files may be available on the USB drive under the ``Workshop`` directory. You will need the Workshop files. They are located in the -`fomu-workshop `__ Github -repository. You can download -`master.zip `__ -or clone it from git: +`fomu-workshop `_ Github +repository. You can clone it with git, or download +`master.zip `_ | +`master.tar.gz `_. .. session:: shell-session diff --git a/docs/requirements/hardware.rst b/docs/requirements/hardware.rst index 52a7d66..f69d310 100644 --- a/docs/requirements/hardware.rst +++ b/docs/requirements/hardware.rst @@ -3,54 +3,54 @@ Required Hardware ################# -For this workshop, you will need a Fomu board. +- For this workshop, you will need a `Fomu board `_. +- Aside from that, you need a computer with a USB port that can run the :ref:`required-software`. -Aside from that, you need a computer with a USB port that can run the -:ref:`required-software`. +.. NOTE:: + You should not need any special drivers, though on Linux you may need ``sudo`` + access, or special ``udev`` rules for granting permission to use the USB device from a + non-privileged account. -You should not need any special drivers, though on Linux you may need sudo -access, or special udev rules to grant permission to use the USB device from a -non-privileged account. - -This workshop may be competed with any model of Fomu, though there are some -parts that require you to identify which model you have. See the -:ref:`which-fomu` section. +.. ATTENTION:: + This workshop may be competed with any model of Fomu, though there are some + parts that require you to identify which model you have. See the + :ref:`which-fomu` below. .. _which-fomu: Which Fomu do I have? ===================== -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| | Hacker | Production | -+===================+=========================================================================+===================================================================+ -| **String** | hacker | pvt | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Bash Command** | ``export FOMU_REV=hacker`` | ``export FOMU_REV=pvt`` | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Front** | |Hacker Hardware Front without case| | |Production Hardware Front without case| | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Back** | |Hacker Hardware Back without case| | |Production Hardware Back without case| | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **In Case** | |Hacker Hardware Back with case| | |Production Hardware Back with case| | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Parts** | |Hacker Hardware Annotated Diagram| | |Production Hardware Annotated Diagram| | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Color** | |Dark Blue| | |Cyan Light Blue| | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Bootloader** | Fomu **Hacker** running DFU Bootloader vX.X.X | Fomu **PVT** running DFU Bootloader vX.X.X | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Description** | These are the original design and cut corners to make it easier to | If you ordered a Fomu from Crowd Supply, this is the model you'll | -| | manufacture. If you received one directly from Tim before 36C3, you | receive. It is small, and fits in a USB port. There is no | -| | probably have one of these. Hacker boards have white silkscreen on | silkscreen on it. This model of Fomu has a large silver crystal | -| | the back. | oscillator that is the tallest component on the board. | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Schematic** | `schematic-hacker.pdf <_static/reference/schematic-hacker.pdf>`__ | `schematic-pvt.pdf <_static/reference/schematic-pvt.pdf>`__ | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Received at** | From Tim at 35C3, CCCamp19, HackADay Supercon 2019 | At RISC-V Summit 2019, 36C3, Crowdsupply, Mouser | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ -| **Buy more** | End of Life | `CrowdSupply `__, | -+-------------------+-------------------------------------------------------------------------+-------------------------------------------------------------------+ ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| | Hacker | Production | ++==================+=====================================================================+===================================================================+ +| **String** | hacker | pvt | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Bash Command** | ``export FOMU_REV=hacker`` | ``export FOMU_REV=pvt`` | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Front** | |Hacker Hardware Front without case| | |Production Hardware Front without case| | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Back** | |Hacker Hardware Back without case| | |Production Hardware Back without case| | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **In Case** | |Hacker Hardware Back with case| | |Production Hardware Back with case| | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Parts** | |Hacker Hardware Annotated Diagram| | |Production Hardware Annotated Diagram| | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Color** | |Dark Blue| | |Cyan Light Blue| | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Bootloader** | Fomu **Hacker** running DFU Bootloader vX.X.X | Fomu **PVT** running DFU Bootloader vX.X.X | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Description** | These are the original design and cut corners to make it easier to | If you ordered a Fomu from Crowd Supply, this is the model you'll | +| | manufacture. If you received one directly from Tim before 36C3, you | receive. It is small, and fits in a USB port. There is no | +| | probably have one of these. Hacker boards have white silkscreen on | silkscreen on it. This model of Fomu has a large silver crystal | +| | the back. | oscillator that is the tallest component on the board. | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Schematic** | `schematic-hacker.pdf <_static/reference/schematic-hacker.pdf>`__ | `schematic-pvt.pdf <_static/reference/schematic-pvt.pdf>`__ | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Received at** | From Tim at 35C3, CCCamp19, HackADay Supercon 2019 | At RISC-V Summit 2019, 36C3, Crowdsupply, Mouser | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ +| **Buy more** | End of Life | `CrowdSupply `__, | ++------------------+---------------------------------------------------------------------+-------------------------------------------------------------------+ .. |Dark Blue| raw:: html @@ -76,4 +76,4 @@ Which Fomu do I have? the Fomu crowd funding campaign. This model of Fomu is about the size of a credit card. It should have the text “Fomu EVT3” written across it in white silkscreen. If you have a different EVT board such as - EVT2 or EVT1, they should work also. + EVT2 or EVT1, they should also work. diff --git a/docs/requirements/index.rst b/docs/requirements/index.rst index d045883..fdf21cf 100644 --- a/docs/requirements/index.rst +++ b/docs/requirements/index.rst @@ -3,21 +3,18 @@ Requirements ############ -For this workshop you will need; +.. NOTE:: + If you are at a workshop, please **install the tools first** and then get + the hardware from your presenter. -#. The Fomu workshop files - see :ref:`required-files` section. -#. The Fomu toolchain - see :ref:`required-software` section. -#. A Fomu board - see :ref:`required-hardware` section. -#. Set up drivers - see :ref:`required-drivers` section. +For this workshop you will need: -.. note:: - - If you are at a workshop, please **install the tools first** and then get - the hardware from your presenter. - - -.. warning:: +- :ref:`The Fomu workshop files ` +- :ref:`The Fomu toolchain ` +- :ref:`A Fomu board ` +- :ref:`Set up drivers ` +.. WARNING:: Your Fomu should be running Foboot |Foboot Version| or newer. You can see what version you are running by typing ``dfu-util -l`` like so; @@ -36,7 +33,7 @@ For this workshop you will need; Found DFU: [1209:5bf0] ver=0101, devnum=19, cfg=1, intf=0, path="1-2", alt=0, name="Fomu PVT running DFU Bootloader v2.0.3", serial="UNKNOWN" $ - If your Fomu is running an version older than |Foboot Version| follow the + If your Fomu is running an version older than |Foboot Version|, follow the :ref:`bootloader-update` section. .. toctree:: diff --git a/docs/requirements/software.rst b/docs/requirements/software.rst index 1060d77..51b1924 100644 --- a/docs/requirements/software.rst +++ b/docs/requirements/software.rst @@ -3,8 +3,7 @@ Required Software ################# -.. note:: - +.. NOTE:: If you’re taking this workshop as a class, the toolchains are provided on the USB disk. @@ -13,7 +12,7 @@ and Windows, via `Fomu Toolchain `__. To install the software, extract it somewhere on your computer, then -open up a terminal window and add that directory to your PATH: +open up a terminal window and add that directory to your ``PATH``: .. tabs:: @@ -37,9 +36,9 @@ open up a terminal window and add that directory to your PATH: C:\> PATH=[path-to-toolchain]\bin;%PATH% -Examples in :ref:`HDLs:VHDL` and :ref:`HDLs:mixed` use ghdl-yosys-plugin, which -looks for standard libraries in the path used when GHDL was configured/built. -Therefore, when the toolchain is extracted to an arbitrary location, `GHDL_PREFIX` +Examples in :ref:`HDLs:VHDL` and :ref:`HDLs:mixed` use `ghdl-yosys-plugin `_, +which looks for standard libraries in the path used when GHDL was configured/built. +Therefore, when the toolchain is extracted to an arbitrary location, ``GHDL_PREFIX`` needs to be set: .. tabs:: @@ -98,7 +97,6 @@ the following output; Type ``exit`` to quit ``yosys``. -.. note:: - +.. NOTE:: See the README of `Fomu Toolchain `_ for a complete list of the tools included in the toolchain.