faezor for VS Code

faezor turns a description of a device into a circuit board (faezorpcb), its case (faezorcad), its firmware (faezorfirmware), a simulator that runs the firmware on the simulated board (faezorsim) and the fleet of devices it ships to (faezorfleet). The faezor extension brings those products into VS Code, VSCodium and code-server, in two places:

• On your own computer, to edit a faezor project locally: see your projects and what each product is doing, clone a project, build, test and run its firmware on faezor's servers, debug it in the simulator with GDB, build the case and read its fit checks, and ask faezor's central chat.
• Inside faezor's expert editors (the code editors in your browser for the Firmware and CAD products), where it is already installed. Nothing to set up: the editor is connected to its own project.

Install

1. Download the package above (faezor-vscode.vsix).
2. In VS Code: open the Extensions view, select the ... menu at its top and Install from VSIX..., and pick the file. Or from a terminal: code --install-extension faezor-vscode.vsix.
3. VSCodium: codium --install-extension faezor-vscode.vsix. code-server: code-server --install-extension faezor-vscode.vsix.
4. Check the download if you like: sha256sum faezor-vscode.vsix prints the SHA-256 shown above.

The extension needs VS Code 1.90 or newer (or a VSCodium / code-server of the same age). It has no runtime dependencies and sends no telemetry.

Sign in

Open the faezor view in the activity bar and select Sign in. Your browser opens on faezor's own consent page; the extension asks for three things, and you decide on that page which of them to allow:

• faezor:read: your projects, the state of their products, versions, check results, the simulation's output.
• faezor:run: builds and tests on faezor's servers, simulation sessions, and saving your firmware as a new version.
• faezor:chat: messages to faezor's central chat (each one is a paid model call on our side, counted against your limits).

The answer comes back to a short-lived address on your own computer (http://127.0.0.1:<port>), so VS Code and the browser must be on the same machine. The sign-in uses OAuth 2.1 with PKCE; the tokens are kept in VS Code's secret storage, never in settings or files, and the access token lasts one hour (the extension renews it by itself). Disconnect any time under Account → Connected apps: that ends the extension's access at once.

Edit a project on your own computer

Open a project locally (in the view, or the Command Palette) runs git clone git@faezor.ai:<project id>/<name>.git over the SSH key you added under Account → SSH keys, and opens the folder. The clone is read only on faezor's side: faezor commits to a project after each run and each save in the browser; to keep your own changes, save firmware/ back to faezor with Firmware: save firmware/ to faezor (a new version, the old files stay in the history) or push your clone to a remote of your own.

The view shows each product with its live state:

• running (a run of that product's agent is going), queued, waiting for you (it asked a question or needs a document), failed (the last run's reason is in the tooltip), ready (its result exists), idle.
• the project's version next to its name. The link icon next to a project or a product opens it on faezor.ai.

Firmware: build, test, run

Firmware: build on faezor's servers (also a task: Terminal → Run Task → faezor) sends the files of your firmware/ as a zip, runs pcbw-fw build in a container on faezor's servers, and streams its output into a terminal as it is written. The container is the one faezor's own builds use: the Arm GCC, the chip's CMSIS and HAL, no network at all. Compiler errors and warnings land in the Problems panel with their file and line. The build is a scratch build: nothing of it is saved in the project.

• build and run the simulator tests also runs firmware/sim-tests.yaml in the simulator (for boards the simulator models) and lists each test.
• run in the simulator runs the firmware headless for 5 seconds of the board's time and prints the UART's text and what the LEDs did.
• build locally uses your own toolchain, if it is there. The extension runs arm-none-eabi-gcc --version and make --version (the programs named in the settings faezor.firmware.armGccPath and faezor.firmware.makePath, else the ones on PATH), needs answers that say Arm GCC and GNU Make, and needs firmware/Makefile; it then runs make OUT=build/firmware.elf as faezor's servers do. If something is missing the output says what.

The same builds are tasks, so they can go in your tasks.json:

{ "label": "faezor build", "type": "faezor", "action": "firmware-build" }

(firmware-build, firmware-test, firmware-run, cad-build; add "project": "<id>" to name a project.)

Simulation and GDB

Simulation: start a session runs the project's simulated board on faezor's servers and follows its UART output in an output channel (the board's LEDs and buttons are on the project's page on faezor.ai).

Simulation: debug in the simulator first builds the folder's firmware on faezor's servers for debugging (-Og -g3, so that the locals can be read; the release build and the tests are not touched; the ELF is .faezor/build/firmware-debug.elf), then starts GDB with that ELF and connects it to the simulated MCU through faezor's SSH command, as a launch configuration:

target extended-remote | ssh -T -o BatchMode=yes git@faezor.ai debug <project id>

with set remotetimeout 60 (the simulated board takes a few seconds to start, longer than GDB's default 2 s) and load. The session starts halted at the reset vector, like a board, with a temporary breakpoint at main: Continue (F5) runs to it. It needs gdb-multiarch (or arm-none-eabi-gdb) and the C/C++ extension (or, in VSCodium, Native Debug with the setting faezor.debug.type set to gdb). Add the GDB launch configuration writes the same configuration into .vscode/launch.json. The first time, run ssh git@faezor.ai once in a terminal to confirm faezor's host key.

CAD

CAD: build the case and show the fit checks sends the case's code (case/*.py, case.yaml) to faezor's CAD container, builds it with casekit and checks its fit: it builds, watertight solids, clearances, bosses under the mounting holes, openings that fit the plugs, wall thickness. The result is a page beside the editor with every check and its numbers, and a button for the 3D view on faezor.ai.

Ask faezor

Ask faezor sends a message to a project's central chat. It answers, and starts the right product's agent where that is what you asked: the answer and the runs it started are shown, and the view's states follow. Plans that need your OK wait on faezor.ai.

In faezor's expert editors

The extension is preinstalled in the Firmware and CAD expert editors. There it needs no sign-in: the editor's container has no network at all (faezor does not give machines internet access), so it talks to the site through one narrow channel, a socket the site mounts into that container. The channel is that one project's, for that editor's owner, and only for what the extension does there: the project's state, builds, tests, headless runs and the case's fit checks, and Save the editor's folder as a version. No chat, no uploads, no other projects, no internet. A GDB session needs the site's simulator and is not possible from inside the editor; the editor says so and points to your own computer.

What leaves your computer

Only what you ask for: a build, test or run on faezor's servers sends the files of firmware/ (or the case's code) as a zip over HTTPS to faezor.ai; saving to faezor sends the same. Your sign-in's tokens stay in VS Code's secret storage. The extension sends no telemetry and contacts no other server.

Troubleshooting

• Sign-in says it needs VS Code on the same computer as the browser. The answer comes back to a loopback address; a remote or hosted VS Code window cannot receive it.
• git clone: Permission denied (publickey). Add your public key under Account → SSH keys.
• "Too many requests". Builds and tests count against your account's limits (the message says when to try again).
• One build at a time. A second build while one runs is refused; wait for it or stop it with Ctrl+C in its terminal.

The API behind it

The extension uses faezor's API, version 1, which anyone can call with the same sign-in (OAuth 2.1, PKCE; resource https://faezor.ai/api/v1; scopes faezor:read, faezor:run, faezor:chat). Every call is for the signed-in account's own projects; limits apply (a refused call is HTTP 429 with a Retry-After). JSON, except builds (newline-delimited JSON events) and the simulation's output (server-sent events). Errors are {"ok": false, "error": "...", "code": "..."}.

• GET /api/v1: who you are, the scopes of the token, the products, the git host, the extension's current version.
• GET /api/v1/projects: your projects with their products' states and versions.
• GET /api/v1/projects/<id>: one project in detail: the last firmware build and tests, the case's fit checks, the simulator's readiness and session, the open editors.
• POST /api/v1/projects/<id>/firmware/build?what=build|test|run[&seconds=N] (faezor:run; what=build&debug=1: a build for GDB, -Og): a build in a container on the servers. The body is a zip of firmware/ (or empty: the project's own copy). The answer is a stream of events, one JSON object per line: start, log (the output), queued, result (the verdict, the tests, the UART's text, the ELF) or error.
• POST /api/v1/projects/<id>/cad/build (faezor:run): the same for the case; the result carries the fit checks.
• PUT /api/v1/projects/<id>/firmware?name=... (faezor:run): a zip of the sources or an ELF, saved as a new version.
• POST /api/v1/projects/<id>/sim/session with {"action": "start" | "stop", "debug": false} (faezor:run) and GET /api/v1/projects/<id>/sim/events (faezor:read, server-sent events): a simulation session and its output.
• POST /api/v1/projects/<id>/chat with {"text": "..."} (faezor:chat): a message to faezor's central chat.