Emulica Emulator VS Code Extension

VS Code extension for running Emulica simulations and deterministically onboarding MCU firmware from reviewed target and example specifications. This extension owns every example/target/project-store concern: it bundles its own examples/+targets/, resolves a project name against them, builds/stages the firmware locally (src/projectConfig.ts/src/firmwareBuild.ts), and uploads the resulting bundle to a emulicaEmulator.serverUrl server (local or remote) to run it. It never spawns a remote process and never reads or writes an Emulica server's own source tree in normal use — the server does nothing but processing.

See emulica-server's docs/ARCHITECTURE.md for the full communication diagrams.

Quickstart: running both together

1. Start the server (see emulica-server):

   git clone git@github.com:Microtherium/EmbeddedClaw-Server.git
   cd EmbeddedClaw-Server
   pixi install
   pixi run server          # listens on localhost:50051 by default
   

2. Install this extension (see Build & Install below), or run it from source via the Extension Development Host (see Develop below).
3. This extension defaults emulicaEmulator.serverUrl to the hosted production server (grpc.emulica.dev:443). To point it at the local server you just started instead, either set emulicaEmulator.serverUrl in VS Code Settings to localhost:50051, or (for a source checkout) set EMULICA_SERVER_URL=localhost:50051 in a local .env - see .env.example.
4. Open the command palette (Ctrl+Shift+P) and run:
   • Emulica Emulator: Open Assistant — select a firmware folder, analyze it, and run a simulation.
   • Emulica Emulator: Open Simulation Timeline — watch live RTOS/CPU/interrupt/register telemetry for the current simulation.

Both commands only need emulicaEmulator.serverUrl reachable — nothing else to start or configure for normal use.

Requirements

• A running emulica-server instance, local (pixi run server, default localhost:50051) or remote.

Build & Install

npm install
npm run bundle
npx @vscode/vsce package --no-dependencies
code --install-extension vscode-emulica-emulator-0.2.0.vsix --force

Reload VS Code, then open the panel with Ctrl+Shift+P -> Emulica Emulator: Open Assistant.

emulicaEmulator.serverUrl defaults to the hosted production server (grpc.emulica.dev:443) - set it in Settings if you're pointing at a local or otherwise different server.

Two execution modes

Open Assistant's "Run Simulation" (batch: uploads a bundle, streams back logs, then ends) and Open Simulation Timeline's Run/Pause/Stop (interactive: full telemetry, bus/register inspection, recording) are deliberately separate - not two ways to do the same thing. See emulica-server's docs/ARCHITECTURE.md's "Two execution modes" section.

Simulation Timeline

Ctrl+Shift+P -> Emulica Emulator: Open Simulation Timeline opens a live RTOS/CPU-utilization/interrupts/events/bus-traffic/register-history view in its own editor panel. It streams from TelemetryService on the same emulicaEmulator.serverUrl server as everything else — there's no separate process to start, and no dependency on the Open Assistant panel having been opened first.

Onboarding

Check support and analyze firmware work out of the box against any server: check-support merges a gRPC call (OnboardingService.CheckSupport

• backend/parser support, reading the server's own engine source) with a local check against this extension's own examples/+targets/ (target/ example support); firmware analysis runs entirely locally against the folder you select.

Develop (Extension Development Host)

npm install
npm run bundle

Open this folder in VS Code and press F5. A new Extension Development Host window opens with the extension loaded.

Environment

Create or update your local ignored .env from .env.example, then set your AI provider and API key before connecting:

npm run env:pull

To push non-secret local env defaults back into the tracked template, run:

npm run env:push

The pull command creates .env when missing, or adds newly introduced template keys without overwriting local secrets. The push command updates .env.example from .env, but keeps secret-looking values out of git.

Proto contracts

proto/*.proto are vendored copies of emulica-server's gRPC contracts, loaded dynamically at runtime via @grpc/proto-loader (no generated stub codegen step). Update them by copying from emulica-server's proto/ directory when the contract changes.

Scripts