BooleX answers trip and alarm questions about your line from its PLC code, drawings, manuals, alarm history and work orders. These docs get one line set up and answering, then show your team how to use it on shift.
Preview. These docs describe the pilot release. Commands and file layouts may change before general availability.
One engineer, one line, one prepared edge PC. You don't need a live connection to the control system for any of this. Add live data once the first answers look right.
BooleX ships as containers on one host. Install the signed release package from the USB drive or file share, choose the deployment profile, then start it. Nothing is downloaded from the internet. Installation in full.
$ python -m settings.release install /media/usb/boolex-<version> # checks the signature offline $ echo production > deploy/config/profile $ make up PROFILES= # a site: no simulator; the Web UI on HTTPS
Create the site folder: site.yaml with the site name, endpoints, code exports, glossary and starter prompts, and beside it the line's tag, alarm and interlock lists and the documents manifest. Keep the folder in version control. Then check the tag list against the PLC or OPC UA server. Site configuration.
$ python -m ingest.validate_tags --url opc.tcp://10.20.1.15:4840 58 of 60 node IDs found on opc.tcp://10.20.1.15:4840 unmatched: Spare_DI_07 ns=2;s=CIP.Spare_DI_07
Export the project from your engineering tool in its standard format, list the export under exports in site.yaml and run the import for the site (BOOLE_PLANT is the site ID). Later exports can arrive through the watched folder instead. Read the import summary before you move on: it lists what was understood and what was not.
$ BOOLE_PLANT=dairy docker compose -f deploy/compose.yaml run --rm import-code # the code exports, lists and documents named in the site folder
List the line's drawings and manuals, the work-order export from your CMMS and the spare-parts list in the documents manifest, then import them; add at least a month of alarm log. Map the CSV columns once and the mapping is reused.
$ python -m documents.load docs/manifest.yaml # documents, work orders, parts $ python -m edge.import_history --alarm-log alarms.csv alarm-map.yaml \ --trend trends.csv trend-map.yaml
Open Knowledge gaps in the web UI (experts and administrators): its knowledge-health panel shows each import with a time and a status. Fix anything red before you ask, because a missing manual becomes an answer that says "no supporting source". What each tile means.
Pick a recent stoppage whose cause your team knows, and ask about it. If BooleX finds the same cause and cites the right rung and work order, the line is ready for shift use.
Interlock IL-10 stopped P-101 and HE-101: return valve XV-105 lost its open limit switch while commanded open plc alm. Return flow FT-102 fell at the same time ts. Same signature as WO-2291 wo.
The rest of week one covers the rest of the line: more assets, live data through OPC UA or the site historian, and replaying five past stops with your engineers. One engineer can onboard a full line in five working days.
Gather these before day one. Only the first four are needed for the quickstart. Tick them off here as you go; the list is only kept in this browser.
0 of 8 ready
Twelve demo plants come with BooleX, one per sector. Each has its PLC code, functional spec, manuals and SOPs, work orders, spare parts and a history of four past stops to investigate, each replayed from a recording. The dairy plant also has electrical drawings and a P&ID. All plant data is synthetic.
| Demo plant | Equipment | Stories it tells |
|---|---|---|
| Dairy | CIP skid, separator and evaporator | A return valve closing mid-wash, pump cavitation, a separator vibration trip, evaporator fouling |
| Food and beverage | Bottling line: rinser, filler, checkweigher, capper, labeller | Stops after a format changeover: wrong recipe, a knocked photo-eye, the wrong capper chucks, a bend left in the CIP position |
| Medtech | Assembly cell: ultrasonic weld, leak test, vision | A leaking nest seal, weld energy drifting inside its window, low test air, parts tested warm after a cycle time cut |
| Automotive suppliers | Weld and assembly line, Siemens and Rockwell | A robot handshake timeout, a skipped tip dress, a part sensor after a fixture change, a light curtain stop explained |
| Machine builders | Hydraulic press at a customer site (Beckhoff) | What an alarm means, what changed since commissioning, a fix from another site, a diagnosis from exported files only |
| Packaging and plastics | Palletiser, stretch wrapper and extruder (PackML), Rockwell and CODESYS | False film breaks, a worn carriage chain, a double-counting photo-eye, a blocked screen pack |
| Process and chemicals | Batch reactor with phase logic | A hold at dosing, a stuck cooling valve, an agitator speed switch, a slow charge valve |
| Water and wastewater | Remote sewage pumping station | A thermistor trip from rags, a failed level transducer, a standby left out of service, a radio link drop |
| Energy and renewables | Wind turbine pitch system (Bachmann) | A degraded capacitor bank, a pitch motor bearing, encoder drift, a grid dip reported as a pitch fault |
| Data centres | Power and cooling plant (Rockwell) | A chiller trip on the generator test, a slow ATS transfer, a sticking flow switch, the first-out in an alarm flood |
| Marine and offshore | Ship's generators and power management (Siemens) | A load shed from a governor actuator, reverse power, low fuel pressure, a bus tie contact discrepancy |
| Pharma and biotech | SIP skid on a media preparation vessel, non-GMP (Siemens) | A failed steam trap, a clean-steam header dip outside the skid, a failed drain RTD read as bad data, a condensate valve switch |
$ make up # the dairy plant, on http://127.0.0.1:8080 $ make replay F=F16 # the CIP held on the caustic wash two minutes ago: ask why $ make up PLANT=food-bev # another plant, by its pack ID
On the demo stack an administrator switches plants from the top bar (Load pack), with no restart. The dairy plant's code comes as Bachmann, Siemens, Rockwell, CODESYS, STEP 7 Classic and other exports of the same logic. Switch the vendor and ask the same question: you get the same cause and the same sequence of events, each citing that vendor's code.
$ make vendor VENDOR=siemensBooleX runs on one PC inside your plant. In the default production profile the language model runs on that PC too, so it makes no external connections. In the hybrid and client-cloud profiles the model runs at an endpoint you approve, and the edge PC then needs no GPU.
| Item | Minimum | Notes |
|---|---|---|
| CPU | 8 cores | x86-64 |
| Memory | 32 GB | Excluding the language model |
| Storage | 1 TB SSD | 90 days of 2,000 tags at 1 s, plus documents |
| GPU | Sized per site | For the local language model. BooleX keeps each question within the model's context, so a modest card works. We confirm the card with you |
| OS | Linux with Docker Compose | All services run as containers on this host |
| Profile | Use it for | Network |
|---|---|---|
production | Live use on site (default) | No external connections. Local model only |
hybrid | Live use with a model you approve, in your cloud or on a site server | Outbound to approved model endpoints only. Only the question, the conversation and the cited excerpts are sent; every call is logged |
client_cloud | BooleX in your own cloud account, with a small collector on site | The collector connects out over HTTPS and accepts no connections in. It buffers if the link drops. Model calls follow the hybrid rules |
offline_import | Starting from files before a conduit is approved | No external connections and no control-zone connection |
Updates arrive as signed bundles that you install offline, and every update can be rolled back. A site marked as a customer site refuses to start in a development profile. For high availability, add a standby edge PC: it mirrors the store and takes over within five minutes if the primary stops.
One folder holds everything specific to your site: site.yaml (endpoints, code exports, glossary, starter prompts, KPIs and options), the tag, alarm, interlock and equipment lists beside it as CSV, and the documents manifest. Keep it in version control so anyone can see what was configured and when. The deployment profile is chosen separately, in deploy/config/profile. Every key in the configuration reference.
id: dairy title: Dairy site, CIP skid 1 site: dairy-site # appears in every source ID project: cip # code projects are cip-<vendor> customer_site: true # refuses the development profile exports: # vendor: the line's code export siemens: plc/siemens default_vendor: siemens manifest: docs/manifest.yaml # documents, work orders, parts endpoints: opcua_url: opc.tcp://10.20.1.15:4840 glossary: # the names the floor uses supply pump: P-101 prompts: # starter prompts, per asset or default CIP-100: - Why did the CIP stop? - Which interlocks are bypassed right now? kpi: baseline_median_minutes: 45 timezone: Europe/Dublin
What counts as a stop. BooleX reads the sequence state and step tags from the code: a stop is the sequence leaving its running state for held or aborting. It drives the shift summary, the time-to-diagnosis figures and the questions it can answer about "the last stop". The soe key tunes how the first signs are ranked.
Export the project from your engineering tool and import the file. Each vendor's format is read into one common model of tags, blocks, sequences, interlocks and alarm definitions, so answers cite code the same way whatever the brand. Safety programs are read as logic and answers that cite them are marked as safety functions. Know-how-protected blocks stay closed.
| Platform | Export from | Format |
|---|---|---|
| Siemens S7-1200/1500 | TIA Portal (Openness) | SimaticML XML, including S7-GRAPH and F-blocks; early access: confirmed against synthetic exports, awaiting a site export |
| Siemens S7-300/400 | STEP 7 Classic | Source files (.awl, .scl) with the symbol table (.sdf); early access: confirmed against synthetic exports, awaiting a site export |
| Rockwell Logix | Studio 5000 | L5X, including SFC and GuardLogix safety; early access: confirmed against synthetic exports, awaiting a site export |
| Rockwell SLC 500, MicroLogix, PLC-5 | RSLogix 500 / RSLogix 5 | ASCII export (.SLC, .PC5) with the address database CSV; early access: confirmed against synthetic exports, awaiting a site export |
| Schneider M340, M580, Premium, Quantum | Control Expert (Unity Pro) | XEF; early access: confirmed against synthetic exports, awaiting a site export |
| Omron NJ/NX | Sysmac Studio | PLCopen XML; early access: confirmed against synthetic exports, awaiting a site export |
| Mitsubishi iQ-R/iQ-F | GX Works3 | Exported CSV and ST folder; early access: confirmed against synthetic exports, awaiting a site export |
| B&R | Automation Studio | The project's Logical/ source tree; early access: confirmed against synthetic exports, awaiting a site export |
| Emerson PACSystems | PAC Machine Edition | PLCopen XML; early access: confirmed against synthetic exports, awaiting a site export |
| Beckhoff | TwinCAT 3 | PLCopen XML; early access: confirmed against synthetic exports, awaiting a site export |
| Bachmann | SolutionCenter | PLCopen XML; early access: confirmed against synthetic exports, awaiting a site export |
| CODESYS-based | CODESYS V3.5 | PLCopen XML export, read by the CODESYS importer (global variable lists, direct addresses); early access: confirmed against synthetic exports, awaiting a site export |
| Emerson DeltaV (DCS) | DeltaV Explorer | FHX; early access: confirmed against synthetic exports, awaiting a site export |
| Siemens PCS 7, ABB 800xA (DCS) | Engineering exports | XML exports; early access: confirmed against synthetic exports, awaiting a site export. We confirm the export with you first |
Every import ends with a summary: element counts by type, constructs BooleX could not read, and warnings. An unsupported construct is never silently dropped. Answers that depend on it say so.
project cip-bachmann source CIP100_plcopen.xml POUs 14 tags 60 interlocks 13 alarms 46 unsupported CIP_Sequence/net-31 inline C block warning 2 tags in code not in lists/tags.csv: Spare_DI_07, Spare_DI_08
Re-import after every code change. When the code on the PLC is newer than the last import, citations to changed blocks are marked stale until you import again.
Drawings, manuals, procedures and your fix history are what turn a code trace into an answer a technician can act on.
site: dairy-site format: csv # or xlsx date_format: "%Y-%m-%d %H:%M" columns: number: WO No opened: Raised closed: Completed asset: Equipment symptom: Problem cause: Cause action: Remedy
Live data lets BooleX check values while you diagnose. Pick one source per line. If your plant already runs a historian, use it: your IT team then approves one read connection instead of one per PLC.
| Source | When to use it | Access BooleX needs |
|---|---|---|
| Site historian | Ignition already in place (PI, WinCC and FactoryTalk Historian next) | Read-only account |
| OPC UA | No historian, or tags not historised. Includes Alarms & Conditions events | Read, Browse and Subscribe; signed and encrypted |
| MQTT / Sparkplug B | Plants with a broker or unified namespace | Subscribe only |
| Modbus TCP | Devices without OPC UA | Read function codes only, with a register map |
| BACnet/IP | Building and cooling plant | Read services only |
| SNMPv3 | UPS, PDUs and network gear | GET only, authenticated and encrypted |
| DNP3 | Water and power outstations | Read requests only |
| IEC 61850 MMS | Substation protection relays | Read only |
| CMMS | SAP PM, Maximo or a SQL view, for live work orders | Read-only account |
$ python -m ingest.validate_tags --url opc.tcp://10.20.1.15:4840 58 of 60 node IDs found on opc.tcp://10.20.1.15:4840 unmatched: Spare_DI_07 ns=2;s=CIP.Spare_DI_07 unmatched: Spare_DI_08 ns=2;s=CIP.Spare_DI_08
BooleX only reads. It never changes anything on your PLCs or historian. Give it a read-only account all the same; your IT team will expect it.
IT approval for a new conduit can take weeks. You don't have to wait for it. In the offline_import profile BooleX has no connection to the control zone at all, and works from exports alone.
echo offline_import > deploy/config/profile.When the conduit is approved, switch to production and add a live source. Everything already imported stays.
The knowledge health panel, on the Knowledge gaps screen for experts and administrators, shows whether BooleX has what it needs to answer. Check it after setup and after every import.
| Tile | Shows | Act when |
|---|---|---|
| Code | Time of last import per project | The PLC has changed since then |
| Documents | Count by status: indexed, scanned (OCR), failed | Any document failed |
| Work orders | Time of last import, record count | Older than your CMMS export cycle |
| Alarm and trend history | Time of the last history import | History is older than the stops you want to ask about |
| Connectors | Data gaps of each live source in the last 30 days | Any source is down or degraded |
| Journal | Latest technician journal record | No fixes recorded after a week of use |
| Knowledge gaps | Questions answered with "no supporting source", logged with the question and asset (experts and administrators) | The same gap appears twice |
Ask the way you would ask a colleague. Name the asset, the tag or the alarm if you know it. If you don't give a time, BooleX assumes the most recent stop and tells you which one it picked.
BooleX does not carry out control actions and will not advise you to bypass or defeat protection. It tells you what to check. You decide what to do.
Every statement in an answer carries a source. Click a source to open the exact rung, page, work order, alarm or trend window.
Interlock IL-10 stopped P-101 and HE-101 and held the sequence at step 40 plc://dairy-site/cip/@interlocks/IL-10
First-out: XV105_ZSO dropped at 02:13:51; A035 raised 5 s later alm://dairy-site/A035@02:13:56
Check the actuator air supply on XV-105, then the limit switch. doc://dairy-site/FDS-CIP-01@A#7
Statement with its source. A claim without a source does not appear. If nothing supports an answer, BooleX says so.
First-out. The initiating event, found from the sequence of events, not from the loudest alarm.
Ranked candidates. Each candidate cause has its own evidence. The top one is the most likely, not a certainty.
Checks, not actions. Recommendations are things a person checks. Report the result and BooleX re-ranks the candidates.
After a trip, the alarm list fills faster than anyone can read it. BooleX rebuilds the timeline from alarm events and tag changes, groups consequential alarms, and marks the event that started it.
This is the step that makes BooleX better on your line. When the fault is found, mark the candidate that was right, or reject them all, and write what you did.
The next time the same fault starts the same way, BooleX recalls this fix and cites it as a confirmed diagnosis (dx://).
Mark each answer Useful or Not useful. A not-useful rating asks what was wrong, what was missing and what the right cause was. When no plant source could answer a question, log it as a knowledge gap: experts see the list and add the missing document or journal record.
Ask for a summary of any shift. It lists stops and their causes, alarm statistics and open items such as active bypasses or standing alarms, each with its source. Edit it before you send it, as Markdown or PDF.
Workflows run on their own when something happens: an alarm, a stop, a work order or the end of a shift. Each one gathers the evidence and posts a cited briefing to the inbox. Workflows use read-only tools only, and a step that would control or write anything is refused.
| Built-in workflow | Runs on | You get |
|---|---|---|
| Alarm briefing | A priority alarm | The likely cause and where to look, before anyone asks |
| Maintenance briefing | A new work order | Past fixes, the drawing and the part, for the technician |
| Return to service | A work order closed | A check that the equipment runs as before, then a 24-hour watch |
| Shift handover | Shift end | A draft handover to check and send |
| Code change review | A new code import | What changed, and which interlocks and alarms it touches |
| Recurring fault | A repeat of a known cause | A notice with the earlier occurrences and fixes |
Isolation procedures are cited from your documents, never written by the model. Site tools can read prepared answers, sequences of events and workflow results through an optional read-only API, AI assistants through its MCP bridge, and a site group gets one overview tile per site.
Print a code for each asset and fix it to the panel door or guard. Scanning it on a tablet opens a session already scoped to that asset, with its starter prompts showing.
https://boolex.plant.local/#/asset/CIP-100
Administrators print the sheet from Asset codes (PDF) in the top bar. The link only works on the plant network.
| Source | Formats |
|---|---|
| PLC code | SimaticML, L5X, RSLogix 500/5 ASCII, XEF, PLCopen XML, GX Works3 CSV/ST, Automation Studio sources, CODESYS V3.5 PLCopen XML, STEP 7 Classic STL and SCL sources; DCS: DeltaV FHX, PCS 7 and 800xA XML exports |
| Documents | PDF (text or scanned), DOCX, Markdown, plain text |
| Drawings | EPLAN and AutoCAD Electrical report exports, DXF and DWG, PDF from any electrical CAD tool, scanned sheets (OCR), DEXPI P&ID, Visio |
| Spreadsheets | XLSX and CSV: C&E matrices, I/O lists, tag and alarm lists |
| Work orders | CSV or XLSX CMMS export, with a column mapping; or live from SAP PM, Maximo or a SQL view |
| Alarm history | CSV export, with a column mapping; OPC UA Alarms & Conditions live |
| Trends | CSV export; OPC UA, MQTT, Modbus TCP, BACnet, SNMP, DNP3, IEC 61850 or site historian live |
| HMI and electrical | WinCC and FactoryTalk View tag and alarm exports; AutomationML electrical design |
File types read from an import folder or the document importer: .csv, .docx, .dwg, .dxf, .fhx, .l5x, .md, .pdf, .txt, .vsdx, .xef, .xlsx, .xml.
Every citation is a source ID. Click one in an answer to open the source in the source viewer. How each source opens.
| Scheme | Points to | Example |
|---|---|---|
plc:// | A rung, block, tag, alarm or interlock | plc://bench/cip-bachmann/PRG_Sequence/lines-85-97 |
doc:// | A document revision, page and section | doc://bench/OM-CIP-01@B/p14#4.2 |
wo:// | A work order | wo://bench/WO-2025-0412 |
ts:// | A tag over a time window | ts://bench/TT101?from=…&to=… |
alm:// | One alarm occurrence | alm://bench/A017@2026-11-03T02:15:07Z |
dx:// | A confirmed diagnosis and its fix | dx://bench/DX-2026-0007 |
part:// | A spare part and its stock reading | part://bench/SEAL-P104-01 |
mdl:// | A behavioural model replayed on recorded data: its version, asset, variant and window | mdl://bench/centrifugal-pump@2/P-101?variant=route-stuck-closed&from=…&to=… |
The edge PC sits in its own diagnostics zone. It opens connections into the control zone and accepts none from it. Share this table with your IT/OT team; the full list of flows per profile adds sign-in, time, backup, voice, integration and standby flows.
| From | To | Port | Purpose |
|---|---|---|---|
| Edge PC | PLC or OPC UA server | 4840/TCP | OPC UA read and subscribe |
| Edge PC | Modbus device | 502/TCP | Modbus read (fallback) |
| Edge PC | MQTT broker | 1883 or 8883/TCP | Subscribe only |
| Edge PC | BACnet device | 47808/UDP | BACnet read services |
| Edge PC | SNMP agent | 161/UDP | SNMPv3 GET |
| Edge PC | DNP3 outstation | 20000/TCP | DNP3 read |
| Edge PC | IEC 61850 server | 102/TCP | MMS read |
| Edge PC | Site historian | Historian API | Read-only queries |
| Plant office | Edge PC | 443/TCP | Web UI over HTTPS |
| Edge PC | Approved model endpoint | 443/TCP | Hybrid profile only |
| Support engineer, over your VPN or jump host | Edge PC | 443/TCP | Only while your administrator has a remote support window open; off by default |
| Site collector | Your cloud receiver | 443/TCP | Client-cloud profile only; outbound only |
| Edge PC | Anything else on the internet | none | Never required |
| You see | Likely reason | Do this |
|---|---|---|
| "No supporting source" | The document, code or history is not imported | Check knowledge health, import it, ask again. Log the gap from the answer |
| Citation marked stale | The code changed since the last import | Export and re-import the project |
| OPC UA certificate rejected | The server does not trust BooleX yet | Trust the BooleX client certificate on the server |
| Tags not found | Tag list and server address space differ | Run python -m ingest.validate_tags and fix the unmatched node IDs in the tag list |
| Unsupported construct | Code BooleX cannot read yet | Answers touching it will say so; tell us which construct |
| Wrong stop picked | The question had no time | Add a time or date to the question |
| Answer mentions a data gap | The live connection dropped for a while | Nothing; BooleX records the gap, carries on after reconnecting and tells you when evidence falls inside it |