Metadata-Version: 2.5
Name: kymoscope-collector
Version: 0.1.2
Summary: Site collector for Kymoscope: OPC UA, logger files and custom sources to end-to-end encrypted streams
Project-URL: Homepage, https://kymoscope.com
Project-URL: Documentation, https://kymoscope.com/docs/collector
License: # Kymoscope SDK License Agreement
        
        Copyright © 2026 Kymoscope. All rights reserved.
        
        This is proprietary software. It is licensed, not sold. By installing, copying
        or using the Kymoscope SDK (the "Software") you agree to these terms. If you do not
        agree, do not use the Software.
        
        > Template notice for the owner: this agreement was drafted as a starting point.
        > Have it reviewed by a lawyer for your jurisdiction and fill in the legal
        > entity, governing law and contact details before relying on it.
        
        ## 1. Licenses
        
        **1.1 Evaluation.** You may use the Software without a license key to evaluate
        it and to develop your integration. Unlicensed use displays a "Powered by
        Kymoscope" attribution in the workspace.
        
        **1.2 Production.** Using the Software in a product, service or internal tool
        made available to anyone other than your own developers ("Production Use")
        requires a valid license key issued by Kymoscope for each domain the Software is
        served from, under an order or agreement with Kymoscope.
        
        **1.3 Scope.** A license key is personal to the licensee named in it, for the
        domains listed in it and until its expiry date.
        
        ## 2. Restrictions
        
        You must not, and must not allow others to:
        
        1. make the Software available in Production Use without a valid license key
           for that domain;
        2. remove, hide, obscure or alter the attribution shown by unlicensed use, or
           the copyright notices in the Software;
        3. circumvent, disable or modify the license check, or create, alter or share
           license keys;
        4. copy, sell, sublicense, distribute or publish the Software, or offer it as a
           standalone component library or SDK, except as embedded in your own product
           as permitted above;
        5. reverse engineer, decompile or disassemble the Software, except to the
           extent applicable law expressly permits it despite this restriction;
        6. use the Software to build a competing embeddable analytics or charting
           product.
        
        ## 3. Kymoscope services
        
        Live-stream relaying, watch tickets and other hosted services are provided
        under your Kymoscope account terms and may be rate limited or suspended for abuse.
        
        ## 4. Ownership
        
        Kymoscope and its licensors own all rights in the Software. No rights are granted
        except those expressly stated here.
        
        ## 5. Termination
        
        This license ends automatically if you breach it. On termination you must stop
        using the Software and delete all copies.
        
        ## 6. No warranty and limitation of liability
        
        The Software is provided "as is", without warranties of any kind. To the
        maximum extent permitted by law, Kymoscope is not liable for any indirect,
        incidental or consequential damages, and its total liability is limited to the
        fees you paid for the Software in the twelve months before the claim.
        
        ## 7. Contact
        
        For license keys and commercial terms, contact Kymoscope.
License-File: LICENSE.md
Requires-Python: >=3.10
Requires-Dist: asyncua<3,>=2.1
Requires-Dist: kymoscope>=0.4.0
Requires-Dist: numpy>=1.22
Requires-Dist: pyyaml>=6
Requires-Dist: tzdata; sys_platform == 'win32'
Provides-Extra: files
Requires-Dist: asammdf>=7.4; extra == 'files'
Requires-Dist: nptdms>=1.7; extra == 'files'
Requires-Dist: pyarrow>=12; extra == 'files'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=7; extra == 'test'
Provides-Extra: windows
Requires-Dist: pywin32>=306; (sys_platform == 'win32') and extra == 'windows'
Description-Content-Type: text/markdown

# 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`:

```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
