mule-attiny: i2c-flash: reorganize as proper Python project

This should allow for easier integration with build systems such as the
Yocto Project or Buildroot.

The LICENSE file is a copy of the MIT license file already at the root
of the git repository, only with the copyright year changed to this
year.

At the same time, a README is added to explain what this is useful for.

Relates-to: EHSW-1799
Signed-off-by: Quentin Schulz <quentin.schulz@theobroma-systems.com>

6 files changed, 116 insertions, 0 deletions

diff --git a/mule-attiny/i2c-flash/.gitignore b/mule-attiny/i2c-flash/.gitignore
new file mode 100644
index 0000000..c4e7496
--- /dev/null
+++ b/mule-attiny/i2c-flash/.gitignore
@@ -0,0 +1,2 @@
+dist/
+*.egg-info/
diff --git a/mule-attiny/i2c-flash/LICENSE b/mule-attiny/i2c-flash/LICENSE
new file mode 100644
index 0000000..870abd0
--- /dev/null
+++ b/mule-attiny/i2c-flash/LICENSE
@@ -0,0 +1,19 @@
+Copyright (c) 2023 Theobroma Systems Design und Consulting GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/mule-attiny/i2c-flash/README.md b/mule-attiny/i2c-flash/README.md
new file mode 100644
index 0000000..242a51a
--- /dev/null
+++ b/mule-attiny/i2c-flash/README.md
@@ -0,0 +1,71 @@
+# I2C flashing of ATtiny microcontroller firmware
+
+For some hardware designs, using UPDI to flash the ATtiny microcontroller may
+not be available. Provided a special bootloader has been flashed beforehand on
+the ATtiny microcontroller (this one unfortunately through an UPDI interface),
+it is possible to flash the application firmware (`APP_SECTION`) via I2C.
+
+# Dependencies
+
+This depends on:
+- `gpiod` Python package,
+- `smbus2` Python package,
+- `nice` binary (available in `coreutils` package),
+- `updi_reset` binary (sources available at
+   https://git.theobroma-systems.com/som-tools.git)
+
+# Running instructions
+
+```
+usage: i2c_flash.py [-h] -f FIRMWARE -c BOOT_REQ_GPIOCHIP -g BOOT_REQ_GPIO -b
+                    I2C_BUS -rc UPDI_RESET_GPIOCHIP -rg UPDI_RESET_GPIO
+
+Script to flash mule-ATtiny firmware through I2C-Flashloader
+
+options:
+  -h, --help            show this help message and exit
+  -f FIRMWARE, --firmware FIRMWARE
+                        Path to the firmware binary file
+  -c BOOT_REQ_GPIOCHIP, --boot_req_gpiochip BOOT_REQ_GPIOCHIP
+                        Boot request gpiochip index number (e.g. 0 if
+                        /dev/gpiochip0)/
+  -g BOOT_REQ_GPIO, --boot_req_gpio BOOT_REQ_GPIO
+                        Boot request GPIO index in the gpiochip (e.g. if
+                        GPIO3_A5, boot_req_gpiochip is 3 and boot_req_gpio is
+                        5
+  -b I2C_BUS, --i2c_bus I2C_BUS
+                        I2C bus index (e.g. 2 if /dev/i2c-2) connected to
+                        ATtiny
+  -rc UPDI_RESET_GPIOCHIP, --updi_reset_gpiochip UPDI_RESET_GPIOCHIP
+                        Updi_reset gpiochip index number (e.g. 0 if
+                        /dev/gpiochip0)/
+  -rg UPDI_RESET_GPIO, --updi_reset_gpio UPDI_RESET_GPIO
+                        Updi_reset GPIO index in the gpiochip (e.g. if
+                        GPIO3_A4, boot_req_gpiochip is 3 and boot_req_gpio is
+                        4
+```
+# Notes
+
+## Specificity
+
+This is specific to Theobroma Systems' Mule-ATtiny companion microcontroller.
+
+One may find this useful in case one has bought:
+- PX30-uQ7 (codename "Ringneck") with an ATtiny companion microcontroller,
+
+Other publicly available Theobroma Systems products can typically make use of
+the more common UPDI flashing process.
+
+## I2C transfer conflicts
+
+The I2C flashing process uses the same I2C device address and bus than the
+ISL1208 RTC emulated device. Since the bootloader implements a very simple I2C
+transfer mechanism, no other I2C transfer should happen on that device address,
+which is why the script will unbind the ISL1208 RTC device from the kernel to
+make sure it doesn't happen.
+
+## Reboot recommended
+
+We highly recommend that one reboots the main SoC interacting with the companion
+microcontroller to make sure driver devices are properly initialized after a
+flash of the Mule-ATtiny firmware.
diff --git a/mule-attiny/i2c-flash/pyproject.toml b/mule-attiny/i2c-flash/pyproject.toml
new file mode 100644
index 0000000..e82d817
--- /dev/null
+++ b/mule-attiny/i2c-flash/pyproject.toml
@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+version = "0.0.1"
+name = "mule-attiny_i2c_flash"
+authors = [
+	{ name = "Theobroma Systems Design und Consulting GmbH", email = "FIXME@theobroma-systems.com" }, #FIXME
+]
+description = "Flash Mule-ATtiny application FW via I2C"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+classifiers = [
+	"License :: OSI Approved :: MIT License",
+	"Programming Language :: Python :: 3",
+	"Operating System :: POSIX :: Linux",
+	"Topic :: Utilities",
+]
+dependencies = [
+	"gpiod==1.5.4",
+	"smbus2==0.4.2",
+]
diff --git a/mule-attiny/i2c-flash/src/mule-attiny_i2c_flash/__init__.py b/mule-attiny/i2c-flash/src/mule-attiny_i2c_flash/__init__.py
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/mule-attiny/i2c-flash/src/mule-attiny_i2c_flash/__init__.py
diff --git a/mule-attiny/i2c-flash/i2c_flash.py b/mule-attiny/i2c-flash/src/mule-attiny_i2c_flash/i2c_flash.py
index 185ea2e..185ea2e 100755
--- a/mule-attiny/i2c-flash/i2c_flash.py
+++ b/mule-attiny/i2c-flash/src/mule-attiny_i2c_flash/i2c_flash.py