simantic.json: describe your firmware project to the reviewer

Overview

simantic.json tells the reviewer what it would otherwise have to work out: which MCU the firmware is for, how to build it and where the ELF ends up. Put one in each firmware project’s folder; the folder it is in is the project, the way vercel.json’s folder is the deployment. A repository may hold several. Without one, the reviewer detects the build and the MCU from the repository as before, and its review ends with a simantic.json to commit. Only mcu is required. Unknown keys are an error; a file that does not parse or does not validate is reported as a finding on it, and the reviewer falls back to detection for that review.

Example

{
  "$schema": "https://simantic.com/schema/simantic.json",
  "name": "hello-world",
  "mcu": "STM32F401RE",
  "build": { "system": "cubemx-make", "elf": "build/hello-world.elf" }
}

This is the file in the Cloud Sim examples’ hello-world.

Fields

Field	Type	Required	Description
`$schema`	string		The JSON Schema this file follows, for editors: https://simantic.com/schema/simantic.json.
`name`	string		The project's name, unique in the repository: letters, digits, dot, underscore and hyphen, up to 64. The folder's name when left out.
`mcu`	string	yes	The microcontroller the firmware is for, as the simulator names it: STM32F401RE, RP2040, ESP32-C3. An order code such as STM32F401RET6 is accepted. The only required field.
`build`	object		How the firmware is built. Left out, the reviewer detects the build system from the directory.
`build.system`	string		The build system, which picks the command the reviewer runs: cubemx-make (an STM32CubeMX Makefile, built with the image's Arm toolchain), make, cmake, pico-sdk, esp-idf or zephyr. When neither system nor command is given, the reviewer detects the build system in the directory. One of `cubemx-make`, `make`, `cmake`, `pico-sdk`, `esp-idf`, `zephyr`.
`build.command`	string		A command to build with instead of the build system's own, run in a shell in the build directory, with args after it. The build must leave an ELF under the directory, or name it in elf.
`build.dir`	string		The directory to build in, relative to this file's; this file's own directory when left out. It must stay inside the repository.
`build.args`	string[]		Arguments added to the build command: make variables, -D defines for cmake's configure step, or anything after a custom command.
`build.target`	string		The ESP-IDF target (idf.py set-target), such as esp32c3.
`build.board`	string		The pico-sdk PICO_BOARD, or the Zephyr board given to west build -b.
`build.elf`	string		The ELF the build produces, relative to the build directory, such as build/app.elf. When left out, the newest .elf under the directory after the build is taken.
`toolchain`	object		The toolchain versions the project builds with, as prefixes (14.3 matches 14.3.1). The reviewer has one version of each and checks these against it: a difference is a note in the review, never a refusal.
`toolchain.arm-gnu`	string		The Arm GNU Toolchain (arm-none-eabi-gcc) version, such as 14.3.
`toolchain.pico-sdk`	string		The pico-sdk version, such as 2.1.
`toolchain.zephyr`	string		The Zephyr version, such as 4.4.
`toolchain.esp-idf`	string		The ESP-IDF version, such as 5.4.
`simulate`	object		Defaults for the reviewer's simulation runs of this project.
`simulate.seconds`	number		Simulated seconds a run lasts when the reviewer names no other length; at most 120.
`simulate.board`	string		A .board file laid over the chip in every run (parts on its buses), relative to the build directory.
`simulate.expect`	string[]		Texts the firmware prints on a UART when it boots, which a smoke run should show.

The build.system values are the build systems the reviewer knows; a build.command runs in a shell in the build directory instead.

Several projects

Several simantic.json files, one per folder. A pull request that changes files under a project’s folder (or its build directory) gets that project built and reviewed; when no changed file falls under any project, all of them are. name labels the project in the report’s Projects table and defaults to the folder’s name; it must be unique in the repository.

Static review

A review in which nothing ran in the simulator is static, whatever kept it from running: the MCU is one the simulator does not run or does not know, the review image has no toolchain for the build system, the build failed, or the firmware was built and never run. The diff is read, the firmware is built when the image can, no scenario runs, and the verdict is never approve. The review says why on GitHub and in the dashboard: Static review: STM32H743ZI is not run by the simulator (incomplete). To see which MCUs run, sim models lists the CLI’s (see the CLI reference), and the Cloud Sim API’s GET /v1/mcus lists each MCU’s status per engine and whether it is runnable. The reviewer’s simulator is the review image’s build of the same engine, which can be a step ahead of or behind the API’s list. A version under toolchain that differs from the image’s is a note in the report, not a refusal.

Editor support

"$schema": "https://simantic.com/schema/simantic.json"

Editors that honor $schema (VS Code among them) validate and complete the file from it.