gps-denied-onboard/docs/02_components/01_Service_Interface/spec.md

Service Interface Component

Detailed Description

The Service Interface serves as the external communication boundary of the ASTRAL-Next system. It implements the ZeroMQ patterns required for the background service architecture. It isolates the core logic from the communication protocol, allowing for easy testing and integration with different ground control stations or UI clients.

It manages two primary sockets:

1. Command Socket (REP): Synchronous request-reply pattern for control commands (Start, Stop, User Input).
2. Data Socket (PUB): Asynchronous publish-subscribe pattern for broadcasting telemetry and localization results.

API Methods

start_service

• Input: port_cmd: int, port_data: int
• Output: void
• Description: Initializes the ZeroMQ contexts and binds the sockets to the specified ports. Starts the listener loop in a non-blocking manner (or separate thread).
• Test Cases:
  • Bind to valid ports -> Success.
  • Bind to used ports -> Raise Error.

listen_for_commands

• Input: timeout_ms: int
• Output: CommandObject | None
• Description: Checks the REP socket for incoming messages. If a message is received, it parses the JSON and validates the schema. Returns a structured Command object (e.g., StartCmd, UserFixCmd) or None if timeout.
• Test Cases:
  • Receive valid JSON {"cmd": "START", ...} -> Return StartCmd object.
  • Receive invalid JSON -> Send error reply, Return None.
  • Timeout -> Return None.

send_reply

• Input: response: Dict
• Output: void
• Description: Sends a JSON response back on the REP socket. Must be called after a request is received to complete the REQ-REP cycle.
• Test Cases:
  • Send valid dict -> Success.
  • Send without receiving request -> ZeroMQ Error state.

publish_telemetry

• Input: telemetry: Dict
• Output: void
• Description: Serializes the telemetry dictionary to JSON and publishes it on the PUB socket with the topic "telemetry".
• Test Cases:
  • Publish dict -> Client receives JSON string.

publish_request_input

• Input: request_data: Dict (contains image base64, satellite tiles base64)
• Output: void
• Description: Publishes a high-priority message on a specific topic (e.g., "system_alert") indicating user input is needed.
• Test Cases:
  • Publish huge payload (images) -> Verify serialization performance.

Integration Tests

• Mock Client Test: Spin up a separate process acting as a client. Send "START" command, verify "ACK". Subscribe to telemetry, verify stream of messages.

Non-functional Tests

• Latency: Measure round-trip time for REQ-REP (< 10ms).
• Throughput: Verify it can handle high-frequency status updates (e.g., 100Hz) without lagging the main loop.