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