SXXXXXXX_PyDownloadFwViaSRIO/.github/copilot-instructions.md

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/.