Skip to main content
The EVCore knowledge database stores structured engineering knowledge about vehicles, components, connectors, communication protocols, and vendor fault codes. Every entry carries provenance, confidence, and a validation status so nothing ships on guesswork. The database is the source of truth in git; a cloud mirror and a Studio bundle are generated from it.

​
Layout

Ids are lower-case words joined by dashes and must match the file name. References between entries use ids and must resolve.

​
Fields every entry has

​
Entry kinds

​
Vehicle

make, model, category (e-bike, e-moto, e-scooter, other-lev), years {from, to?}, components[] {component, role?}, protocols[].

​
Component

type (motor, controller, battery, bms, display, throttle, brake-sensor, pas-sensor, torque-sensor, thermistor, charger, lights, other), manufacturer, model, specs[] {name, value, unit?}, connectors[], protocols[], fault_codes[].

​
Connector

family, pin_count, pins[] {pin, signal, wire_color?, evidence[], confidence}. Evidence is one or more of pinout-doc, continuity, electrical, protocol, component-identity, wire-color. A pin known from wire colour alone must be unverified. Use signal unknown rather than guessing.

​
Protocol

transport (can, uart, rs485, lin, other), settings (bitrate, baud, id_bits 11 or 29, and other bus settings), detection[] (how to recognize it on a bus), checksum (notes), messages[]: DBC bit numbering: for little the start bit is the least significant bit; for big it is the most significant bit, numbered byte x 8 + bit with bit 7 the top bit of each byte.

​
Fault codes

vendor, applies_to_components[], applies_to_protocols[], codes[] {code, title, meaning?, checks[]?, status} with status as for messages. code is written as the display or tool shows it (E10, 21, P0A1F).

​
Knowledge tool

scripts/knowledge.mjs is the command-line interface for the knowledge database. It validates entries, builds the Studio bundle, searches, scaffolds drafts, decodes CAN captures, and publishes to the cloud mirror.
Use --root <dir> to work with another database that has the same layout (for example knowledge/examples).

​
Publishing and shipping

  • Source of truth is git. Every change is reviewed, versioned, and checked by scripts/knowledge.mjs check (a verify.ps1 gate) before it reaches a build.
  • Cloud mirror. Each version is published in full to Supabase (knowledge_releases, knowledge_entries, knowledge_articles) by the knowledge workflow when knowledge/ changes on main. A version is immutable. Readable only by CS Harness staff.
  • Studio ships it; no updates between releases. scripts/knowledge.mjs build generates software/evcore-studio/public/knowledge.js, and the gate fails if it is out of date, so every Studio release carries the database as of its build. Installed Studio does not download knowledge on its own.
  • Drafts stay internal. Only entries with status reviewed or validated ship in Studio. Draft entries and articles stay in git and the cloud. References to entries that do not ship are removed from the bundle.

​
Versions

knowledge.json version follows MAJOR.MINOR.PATCH: PATCH for corrections, MINOR for new entries, MAJOR when the schema changes incompatibly (with schema_version). A published version is never changed; publish a new one. Studio shows the version it ships in Settings.