67 lines
4.6 KiB
Markdown
67 lines
4.6 KiB
Markdown
# PyBusMonitor1553 - AI Coding Instructions
|
|
|
|
## Project Overview
|
|
MIL-STD-1553 bus monitor and simulator for radar system integration (GRIFO-F/TH). Receives/transmits 1553 messages over UDP, supports both CLI and Tkinter GUI modes.
|
|
|
|
## Architecture
|
|
|
|
### Data Flow
|
|
```
|
|
UDP Network → UdpHandler → MessageDispatcher → Message Objects (MsgA1-A8, MsgB1-B8)
|
|
↓
|
|
GUI/CLI ← RadarController ← TrafficScheduler → PacketBuilder → UDP Network
|
|
```
|
|
|
|
### Key Modules
|
|
- **lib1553/**: Protocol layer - message definitions, field descriptors, headers
|
|
- **core/**: Business logic - dispatcher, network, scheduler, controller
|
|
- **gui/**: Tkinter-based bus monitor interface
|
|
- **utils/**: Debug helpers (printer)
|
|
|
|
## Message System Patterns
|
|
# PyBusMonitor1553 — AI Coding Instructions (condensed)
|
|
|
|
Purpose: short, actionable guidance for AI agents to be productive in this repo.
|
|
|
|
**Big Picture**
|
|
- **Data flow**: UDP network → UDP handler/receiver → MessageDispatcher → Message objects (lib/Grifo_E_1553lib or pybusmonitor1553 messages) → GUI/CLI or TrafficScheduler → PacketBuilder → UDP sender. Key components live under `pybusmonitor1553/` and `___OLD/_old/Grifo_E_1553lib/src`.
|
|
- **Why this layout**: protocol parsing is separated (message descriptors & pack/unpack) from runtime orchestration (schedulers, controllers, GUI) to keep message definitions deterministic and testable.
|
|
|
|
**Where to look (quick links)**
|
|
- **Message descriptors**: `pybusmonitor1553/Grifo_E_1553lib/src/Grifo_E_1553lib` and `pybusmonitor1553/messages/` — add new messages here.
|
|
- **Dispatcher / registry**: look for `_init_registry()` in dispatching code (search for `MessageDispatcher`/`dispatcher`).
|
|
- **UDP I/O & parser**: `pybusmonitor1553/mil1553udp.py`, `pybusmonitor1553/udp_parser.py`, `pybusmonitor1553/udp_receiver.py`, `pybusmonitor1553/udp_sender.py`.
|
|
- **Docs & mapping**: `doc/C++-Python-Message-Mapping.md`, `doc/ICD-Implementation-Notes.md`.
|
|
- **C++ reference (source-of-truth for ICD mismatches)**: `___OLD/_old/cpp/GrifoScope/GrifoSdkEif/pub/TH/th_b1553_icd.h`.
|
|
|
|
**Project-specific conventions (do not assume defaults)**
|
|
- **Field descriptors**: messages use descriptor classes (BitField, EnumField, ScaledField, ASCIIField). Use existing patterns in `lib1553/fields.py` or `Grifo_E_1553lib` equivalents.
|
|
- **Bit numbering**: MIL-STD-1553 MSB=0 convention (Bit 0 is MSB). Descriptor layer converts to Python-native bit ordering — follow existing field args (word_index, start_bit, width).
|
|
- **Endianness**: UDP headers are little-endian; message payloads are big-endian (network order). Use MessageBase.pack()/unpack() helpers.
|
|
- **Validity flags**: inverse logic is common (0 = VALID, 1 = INVALID). Double-check when changing message semantics.
|
|
|
|
**Adding or changing messages (concrete steps)**
|
|
1. Copy an existing message module in `pybusmonitor1553/Grifo_E_1553lib/src/Grifo_E_1553lib/messages/` or `pybusmonitor1553/messages/` and update fields.
|
|
2. Use the same descriptor args: `BitField(word_index=0, start_bit=0, width=1)`, `ScaledField(..., lsb_value=..., signed=True)`, `EnumField(..., enum_cls=...)`.
|
|
3. Register new message in the messages package `__init__.py` and in dispatcher registry (`_init_registry()` or equivalent).
|
|
4. When in doubt about bit positions, compare against `___OLD/_old/cpp/.../th_b1553_icd.h` and `doc/ICD-Implementation-Notes.md` — C++ implementation wins over textual ICD.
|
|
|
|
**Developer workflows & commands**
|
|
- Run app (GUI default): `python -m pybusmonitor1553`
|
|
- CLI mode: `python -m pybusmonitor1553 --cli`
|
|
- Run tests: `pytest` (see `tests/` and `pytest.ini`).
|
|
- Network overrides: set `PYBM_RX_IP` / `PYBM_RX_PORT` environment variables before running if needed.
|
|
|
|
**Testing & debugging tips**
|
|
- Field-level tests: create minimal `DummyMsg(MessageBase)` tests to verify pack/unpack and scaling.
|
|
- Binary compatibility: use `tools/compare_a2_messages.py` for A2/Ax comparisons where present.
|
|
- Network debug flags: set `DEBUG_PACKETS`, `DEBUG_BUILD` in `network.py` / `packet_builder.py` / `scheduler.py` for hex dumps.
|
|
|
|
**Integration points & pitfalls**
|
|
- UDP framing and parity follow the proprietary UDP1553 layout — don't assume standard library framing.
|
|
- Several ICD entries are inconsistent; always cross-check with the C++ header used in the original product.
|
|
- Some message fields are implemented as multi-word (MSW/LSW) read-only properties — editing one half without updating pack/unpack will break compatibility.
|
|
|
|
If anything in this condensed guide is unclear or you'd like more examples (e.g., a concrete `msg_xx.py` scaffold or dispatcher registration diff), tell me which area to expand.
|
|
|