docs: Update README & misc other small adjustments

Author: tuxuser

.github/workflows/pyinstaller.yml

@@ -65,7 +65,7 @@ jobs:
 
       - name: Create release zip
         run: |
-          for DIR in *; do 7z a ../${DIR}-${{ github.ref_name }}.zip *; done
+          for DIR in *; do 7z a ../${DIR}-${{ github.ref_name }}.zip ${DIR}; done
 
       - name: Create release
         uses: softprops/action-gh-release@v2

README.md

@@ -2,9 +2,16 @@
 
 # Durango RF Unit I2C tooling
 
+[![GitHub Release](https://img.shields.io/github/v/release/xboxoneresearch/DuRFUnitI2C)](https://github.com/xboxoneresearch/DuRFUnitI2C/releases/latest)
+
 > [!WARNING]
 > Use at your own risk!
 
+> [!INFO]
+> Grab the latest release @ [Releases page](https://github.com/xboxoneresearch/DuRFUnitI2C/releases)
+
+This repo contains tooling for Xbox One's RF Unit to dump / write flash and edit the firmware binaries with custom sounds.
+
 Technical infos: <https://xboxoneresearch.github.io/wiki/hardware/rf-unit/>
 
 ## Kudos
@@ -20,15 +27,37 @@ Special thanks to:
 
 I2C Device clients:
 - GreatFET One board
+
 or
 - Raspberry Pi (untested)
+
 or
+
 - Micropython device (ESP8266, ESP32, Pi Pico ..)
 
 Depending on the device, pull-up resistors might be necessary.
 
-## Connections
+## Quickstart Raspberry Pi Pico
+
+- Download latest [release](https://github.com/xboxoneresearch/DuRFUnitI2C/releases)
+- Unpack the archive
+- Read [QUICKSTART_PICO.txt](./QUICKSTART_PICO.txt)
+- Profit
+
+## Features
 
+**RFUnit tool**
+
+- Play sounds
+- Dump flash
+- Write flash
+
+**VPE tool**
+
+- Play sounds from firmware
+- Inject custom sounds
+
+## Connections
 
 | Xbox / Pin       | 3V3 | GND | SDA (DATA) | SCL (CLOCK) | Note                                                   |
 | ---------------- | --- | --- | ---------- | ----------- | ------------------------------------------------------ |
@@ -43,7 +72,7 @@ Depending on the device, pull-up resistors might be necessary.
 | RasPi Pico       | 3V3 | Any |              1 (GP0) |             2 (GP1) |
 | ESP 8266         | 3V3 | Any |               GPIO 4 |               GPIO 5|
 
-### Notes on FACET
+### Notes when directly soldering to Xbox motherboard (FACET-port)
 
 General info: [Wiki](https://xboxoneresearch.github.io/wiki/hardware/facet/)
 
@@ -63,94 +92,77 @@ Xbox One S
 
 ![Pi Pico Rf Unit connection diagram One S](./pi_pico_diagram_one_s.png)
 
-## Features
-
-- Play sounds
-- Dump flash
-- Write flash
-
 ## Usage
 
 - Solder I2C connections and 5V/3.3V/GND
-- Install python requirements, preferrably in a python venv
-  - GreatFET: `pip install greatfet`
-  - Raspberry Pi (not Pico): `pip install smbus2`
-  - Micropython: `pip install pyserial tqdm`
 - For flashing: Copy `flash.bin` next to script/executable
-- Execute `rfunit.py` (see below for micropython)
+- Execute tool
+  - For GreatFET / RPi (non-Pico): `rfunit-cli` for command-line
+  - Graphical interface: `rfunit-gui`
+  - For Micropython (RPi Pico, ESP8266 ...): see below @ [Micropython](#micropython)
 
 ### GUI
 
 For interactive control (play sounds, dump/flash, raw command TX/RX), run:
 
-- `python rfunit_gui.py`
+- `rfunit-gui`
 
 Device notes:
 
 - GreatFET on Windows: select `greatfet`
 - Pi Pico running MicroPython: select `pico` (leave port blank and click `Detect`)
 - Raspberry Pi (Linux): select `rpi`
 
+![RFUnit GUI - Screenshot Main](./assets/rfunit_gui-main.png)
+![RFUnit GUI - Screenshot Flash](./assets/rfunit_gui-flash.png)
+
 ### Micropython
 
 Check [Pyboard tool](https://docs.micropython.org/en/latest/reference/pyboard.py.html) for an overview.
 
 Easy:
 
 - For flashing: Copy `flash.bin` next to script/executable
-- Execute `micropython_rfunit.py`
-
-Manual:
-
-- Identify the serial port where you micropython device got enumerated (via `dmesg`), f.e. `/dev/ttyACM0`
-
-- Dumping
-  - Execute the script: `./vendor/pyboard.py --device /dev/ttyACM0 rfunit.py`
-  - Copy the dump to the PC: `./vendor/pyboard.py --device /dev/ttyACM0 -f cp :dump.bin .`
-- Flashing
-  - Copy flash.bin to the Micropython device: `./vendor/pyboard.py --device /dev/ttyACM0 -f cp flash.bin :flash.bin`
-  - Execute the script: `./vendor/pyboard.py --device /dev/ttyACM0 rfunit.py`
+- Execute `rfunit-micropython`
 
 ## ISD9160 VPE Editor tool
 
 This tool can be used to playback audio segments of ISD9160 firmware files, wrapped in custom VPE blob.
 Used on Xbox One/S/X for button-sounds.
 
-More features coming soon...
+NOTE: The tool requires an original firmware as a base.
+
+Run: `vpe-gui`
+
+![VPE Editor screenshot](./assets/vpe_gui-creator.png)
+
+## Manual
 
-Kudos to [flynnyfoo](https://github.com/FJCFJC123) for not giving up on this major task <3
+Obviously you can do everything manually too, instead of relying on the pyinstaller binaries.
 
-### Requirements
+Requirements:
 
-- [uv](https://docs.astral.sh/uv/)
+- Install uv (<https://docs.astral.sh/uv>)
 
-### Usage
+### Micropython dump / flash
+
+- Identify the serial port where you micropython device got enumerated (via `dmesg`), f.e. `/dev/ttyACM0`
+- Dumping
+  - Execute the script: `uv run pyboard --device /dev/ttyACM0 ./src/rfunit.py`
+  - Copy the dump to the PC: `uv run pyboard --device /dev/ttyACM0 -f cp :dump.bin .`
+- Flashing
+  - Copy flash.bin to the Micropython device: `uv run pyboard --device /dev/ttyACM0 -f cp flash.bin :flash.bin`
+  - Execute the script: `uv run pyboard --device /dev/ttyACM0 ./src/rfunit.py`
 
-Run the GUI
+### RFUnit GUI
 
-```
-uv run vpe_gui.py
-```
+Run: `uv run rfunit-gui`
 
+### VPE Editor (CLI)
 
-## Flashdump
+Run: `uv run vpe-cli`
 
-Size: 0x24400
+### VPE Editor (GUI)
 
-Checksum (SHA256)
-```
-8150af1889203260bbbd25884447c0540f1cbc843a13e86bb0b6d501a6d032e1  dump_phat_cod_aw.bin
-3789e76fd6c37bdf39751afd6164c1d8d67a53c31eca5b630901210b55753dba  dump_phat_forza6.bin
-388d252d7783fd2946b9b3fca57ecd1ed13a4f17ea6665f577da34224f9930da  dump_phat_halo5.bin
-abc699513959372faee038c78a1d7509c2020f65cb78ad07ab9c90b21b406a87  dump_phat_retail.bin
-4812af697716464dff1a49e0ab2f45497492fec71aa0a73308f522db45d2b42e  dump_one_s_minecraft.bin
-222fcaec65d1ffd7f275616df1af5f1128d34e3b32035e3377ab48f91b232ffc  dump_one_s_gow4.bin
-c39871fcfef69c632955658f8e876d35a35dafb9c88c7fc082dca23d2102289f  dump_one_x_tacobell.bin
-```
+Run: `uv run vpe-gui`
 
-Some strings
-```
-ISD9160FIMS03 FW Jun 14 2013 at 10:41:12 (C) Nuvoton 2013
-Nuvoton ISD9160MS Boot FW Jun 14 2013 10:40:21 
-ISD-VPE Ver 920.000c 08/05/2013 PV_Prod_Units_Rev5 VERSION:0x10000007
-```

assets/rfunit_gui-flash.png

@@ -1,11 +1,18 @@
 # -*- mode: python ; coding: utf-8 -*-
 
+from PyInstaller.utils.hooks import collect_data_files
+
+use_upx=False
+# 'cmsis_svd' is a dependency of 'greatfet'
+rfunit_py_datas = [('src/rfunit.py', '.'), *collect_data_files('cmsis_svd', includes=['schemas/*'])]
+rfunit_hiddenimports = ["smbus2", "greatfet"]
+
 a1 = Analysis(
     ['src/rfunit.py'],
     pathex=[],
     binaries=[],
-    datas=[],
-    hiddenimports=[],
+    datas=rfunit_py_datas,
+    hiddenimports=rfunit_hiddenimports,
     hookspath=[],
     hooksconfig={},
     runtime_hooks=[],
@@ -18,10 +25,8 @@ a2 = Analysis(
     ['src/rfunit_gui.py'],
     pathex=[],
     binaries=[],
-    datas=[
-        ('src/rfunit.py', '.')
-    ],
-    hiddenimports=[],
+    datas=rfunit_py_datas,
+    hiddenimports=rfunit_hiddenimports,
     hookspath=[],
     hooksconfig={},
     runtime_hooks=[],
@@ -62,10 +67,8 @@ a5 = Analysis(
     ['src/micropython_rfunit.py'],
     pathex=[],
     binaries=[],
-    datas=[
-        ('src/rfunit.py', '.')
-    ],
-    hiddenimports=[],
+    datas=rfunit_py_datas,
+    hiddenimports=rfunit_hiddenimports,
     hookspath=[],
     hooksconfig={},
     runtime_hooks=[],
@@ -88,7 +91,7 @@ exe_rfunit_cli = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    upx=use_upx,
     disable_windowed_traceback=False,
     argv_emulation=False,
     target_arch=None,
@@ -106,7 +109,7 @@ exe_rfunit_gui = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    upx=use_upx,
     disable_windowed_traceback=False,
     argv_emulation=False,
     target_arch=None,
@@ -124,7 +127,7 @@ exe_vpe_cli = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    upx=use_upx,
     disable_windowed_traceback=False,
     argv_emulation=False,
     target_arch=None,
@@ -142,7 +145,7 @@ exe_vpe_gui = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    upx=use_upx,
     disable_windowed_traceback=False,
     argv_emulation=False,
     target_arch=None,
@@ -160,13 +163,13 @@ exe_rfunit_cli_easy = EXE(
     debug=False,
     bootloader_ignore_signals=False,
     strip=False,
-    upx=True,
+    upx=use_upx,
     disable_windowed_traceback=False,
     argv_emulation=False,
     target_arch=None,
     codesign_identity=None,
     entitlements_file=None,
-    name='rfunit-easy',
+    name='rfunit-micropython',
     console=True,
 )
 
@@ -197,7 +200,7 @@ coll = COLLECT(
     a5.datas,
 
     strip=False,
-    upx=True,
+    upx=use_upx,
     upx_exclude=[],
 
     name="durango-rfunit-tools"

assets/rfunit_gui-main.png

@@ -25,6 +25,7 @@ dev = [
 [project.scripts]
 rfunit-cli = "rfunit:main"
 rfunit-gui = "rfunit_gui:main"
-rfunit-easy = "micropython_rfunit:main"
+rfunit-micropython = "micropython_rfunit:main"
 vpe-cli = "vpe:main"
 vpe-gui = "vpe_gui:main"
+pyboard = "vendor.pyboard:main"

assets/vpe_gui-creator.png

@@ -2,6 +2,7 @@
 Xbox One I2C RF Unit
 """
 
+# NOTE: These typing hints in try/except-wrap are not available for micropython
 try:
     from typing import List, Generator
     from io import BufferedReader, BufferedWriter
@@ -114,7 +115,7 @@ class DummyDevice(I2CClient):
     def __init__(self):
         pass
 
-    def scan(self) -> bool:
+    def scan(self) -> List[int]:
         return [I2C_ADDR]
 
     def read(self, read_len: int) -> List[int]:
@@ -427,7 +428,7 @@ def dump_flash(self, offset: int, count: int) -> Generator[bytes, None, None]:
             bytecnt = min(CHUNK_SIZE, end_offset - addr)
             yield res[:bytecnt]
 
-def print_position(position: int, mod_value: int = None):
+def print_position(position: int, mod_value: int | None = None):
     # As we dont want to print on each iteration..
     if not mod_value or position % mod_value == 0:
         print(f"{position:#08x}")

pyinstaller.spec

@@ -475,8 +475,10 @@ def work() -> None:
             if dev_type == "greatfet":
                 try:
                     dev = rfunit.GreatFetDevice()
-                except Exception as e:
+                except ImportError as e:
                     raise RuntimeError("Failed to init GreatFET. Did you `pip install greatfet`?") from e
+                except Exception as e:
+                    raise RuntimeError("No GreatFET device found") from e
             elif dev_type == "rpi":
                 if os.name == "nt":
                     raise RuntimeError(
@@ -489,12 +491,14 @@ def work() -> None:
                     raise ValueError("Invalid RPi bus id") from e
                 try:
                     dev = rfunit.RPiDevice(bus_id=bus_id)
-                except Exception as e:
+                except ImportError as e:
                     raise RuntimeError("Failed to init smbus2. Did you `pip install smbus2` (and run on a Pi)?") from e
+                except PermissionError as e:
+                    raise RuntimeError("Could not access RPi smbus2 - permission error?") from e
             elif dev_type == "pico":
                 try:
                     from vendor import pyboard
-                except Exception as e:
+                except ImportError as e:
                     raise RuntimeError("Failed to import vendor.pyboard") from e
 
                 port = (self.pico_port_var.get() or "").strip()
@@ -864,4 +868,4 @@ def main() -> int:
 
 
 if __name__ == "__main__":
-    raise SystemExit(main())
+    sys.exit(main())