SXXXXXXX_PyBusMonitor1553/.github/copilot-instructions.md

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.