64 lines
4.9 KiB
Markdown
64 lines
4.9 KiB
Markdown
## 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. |