Data sources and connectors

Live data (OPC UA, Modbus, MQTT, BACnet, SNMP, DNP3, IEC 61850), site historians, the CMMS and document sources.

Every connector only reads, and each has a test that proves it. Give each one an account that can do nothing else.

Live data

The ingest service reads one live source, set in site.yaml endpoints or overridden by environment variables. BACnet, SNMP, DNP3 and IEC 61850 can run together.

Each also takes a …_PORT and a …_PERIOD_S polling period (5 s by default for the polled protocols). A lost connection is recorded as a data gap with its start, end and source; answers that need data from a gap say so, and the knowledge health view shows the connector as disconnected.

OPC UA

Security is set in site.yaml opcua:. Paths are relative to the site folder; secrets are files.

opcua:
  policy: Basic256Sha256          # or Aes128_Sha256_RsaOaep; None only in development
  mode: SignAndEncrypt            # or Sign
  client_cert: pki/edge.der
  client_key: pki/edge.pem
  trust_dir: pki/trusted          # trusted server and CA certificates
  crl_dir: pki/crl                # certificate revocation lists
  username: boolex                # or user_cert / user_key for an X.509 identity
  password_file: /run/secrets/opcua_password

Add the edge PC's application certificate to each server's trusted clients. An untrusted, expired or revoked server certificate is refused, leaves an open data gap naming the endpoint and the reason, and raises a platform alarm.

Check the site's tag list against the server before going live:

python -m ingest.validate_tags --url opc.tcp://<server>:4840

It prints how many of the tag list's node IDs were found, and each one that was not.

Site historian

Where the site already has a historian, BooleX reads process data and alarm history from it instead of storing its own copy. Supported: Ignition SQL tag history and AVEVA PI through PI Web API.

historian: {product: ignition, prefix: "[default]CIP/"}

Put the read-only connection string in BOOLE_SITE_HISTORIAN_DSN. The login needs SELECT on the tag-history and alarm-journal tables only, with a read-only default transaction; every query runs in a read-only transaction.

historian: {product: pi_web_api, base_url: "https://pi.plant.local/piwebapi", data_server: PISRV01, prefix: "CIP.", asset_database: "\\\\AFSRV01\\Dairy", ca_file: certs/pi-web-api.pem, username: "PLANT\\svc-boolex"}

For PI, BooleX sends HTTP GET requests only (recorded values, summaries, event frames), over HTTPS with the server certificate checked against ca_file. Authentication is Basic, with the password in BOOLE_SITE_HISTORIAN_PASSWORD_FILE, or a bearer token in BOOLE_SITE_HISTORIAN_TOKEN_FILE; Kerberos is not supported. The account needs read access only on the PI points and, for alarm history, on the AF database's event frames. See Connect a historian.

Files instead of a live connection

Alarm logs, trend exports, drive and robot fault logs and batch records can be imported as files (the offline-import profile, or history from before go-live):

python -m edge.import_history --alarm-log alarms.csv alarm-mapping.yaml --trend trend.csv trend-mapping.yaml
python -m edge.import_history --device-log drive-faults.csv drive-mapping.yaml
python -m edge.import_history --batches batches.csv

A mapping file names the export's columns and time format, so any historian's or HMI's export can be read.

CMMS

Work orders come either as exports (CSV or XLSX listed in the documents manifest, with a column mapping) or live from the CMMS through the cmms service (make up PROFILES=…,cmms):

cmms:
  product: maximo                 # sap_pm, maximo or sql
  base_url: https://maximo.site.local/maximo
  username: boolex_ro
  password_file: /run/secrets/cmms_password   # or api_key_file (Maximo)
  interval_s: 900
  # sql: dsn_file and query (one SELECT)

SAP PM is read through its maintenance-order OData service, Maximo through its OSLC mxwo object structure, and a SQL source through one configured SELECT in a read-only transaction. The REST client can only send GET. New and changed work orders are cited as wo://. BooleX never writes to the CMMS; a confirmed fix becomes a work-order draft file for a person to import.

Documents

Documents, drawings, work-order exports and parts lists are imported from a manifest, or read in place (document_sources, the watch profile) from a read-only file share, SharePoint Server, SharePoint Online, OneDrive or Google Drive: see Documents and work orders. The cloud libraries are read only in the hybrid and client-cloud profiles, on approved endpoints.