S1005403_RisCC/.github/copilot-instructions.md

Copilot / AI agent instructions — Target Simulator (concise)

This file contains the minimal, repository-specific guidance an AI coding agent needs to be productive.

1. Big picture

• Type: Python desktop app (Tkinter) that simulates radar targets and communicates with hardware/emulators via SFP/TFTP/Serial.
• Major areas:
  • target_simulator/core/ — simulation, command builders, communicator interfaces (CommunicatorInterface is the contract).
  • target_simulator/gui/ — Tkinter windows; MainView is the app host and coordinates simulation + communicators.
  • target_simulator/utils/ — ConfigManager, logging helpers (utils/logger.py), CSV trace helpers.

2. Key workflows & commands (PowerShell)

• Run app (development): $env:PYTHONPATH='C:\src____GitProjects\target_simulator'; python -m target_simulator
• Open REPL with project path: $env:PYTHONPATH='C:\src____GitProjects\target_simulator'; python
• Run tests (coverage task available): use the workspace task labeled "pytest coverage report" or run directly: $env:PYTHONPATH='C:\src____GitProjects\target_simulator'; pytest --cov=target_simulator.core.models --cov-report=term-missing

3. Project-specific patterns & conventions

• Absolute imports are used throughout; __main__.py inserts the project root into sys.path for convenience.
• Persistence: ConfigManager stores general settings in settings.json and scenarios in scenarios.json (atomic write + rotating backups .bak1, .bak2).
• Logging: central queue-based logging that forwards to console/file/GUI. Use setup_basic_logging(app, LOGGING_CONFIG) and add_tkinter_handler(widget, LOGGING_CONFIG); temporary increases via temporary_log_level(logger, level).
• Simulation: SimulationEngine runs as a daemon thread and emits GUI updates via a Queue; do not change update semantics lightly — runtime sends tgtset without qualifiers while debug GUI may include qualifiers.
• Communicator contract: implement CommunicatorInterface (methods like connect(config)->bool, disconnect(), send_commands(list), property is_open). SFP communicator supports deferred connect and an optional _use_json_protocol flag (checked by engine).

4. Important implementation details to preserve

• Debug vs runtime sending: the SFP debug window intentionally sends tgtset with state qualifiers (Active/Traceable/Restart) while the live SimulationEngine uses tgtset without qualifiers to avoid changing lifecycle flags. See gui/sfp_debug_window.py and core/command_builder.py for the builders.
• Scenarios are saved to a separate scenarios.json; ConfigManager will avoid overwriting it with empty data and performs atomic replace + rotating backups.
• MainView._setup_communicator shows how new communicator types are wired (update this method when adding a protocol).

5. Integration points & external artifacts

• Native libs: Tkinter (GUI). No heavy third-party dependencies are required for core features.
• Optional C++ helpers exist in cpp/ (e.g., BupTFTP.cpp) but are not integrated by default.
• Temporary CSV logs and traces live in Temp/ (filenames configured in settings.json debug block).

6. Files to inspect for common tasks (quick links)

• App start: target_simulator/__main__.py
• Main UI and lifecycle: target_simulator/gui/main_view.py
• Simulation loop and sending logic: target_simulator/core/simulation_engine.py
• Command builders: target_simulator/core/command_builder.py
• Communicators: target_simulator/core/*.py (look for SFP, Serial, TFTP implementations)
• Persistence: target_simulator/utils/config_manager.py and settings.json / scenarios.json
• Logging helpers: target_simulator/utils/logger.py and logger_prefs.json

7. Small examples (copyable snippets)

• Enable module debug at runtime (REPL): import logging; logging.getLogger('target_simulator.gui.sfp_debug_window').setLevel(logging.DEBUG)
• Start app (PowerShell): $env:PYTHONPATH='C:\src____GitProjects\target_simulator'; python -m target_simulator

8. When changing behavior

• If you change how commands are formatted (e.g., build_tgtset_*), update both the SimulationEngine logic and the SFP debug sender to keep debug vs runtime semantics clear.
• If you add a new persistent key, prefer storing it under general in settings.json via ConfigManager.save_general_settings().

9. What the agent should not do automatically

• Do not change scenario storage semantics (moving scenarios back into settings.json), since ConfigManager intentionally separates scenarios and performs backups.

10. If more detail is needed

• Ask which area to expand (GUI wiring, communicator API, command builders, or logging). Provide the specific file and a brief goal and the agent will produce patches and tests.

---

If anything here is unclear or you want additional examples (unit tests, small refactors, or a runtime checklist), tell me which sections to expand and I will iterate.