Merge pull request #430 from greatscottgadgets/antoinevg/pre-release

Release chores

Makefile

@@ -45,10 +45,10 @@ ARCHIVE_FLAGS = \
 	--force-submodules --prefix=greatfet-$(VERSION)/
 
 #
-# If we have a release version, also include the version and release-notes files.
+# If we have a release version, also include the version file.
 #
 ifdef RELEASE_VERSION
-ARCHIVE_FLAGS += --extra=VERSION --extra=RELEASENOTES
+ARCHIVE_FLAGS += --extra=VERSION 
 endif
 
 
@@ -124,7 +124,7 @@ libgreat/README.md:
 
 
 #
-# Prepares a GreatFET release based on the VERSION arguments and based on a RELEASENOTES file.
+# Prepares a GreatFET release based on the VERSION arguments and based on a RELEASENOTES.md file.
 #
 prepare_release_files: firmware
 	@mkdir -p release-files/
@@ -140,13 +140,13 @@ endif
 	@mkdir -p host-packages
 	@mkdir -p build
 
-	@#Create our python pacakges. These universal packages work for py2/py3.
-	@pushd libgreat/host; $(PYTHON3) setup.py bdist_wheel --universal -d $(CURDIR)/host-packages; popd
-	@pushd host; $(PYTHON3) setup.py bdist_wheel --universal -d $(CURDIR)/host-packages; popd
+	@#Create our python pacakges. 
+	@pushd libgreat/host; $(PYTHON3) setup.py bdist_wheel -d $(CURDIR)/host-packages; popd
+	@pushd host; $(PYTHON3) setup.py bdist_wheel -d $(CURDIR)/host-packages; popd
 
 	@# Create files for e.g. the nightly.
-	@pushd libgreat/host; $(PYTHON3) setup.py bdist_wheel -p any -b build_dist --universal -d $(CURDIR)/release-files; popd
-	@pushd host; $(PYTHON3) setup.py bdist_wheel -p any --universal -d $(CURDIR)/release-files; popd
+	@pushd libgreat/host; $(PYTHON3) setup.py bdist_wheel -p any -b build_dist -d $(CURDIR)/release-files; popd
+	@pushd host; $(PYTHON3) setup.py bdist_wheel -p any -d $(CURDIR)/release-files; popd
 	ls $(CURDIR)/release-files
 
 	@echo --- Creating our firmware-binary directory.
@@ -179,7 +179,7 @@ prepare_release_archives: prepare_release_files
 #
 # prepare_release generates the actual release, and then prints instructions.
 #
-prepare_release: RELEASENOTES prepare_release_archives
+prepare_release: RELEASENOTES.md prepare_release_archives
 
 	@# If no tag was supplied, warn the user.
 ifndef RELEASE_VERSION

RELEASENOTES.md

@@ -0,0 +1,56 @@
+This the fourth major release of the GreatFET software and firmware stacks. As usual, this release contains firmware images in `firmware-bin`, host software in `host-packages`, and a copy of all sources necessary to build the entire codebase.
+
+## Upgrading to this release
+
+You can upgrade the GreatFET host tools to the latest release with:
+
+    pip install --upgrade greatfet
+
+After upgrading the host tools, update your GreatFET firmware to the latest release with:
+
+    greatfet_firmware --autoflash
+
+Happy hacking!
+
+
+# Changelog
+
+
+## v2024.0.0
+
+### GreatFET
+
+* [gpio: add support for configuring all gpio pin
+* [uart: fix python KeyError when parity argument not specified](https://github.com/greatscottgadgets/greatfet/pull/375)
+* [shell: support versions of IPython >= 3.11](https://github.com/greatscottgadgets/greatfet/pull/414)
+modes](https://github.com/greatscottgadgets/greatfet/pull/418)
+* [facedancer: fix usb mass storage example](https://github.com/greatscottgadgets/greatfet/pull/425)
+* [shell: fix runtime errors when using uart functionality](https://github.com/greatscottgadgets/greatfet/pull/426)
+
+### libgreat
+
+* [Added TX & RX pin definitions for UART1, USART2&3](https://github.com/greatscottgadgets/libgreat/pull/25)
+* [Implement NXP's recommended PLL setup sequence](https://github.com/greatscottgadgets/libgreat/pull/30)
+* [Add support for configuring all gpio pin modes](https://github.com/greatscottgadgets/libgreat/pull/35)
+* [Don't try to claim USB interface on Windows](https://github.com/greatscottgadgets/libgreat/pull/38)
+* [Add initial implementation of usb1 bulk transfer backend](https://github.com/greatscottgadgets/libgreat/pull/33)
+* [Do not set USB device address to zero](https://github.com/greatscottgadgets/libgreat/pull/26)
+
+
+## v2021.2.1
+
+NOTE: We no longer support Python 2. This release targets Python 3.6+.
+
+### Highlights for this release:
+
+* This release adds a new chipcon programmer for Texas Instruments CCxxxx ("SWRA124") devices.
+    - In Python: `chipcon = gf.create_programmer('chipcon')`
+        - From there you can perform manual operations like `chipcon.run_instruction()` and `read_xdata_memory()`,
+        - Or use higher-level interface methods like `program_flash()` and `read_flash()`.
+    - Flash operations can also be done from the command line with `greatfet chipcon`.
+* This release adds a new programmer for Microchip I2C EEPROM devices: `eeprom = gf.create_programmer('microchipEEPROM', device='24LC128')`.
+    - This mainly provides two higher-level methods: `read_bytes(start, end)`, and `write_bytes(start, data)`.
+
+### Major bugfixes:
+
+ - #344: Facedancer with bMaxPacketSize0 < 32 does not work.

docs/source/conf.py

@@ -60,7 +60,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/source/getting_started.rst

@@ -0,0 +1,86 @@
+=============================
+Getting Started with GreatFET
+=============================
+
+
+Prerequisites
+-------------
+
+To use GreatFET you will need to ensure the following software is installed:
+
+  * `Python <https://wiki.python.org/moin/BeginnersGuide/Download>`__ v3.8, or later.
+
+If you want to use GreatFET's interactive shell you will also need to install:
+
+  * `IPython <https://ipython.readthedocs.io>`__
+
+
+GreatFET Host Software Installation
+-----------------------------------
+
+You can install the GreatFET host software from the `Python Package Index (PyPI) <https://pypi.org/project/greatfet/>`__ or :doc:`directly from source <getting_started_firmware_development>`.
+
+To install the GreatFET host software from PyPI using the `pip <https://pypi.org/project/pip/>`__ tool:
+
+.. code-block :: sh
+
+    pip install greatfet
+
+.. note::
+
+    For more information on installing Python packages from PyPI please refer to the
+    `"Installing Packages" <https://packaging.python.org/en/latest/tutorials/installing-packages/>`__
+    section of the Python Packaging User Guide.
+
+
+Install udev Rules (Linux Only)
+-------------------------------
+
+Configure your system to allow access to GreatFET:
+
+.. code-block :: sh
+
+    # install udev rules
+    sudo cp host/util/54-greatfet.rules /etc/udev/rules.d
+
+    # reload udev rules
+    sudo udevadm control --reload
+
+    # apply udev rules to any devices that are already plugged in
+    sudo udevadm trigger
+
+
+Test Installation
+-----------------
+
+Ensure that GreatFET's `USB0` port is connected to the host and type the following command into a terminal:
+
+.. code-block :: sh
+
+    greatfet info
+
+If everything is working you will see the following output:
+
+.. code-block :: text
+
+    Found a GreatFET One!
+      Board ID: 0
+      Firmware version: v2024.0.0
+      Part ID: xxxxxxxxxxxxxx
+      Serial number: xxxxxxxxxxxxxxxxxxxx
+
+
+Upgrading to a new release
+--------------------------
+
+You can upgrade the GreatFET host tools to the latest release with:
+
+.. code-block :: sh
+
+    pip install --upgrade greatfet
+
+After upgrading the host tools, update your GreatFET firmware to the latest release with:
+
+.. code-block :: sh
+
+    greatfet_firmware --autoflash

docs/source/index.rst

@@ -7,6 +7,7 @@ The GreatFET project produces interface tools for hardware hacking, making, and
   :maxdepth: 2
   :caption: User Documentation
 
+  getting_started
   greatfet_gnuradio
   linux_distribution_python_version_matrix
   troubleshooting

docs/source/release_process.rst

@@ -2,91 +2,83 @@
 Release Process
 ================================================
 
-This is the process for tagging and publishing a release. Change the release version number and paths as appropriate. Release version numbers are in the form YYYY.MM.N where N is the release number for that month (usually 1).
+This is the process for tagging and publishing a release. Change the release version number and paths as appropriate. Release version numbers are in the form ``YYYY.major.minor`` where ``YYYY`` is the year and ``major``, ``minor`` are the release numbers.
 
 
-
-tag the release
-~~~~~~~~~~~~~~~
+Create Environment
+~~~~~~~~~~~~~~~~~~
 
 .. code-block:: sh
 
-	git tag -a v2013.07.1 -m 'release 2013.07.1'
-	git push --tags
+    pyenv install 3.8
+    pyenv virtualenv 3.8 gsg-release
+    pyenv local gsg-release
 
+    python -m pip install --upgrade pip
+    pip install --upgrade setuptools setuptools_git_versioning build twine
 
 
-make the release directory
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+Dependencies
+~~~~~~~~~~~~
 
 .. code-block:: sh
 
-	cd /tmp
-	git clone ~/src/greatfet
-	cd greatfet
-	rm -rf .git*
-	mkdir firmware-bin
-	cd ..
-	mv greatfet greatfet-2013.07.1
-
+    pip install pyyaml wheel git-archive-all
 
 
-copy/update RELEASENOTES from previous release
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-  - prepend the current release notes to previous release notes
+Clone Repository
+~~~~~~~~~~~~~~~~
 
+.. code-block:: sh
 
+    # clone repository
+    git clone [email protected]:greatscottgadgets/greatfet.git greatfet.git
 
-make second clone for firmware build
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    # update submodules
+    cd greatfet.git/
+    git submodule update --init --recursive
 
-.. code-block:: sh
 
-	git clone --recursive ~/src/greatfet
-	cd greatfet/firmware/libopencm3
-	make
-	cd ..
+Update ``RELEASENOTES.md`` from previous release
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+  - update ``RELEASENOTES.md`` for the latest release
 
 
-update the firmware VERSION_STRING and compile firmware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Prepare release
+~~~~~~~~~~~~~~~
 
 .. code-block:: sh
 
-	sed -i 's/git-${VERSION}/2013.07.1/' cmake/greatfet-common.cmake
-	mkdir build
-	cd build
-	cmake ..
-	make
-	cp flash_stub/flash_stub.dfu /tmp/greatfet-2013.07.1/firmware-bin/
-	cp greatfet_usb/greatfet_usb.bin /tmp/greatfet-2013.07.1/firmware-bin/
-
+    RELEASE_VERSION=2024.0.1 make prepare_release
 
 
-make the release archives
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Push Release Tag
+~~~~~~~~~~~~~~~~
 
 .. code-block:: sh
 
-	tar -cJvf greatfet-2013.07.1.tar.xz greatfet-2013.07.1
-	zip -r greatfet-2013.07.1.zip greatfet-2013.07.1
-
+    git tag -a v2024.0.1 -m 'release 2024.0.1'
+    git push --tags
 
 
 "Draft a new release" on github
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    - call it "release 2013.07.1"
+    - call it "release 2024.0.1"
     - paste release notes (just for this release, not previous)
     - upload .tar.xz and .zip files
 
 
+Upload release to PyPI
+~~~~~~~~~~~~~~~~~~~~~~
+
+    python -m twine upload --repository pypi host-packages/*
+
 
-announce the release
+Announce the release
 ~~~~~~~~~~~~~~~~~~~~
 
-    - irc
+    - discord
     - greatfet mailing list
     - twitter

host/pyproject.toml

@@ -1,17 +1,17 @@
 [build-system]
-requires = ["setuptools>=41", "wheel", "setuptools-git-versioning<2"]
+requires = ["setuptools>=64", "wheel", "setuptools-git-versioning<2"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "greatfet"
-dynamic = ["version"]
+description = "Python library for hardware hacking with the GreatFET"
+license = { text = "BSD" }
+readme = "README.md"
+requires-python = ">=3.8"
 authors = [
     {name = "Great Scott Gadgets", email = "[email protected]"},
 ]
-license = { text = "BSD" }
-description = "Python library for hardware hacking with the GreatFET"
-urls = { Source = "https://greatscottgadgets.com/greatfet" }
-readme = "README.md"
+
 classifiers = [
     "Programming Language :: Python",
     "Development Status :: 5 - Production/Stable",
@@ -25,6 +25,7 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Topic :: Security",
 ]
+
 dependencies = [
     "pyusb",
     "future",
@@ -36,6 +37,13 @@ dependencies = [
     "pygreat"
 ]
 
+dynamic = ["version"]
+
+[project.urls]
+Documentation = "https://greatfet.readthedocs.io"
+Repository    = "https://github.com/greatscottgadgets/greatfet"
+Issues        = "https://github.com/greatscottgadgets/greatfet/issues"
+
 [project.scripts]
 greatfet = "greatfet.commands.gf:main"
 gf = "greatfet.commands.gf:main"
@@ -64,6 +72,9 @@ greatfet_pirate = "greatfet.commands.greatfet_pirate:main"
 greatfet_jtag = "greatfet.commands.greatfet_jtag:main"
 greatfet_chipcon = "greatfet.commands.greatfet_chipcon:main"
 
+[tool.setuptools.package-data]
+greatfet = ["gnuradio/*.yml", "examples/greatfet_flame"]
+
 [tool.setuptools-git-versioning]
 enabled = true
-starting_version = "2019.05.01"
+starting_version = "2024.0.0"