Source code coming soon. The GitHub repository is private for now and opens to everyone very soon.
BetterSPICE Beta 0.8.0 Join the beta Download soon
Part VII  Files and integrationReferenceContentsIndex
48

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.

Files and formats
ExtensionWhat it’sOpened by
.bscA circuitDouble-click, File›Open, the command line, AI agents
.bspartA part: identity, datasheet values, pins, optional symbol and SPICE modelDouble-click (adds to My parts), the Part Wizard, bspice parts
.bssymA schematic symbolDouble-click (adds to My parts), the symbol editor
.cirAn ngspice netlist, written by Export SPICE netlistbspice ngspice, ngspice
.verify.jsonThe settings of a verification circuitbspice 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)

Circuit files (.bsc)
KeyTypeMeaning
bsc1Format version. Required.
name, description, categorytextTitle, a line saying what to watch, and the examples category.
simobjectSimulation settings, see below.
partslistThe components.
wireslist of [x1, y1, x2, y2]Wire segments in grid units. Only their ends connect.
labelslist of {name, at}Net labels. The same name is the same net on a sheet.
powerlist of {net, at, style}Power flags, global by name. style: bar, arrow, gnd, chassis.
globals, portslist of {name, at}Global labels, and sheet ports inside a child sheet.
probeslistScope 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.
graphicslistText, lines, rectangles, circles, arcs, polylines. No electrical meaning.
sheetslistHierarchical sheets: {id, name, file or doc, at, size, pins}.
buses, busEntrieslistDrawing aids. They never connect.
symbols, partDefsobjectCustom symbols and part files embedded in the circuit.
Circuit files (.bsc)
sim keyMeaning
dtThe live engine's maximum timestep in seconds.
speedThe 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.
vRangeThe 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.

Circuit files (.bsc)
Part (type)PinsKeys 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 …, gndcoeffs, table [[in, out], …], states [{name, out}], transitions [{from, to, after, when}], initial. The inspector edits them as tables.
MCU (mcu)from the codecode. 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.

Part files (.bspart)
SectionContents
bspart"1.0". Must be the first key.
kindThe template, for example regulator.ldo. It decides the device type and the fields (Part templates reference).
identitympn (required), manufacturer, family, description, aliases, lifecycle, tags.
packagename, mounting (smd, tht, chassis, module), pins (number, name, function), fields.
electrical, noise, thermalThe values. Each one: min, typ, max, unit, conditions, source {page, table, row, figure}, unverified, note.
curvesPoints read from datasheet graphs, sorted by x.
modellive (device, variant, parameters that override the derived ones, pin map) and spice (file, sha256, name, type, dialect, pins, encrypted).
provenancedatasheet (file, sha256, url, revision, date), author, created, tool, verified_by, notes.
symbolAn 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.

Symbol files (.bssym)
KeyMeaning
bssym1, in standalone files.
idLower-case letters, digits, dots, dashes and underscores. Parts refer to it by id.
name, description, title, titleAtLibrary text, and the bold title in the body.
body[x0, y0, x1, y1]: the body box.
pinNames, pinNumbersinside or hidden, outside or hidden.
pins{name, number, at, side (l, r, t, b), role, length, shape, hideName}.
graphicsline, polyline, rect, circle, arc, text, with width and dash. No fills.
variantsAlternative 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" } ] }