<!-- Copilot / AI agent guidance for SXXXXXXX_PyDownloadFwViaSRIO -->
# Quick agent instructions

This repo contains a small Python package (`pydownloadfwviasrio`) and a legacy C++/Qt implementation in `_OLD/` that documents the firmware-download protocol. Focus work on the Python package; use `_OLD/` as the authoritative protocol reference.

- **Run (dev):** `python -m pydownloadfwviasrio` (see `pydownloadfwviasrio/__main__.py`).
- **Key source folders:** `pydownloadfwviasrio/core/` (business logic) and `pydownloadfwviasrio/gui/` (UI).
- **Reference docs:** `doc/system_instruction.md` contains user-specific interaction rules — read before editing code or proposing major changes.

**Important interaction rules (user expectation, speak Italian):**
- Chat language: speak in *Italiano* for all conversation and reasoning.
- Code, identifiers, comments, and docstrings: always in *English*.
- Be critical: if a user suggestion is suboptimal, explain why and propose a better alternative.
- Before giving code: always explain *how* and *why* the solution works.

**Coding standards (project-specific):**
- Python: follow **PEP8**, use **type hints** for functions and complex variables.
- C++: prefer modern standards (C++17/20), RAII, and memory-safety practices.
- Keep code concise and clean; minimal essential comments only.

**Update / delivery protocol (strict):**
1. Small edits (<5 lines): show exactly the changed lines.
2. Function-level edits (>5 lines): provide full contents of all modified functions.
3. Module-level changes: provide the full module source.
4. Deliver one module at a time and wait for user confirmation before proceeding.
5. Always summarize *what* changed and *why* compared to the previous version.

**Project patterns & integration:**
- Keep runtime logic in `pydownloadfwviasrio/core/`; expose a single callable `main()` or similar that `__main__.py` will call.
- Treat `_OLD/` as protocol reference only; copy snippets with attribution comments rather than editing originals.
- The firmware flow in `_OLD/` is typically: host -> SRIO transport -> flash ops (erase → write → verify). Key reference files: `_OLD/linux_app/dwl_fw.cpp`, `_OLD/Vecchia_app/fpgaflashengine.cpp`, `_OLD/Vecchia_app/fpgaflashinterface.h`.

**Developer workflows:**
- Run the package: use the `python -m` invocation above.
- No test harness is present; add small unit-test hooks when implementing core functions.
- C++ components: build with Qt Creator or `qmake`/`make` on Linux when needed.

If you want, I can extract the erase/write/verify pseudocode from `_OLD/linux_app/dwl_fw.cpp` next and produce a Python skeleton implementation in `pydownloadfwviasrio/core/`.
