Developers/Foundations

Project format

Reference for the v1 JSON documents — manifest, types, variables, connections and screens.

3 min read

Every document is UTF-8 JSON without comments. Screen and faceplate names are file names without extension.

Manifest

The main file is <Name>.abscada (older projects use project.json):

{"schema_version": 1, "name": "Plant", "startup_screen": "main",
 "screen_folders": ["Process", "Process/Pumping"],
 "screen_defaults": {"width": 1920, "height": 1080},
 "display": {"main": {"mode": "maximized", "scale": "fit"}}}
Key Use
screen_folders Screen folders, empty ones included (Studio only)
screen_defaults Size proposed for new screens
display.main.mode normal, maximized (default) or fullscreen
display.main.scale fit (keep proportions, default), stretch (fill) or none (actual size)

Unknown schema versions are rejected; migrations will be explicit.

Types

{"Pump": {"running": "bool", "flow": "float", "setpoint": "float"}}

Primitives: bool, int, float, string. Fields may use other types; cycles are forbidden. No arrays in v1.

Variables

[
  {"name": "Level", "type": "float", "initial": 0.0, "writable": false,
   "binding": {"connection": "plc", "address": "%DB1.DBD12"}},
  {"name": "Pump1", "type": "Pump",
   "initial": {"running": false, "flow": 0.0, "setpoint": 60.0},
   "writable": true,
   "overrides": {"flow": {"writable": false}},
   "bindings": {
     "Pump1.running": {"connection": "plc", "address": "%DB1.DBX0.0"},
     "Pump1.flow": {"connection": "plc", "address": "%DB1.DBD4"}
   }}
]
  • A structure's initial must contain exactly its fields.
  • bindings uses full names; overrides uses relative paths.
  • Without a binding the field is internal. writable defaults to false.

Connections

[
  {"id": "plc", "protocol": "s7", "host": "192.168.1.10",
   "rack": 0, "slot": 1, "port": 102, "poll_ms": 250},
  {"id": "meter", "protocol": "modbus_tcp", "host": "192.168.1.20",
   "port": 502, "unit_id": 1, "poll_ms": 1000}
]

Screens

{"width": 1280, "height": 720, "background": "#0f172a",
 "on_open": ["screen_open"],
 "elements": [
   {"id": "level", "kind": "text", "x": 20, "y": 20, "w": 180, "h": 45,
    "text": "Level ", "tag": "Level", "unit": "%", "decimals": 1},
   {"id": "start", "kind": "button", "x": 20, "y": 80, "w": 140, "h": 44,
    "text": "Start", "tag": "Pump1.running", "action": "toggle"}
 ]}

The order of elements is the drawing order: the last ones are on top. folder (optional) is the Studio folder, e.g. "Process/Pumping". A layout is a screen with screen_container elements; the old "layout": true flag is migrated to a Layouts folder.

Other documents

File Contents
alarms.json Categories and alarm definitions
alarm_views.json Configuration of each alarm viewer (one per control)
historian.json Logger files and retention
trends.json Configuration of each trend (one per control)
automation.json Startup scripts, timeout and tasks
libraries.json Linked libraries with their hash

See faceplates for the full catalogue of elements and properties.

Security and OPC UA

security.json contains policy and roles; users.json, accounts and scrypt hashes; secrets.json, base64 connection passwords (not encrypted); opcua_server.json, server settings; and pki/, certificates and private keys. Accounts and secrets are updated immediately. Legacy files in runtime/ migrate when their project destination does not exist. Protect this data when copying or versioning projects.

A protocol: "opcua" connection stores endpoint, security and username; its binding identifies the NodeId. The manifest supports library_folders for library object organisation; a template's folder specifies its Studio location. Controls retain kind: "faceplate". See OPC UA and Users and roles.

Multilingual texts

The manifest declares languages and the initial language source:

{"schema_version": 1, "name": "Plant", "startup_screen": "main",
 "languages": ["es", "en"], "default_language": "es", "initial_language": "project"}

initial_language accepts project, station and user. Older projects without these fields retain Spanish and their plain strings.

Text properties accept a string or a translation map:

{"id": "title", "kind": "text", "text": {"es": "Sala de cocción", "en": "Brewhouse"}}

Supported properties are text, title, message, default_text, disabled_reason, tooltip and description; alarm categories use name. Maps must include the default language, use declared languages and contain strings. Missing or empty translations fall back to the default language.

A button switches language during execution:

{"id": "english", "kind": "button", "text": "EN", "action": "set_language", "language": "en"}

Published libraries include languages and default_language; consumers must declare the languages of linked objects. See Project languages.

Project format · abSCADA