fpbinject 1.6.8__tar.gz

fpbinject-1.6.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VIFEX
+
+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.

fpbinject-1.6.8/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: fpbinject
+Version: 1.6.8
+Summary: Runtime code injection for ARM Cortex-M via the FPB (Flash Patch and Breakpoint) hardware unit
+Author-email: VIFEX <vifextech@foxmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FASTSHIFT/FPBInject
+Project-URL: Repository, https://github.com/FASTSHIFT/FPBInject
+Keywords: arm,cortex-m,fpb,firmware,code-injection,debugging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Flask
+Requires-Dist: Flask-Cors
+Requires-Dist: pyserial
+Requires-Dist: pygdbmi
+Requires-Dist: watchdog
+Requires-Dist: tree_sitter
+Requires-Dist: zeroconf>=0.131
+Requires-Dist: platformdirs
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: license-file
+
+# FPBInject
+
+**English** | [中文](README_zh.md)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/Platform-STM32F103-blue.svg)](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
+[![Platform](https://img.shields.io/badge/Platform-NuttX-blue.svg)](https://github.com/apache/nuttx)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/FASTSHIFT/FPBInject)
+[![CI](https://github.com/FASTSHIFT/FPBInject/actions/workflows/ci.yml/badge.svg)](https://github.com/FASTSHIFT/FPBInject/actions/workflows/ci.yml)
+
+Runtime code injection for ARM Cortex-M. Replace any function on a running MCU through a serial connection — no reflashing, no debugger, no downtime.
+
+FPBInject uses the [Flash Patch and Breakpoint (FPB)](https://developer.arm.com/documentation/ddi0337/h/debug/about-the-flash-patch-and-breakpoint-unit--fpb-) hardware unit to intercept function calls and redirect them to your custom code in RAM, while the original Flash stays untouched.
+
+![FPBInject Workbench](Docs/images/webserver-overview.png)
+
+## Traditional vs FPBInject
+
+```mermaid
+gantt
+    title Iteration cycle comparison (typical STM32 project)
+    dateFormat  s
+    axisFormat  %Ss
+
+    section Traditional
+    Edit code          : a1, 0, 5s
+    Compile & link     : a2, after a1, 15s
+    Erase flash        : a3, after a2, 3s
+    Flash write        : a4, after a3, 5s
+    MCU reboot         : a5, after a4, 2s
+    Reproduce issue    : a6, after a5, 5s
+
+    section FPBInject
+    Edit code          : b1, 0, 5s
+    Compile & inject   : b2, after b1, 1s
+    Reproduce issue    : b3, after b2, 5s
+```
+
+The traditional cycle touches flash on every iteration — compile, erase, write, reboot, then finally reproduce the issue. With FPBInject, the MCU never stops: save your patch, it's live in under a second. No pit stop required.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A["caller()<br/>calls foo()"] -->|"FPB intercepts<br/>foo's address"| B["Trampoline<br/>in Flash"]
+    B -->|"Jump to RAM"| C["Your Code<br/>in RAM"]
+```
+
+The FPB unit matches the target function's address, redirects execution through a trampoline in Flash, which jumps to your replacement function in RAM. All handled by hardware — zero software overhead on the call path.
+
+## Workbench
+
+FPBInject ships with a browser-based workbench for the full workflow: browse symbols, read disassembly, write patches, and inject — all from one interface.
+
+### Symbol Search & Disassembly
+
+Search the firmware's symbol table, click a function to view its disassembly or decompiled source.
+
+![Disassembly View](Docs/images/webserver-disasm.png)
+
+### Manual Inject
+
+Write your replacement function in C, then hit inject. The workbench compiles, uploads, and patches — typically under a second.
+
+![Inject View](Docs/images/webserver-inject.png)
+
+### Auto Inject
+
+Point the workbench at your source directory and enable file watching. Add `/* FPB_INJECT */` before any function you want to patch, then just save the file — the workbench detects the change, recompiles, and re-injects automatically.
+
+![Auto Inject - Editor](Docs/images/editor-auto-inejct.png)
+
+![Auto Inject - Workbench](Docs/images/webserver-auto-inject.png)
+
+## File Transfer (Optional)
+
+FPBInject also supports file transfer over serial — browse, upload, and download files on the device's filesystem. Supports drag-and-drop (files and folders), CRC verification, and progress tracking.
+
+Filesystem backends: POSIX (NuttX VFS, Linux), FatFS, standard C library (stdio), or custom implementations via the `fl_fs_ops_t` interface.
+
+![File Transfer](Docs/images/file-transfer.png)
+
+## Quick Start
+
+### 1. Build & Flash Firmware
+
+```bash
+git clone https://github.com/FASTSHIFT/FPBInject.git
+cd FPBInject
+
+cmake -B build -DAPP_SELECT=3 -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi-gcc.cmake
+cmake --build build
+
+st-flash write build/FPBInject.bin 0x08000000
+```
+
+### 2. Start the Workbench
+
+```bash
+cd Tools/WebServer
+pip install -r ../requirements.txt
+python main.py
+```
+
+Open `http://127.0.0.1:5500` in your browser, connect to the serial port, load your ELF file, and start patching.
+
+### 3. Or Use the CLI
+
+All commands output JSON, designed for scripting and AI agent integration.
+
+```bash
+# Search for functions
+python fpb_cli.py search firmware.elf "gpio"
+
+# View disassembly
+python fpb_cli.py disasm firmware.elf digitalWrite
+
+# Inject a patch
+python fpb_cli.py --port /dev/ttyACM0 --elf firmware.elf \
+    --compile-commands build/compile_commands.json \
+    inject digitalWrite patch.c
+```
+
+See the [CLI Guide](Docs/CLI.md) for the full command reference.
+
+## Writing Patches
+
+Create a C file with the `/* FPB_INJECT */` marker. The function signature must match the original.
+
+```c
+#include <Arduino.h>
+
+/* FPB_INJECT */
+__attribute__((section(".fpb.text"), used))
+void digitalWrite(uint8_t pin, uint8_t value) {
+    printf("Patched: pin=%d val=%d\n", pin, value);
+    value ? digitalWrite_HIGH(pin)
+          : digitalWrite_LOW(pin);
+}
+```
+
+> To call the original function from injected code, you need two things: a function pointer pointing directly at the original address (bypassing the FPB redirect), and temporarily disabling the patch around the call. Direct calls by name will still be intercepted by FPB and cause infinite recursion.
+>
+> ```c
+> /* Define a function pointer to the original address (| 1 sets the Thumb bit) */
+> typedef void (*digitalWrite_fn_t)(uint8_t, uint8_t);
+> static digitalWrite_fn_t const ORIG_DIGITALWRITE = (digitalWrite_fn_t)(0x08001234 | 1);
+>
+> /* FPB_INJECT */
+> __attribute__((section(".fpb.text"), used))
+> void digitalWrite(uint8_t pin, uint8_t value) {
+>     printf("Patched: pin=%d val=%d\n", pin, value);
+>
+>     /* Disable patch -> call original via pointer -> re-enable */
+>     fpb_enable_patch(0, false);
+>     ORIG_DIGITALWRITE(pin, value);
+>     fpb_enable_patch(0, true);
+> }
+> ```
+>
+> The workbench generates this pattern automatically when the original function address is known.
+
+## Supported Hardware
+
+| Feature | Spec |
+|---------|------|
+| Architecture | ARMv7-M, ARMv8-M |
+| Tested MCU | STM32F103C8T6 |
+| Patch Slots | 6 (FPB v1) or 8 (FPB v2) |
+| Patch Modes | Trampoline / Direct (ARMv7-M REMAP), DebugMonitor (ARMv8-M BKPT) |
+| RTOS Support | Bare-metal, NuttX |
+| Connection | Serial (USB-to-UART or USB CDC) |
+
+
+<details>
+<summary>CMake Build Options</summary>
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `APP_SELECT` | 1 | Application selection (3 = func_loader) |
+| `FL_ALLOC_MODE` | STATIC | Memory allocation: STATIC or LIBC |
+| `FPB_NO_DEBUGMON` | OFF | Disable DebugMonitor mode |
+
+</details>
+
+<details>
+<summary>Project Structure</summary>
+
+```
+FPBInject/
+├── Source/                 # FPB driver, trampoline, DebugMonitor
+├── App/
+│   ├── func_loader/        # Serial protocol, memory allocator, FPB control
+│   ├── inject/             # Injection helpers
+│   └── tests/              # Firmware unit tests (host-based, with coverage)
+├── Project/                # Platform HAL (STM32F10x, Arduino API)
+├── Tools/
+│   └── WebServer/          # Workbench (Flask backend + JS frontend) & CLI
+└── Docs/                   # Architecture, CLI reference, WebServer guide
+```
+
+</details>
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](Docs/Architecture.md) | FPB internals, patch modes, memory layout, protocol |
+| [CLI Reference](Docs/CLI.md) | All CLI commands with examples and JSON output format |
+| [WebServer Guide](Docs/WebServer.md) | Workbench setup and usage |
+
+## License
+
+[MIT](LICENSE)
+
+## References
+
+- [ARM Cortex-M3 Technical Reference Manual](https://developer.arm.com/documentation/ddi0337)
+- [ARMv7-M Architecture Reference Manual](https://developer.arm.com/documentation/ddi0403)
+- [STM32F103 Reference Manual](https://www.st.com/resource/en/reference_manual/rm0008.pdf)

fpbinject-1.6.8/README.md

@@ -0,0 +1,220 @@
+# FPBInject
+
+**English** | [中文](README_zh.md)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Platform](https://img.shields.io/badge/Platform-STM32F103-blue.svg)](https://www.st.com/en/microcontrollers-microprocessors/stm32f103.html)
+[![Platform](https://img.shields.io/badge/Platform-NuttX-blue.svg)](https://github.com/apache/nuttx)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/FASTSHIFT/FPBInject)
+[![CI](https://github.com/FASTSHIFT/FPBInject/actions/workflows/ci.yml/badge.svg)](https://github.com/FASTSHIFT/FPBInject/actions/workflows/ci.yml)
+
+Runtime code injection for ARM Cortex-M. Replace any function on a running MCU through a serial connection — no reflashing, no debugger, no downtime.
+
+FPBInject uses the [Flash Patch and Breakpoint (FPB)](https://developer.arm.com/documentation/ddi0337/h/debug/about-the-flash-patch-and-breakpoint-unit--fpb-) hardware unit to intercept function calls and redirect them to your custom code in RAM, while the original Flash stays untouched.
+
+![FPBInject Workbench](Docs/images/webserver-overview.png)
+
+## Traditional vs FPBInject
+
+```mermaid
+gantt
+    title Iteration cycle comparison (typical STM32 project)
+    dateFormat  s
+    axisFormat  %Ss
+
+    section Traditional
+    Edit code          : a1, 0, 5s
+    Compile & link     : a2, after a1, 15s
+    Erase flash        : a3, after a2, 3s
+    Flash write        : a4, after a3, 5s
+    MCU reboot         : a5, after a4, 2s
+    Reproduce issue    : a6, after a5, 5s
+
+    section FPBInject
+    Edit code          : b1, 0, 5s
+    Compile & inject   : b2, after b1, 1s
+    Reproduce issue    : b3, after b2, 5s
+```
+
+The traditional cycle touches flash on every iteration — compile, erase, write, reboot, then finally reproduce the issue. With FPBInject, the MCU never stops: save your patch, it's live in under a second. No pit stop required.
+
+## How It Works
+
+```mermaid
+flowchart LR
+    A["caller()<br/>calls foo()"] -->|"FPB intercepts<br/>foo's address"| B["Trampoline<br/>in Flash"]
+    B -->|"Jump to RAM"| C["Your Code<br/>in RAM"]
+```
+
+The FPB unit matches the target function's address, redirects execution through a trampoline in Flash, which jumps to your replacement function in RAM. All handled by hardware — zero software overhead on the call path.
+
+## Workbench
+
+FPBInject ships with a browser-based workbench for the full workflow: browse symbols, read disassembly, write patches, and inject — all from one interface.
+
+### Symbol Search & Disassembly
+
+Search the firmware's symbol table, click a function to view its disassembly or decompiled source.
+
+![Disassembly View](Docs/images/webserver-disasm.png)
+
+### Manual Inject
+
+Write your replacement function in C, then hit inject. The workbench compiles, uploads, and patches — typically under a second.
+
+![Inject View](Docs/images/webserver-inject.png)
+
+### Auto Inject
+
+Point the workbench at your source directory and enable file watching. Add `/* FPB_INJECT */` before any function you want to patch, then just save the file — the workbench detects the change, recompiles, and re-injects automatically.
+
+![Auto Inject - Editor](Docs/images/editor-auto-inejct.png)
+
+![Auto Inject - Workbench](Docs/images/webserver-auto-inject.png)
+
+## File Transfer (Optional)
+
+FPBInject also supports file transfer over serial — browse, upload, and download files on the device's filesystem. Supports drag-and-drop (files and folders), CRC verification, and progress tracking.
+
+Filesystem backends: POSIX (NuttX VFS, Linux), FatFS, standard C library (stdio), or custom implementations via the `fl_fs_ops_t` interface.
+
+![File Transfer](Docs/images/file-transfer.png)
+
+## Quick Start
+
+### 1. Build & Flash Firmware
+
+```bash
+git clone https://github.com/FASTSHIFT/FPBInject.git
+cd FPBInject
+
+cmake -B build -DAPP_SELECT=3 -DCMAKE_TOOLCHAIN_FILE=cmake/arm-none-eabi-gcc.cmake
+cmake --build build
+
+st-flash write build/FPBInject.bin 0x08000000
+```
+
+### 2. Start the Workbench
+
+```bash
+cd Tools/WebServer
+pip install -r ../requirements.txt
+python main.py
+```
+
+Open `http://127.0.0.1:5500` in your browser, connect to the serial port, load your ELF file, and start patching.
+
+### 3. Or Use the CLI
+
+All commands output JSON, designed for scripting and AI agent integration.
+
+```bash
+# Search for functions
+python fpb_cli.py search firmware.elf "gpio"
+
+# View disassembly
+python fpb_cli.py disasm firmware.elf digitalWrite
+
+# Inject a patch
+python fpb_cli.py --port /dev/ttyACM0 --elf firmware.elf \
+    --compile-commands build/compile_commands.json \
+    inject digitalWrite patch.c
+```
+
+See the [CLI Guide](Docs/CLI.md) for the full command reference.
+
+## Writing Patches
+
+Create a C file with the `/* FPB_INJECT */` marker. The function signature must match the original.
+
+```c
+#include <Arduino.h>
+
+/* FPB_INJECT */
+__attribute__((section(".fpb.text"), used))
+void digitalWrite(uint8_t pin, uint8_t value) {
+    printf("Patched: pin=%d val=%d\n", pin, value);
+    value ? digitalWrite_HIGH(pin)
+          : digitalWrite_LOW(pin);
+}
+```
+
+> To call the original function from injected code, you need two things: a function pointer pointing directly at the original address (bypassing the FPB redirect), and temporarily disabling the patch around the call. Direct calls by name will still be intercepted by FPB and cause infinite recursion.
+>
+> ```c
+> /* Define a function pointer to the original address (| 1 sets the Thumb bit) */
+> typedef void (*digitalWrite_fn_t)(uint8_t, uint8_t);
+> static digitalWrite_fn_t const ORIG_DIGITALWRITE = (digitalWrite_fn_t)(0x08001234 | 1);
+>
+> /* FPB_INJECT */
+> __attribute__((section(".fpb.text"), used))
+> void digitalWrite(uint8_t pin, uint8_t value) {
+>     printf("Patched: pin=%d val=%d\n", pin, value);
+>
+>     /* Disable patch -> call original via pointer -> re-enable */
+>     fpb_enable_patch(0, false);
+>     ORIG_DIGITALWRITE(pin, value);
+>     fpb_enable_patch(0, true);
+> }
+> ```
+>
+> The workbench generates this pattern automatically when the original function address is known.
+
+## Supported Hardware
+
+| Feature | Spec |
+|---------|------|
+| Architecture | ARMv7-M, ARMv8-M |
+| Tested MCU | STM32F103C8T6 |
+| Patch Slots | 6 (FPB v1) or 8 (FPB v2) |
+| Patch Modes | Trampoline / Direct (ARMv7-M REMAP), DebugMonitor (ARMv8-M BKPT) |
+| RTOS Support | Bare-metal, NuttX |
+| Connection | Serial (USB-to-UART or USB CDC) |
+
+
+<details>
+<summary>CMake Build Options</summary>
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `APP_SELECT` | 1 | Application selection (3 = func_loader) |
+| `FL_ALLOC_MODE` | STATIC | Memory allocation: STATIC or LIBC |
+| `FPB_NO_DEBUGMON` | OFF | Disable DebugMonitor mode |
+
+</details>
+
+<details>
+<summary>Project Structure</summary>
+
+```
+FPBInject/
+├── Source/                 # FPB driver, trampoline, DebugMonitor
+├── App/
+│   ├── func_loader/        # Serial protocol, memory allocator, FPB control
+│   ├── inject/             # Injection helpers
+│   └── tests/              # Firmware unit tests (host-based, with coverage)
+├── Project/                # Platform HAL (STM32F10x, Arduino API)
+├── Tools/
+│   └── WebServer/          # Workbench (Flask backend + JS frontend) & CLI
+└── Docs/                   # Architecture, CLI reference, WebServer guide
+```
+
+</details>
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](Docs/Architecture.md) | FPB internals, patch modes, memory layout, protocol |
+| [CLI Reference](Docs/CLI.md) | All CLI commands with examples and JSON output format |
+| [WebServer Guide](Docs/WebServer.md) | Workbench setup and usage |
+
+## License
+
+[MIT](LICENSE)
+
+## References
+
+- [ARM Cortex-M3 Technical Reference Manual](https://developer.arm.com/documentation/ddi0337)
+- [ARMv7-M Architecture Reference Manual](https://developer.arm.com/documentation/ddi0403)
+- [STM32F103 Reference Manual](https://www.st.com/resource/en/reference_manual/rm0008.pdf)

fpbinject-1.6.8/Tools/WebServer/__init__.py

@@ -0,0 +1,10 @@
+"""FPBInject — runtime code injection for ARM Cortex-M via the FPB unit.
+
+This package bundles the WebServer, CLI, and supporting modules. The physical
+layout lives under ``Tools/WebServer/`` and is mapped to the import name
+``fpbinject`` via setuptools ``package-dir`` (see pyproject.toml).
+"""
+
+from fpbinject.version import __version__
+
+__all__ = ["__version__"]

fpbinject-1.6.8/Tools/WebServer/__main__.py

@@ -0,0 +1,9 @@
+"""Enable ``python -m fpbinject`` to launch the WebServer.
+
+Equivalent to the ``fpbinject-server`` console script.
+"""
+
+from fpbinject.main import main
+
+if __name__ == "__main__":
+    main()

fpbinject-1.6.8/Tools/WebServer/app/__init__.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+
+# MIT License
+# Copyright (c) 2025 - 2026 _VIFEXTech
+
+"""
+FPBInject WebServer Flask Application Package.
+
+This package contains the Flask application factory and route blueprints.
+"""
+
+import os
+
+from flask import Flask
+from flask_cors import CORS
+
+# Locate the package root (holds templates/ and static/) via importlib.resources
+# so it resolves correctly whether run from source or an installed wheel.
+try:
+    from importlib.resources import files as _res_files
+
+    WEBSERVER_DIR = str(_res_files("fpbinject"))
+except Exception:  # pragma: no cover - fallback for odd layouts
+    WEBSERVER_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def create_app():
+    """Create and configure the Flask application."""
+    app = Flask(
+        "fpbinject",
+        template_folder=os.path.join(WEBSERVER_DIR, "templates"),
+        static_folder=os.path.join(WEBSERVER_DIR, "static"),
+    )
+    CORS(app)
+
+    # Import and register routes
+    from fpbinject.routes import register_routes
+
+    register_routes(app)
+
+    return app