PlatSim_Genova/.github/copilot-instructions.md

Copilot / AI agent instructions for GrifoAutomaticTestEnv

Purpose: concise, actionable guidance for AI coding agents working in this repository.

1. Big picture

• Python-based automated test harness for GRIFO radar. Core responsibilities:
  • 1553 bus access via SWIG bindings in PlatformSimulator/bin (interpreter / _interpreter.pyd).
  • Test framework and helpers under TestEnvironment/env (leo_grifo_* modules).
  • Test scripts under TestEnvironment/scripts (e.g. GRIFO_M_PBIT.py).
  • Simulation mode implemented in GRIFO_M_PBIT_mock.py (opt-in via --simulate).

2. Primary integration & boundaries

• Native 1553 hardware is wrapped by SWIG: PlatformSimulator/bin/interpreter.py -> used by leo_grifo_1553.py.
• Serial and power control are separate modules: leo_grifo_terminal.py and leo_grifo_io_box.py.
• Test scripts call the common API in TestEnvironment/env (singletons such as theGrifo1553, theBrainBox, theRecorder).

3. Key coding patterns to preserve

• Singletons: code expects global singletons (e.g. theGrifo1553 = GrifoInstrumentInterface(...)). Do not replace with factories unless you update all call sites.
• TestCommonInterface: modules implement check(), get(), set() and are consumed via helpers in test_common_function.py (use check() / getValue() / setValue() patterns).
• Recorder pattern: use theRecorder to record test steps (add_step, close_session) rather than ad-hoc prints.
• Path-bootstrap: TestEnvironment/scripts/__init__.py appends ../env and env/site-packages to sys.path; maintain that import behavior for scripts and wrappers.
• Simulation approach: GRIFO_M_PBIT.py detects --simulate and monkey-patches the global singletons with mock objects from GRIFO_M_PBIT_mock.py. Respect the same API surface when changing mocks.

4. Developer workflows / commands (documented and reproducible)

• Quick simulate (recommended):
  • Run run_simulate_simple.bat from repo root (uses system Python).
  • Or: python TestEnvironment/scripts/GRIFO_M_PBIT.py --simulate.
• Production-like simulate (embedded):
  • Run run_simulate.bat to use embedded PlatformSimulator/bin Python/uPlatSim.
• Manual wrapper for CI / debug: python python_simulate_wrapper.py (ensures env/site-packages precedence).

5. Important files to inspect for changes

• TestEnvironment/env/leo_grifo_1553.py — 1553 wrapper; shows check/get/set semantics and theGrifo1553 singleton.
• TestEnvironment/env/leo_grifo_terminal.py — serial parsing rules (%%E, %%F, RECYCLE) and statistics keys.
• TestEnvironment/env/leo_grifo_io_box.py — theBrainBox and power_grifo_on/off helpers.
• TestEnvironment/env/leo_grifo_core.py & test_common_function.py — recorder and common helper functions used by scripts and reports.
• TestEnvironment/scripts/GRIFO_M_PBIT.py — main test flow, known-failures list and CSV/PDF export logic.
• TestEnvironment/scripts/GRIFO_M_PBIT_mock.py — reference mock implementation and configuration options.

6. Testing, CI and safety notes for agents

• Prefer non-invasive edits: simulation mode exists to run and validate logic without hardware — use --simulate in CI.
• Do not change singleton names or function signatures (check, get, set, enable_notification) without sweeping updates across TestEnvironment/scripts.
• When changing report generation, update leo_grifo_test_report.py and ensure generate_pdf_report() callers still pass expected JSON templates from TestEnvironment/json.

7. Suggested quick tasks for agents

• Small bugfix: preserve existing theGrifo1553 usage; add defensive None checks when calling native interface methods.
• Add small unit-style smoke script that runs GRIFO_M_PBIT.py --simulate and asserts exit code 0 and that a PDF appears under TestEnvironment/pdf_reports.

8. Where to find more documentation

• Read GRIFO_Test_Environment_Analysis.md, IMPLEMENTATION_SUMMARY.md, and LAUNCHER_GUIDE.md at repo root for architecture and run details.

If anything here is unclear or you'd like more examples (e.g. common refactors that are safe), tell me which area to expand. If anything here is unclear or you'd like more examples (e.g. common refactors that are safe), tell me which area to expand.

---

9. System / Interaction rules (from repository owner)

• Language: Communicate with maintainers in Italian for chat, reasoning, and explanations. Keep all code, function names, variables, comments and docstrings in English.
• Coding standards: Follow PEP8 for Python, use type hints for functions and complex variables, and prefer clear, small functions. Avoid one-letter variable names.
• Comments: Keep comments essential and concise; do not include historical or debugging notes in committed code.
• Critical thinking: Evaluate proposals and suggest better alternatives when appropriate (performance, security, maintainability). Explain "how" and "why" before providing code.

10. Update protocol (strict - follow these when editing repo files)

• Small changes (<5 lines): show exactly which lines change and the new lines.
• Function-level changes (>5 lines in a few functions): provide full contents of each modified function.
• Module-level changes (majority of a file): provide the full module code.
• Sequential delivery: modify one module at a time and wait for confirmation before the next.
• Provide a brief comparison: what changed and why.

11. Agent notes / safe defaults

• When editing tests or reports, prefer using simulation mode (--simulate) to validate logic without hardware.
• Preserve global singleton names (theGrifo1553, theBrainBox, theRecorder) unless performing a repo-wide refactor.
• Prefer non-invasive fixes that add defensive checks (e.g., if obj is None:) around native calls to interpreter objects.

12. Where to put these instructions

• This file (.github/copilot-instructions.md) is the canonical location; keep it concise and up-to-date.

If you want, I can now: (A) add a short smoke-test script under TestEnvironment/scripts that runs GRIFO_M_PBIT.py --simulate and verifies PDF output, or (B) reformat the file to include inline examples for the update protocol. Which do you prefer?