Files and formats
BetterSPICE keeps everything in plain JSON text files that you can read, diff and keep in version control. All three formats are UTF-8. A file saved by Notepad with a byte-order mark opens normally. UTF-16, binary files and files over 64 MB are refused with a message that says so. Keys BetterSPICE doesn’t know are kept when a file is saved, so other tools can store their own data.
| Extension | What it’s | Opened by |
|---|---|---|
.bsc | A circuit | Double-click, , the command line, AI agents |
.bspart | A part: identity, datasheet values, pins, optional symbol and SPICE model | Double-click (adds to My parts), the Part Wizard, bspice parts |
.bssym | A schematic symbol | Double-click (adds to My parts), the symbol editor |
.cir | An ngspice netlist, written by Export SPICE netlist | bspice ngspice, ngspice |
.verify.json | The settings of a verification circuit | bspice verify |
48.1Saving
- Save writes to a temporary file first and then replaces the old one, so a crash cannot leave a half-written circuit.
- The desktop app watches the open file: if another program changes it, such as an AI agent, a text editor or git, the circuit reloads in place as one undo step, and the changed parts flash. Its own saves aren’t reloaded.
- Hierarchical sheets are stored inside the circuit file, or as separate files next to it.
- Custom symbols and part files a circuit uses are copied into it, so it opens on another computer.
48.2Circuit files (.bsc)
| Key | Type | Meaning |
|---|---|---|
bsc | 1 | Format version. Required. |
name, description, category | text | Title, a line saying what to watch, and the examples category. |
sim | object | Simulation settings, see below. |
parts | list | The components. |
wires | list of [x1, y1, x2, y2] | Wire segments in grid units. Only their ends connect. |
labels | list of {name, at} | Net labels. The same name is the same net on a sheet. |
power | list of {net, at, style} | Power flags, global by name. style: bar, arrow, gnd, chassis. |
globals, ports | list of {name, at} | Global labels, and sheet ports inside a child sheet. |
probes | list | Scope probes: {label, kind (v, vd or i), at, ref, part, pin, scope, color, value, tag}. value: true shows the live value in the probe’s tag. tag: [dx, dy] is where the tag sits, in grid units from the probed point (absent: beside the probe). color is the trace colour. |
graphics | list | Text, lines, rectangles, circles, arcs, polylines. No electrical meaning. |
sheets | list | Hierarchical sheets: {id, name, file or doc, at, size, pins}. |
buses, busEntries | list | Drawing aids. They never connect. |
symbols, partDefs | object | Custom symbols and part files embedded in the circuit. |
| sim key | Meaning |
|---|---|
dt | The live engine's maximum timestep in seconds. |
speed | The starting timebase: simulated seconds per real second. |
start | "rest": the live simulation starts at 0 V with capacitors empty (power-on). Absent or "op": it starts from the DC operating point. New circuits write "rest". Simulate › Start at rest (power-on) toggles it. The live simulation only: Simulate doesn’t use it. |
vRange | The voltage at which wire colours are full. |
simulate | {stop, maxStep, method, uic, options}: the Transient setup, also used by bspice tran. method is trap, gear or be. uic: true always starts from 0 V. options is a string of ngspice name=value options (Settings saved in the circuit). |
ac | {source, fStart, fStop, ppd, out}: the AC setup. |
A part is {id, type, variant, pins, p}: the designator, the device type, the symbol variant, its pin points in the order the device lists them, and its parameters in SI units. A part can also have sliders (the inspector slider ranges), symbol and symPins for a custom symbol. Model references live in p: model, lib, libSource, modelId, modelLine, pinmap.
A microcontroller (mcu) keeps its program in p.code, as text in the MCU language (Programming the MCU); its pins come from the pin and bus lines of that text, and the part’s pins are laid out again when the code changes. The memory, flash and RTC chips and the USB-UART bridge are chip parts with the variants eeprom, spi_flash, rtc and usb_uart. The bridge keeps its settings in p.baud, p.send, p.send_at, p.eol, p.dtr, p.rts and p.flow. A battery keeps its chemistry in variant and its start in soc.
| Part (type) | Pins | Keys in p |
|---|---|---|
PWL source (vpwl) | +, - | points [[t, v], …] in s and V. td, the time offset in s (default 0). r, the repeat time in s, a time before the last point (absent: the points play once, 0: the whole list repeats). SPICE PWL(…) r=… td=…. |
Voltage-controlled sources (vcvs, vccs) | +, -, c+, c- | gain (V/V), gm (S). |
Current-controlled voltage source (ccvs) | +, -, s+, s- | rt in Ω (default 1000). The current into s+ and out of s- is sensed. SPICE H with a 0 V source. |
Current-controlled current source (cccs) | +, -, s+, s- | gain in A/A (default 1). SPICE F with a 0 V source. |
Pulse source (vpulse) | +, - | v1, v2, delay, rise, fall, width, period. Times are 0 or more. Edges and width longer than the period warn W_PARAM. |
Digital filter, lookup table, state machine (filter, lut, fsm) | in, out, gnd; in0 …, out0 …, gnd | coeffs, table [[in, out], …], states [{name, out}], transitions [{from, to, after, when}], initial. The inspector edits them as tables. |
MCU (mcu) | from the code | code. A complementary output is declared in it: pin LO complement HI dead 200ns. |
A sine source can carry delay. A sheet made with Edit subcircuit is an ordinary entry in sheets, with the inside in doc.
{
"bsc": 1,
"name": "RC step",
"sim": { "simulate": { "stop": 0.005, "maxStep": 1e-5 } },
"parts": [
{ "id": "V1", "type": "vdc", "pins": [[0, 0], [0, 6]], "p": { "v": 1 } },
{ "id": "R1", "type": "res", "pins": [[0, 0], [6, 0]], "p": { "r": 1000 } },
{ "id": "C1", "type": "cap", "pins": [[6, 0], [6, 6]], "p": { "c": 1e-6 } },
{ "id": "GND", "type": "gnd", "pins": [[3, 6]] }
],
"wires": [[0, 6, 3, 6], [3, 6, 6, 6]],
"labels": [{ "name": "OUT", "at": [6, 0] }]
}
How nets are formed
- Pins, wire ends, labels, flags and ports on the same grid point are one net. A point in the middle of a wire doesn’t connect, the editor splits the wire at a T.
- Labels, flags and ports with the same name join. Global labels and power flags join across sheets, labels and ports only within their sheet.
- Ground is every gnd part, a flag with style gnd or net GND, and a label named GND or 0.
- Net names come from labels and flags. Unnamed nets are named after their first point, like
N@12,4. Inside sheets names get the sheet prefix,S1/. - Pin currents are measured into the part.
48.3Part files (.bspart)
A part file describes a real part from its datasheet. Every value has its minimum, typical and maximum where the datasheet gives them, its unit, its test conditions and the page it came from.
| Section | Contents |
|---|---|
bspart | "1.0". Must be the first key. |
kind | The template, for example regulator.ldo. It decides the device type and the fields (Part templates reference). |
identity | mpn (required), manufacturer, family, description, aliases, lifecycle, tags. |
package | name, mounting (smd, tht, chassis, module), pins (number, name, function), fields. |
electrical, noise, thermal | The values. Each one: min, typ, max, unit, conditions, source {page, table, row, figure}, unverified, note. |
curves | Points read from datasheet graphs, sorted by x. |
model | live (device, variant, parameters that override the derived ones, pin map) and spice (file, sha256, name, type, dialect, pins, encrypted). |
provenance | datasheet (file, sha256, url, revision, date), author, created, tool, verified_by, notes. |
symbol | An optional custom symbol, as in a .bssym. |
"vdo": { "typ": 0.25, "max": 0.4, "unit": "V",
"conditions": { "iout": 0.6, "ta": 25 },
"source": { "page": 4, "table": "Electrical Characteristics", "row": "Dropout Voltage" } }
Rules: units are SI base units (store 0.25 V, never 250 mV), min ≤ typ ≤ max, every value inside its field's sanity range, pin numbers unique, every simulation pin on a package pin. A bare number is shorthand for a typical value. The live model uses the typical value, or the middle of min and max. bspice parts validate checks a file and names every problem, for example "electrical.vout: min 3.4 V is greater than typ 3.3 V, expected min ≤ typ ≤ max". A template's TODO placeholders give E_PART_TODO until they are filled.
48.4Symbol files (.bssym)
Symbols are outlines on the 20 px grid, with the origin near the body centre and y pointing down. Pin connection points are whole grid units, drawings can use tenths.
| Key | Meaning |
|---|---|
bssym | 1, in standalone files. |
id | Lower-case letters, digits, dots, dashes and underscores. Parts refer to it by id. |
name, description, title, titleAt | Library text, and the bold title in the body. |
body | [x0, y0, x1, y1]: the body box. |
pinNames, pinNumbers | inside or hidden, outside or hidden. |
pins | {name, number, at, side (l, r, t, b), role, length, shape, hideName}. |
graphics | line, polyline, rect, circle, arc, text, with width and dash. No fills. |
variants | Alternative drawings a part picks with symVariant. |
{ "bssym": 1, "id": "ap2112", "name": "AP2112 LDO", "body": [-3, -2, 3, 2], "title": "AP2112",
"pins": [
{ "name": "VIN", "number": "1", "at": [-5, -1], "side": "l", "role": "power_in" },
{ "name": "EN", "number": "3", "at": [-5, 1], "side": "l", "role": "in" },
{ "name": "GND", "number": "2", "at": [ 0, 4], "side": "b", "role": "power_in" },
{ "name": "NC", "number": "4", "at": [ 5, 1], "side": "r", "role": "nc" },
{ "name": "VOUT", "number": "5", "at": [ 5, -1], "side": "r", "role": "power_out" } ] }