kymoscope-collector

Site collector for Kymoscope. It runs on one host in a plant (normally the DMZ), reads an OPC UA server, a folder of logger files or your own Python source, encrypts the data and publishes it as Kymoscope streams. Outbound connections only; the disk buffer holds ciphertext.

Install

pip install kymoscope-collector              # core: OPC UA, CSV files, Python sources
pip install "kymoscope-collector[files]"     # + Parquet, TDMS and MF4 files
pip install "kymoscope-collector[windows]"   # + Windows service

Requires Python 3.10 or later.

• Docker: ghcr.io/javijur/kymoscope-collector (mount a folder with collector.yaml at /data). The container runs as uid 10001, so give it the folder: sudo chown -R 10001:10001 /srv/kymoscope (or use --user). It stops with a clear message when /data is not writable.
• Linux (systemd): sudo useradd --system --no-create-home --shell /usr/sbin/nologin kymoscope, then copy the unit file to /etc/systemd/system/. It ships in the package at <site-packages>/kymoscope_collector/packaging/kymoscope-collector.service (and in the repository at packages/collector/packaging/). Uncomment ReadWritePaths= for any folder a files source writes to (ProtectSystem=strict).
• Windows service: runs as LocalSystem by default. For a dedicated account: sc config KymoscopeCollector obj= .\kymoscope password= ..., with modify rights on state_dir and on every watched folder (its done and failed folders too). The service restarts itself after any failure.

Code-signed installers are coming.

Quick start (no plant needed)

kymoscope-collector simulate                                   # demo OPC UA server on port 4840
kymoscope-collector browse --url opc.tcp://localhost:4840 --out tags.csv
kymoscope-collector run --config collector.yaml

A minimal collector.yaml:

api_key: env:KYMOSCOPE_API_KEY
sources:
  - name: Demo plant
    type: opcua
    url: opc.tcp://localhost:4840
    security: None
    allow_insecure: true      # demo server only
    tags: tags.csv

Notes:

• Unknown keys in collector.yaml are an error that lists the valid ones; a password with security: None is allowed but logged as a warning.
• Editing tags.csv reconnects the source, so its tags have a short gap.
• One OPC UA source handles about 2,000 tags reporting at distinct millisecond times per second. Split larger tag lists into several type: opcua sources with different tags files.
• The enumeration labels are not sent. Blocks wait in a memory queue bounded by buffer.memory_mb (default 256) while a stream cannot register; the oldest are dropped and counted in <source>.queue_dropped.
• The private key state_dir/pki/own/key.pem is created owner-only (0600; on Windows user, SYSTEM and Administrators).

Other commands: cert (show or renew the collector's certificate), service install|remove|start|stop (Windows).

Documentation

Configuration reference, certificates, security notes, health stream and troubleshooting: https://kymoscope.com/docs/collector