Skip to content

README.md

Latest commit

 

History

History
253 lines (177 loc) · 6.48 KB

README.md

File metadata and controls

253 lines (177 loc) · 6.48 KB
Raw

eSim Docker

eSim Logo eSim

Run eSim anywhere using Docker - No installation required!

Download Launcher • Quick Start • Troubleshooting

About

This project provides a Docker-based solution to run eSim (Electronic Circuit Simulation) on any operating system. eSim is developed by FOSSEE, IIT Bombay and integrates KiCad, Ngspice, and Python for circuit design and simulation.

What's included:

  • KiCad for schematic design
  • Ngspice for SPICE simulation
  • GAW3 analog waveform viewer
  • All eSim libraries pre-configured

Quick Start

Step 1: Get Docker

Download Docker Desktop and make sure it's running.

Step 2: Download the Launcher

Go to Releases and download:

  • Windows: eSim-Launcher-Windows.exe
  • Linux: eSim-Launcher-Linux
  • macOS: eSim-Launcher-macOS

Step 3: Run it

Windows: Double-click the .exe file.

Linux: Open terminal and run:

chmod +x eSim-Launcher-Linux
./eSim-Launcher-Linux

macOS: Open terminal and run:

chmod +x eSim-Launcher-macOS
./eSim-Launcher-macOS

OR

Step 1: Get Docker

Download Docker Desktop and make sure it's running.

Step 2: Get Python3

Download and installPython3.

Step 3: Download the files

  • Download Dockerfile. Note that the Dockerfile should be without extension. If the Dockerfile downloads with extension rename the file and remove the extension.
  • Download run_esim_docker.py.

Step 3: Run it

Make sure docker is already running in the background. Windows: Open terminal and run:

python3 run_esim_docker.py

Linux: Open terminal and run:

chmod +x run_esim_docker.py
python3 run_esim_docker.py

macOS: Open terminal and run:

chmod +x run_esim_docker.py
python3 run_esim_docker.py

Display Modes

The launcher offers two display modes:

Mode Best For How it Works
VNC Windows, macOS Opens eSim in your browser. Works everywhere, no setup needed.
X11 Linux Opens eSim in a native window. Best performance on Linux.

Recommendations

  • Linux → Use X11 mode (recommended, no lag)
  • Windows → Use VNC mode (X11 works but KiCad may lag)
  • macOS → Use VNC mode (X11 requires XQuartz)

Both modes work on all platforms - the launcher will guide you through any required setup.

Note for MAC to be run in X11 mode:

  • Install XQuartz on the Mac if you haven't already. You can download it from the XQuartz website.
  • Enable network connections in XQuartz: Go to XQuartz > Preferences > Security tab, and check "Allow connections from network clients".
  • Restart XQuartz and then restart your Docker application after making changes to the security settings.
  • Run xhost +localhost in your Mac's terminal before running the Docker container. This allows local connections to your X server. 
    Run the following command in a terminal:
xhost +localhost
docker run --platform linux/amd64 -it --env="DISPLAY=host.docker.internal:0" -v /tmp/.X11-unix/:/tmp/.X11-unix/:rw   esim:latest

Command Line Usage

# Interactive menu
python run_esim_docker.py

# Direct VNC mode
python run_esim_docker.py --vnc

# Direct X11 mode  
python run_esim_docker.py --x11

# Update image
python run_esim_docker.py --pull

Workspace

Your projects are saved to:

OS Location
Windows C:\Users\<you>\eSim_Workspace
Linux/macOS ~/eSim_Workspace

This folder is mounted into the container, so your files persist.

Steps to Copy File from Local Path to docker container

To copy a file or folder from your local machine into a Docker container, use the docker cp command.

Please follow these commands on a terminal as an example to copy a folder named counter:

$ docker cp counter4bit/counter4bit.v esim-container:/home/esim-user
$ docker exec -it -u root esim-container bash
$ chown -R esim-user:esim-user /home/esim-user/counter
$ chmod -R 777 /home/esim-user/counter

Troubleshooting

Docker not running

Open Docker Desktop and wait for it to fully start.

Browser shows "localhost not found"

Wait a few seconds and refresh. The container needs time to start.

VNC shows blank screen

Refresh the browser page. If still blank, restart the launcher.

X11 mode: window doesn't appear (Windows)

Make sure VcXsrv is running. The launcher auto-installs it if needed.

X11 mode: window doesn't appear (macOS)

Install XQuartz from xquartz.org, then run xhost +localhost in terminal.

Building from Source

docker build -t esim:latest .
python run_esim_docker.py --build

For Maintainers

This section explains how to set up the automated build pipeline.

Setting up GitHub Actions

  1. Copy the workflow file to the repository root:

    docker-launcher/github-workflow/docker-launcher-build.yml
→ .github/workflows/docker-launcher-build.yml

  2. Update the Docker image URL in run_esim_docker.py (line 21):

    DOCKER_IMAGE = "ghcr.io/fossee/esim-docker-launcher:latest"

Creating a Release

Option 1: Manual trigger

  1. Go to Actions tab on GitHub
  2. Select "Build and Release" workflow
  3. Click "Run workflow"

Option 2: Using tags

git tag docker-launcher-v1.0.0
git push origin docker-launcher-v1.0.0

Both methods will build executables for Windows, Linux, and macOS, then create a GitHub Release with download links.

Build Triggers

Event Builds Docker Builds Executables
Tag docker-launcher-v* Yes Yes
Manual workflow dispatch Yes Yes
PR modifying docker-launcher/ Yes No

Credits

  • eSim - FOSSEE Team, IIT Bombay
  • KiCad - KiCad Developers
  • Ngspice - Ngspice Team
  • GAW3 - Hervé Quillévéré, Stefan Schippers
  • Verilator - Verilator Team
  • GHDL - GHDL Team

Created as part of the FOSSEE Internship program.

License

GPL-3.0