Deploying to gh-pages from @ 6362f90 🚀

GlasgowEmbedded · Oct 2, 2023 · 4cd696d · 4cd696d
commit 4cd696d
Show file tree

Hide file tree

Showing 93 changed files with 10,495 additions and 0 deletions.
diff --git a/.nojekyll b/.nojekyll
diff --git a/CNAME b/CNAME
@@ -0,0 +1 @@
+glasgow-embedded.org
diff --git a/index.html b/index.html
@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <meta charset="utf-8">
+  <title>Redirecting&hellip;</title>
+  <link rel="canonical" href="latest/">
+  <script>location="latest/"</script>
+  <meta http-equiv="refresh" content="0; url=latest/">
+  <meta name="robots" content="noindex">
+  <h1>Redirecting&hellip;</h1>
+  <a href="latest/">Click here if you are not redirected.</a>
+</html>
diff --git a/latest/.buildinfo b/latest/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: c101cf2d1e85d996ce1a78c8701bbc9a
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/latest/.doctrees/community.doctree b/latest/.doctrees/community.doctree
diff --git a/latest/.doctrees/contribute.doctree b/latest/.doctrees/contribute.doctree
diff --git a/latest/.doctrees/develop/applet.doctree b/latest/.doctrees/develop/applet.doctree
diff --git a/latest/.doctrees/develop/docs.doctree b/latest/.doctrees/develop/docs.doctree
diff --git a/latest/.doctrees/develop/firmware.doctree b/latest/.doctrees/develop/firmware.doctree
diff --git a/latest/.doctrees/develop/hardware.doctree b/latest/.doctrees/develop/hardware.doctree
diff --git a/latest/.doctrees/develop/index.doctree b/latest/.doctrees/develop/index.doctree
diff --git a/latest/.doctrees/develop/software.doctree b/latest/.doctrees/develop/software.doctree
diff --git a/latest/.doctrees/environment.pickle b/latest/.doctrees/environment.pickle
diff --git a/latest/.doctrees/factory.doctree b/latest/.doctrees/factory.doctree
diff --git a/latest/.doctrees/index.doctree b/latest/.doctrees/index.doctree
diff --git a/latest/.doctrees/install.doctree b/latest/.doctrees/install.doctree
diff --git a/latest/.doctrees/intro.doctree b/latest/.doctrees/intro.doctree
diff --git a/latest/.doctrees/license.doctree b/latest/.doctrees/license.doctree
diff --git a/latest/.doctrees/purchase.doctree b/latest/.doctrees/purchase.doctree
diff --git a/latest/.doctrees/revisions.doctree b/latest/.doctrees/revisions.doctree
diff --git a/latest/.doctrees/use/basic.doctree b/latest/.doctrees/use/basic.doctree
diff --git a/latest/.doctrees/use/index.doctree b/latest/.doctrees/use/index.doctree
diff --git a/latest/.doctrees/use/repl-script.doctree b/latest/.doctrees/use/repl-script.doctree
diff --git a/latest/_images/3drender-revC2.png b/latest/_images/3drender-revC2.png
diff --git a/latest/_images/glasgow-in-case.webp b/latest/_images/glasgow-in-case.webp
diff --git a/latest/_images/glasgow-pcba.webp b/latest/_images/glasgow-pcba.webp
diff --git a/latest/_sources/community.rst.txt b/latest/_sources/community.rst.txt
@@ -0,0 +1,33 @@
+.. _community:
+
+Community
+=========
+
+Glasgow Interface Explorer is a community-driven project that coordinates via `GitHub issues <issues_>`__ and real-time chat channels on multiple platforms:
+
+* IRC channel `#glasgow at irc.libera.chat <irc_>`__ with `logs available <irclogs_>`__.
+* Matrix channel `#glasgow-interface-explorer:matrix.org <matrix_>`__.
+* Discord channel `#glasgow at 1BitSquared's Discord server <discord_>`__.
+
+All of our chat channels are bridged together; regardless of which one you choose, your messages reach everyone on all of the platforms. Note that what you say will be logged in a public archive indexed by search engines.
+
+.. _issues: https://github.com/GlasgowEmbedded/glasgow/issues
+.. _irc: https://web.libera.chat/#glasgow
+.. _irclogs: https://libera.irclog.whitequark.org/glasgow
+.. _matrix: https://matrix.to/#/#glasgow-interface-explorer:matrix.org
+.. _discord: https://1bitsquared.com/pages/chat
+
+
+Acknowledgements
+----------------
+
+The Glasgow project has been built by its many `contributors <https://github.com/GlasgowEmbedded/Glasgow/graphs/contributors>`_, including some without whom the project would not have been possible:
+
+* `@whitequark <https://github.com/whitequark>`_ originated the overall design, coordinates the project and implements most of gateware and software
+* `@awygle <https://github.com/awygle>`_ designed the power/analog port circuitry and helped with layout of revB
+* `@marcan <https://github.com/marcan>`_ improved almost every aspect of hardware for revC
+* `@esden <https://github.com/esden>`_ is handling batch manufacturing
+* `@smunaut <https://github.com/smunaut>`_ provided advice crucial for stability and performance of USB communication
+* `@electroniceel <https://github.com/electroniceel>`_ improved the hardware for revC2, designed the test jig and is working on advanced protection circuitry
+* `@Attie <https://github.com/attie>`_ improved and refactored many applets, hardware photos
+* `@mwkmwkmwk <https://github.com/mwkmwkmwk>`_ does important maintenance work to keep the codebase in good shape
diff --git a/latest/_sources/contribute.rst.txt b/latest/_sources/contribute.rst.txt
@@ -0,0 +1,90 @@
+Contributing
+============
+
+The Glasgow project relies on many community members to contribute to the extensive scope covered by its hardware and software. The project has a strong commitment to stability: most importantly, every unit of hardware for which design files have been published in the ``main`` branch will be supported forever. This scope and support commitment is challenging and requires us to be careful in evaluating any contributions.
+
+We expect every contributor to work with the maintainers to ensure longevity of their contribution. If your contribution is substantial, please discuss it via our :ref:`community channels <community>` before working on it to ensure that it fits the project goals and to coordinate a long-term support commitment, especially in the cases where exotic or expensive hardware is required to test the changes.
+
+
+.. _bug-reports:
+
+Contributing bug reports
+------------------------
+
+Bug reports are always welcome! If you are experiencing an issue with your device and you are not sure what kind of issue it is, :ref:`ask the community for assistance <community>`.
+
+For a timely resolution of your issues involving the Glasgow software, include the following information when `reporting a bug on GitHub <issues_>`__:
+
+* Your operating system, including its version (e.g.: "Debian Linux bookworm" or "Windows 10 update 22H2");
+
+* The version of the Glasgow software stack (as printed by ``glasgow --version``);
+
+* The complete debug information produced by the command you are running (as printed by ``glasgow -vvv [command...]``).
+
+If you believe there is an issue with the design of the Glasgow hardware or firmware, `open an issue on GitHub <issues_>`__. The Glasgow hardware and firmware have been extensively reviewed, evaluated, and tested, and it is relatively unlikely for you to experience a design issue.
+
+If you believe that your device may be damaged or malfunctioning, and the device is unmodified from the design files published in this repository (bearing the "Glasgow" name on it), you may :ref:`ask the community for assistance <community>` before referring to the manufacturer of your device. If your device has been :ref:`modified from the original design files <build-your-own>` or does not bear the "Glasgow" name on it, you must request assistance from the manufacturer of your device. You may ask the community for assistance if you make it clear in your request that your device has been modified from the original design files, but the effort required to evaluate the modifications is scarcely available.
+
+.. _issues: https://github.com/GlasgowEmbedded/glasgow/issues/new
+
+
+.. _contributing-code:
+.. _contributing-docs:
+
+Contributing code or documentation
+----------------------------------
+
+You are expected to contribute code as a `pull request <pulls_>`__ containing a small number of self-contained commits with :ref:`descriptive messages <commit-messages>`, each of which individually captures a functional state of the working tree. If your pull request does not fit this description it will not be merged until it is cleaned up, but it is okay to have a draft pull request containing a large number of temporary commits while it is undergoing review or ongoing work.
+
+As Git is a notoriously difficult version control system to use effectively, feel free to :ref:`ask the community for assistance <community>`. Often, your pull request will be edited by maintainers to ensure it fits the codebase well. In those cases the maintainer will usually rearrange the commits to fit our requirements.
+
+The Glasgow project does not strictly adhere to any specific Python or C coding standards. If your code is structured and formatted similarly to existing code, it is good enough. You may be instructed to reformat your code to ensure that it fits the codebase well.
+
+.. _pulls: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
+
+.. _commit-messages:
+
+Writing commit messages
+#######################
+
+When modifying Python code, the first line of a commit message should, if possible, start with the name of the module that is being modified, such that ``git log --grep`` can be used to filter changes by scope. E.g.:
+
+.. code-block:: text
+
+    protocol.jtag_svf: accept and ignore whitespace in scan data.
+
+When modifying documentation, the first line of a commit message should start with ``manual: ``, followed by the base name of the ``.rst`` file that is being modified. E.g.:
+
+.. code-block:: text
+
+    manual: intro: update the list of applets.
+
+When modifying firmware, the first line of a commit message should start with ``firmware: ``. E.g.:
+
+.. code-block:: text
+
+    firmware: fix an operator precedence issue.
+
+If none of the cases above are a good fit, any descriptive message is sufficient.
+
+
+.. _docs-archive:
+
+Vendor documentation
+####################
+
+If you have used vendor documentation while writing the code you're contributing, you are required to:
+
+* upload the documentation to the `Glasgow archive repository <archive_>`__; and
+
+* reference the documentation at the top of the file in the following format:
+
+  .. code-block:: text
+
+      Ref: <insert vendor documentation title or, if impossible, any permanent-looking URL>
+      Document Number: <insert vendor document number; omit the field if one does not exist>
+      Accession: <insert Glasgow archive repository accession number>
+
+If you cannot upload the documentation to the archive because it is under NDA and/or watermarked, :ref:`ask the community for assistance <community>`. Often, it is possible to collate enough information by using existing leaked documents or through parallel construction.
+
+.. _archive: https://github.com/GlasgowEmbedded/archive
diff --git a/latest/_sources/develop/applet.rst.txt b/latest/_sources/develop/applet.rst.txt
@@ -0,0 +1,8 @@
+.. _applet:
+
+Applets
+=======
+
+.. attention::
+
+    We do not yet have documentation for developing applets or a stable API, so for now every applet must be loaded from within the main ``glasgow`` package.
diff --git a/latest/_sources/develop/docs.rst.txt b/latest/_sources/develop/docs.rst.txt
@@ -0,0 +1,47 @@
+.. _docs:
+
+Documentation
+=============
+
+The source files for this documentation manual is contained in the `GlasgowEmbedded/glasgow`_ repository under ``docs/manual/``. It is written in `reStructuredText`_ and published with `Sphinx`_, using `PDM`_ for package management.
+
+To build the documentation locally, first `install PDM`_. Then, navigate to the working directory you have :ref:`installed <initial-setup>` the Glasgow software in, and run:
+
+.. code-block:: console
+
+    $ cd docs/manual
+    $ pdm install
+
+Once this step completes (which should always happen without errors), you are ready to edit the documentation. In a terminal, run:
+
+.. code-block:: console
+
+    $ pdm run live
+    [sphinx-autobuild] > sphinx-build .../glasgow/docs/manual/src .../glasgow/docs/manual/out
+    Running Sphinx v7.1.2
+    loading pickled environment... done
+    building [mo]: targets for 0 po files that are out of date
+    writing output...
+    building [html]: targets for 0 source files that are out of date
+    updating environment: 0 added, 0 changed, 0 removed
+    reading sources...
+    looking for now-outdated files... none found
+    no targets are out of date.
+    build succeeded.
+
+    The HTML pages are in out.
+    [I 231002 04:16:58 server:335] Serving on http://127.0.0.1:8000
+    [I 231002 04:16:58 handlers:62] Start watching changes
+    [I 231002 04:16:58 handlers:64] Start detecting changes
+
+This command starts a web server running on your local PC that allows you to quickly see any changes to the documentation you are making. Navigate to `the URL it prints <http://127.0.0.1:8000>`_, and open the page you would like to change. Whenever you edit the ``.rst`` file corresponding to the page, you should see the page automatically reload in the web browser, reflecting the new contents.
+
+In some cases (primarily when you are updating the documentation index in the sidebar) the changes aren't picked up by the web server. In that case, remove the output directory to trigger a full rebuild.
+
+The markup language we are using, reStructuredText, has an awkward syntax, and it is easy for new editors to introduce syntax changes. If this happens, the web server prints a warning message whenever the ``.rst`` file is saved. Watch out for these warnings---they can save a lot of time trying to understand why the markup does not render correctly.
+
+.. _GlasgowEmbedded/glasgow: https://github.com/GlasgowEmbedded/glasgow
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
+.. _Sphinx: https://www.sphinx-doc.org/en/master/index.html
+.. _PDM: https://pdm.fming.dev/latest/
+.. _install PDM: https://pdm.fming.dev/latest/#installation
diff --git a/latest/_sources/develop/firmware.rst.txt b/latest/_sources/develop/firmware.rst.txt
@@ -0,0 +1,8 @@
+.. _firmware:
+
+Firmware
+========
+
+.. todo::
+
+    This section needs to be written.
diff --git a/latest/_sources/develop/hardware.rst.txt b/latest/_sources/develop/hardware.rst.txt
@@ -0,0 +1,8 @@
+.. _hardware:
+
+Hardware
+========
+
+.. todo::
+
+    This section needs to be written.
diff --git a/latest/_sources/develop/index.rst.txt b/latest/_sources/develop/index.rst.txt
@@ -0,0 +1,13 @@
+Development process
+===================
+
+As an end user, you will most likely only develop :ref:`applets <applet>` or :ref:`documentation <docs>`. Development of :ref:`software <software>`, :ref:`firmware <firmware>`, and :ref:`hardware <hardware>` are advanced topics, and the documentation here is only used for sharing knowledge among already experienced developers rather than teaching the required skills.
+
+
+.. toctree::
+
+    applet
+    docs
+    software
+    firmware
+    hardware
diff --git a/latest/_sources/develop/software.rst.txt b/latest/_sources/develop/software.rst.txt
@@ -0,0 +1,8 @@
+.. _software:
+
+Software
+========
+
+.. todo::
+
+    This section needs to be written.
diff --git a/latest/_sources/factory.rst.txt b/latest/_sources/factory.rst.txt
@@ -0,0 +1,74 @@
+.. _manufacturing:
+
+Manufacturing & flashing
+========================
+
+Pre-assembled Glasgow devices and cases are :ref:`available for purchase <purchasing>`. As Glasgow is open hardware, you also have the option of building a device yourself.
+
+
+.. _build-your-own:
+
+Building your own
+-----------------
+
+.. attention::
+
+    If you manufacture your own devices from the design files in this repository, you must clearly distinguish the PCBs by modifying the silkscreen artwork such that the placeholder manufacturer name and/or logo are replaced with your own contact information.
+
+    If you use the PCBA design files and the BOM that are included in this repository without modifications (other than the modifications required above), the Glasgow project will provide the same degree of support for your device as it does for the CrowdSupply orders (except for repairs under warranty).
+
+    If you modify the design files (which the license allows you to do without restrictions), the Glasgow project will not in general provide support for such devices, and you must not call your modified devices "Glasgow". You must remove the name "Glasgow" from the PCB silkscreen artwork to ensure that the device is clearly identifiable as being modified from the original source files.
+
+    If you are modifying the BOM to replace passive components with equivalent parts from a different vendor (such as in response to shortages), you may call your modified device "Glasgow". In addition, exceptions to the rule above can be made after discussing your case with Catherine "whitequark" or Piotr Esden-Tempski.
+
+.. todo::
+
+    This section is not written yet.
+
+
+.. _factory-flashing:
+
+Factory flashing
+----------------
+
+"Factory flashing" refers to the process of assigning a brand new Glasgow board (that you probably just assembled) a serial number, as well as writing a few critical configuration options that will let the ``glasgow`` command use this device. Barring severe and unusual EEPROM corruption, this process is performed only once in the lifetime of a device.
+
+To prepare for factory flashing, follow the :ref:`installation steps <initial-setup>`.
+
+Any board that is being factory flashed must have a blank ``FX2_MEM`` EEPROM. If the ``FX2_MEM`` EEPROM is not completely erased (all bytes set to ``FF``), the factory flashing process may fail.
+
+.. tab:: Linux
+
+    Configure your system to allow unprivileged access (for anyone in the ``plugdev`` group) to any hardware that enumerates as the Cypress FX2 ROM bootloader:
+
+    .. code-block:: console
+
+        $ sudo cp config/99-cypress.rules /etc/udev/rules.d
+
+    Note that this rule will allow unprivileged access to any device based on the Cypress FX2 that has a blank EEPROM, and not just the Glasgow.
+
+    Plug in the newly assembled device. At this point, ``lsusb -d 04b4:8613`` should list one entry. Note the revision of the board you are factory flashing. If the board has revision ``C3``, run:
+
+    .. code-block:: console
+
+        $ glasgow factory --rev C3
+
+    That's it! After running this command, the device will disconnect from USB and reconnect, and ``lsusb -d 20b7:9db1`` will list one entry.
+
+.. tab:: Windows
+
+    The steps are similar to the steps for Linux, but you will need to use Zadig to bind the WinUSB driver to the device, since this will not happen automatically with a device that hasn't been flashed yet.
+
+    .. todo::
+
+        Write a full explanation here.
+
+.. tab:: macOS
+
+    Plug in the newly assembled device. At this point, ``System Information.app`` should list the FX2 device with Vid ``04b4`` and Pid ``8613``. Note the revision of the board you are factory flashing. If the board has revision ``C3``, run:
+
+    .. code-block:: console
+
+        $ glasgow factory --rev C3
+
+    That's it! After running this command, the device will disconnect from USB and reconnect, and after refreshing (⌘R) the information in ``System Information.app`` you should see a new entry with Vid ``20b7`` and Pid ``9db1``.
diff --git a/latest/_sources/index.rst.txt b/latest/_sources/index.rst.txt
@@ -0,0 +1,16 @@
+Glasgow Interface Explorer manual
+---------------------------------
+
+.. toctree::
+    :maxdepth: 2
+
+    intro
+    revisions
+    purchase
+    factory
+    install
+    use/index
+    develop/index
+    contribute
+    community
+    license