Description

Ethos is a VSCode extension that provides Ethos firmware simulation.

Features

• Start/ Stop Ethos
• Open display
• Open telemetry
• Open controls
• Redirect logs to a file
• Simulator's persistent directory isolation
• Status Bar to set or add a new simulator
• Status Bar shows the current simulator and its status (running or not)
• Optional Quick Pick menu to launch tasks or commands
• Audio support with toolbar icon to mute/unmute
• Screenshot support with a toolbar icon
• Toolbar icon to open the Lua documentation for the selected simulator

Installing

This extension is available for free in the Visual Studio Code Marketplace

On first run in a new project, or if the status bar does not appear, run from the command palette Ethos: Set Simulator to select a simulator or add a new one.

To ease your development process, the installation of the companion extension Ethos DevTools is highly recommended.

Breaking changes

• ethos.root, ethos.firmware and ethos.version are not used anymore.
• ethos.simulatorsFolder is by default simulators and is the workspace folder where all simulators are stored.
• all persistent data for a simulator is stored in its own folder under ethos.simulatorsFolder. The folder is named ${board}_${protocol}@${release} and is not configurable to ensure isolation.
• ethos.board,ethos.protocol and ethos.release are the three required fields to define a simulator. Ethos: Set Simulator will set them for you when you click on the status bar.

Status Bar customization

Like for all Status Bar in VSCode, you can hide it using a right click.

You can set the alignment of the status bar item with ethos.statusBarAlignment ("left" or "right", default is "right").

ethos.statusBarPriority (number, default 0) controls ordering within the same alignment group. Higher values appear further left in both groups (i.e. closer to the center of the status bar).

You can customize the text shown in the status bar with two separate settings:

• ethos.statusBarIdleText — text when the simulator is not running, default is $(radio-tower) ${board}_${protocol}${releaseTag}
• ethos.statusBarRunningText — text when the simulator is running, default is 🟢 ${board}_${protocol}${releaseTag}

Both settings support the following variables: board, protocol, release and releaseTag (releaseTag is shorter as it skips @nightly26). You can also use any VSCode icon using the syntax $(icon-name), e.g. $(radio-tower), emoji are also supported.

The main customization is to show a quick pick menu when clicking on the status bar, which is defined in .vscode/ethos-menu.json (see below).

.vscode/ethos-menu.json

Create .vscode/ethos-menu.json to define a custom quick pick shown when clicking the status bar. The placeholder shows the currently active simulator.

Each item supports the following fields:

[
    {
        "label": "▶️ Start SIM",
        "command": "ethos.start"
    },
    {
        "label": "🛑 Stop SIM",
        "command": "ethos.stop"
    },
    {
        "label": "🆑 Clear Logfile",
        "command": ["ethos.clearLogfile", "ethos.showMenu"]
    },
    { "label": "", "separator": true },
    {
        "label": "🎛️ Open Controls",
        "command": "ethos.openControls"
    },
    {
        "label": "📡 Open Telemetry",
        "command": "ethos.openTelemetry"
    },
    {
        "label": "🖥️ Open Display",
        "command": "ethos.openDisplay"
    },
    { "label": "", "separator": true },
    {
        "label": "⚙️ Change SIM",
        "command": ["ethos.setSimulator", "ethos.showMenu"]
    }
]

[!NOTE] To pass arguments to a command, use the object form { "id": "<commandId>", "args": [...] } instead of a plain string:

[
    {
        "label": "Set Altitude to 100m",
        "command": { "id": "ethos.injectTelemetry", "args": [[{"name": "Altitude", "value": 100}], true] }
    }
]

[!NOTE] If you want to use a task defined in tasks.json, use this format with the task field instead of command.

[
    {
        "label": "$(debug-start)Deploy & Launch SIM",
        "task": "Deploy & Launch [SIM]"
    }
]

Commands

All commands are available from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) under the Ethos category.

[!NOTE] ethos.showMenu should be your entry point to add/set simulators even if you are not using the ethos-menu.json.

Settings

Logging

All output from the simulator is logged to the VS Code Output panel under the "Ethos Logs" channel. You can also redirect logs to a file with the ethos.setLogfile command, having a real logfile is useful if you want to analyze logs with AI. AI currently does not have access to VS Code's Output panel but can read files from the filesystem.