74 lines
4.4 KiB
Markdown
74 lines
4.4 KiB
Markdown
# Sim-Link
|
|
|
|
Sim-Link is a web application designed to take the results of Gazebo simulations, save them, rank the best-performing simulations, and display the detailed results in a clean, easy-to-understand format.
|
|
|
|
## Tech Stack
|
|
- **Frontend:** SvelteKit (built into a completely Static Single Page Application using Bun).
|
|
- **Backend:** Golang.
|
|
- **Database:** SQLite3.
|
|
- **Containerization:** Docker & Docker Compose.
|
|
|
|
## Running with Docker (Recommended)
|
|
|
|
The easiest way to run Sim-Link is by using the provided `docker-compose` environment. This encapsulates the build steps for both the SvelteKit frontend and the Go backend.
|
|
|
|
```bash
|
|
# Build and start the container in the background
|
|
docker compose up -d --build
|
|
```
|
|
*Note: The `results/` folder and `server/` folder are native volume mounts in Docker Compose. This ensures your simulation logs update live, and the `sim-link.db` SQLite file persists on your host machine.*
|
|
|
|
You can then access the interface at: [http://localhost:8080](http://localhost:8080)
|
|
|
|
## Running Locally Manually
|
|
|
|
If you prefer to run the system directly on your OS without Docker, you will need `Bun` and `Go` (with CGO enabled) installed.
|
|
|
|
### 1. Build the Frontend
|
|
Navigate to the root directory and use `npm` to install dependencies and build the static HTML/JS payload.
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
*(This produces a `build/` directory that the Go backend expects).*
|
|
|
|
### 2. Run the Backend Server
|
|
Because the backend uses `go-sqlite3`, it requires CGO to compile. Navigate completely into the `server` directory so the relative paths for serving the `../build` and `../results` folders remain accurate.
|
|
```bash
|
|
cd server
|
|
go run .
|
|
```
|
|
|
|
The server will automatically scan the `../results` folder on startup, index the simulations into the SQLite database, and host the web interface at [http://localhost:8080](http://localhost:8080).
|
|
|
|
## API Endpoints
|
|
|
|
The Go backend provides a simple REST API to interact with the simulations:
|
|
|
|
### `GET /api/simulations`
|
|
Returns a JSON array of all indexed simulations, including their ID, name, created date, and configuration string.
|
|
|
|
### `POST /api/simulations/create`
|
|
Creates a new simulation entry.
|
|
- **Request Body:** JSON object containing the combined configurations (e.g., `search`, `uav`, `ugv`). The configuration *must* contain at least one search pattern definition (either `spiral`, `lawnmower`, or `levy`) inside the JSON.
|
|
- **Behavior:** Checks if an identical config exists. If so, it returns the existing simulation ID/Name for overwriting. If not, it allocates a new `simulation_X` incrementally, inserts it into the database, builds the file directory in `../results`, and returns the new ID/Name. Returns `400 Bad Request` if payload is not valid JSON or lacks a known search pattern.
|
|
- **Response:** JSON object `{"id": <int>, "name": <string>}`
|
|
|
|
### `GET /api/simulations/:id`
|
|
Provides detailed JSON metadata for a specific simulation ID, including its name, JSON config string, creation timestamp, and a dynamically fetched array of all the internal resources (images, logs, videos) located within its folder.
|
|
|
|
### `PUT /api/simulations/:id/time`
|
|
Updates the numeric benchmarking metrics (`search_time` and `total_time`) for a specific simulation run.
|
|
- **Request Body:** JSON object containing floats: `{"search_time": 25.4, "total_time": 105.8}`
|
|
- **Response:** JSON object `{"status": "success"}`
|
|
|
|
### `PUT /api/simulations/:id/rename`
|
|
Renames a specific simulation. Automatically updates the database and physically renames the matching directory path on the system filesystem to mirror structural links.
|
|
- **Request Body:** JSON object containing the new underlying name: `{"name": "new_simulation_name"}`
|
|
- **Response:** JSON object `{"status": "success", "new_name": "new_simulation_name"}`
|
|
|
|
### `POST /api/simulations/:id/upload`
|
|
Uploads a new media or data resource file directly into a completed simulation run. Supports both images (e.g., PNGs) and heavy video files (e.g., AVIs) out of the box with an initial multi-part allocation pool mapping of 500 MB.
|
|
- **Request Data:** `multipart/form-data` packet using the `file` keyword carrying the binary data blocks.
|
|
- **Behavior:** The Go service validates the simulation ID exists, dynamically builds the memory pool, opens a stream writer caching the binary blob into the `../results/simulation_X/filename.ext` directory path, and records the resource in the primary SQLite instance.
|
|
- **Response:** JSON object `{"status": "success", "filename": "example.png"}` |