================================================================================
FOSSEE eSim Research Migration Project (RMP) - Simulation Guide
Project Title: FIGARO TRNG (Fibonacci-Galois Ring Oscillator TRNG)
Participant   : Harshitha Kota (RGUKT Nuzvid)
Target Tool   : eSim Version 2.3 (FOSSEE, IIT Bombay)
================================================================================

1. PREREQUISITES & COMPATIBILITY
--------------------------------------------------------------------------------
- Software: eSim Version 2.3 (Installed in standard directory, e.g. C:\FOSSEE\eSim)
- Operating System: Windows 10/11 or Linux
- Components: Ngveri (Icarus Verilog), KiCad (Eeschema), and Ngspice backend.

2. STEP-BY-STEP PROCEDURE TO OPEN AND SIMULATE IN eSim 2.3
--------------------------------------------------------------------------------

[Step 1] Open eSim 2.3:
  - Launch eSim 2.3 on your system.

[Step 2] Open the Project:
  - Click on "Open Project" from the top menu or left sidebar.
  - Browse to this project directory and select the "FIGARO_TRNG" folder.
  - The project files (FIGARO_TRNG.proj, FIGARO_TRNG.sch, etc.) will load into the workspace.

[Step 3] Open and Verify Schematic (Optional):
  - Click "Open Schematic" to open KiCad (Eeschema).
  - Verify that the top-level schematic "FIGARO_TRNG.sch" loads with the figaro_trng
    digital core, ADC/DAC bridges (adc_bridge_3, dac_bridge_2, dac_bridge_8), and pulse sources.

[Step 4] Convert KiCad to Ngspice:
  - In the main eSim 2.3 window, click "Convert KiCad to Ngspice".
  - The transient analysis settings will automatically populate from the 'analysis' file:
      * Analysis Type: Transient (.tran)
      * Start Time: 0 ns
      * Stop Time: 500 ns (or 1000 ns)
      * Step Time: 1 ns (1e-09)
  - Click "Convert".

[Step 5] Run Simulation:
  - Click on "Simulate" / "Run Simulation" in eSim.
  - Ngspice will execute the mixed-signal transient simulation.

3. HOW TO VIEW THE SIMULATION WAVEFORMS
--------------------------------------------------------------------------------

Method A: Viewing in eSim Python Plotting Window
  - After simulation completes, the Python Plotting window will open automatically.
  - To view the 8-bit random output with clear separation (as shown in the report):
      Check the boxes for:
        v(out_b0)
        v(out_b1)+6
        v(out_b2)+12
        v(out_b3)+18
        v(out_b4)+24
        v(out_b5)+30
        v(out_b6)+36
        v(out_b7)+42
  - To view sampling and control clocks:
      Select v(in_clk), v(out_raw_clk), and v(out_rnd_bit).
  - Click "Plot" to view the non-deterministic switching waveforms.

Method B: Direct Ngspice Batch Execution (Command Line)
  - Open terminal inside the FIGARO_TRNG directory and run:
      ngspice FIGARO_TRNG.cir.out
  - The simulation will execute and generate plot_data_v.txt and plot_data_i.txt.

4. DIRECTORY CONTENTS
--------------------------------------------------------------------------------
- FIGARO_TRNG.proj              : eSim project descriptor
- FIGARO_TRNG.pro               : KiCad project file
- FIGARO_TRNG.sch               : KiCad schematic file
- FIGARO_TRNG.cir / .cir.out    : Ngspice circuit netlists
- FIGARO_TRNG.bak / cache.bak   : Schematic & library cache backups
- FIGARO_TRNG_Previous_Values.xml : Component parameter XML
- analysis                      : Transient simulation configuration (.tran)
- figaro_trng.v                 : Top-level FIGARO TRNG Verilog module
- firo.v                        : Fibonacci Ring Oscillator Verilog module
- garo.v                        : Galois Ring Oscillator Verilog module
- tb_figaro_trng.v              : Verilog digital testbench
- plot_data_v.txt / _i.txt      : Exported transient simulation data
- random_bits.png               : Pre-simulated eSim 2.3 Ngspice waveform plot
- figarotrngabstract.pdf        : Official project report PDF

================================================================================
For any queries, please refer to: https://esim.fossee.in/
================================================================================
