File Format and Code Generation

This page covers how wiRedPanda saves and loads circuits, exports to hardware description languages, visualizes waveforms, and manages resources and translations.

---

The .panda File Format

Circuit files (.panda) use a binary format (App/IO/Serialization.h):

[Preamble]
  - Magic number (0x57504346 = "WPCF") + format version
  - Metadata (QMap): dolphin data, rect, etc.

[Elements]
  - Element count
  - For each element:
    - Type (ElementType)
    - Position, rotation, flip state
    - Input and output ports with IDs
    - Element-specific properties (frequency, color, etc.)

[Connections]
  - Connection count
  - For each connection:
    - Source port ID (output)
    - Destination port ID (input)

On load, a port map is built during element deserialization so that connections can resolve their endpoints. The format is backward-compatible and can read files from older wiRedPanda versions.

Version History

The file App/IO/VersionInfo.h tracks all format versions:

Version	Release	Key Changes
V_1_1	2015	Clock element added
V_2_4	2019	Audio element support (Buzzer, AudioBox)
V_3_1	2021	Lock state for input elements; display colors
V_4_1	2024	QMap-based format; port serial IDs
V_4_2	2024	TruthTable output data stored in file
V_4_5	2025	Preamble gains a metadata QMap
V_4_6	2025	Preamble unified into a single metadata QMap (dolphin filename and scene rect folded in)
V_4_7	2026	QNEConnection uses QMap-based serialization
V_5_0	2026	File format version bump for 5.0.0

The deserialization code reads the file version and applies automatic migrations as needed. Reading older versions is always supported.

---

Code Generation (App/CodeGen)

Arduino (App/CodeGen/ArduinoCodeGen.cpp)

Converts a circuit into an Arduino sketch:

• Maps circuit inputs/outputs to GPIO pins.
• Emits setup() with pinMode() calls.
• Emits computeLogic() with boolean expressions for combinational logic and state machines for sequential elements.
• Supports multiple board configurations (Uno, Mega, etc.).
• Generates testbench for validation.
• Supports IC hierarchy.

SystemVerilog (App/CodeGen/SystemVerilogCodeGen.cpp)

Converts a circuit into synthesizable SystemVerilog:

• Emits module declarations with input/output ports.
• Generates assign statements for combinational logic.
• Handles hierarchical IC modules recursively.
• Supports sequential elements (flip-flops).
• Can be validated with iverilog, yosys, and verilator.

---

BeWavedDolphin (Waveform Viewer)

The built-in waveform viewer (App/BeWavedDolphin/) provides signal visualization, similar to GTKWave:

• BeWavedDolphin.cpp: main tool window
• BeWavedDolphinUI.cpp: generated UI layout
• WaveformView.cpp: waveform rendering
• SignalModel.cpp: data model with input and output signals
• SignalDelegate.cpp: item delegate for signal cells
• Serializer.cpp: saves/loads waveform captures

Features:

• Table-based: Rows = signals, Columns = time steps.
• Simulation: Runs the circuit for every input combination (or user-specified patterns).
• Visualization: Renders waveforms as line plots or binary values.
• Export: PDF, PNG, and text formats.
• Interactive: Users can edit input patterns, set clock waves, and zoom.

Access it from the Simulation menu → Waveform (Ctrl+W) to see how signals propagate through a circuit over time. Ideal for analyzing sequential circuits.

---

Resources and Internationalization

Element Icons

Icons live in App/Resources/Components/, organized by category:

• Input/, Logic/, Memory/, Output/, Misc/
• SVG format for scalability

Translations

wiRedPanda supports 39 languages:

• .ts files (Qt Linguist) in App/Resources/Translations/
• Managed via Weblate
• Compiled to .qm during build
• Uses tr() and QT_TR_NOOP() in code

To add a new translatable string:

QString msg = tr("New translatable message");

For more details on contributing translations, see the Translation Guide.

---

See Also

• Architecture Overview — Where I/O and code generation fit in the overall architecture
• Element System — The elements that are serialized and exported
• Testing and CI — Tests for serialization and code generation