# 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?
