FIREQ Client Architecture & Reference#

Welcome to the FIREQ-Client API reference and architecture guide. The client acts as the front-end workstation interface that connects to the FIREQ-Server, processes experiment definitions, manages TCP streams, and visualizes acquisition results.

Architectural Overview#

The client framework is organized into three main operational layers:

  1. Connection Layer: Establishes and manages TCP socket sessions with the server.

  2. Protocol & Networking Layer: Implements length-prefixed binary framing and manages background I/O threads.

  3. Experiment & Processing Layer: Resolves YAML templates, reconstructs raw binary DMA acquisition payloads into numerical arrays, and stores experiment data.

Interactive & Runtime Lifecycle#

A standard client runtime lifecycle proceeds as follows:

  1. Instantiation & Connection: The Client instance connects to the specified <SERVER_IP>:<SERVER_PORT> endpoint.

  2. Handshake & Auth: Performs authentication via shared token validation.

  3. YAML Preprocessing: Loads .yaml experiment definitions and resolves internal variable placeholders.

  4. Command Execution: Dispatches execution requests.

  5. Data Streaming & Export: Listens for inbound binary DMA frames, converts complex IQ payloads into structured data, and saves them locally as JSON/Pickle files. The client export command creates the single-data.pkl format consumed by the separate FIREQ_PLOTTER package.

API Submodules#

For detailed class and function signatures, select one of the submodules below:

Core Client & CLI

FIREQ_CLIENT.client.Client

Interactive client for the FIREQ server.

FIREQ_CLIENT.prompt_completer

Command completion for the client REPL.

Protocol & Socket Workers

FIREQ_CLIENT.network.protocol.Message

Simple message type, will be sent over the socket as a json.

FIREQ_CLIENT.network.send_worker.SendWorker

Sends framed messages via a socket using a background thread and a queue.

FIREQ_CLIENT.network.receive_worker.ReceiveWorker

Reads framed messages from a socket in a background thread.

Configuration & Preprocessing

FIREQ_CLIENT.yaml_preprocessor

Preprocessing of experiment YAML configuration files.

Data & Export Utilities

FIREQ_CLIENT.data

Data loading helpers for FIREQ experiment data.

FIREQ_CLIENT.export

Export of experiment data.

Plotting

FIREQ_PLOTTER.plotter.CommandCompleter

Complete commands and command-specific arguments.

FIREQ_PLOTTER.plotting.plot_2d._plot_2d

Interactive 2D plot of the experiment data.

FIREQ_PLOTTER.plotting.plot_3d_heatmap._plot_3d_heatmap

Interactive heatmap.

FIREQ_PLOTTER.plotting.plot_iq._plot_iq

Plot the IQ plane of two experiments and the rotated CDF analysis.

FIREQ_PLOTTER.plotting.plot_spectr._plot_spectr

Compare two spectroscopy experiments and highlight the frequency of maximal distance.