Enhance Communications Package Between GCS and FDS

[TylerFlar]

Objective

Enhance communications package to enable data exchange between the Ground Control System (GCS) and the Field Device Software (FDS), focusing on defining packets, implementing callbacks, and ensuring efficient and reliable data transmission.

Requirements

General

• Bidirectional Communication: The package MUST enable two-way communication between GCS and FDS.
• Acknowledgments: The package MUST implement acknowledgment mechanisms for critical commands and configurations.
• State Encoding: Finite state values like gps_state and ping_finder_state SHOULD be efficiently encoded for transmission and converted back on the receiving end.
• Timestamp Handling: The packet_sent_timestamp WILL be set by the communications package before sending.
• Implementation Flexibility: The methods for checksums and state variable encoding MAY be determined by the implementer.

Packet Definitions

From FDS to GCS

1. Ping Detection Packet

   • Fields:
     • drone_latitude_degrees: float
     • drone_longitude_degrees: float
     • drone_altitude_meters: float
     • transmitter_power_db: float
     • transmitter_frequency_hz: int
     • packet_sent_timestamp: datetime
     • checksum: implementation-defined
   • Purpose: Notify GCS of detected pings.

2. Heartbeat Packet

   • Fields:
     • drone_latitude_degrees: float or None
     • drone_longitude_degrees: float or None
     • drone_altitude_meters: float or None
     • drone_heading_degrees: float
     • gps_state: implementation-defined
     • ping_finder_state: implementation-defined
     • packet_sent_timestamp: datetime
     • checksum: implementation-defined
   • Purpose: Provide regular status updates.

3. Transmitter Location Estimation Packet

   • Fields:
     • transmitter_frequency_hz: int
     • transmitter_latitude_degrees: float
     • transmitter_longitude_degrees: float
     • transmitter_altitude_meters: float
     • packet_sent_timestamp: datetime
     • checksum: implementation-defined
   • Purpose: Share estimated transmitter locations.

4. Acknowledgment Packets

   • Configuration Acknowledgment
     • Fields:
       • success: bool
       • message: implementation-defined
       • packet_sent_timestamp: datetime
       • checksum: implementation-defined
   • Command Acknowledgment
     • Fields:
       • command: implementation-defined
       • success: bool
       • message: implementation-defined
       • packet_sent_timestamp: datetime
       • checksum: implementation-defined

From GCS to FDS

1. Set Ping Finder Configuration

   • Fields:
     • run_number_id: int
     • target_frequencies_hz: list of int
     • Optional fields with defaults:
       • sampling_rate_hz: int (default 2,500,000)
       • gain_db: float (default 56.0)
       • center_frequency_hz: int (default: average of target_frequencies_hz)
       • ping_width_ms: int (default 25)
       • ping_min_snr: int (default 25)
       • ping_max_length_multiplier: float (default 1.5)
       • ping_min_length_multiplier: float (default 0.5)
     • checksum: implementation-defined
   • Purpose: Configure the Ping Finder.

2. Control Commands

   • Start Flight Command
     • Fields:
       • checksum: implementation-defined
   • Reset Command
     • Fields:
       • checksum: implementation-defined
   • End Flight Command
     • Fields:
       • checksum: implementation-defined

Data Integrity and Efficiency

• Data Integrity: The implementer MUST implement measures (e.g., checksums) to ensure packets are received correctly.
• Efficient Encoding: State variables and other data SHOULD be encoded efficiently for transmission.

Tasks

1. Review Existing Communications Code

   • Familiarize yourself with the previous communications implementation to understand packet handling and checksum usage:
     • Old Communications Programming Repository

2. Define State Encoding

   • Decide on encoding methods for gps_state and ping_finder_state.
   • Ensure consistent encoding between GCS and FDS.

3. Implement Data Integrity Measures

   • Choose a method for ensuring data integrity (e.g., checksum, CRC).
   • Apply it to all packets.

4. Develop Packet Structures

   • Define packet formats with efficient encoding.
   • Include necessary fields as specified.

5. Develop Packet Sending/Receiving

   • GCS/FDS objects provide functions to create and send packets.
   • GCS/FDS objects decode received packets, update any state info, and call user-specified callback function for packet.

Deliverables

• Source Code

  • The communications package MUST include all required functionalities.
  • Callbacks and handlers MUST be implemented on both GCS and FDS.

• Documentation

  • Detailed packet structures and encoding methods MUST be documented.
  • Integration instructions and examples SHOULD be provided.

• Test Cases

  • Scripts or programs demonstrating communication MUST be included.
  • Test results validating functionality and data integrity SHOULD be provided.

• Pull Request

  • Submit to the dev branch with all deliverables.

[ntlhui]

Consider which level of the OSI network model this package will sit at and what guarantees the underlying layers provide.