Metadata-Version: 2.4
Name: kotori
Version: 0.28.1
Summary: Kotori is a data acquisition, processing and graphing toolkit for humans
Home-page: https://github.com/daq-tools/kotori
Author: Andreas Motl
Author-email: andreas.motl@getkotori.org
License: AGPL 3, EUPL 1.2
Keywords: data acquisition graphing export plotting daq routing engine mqtt http rest amqp wamp sql web html csv json cdf hdf5 png twisted pyramid autobahn influxdb mosquitto grafana mongodb matplotlib ggplot telemetry m2m iot sensor-network sensorwan
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: Pyramid
Classifier: Framework :: Twisted
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Manufacturing
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: Topic :: Communications
Classifier: Topic :: Database
Classifier: Topic :: Internet
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Object Brokering
Classifier: Topic :: System :: Archiving
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Requires-Python: >=3.5
License-File: LICENSE
Requires-Dist: Twisted[tls]<26
Requires-Dist: pyOpenSSL>=16.2.0
Requires-Dist: setuptools<81
Requires-Dist: six>=1.15.0
Requires-Dist: pyramid<1.11
Requires-Dist: pyramid_jinja2<3,>=2.8
Requires-Dist: cornice<7,>=5.0.3
Requires-Dist: simplejson<4,>=3.17.2
Requires-Dist: Jinja2<4
Requires-Dist: munch<5,>=2.5.0
Requires-Dist: appdirs<2,>=1.4.3
Requires-Dist: json-store<5,>=3.1
Requires-Dist: python-dateutil<3,>=2.8.0
Requires-Dist: arrow<2,>=0.17.0
Requires-Dist: funcy<3,>=1.15
Requires-Dist: attrs<26,>=20.2.0
Requires-Dist: importlib-metadata; python_version < "3.8"
Requires-Dist: paho-mqtt<3,>=1.5.1
Requires-Dist: autobahn[twisted]<26,>=20.7.1
Requires-Dist: msgpack-python<0.6,>=0.5.6
Requires-Dist: PyTrie<1,>=0.4.0
Requires-Dist: distlib<0.5
Requires-Dist: docopt-ng<0.10
Requires-Dist: cryptography>=2.9.2
Requires-Dist: certifi>=2020.6.20
Requires-Dist: service_identity<25
Requires-Dist: idna<4
Requires-Dist: pyasn1<0.7
Requires-Dist: pyasn1-modules<0.5
Provides-Extra: full
Requires-Dist: kotori[daq,daq_geospatial,export,firmware,scientific]; extra == "full"
Provides-Extra: daq
Requires-Dist: influxdb<6,>=5.3.0; extra == "daq"
Requires-Dist: pytz>=2020.1; extra == "daq"
Requires-Dist: requests<3,>=2.12.4; extra == "daq"
Requires-Dist: grafana_api_client==0.2.0; extra == "daq"
Requires-Dist: pymongo<5,>=3.11.0; extra == "daq"
Provides-Extra: daq-geospatial
Requires-Dist: Geohash<2,>=1.0; extra == "daq-geospatial"
Requires-Dist: geopy<3,>=1.12.0; extra == "daq-geospatial"
Requires-Dist: Beaker<2,>=1.9.0; extra == "daq-geospatial"
Requires-Dist: tqdm<5; extra == "daq-geospatial"
Provides-Extra: daq-binary
Requires-Dist: pycparser<3.1; extra == "daq-binary"
Requires-Dist: pyparsing<3.4; extra == "daq-binary"
Requires-Dist: pyclibrary<0.4; extra == "daq-binary"
Requires-Dist: tabulate<0.8; extra == "daq-binary"
Requires-Dist: sympy<1.15; extra == "daq-binary"
Provides-Extra: storage-plus
Requires-Dist: alchimia<1,>=0.4; extra == "storage-plus"
Provides-Extra: export
Requires-Dist: pyinfluxql<1,>=0.0.1; extra == "export"
Requires-Dist: numpy==1.18.5; python_version == "3.5" and extra == "export"
Requires-Dist: pandas<1.3; python_version < "3.10" and extra == "export"
Requires-Dist: numpy<1.22; python_version < "3.10" and extra == "export"
Requires-Dist: pandas<1.6; python_version < "3.12" and extra == "export"
Requires-Dist: numpy<1.25; python_version < "3.12" and extra == "export"
Requires-Dist: pandas<3; python_version < "3.13" and extra == "export"
Requires-Dist: numpy<2; python_version < "3.13" and extra == "export"
Requires-Dist: pandas<4; extra == "export"
Requires-Dist: numpy<3; extra == "export"
Requires-Dist: XlsxWriter<4,>=1.3.6; extra == "export"
Provides-Extra: plotting
Requires-Dist: matplotlib<3.11,>=3; extra == "plotting"
Requires-Dist: bokeh<4,>=1.4.0; extra == "plotting"
Requires-Dist: vincent<0.5,>=0.4.4; extra == "plotting"
Provides-Extra: scientific
Requires-Dist: h5py<4,>=2.10.0; python_version < "3.11" and extra == "scientific"
Requires-Dist: tables<4,>=3.5.2; python_version < "3.11" and extra == "scientific"
Requires-Dist: xarray<2025; extra == "scientific"
Requires-Dist: netCDF4<1.8,>=1.5.3; extra == "scientific"
Requires-Dist: ggplot<0.12,>=0.11.5; extra == "scientific"
Provides-Extra: firmware
Requires-Dist: GitPython<4,>=2.0.5; extra == "firmware"
Requires-Dist: plumbum<1.11,>=1.6.1; extra == "firmware"
Provides-Extra: test
Requires-Dist: pytest<8; extra == "test"
Requires-Dist: pytest-cov<8; extra == "test"
Requires-Dist: pytest-twisted<2; extra == "test"
Requires-Dist: datadiff<3; extra == "test"
Requires-Dist: coverage<8; extra == "test"
Requires-Dist: poethepoet<1; extra == "test"
Provides-Extra: release
Requires-Dist: build; extra == "release"
Requires-Dist: bump2version<2; extra == "release"
Requires-Dist: twine<7; extra == "release"
Requires-Dist: keyring<26; extra == "release"
Requires-Dist: invoke<3; extra == "release"
Requires-Dist: requests<3; extra == "release"
Requires-Dist: sh<3; extra == "release"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

.. _kotori-readme:

##########
Kotori DAQ
##########

.. container:: align-center

    .. figure:: https://ptrace.getkotori.org/2016-05-23_chart-recorder.png
        :alt: Chart recorder
        :width: 240px
        :target: .

    |

    *Telemetry data acquisition and sensor networks for humans.*

    .. image:: https://assets.okfn.org/images/ok_buttons/oc_80x15_blue.png
        :target: https://okfn.org/opendata/

    .. image:: https://assets.okfn.org/images/ok_buttons/ok_80x15_red_green.png
        :target: https://okfn.org/opendata/

    .. image:: https://assets.okfn.org/images/ok_buttons/os_80x15_orange_grey.png
        :target: https://okfn.org/opendata/

----

:**Status**:

  .. image:: https://img.shields.io/pypi/status/kotori.svg
        :target: https://pypi.org/project/kotori/
        :alt: Project status (alpha, beta, stable)

  .. image:: https://github.com/daq-tools/kotori/workflows/Tests/badge.svg
        :target: https://github.com/daq-tools/kotori/actions?workflow=Tests
        :alt: CI outcome

  .. image:: https://codecov.io/gh/daq-tools/kotori/branch/main/graph/badge.svg
        :target: https://codecov.io/gh/daq-tools/kotori
        :alt: Code coverage

  .. image:: https://img.shields.io/pypi/v/kotori.svg
        :target: https://pypi.org/project/kotori/
        :alt: Package version on PyPI

  .. image:: https://img.shields.io/pypi/l/kotori.svg
        :target: https://pypi.org/project/kotori/
        :alt: Project license

:**Usage**:

  .. image:: https://static.pepy.tech/personalized-badge/kotori?period=month&left_text=PyPI%20downloads%20%2F%20month&left_color=gray&right_color=orange
        :target: https://pepy.tech/project/kotori
        :alt: PyPI downloads per month

  .. image:: https://img.shields.io/docker/pulls/daqzilla/kotori.svg?label=docker%20pulls%20(kotori)
        :target: https://hub.docker.com/r/daqzilla/kotori
        :alt: Docker image pulls for `kotori` (total)

  .. image:: https://img.shields.io/docker/pulls/daqzilla/kotori-standard.svg?label=docker%20pulls%20(kotori-standard)
        :target: https://hub.docker.com/r/daqzilla/kotori-standard
        :alt: Docker image pulls for `kotori-standard` (total)

:**Compatibility**:

  .. image:: https://img.shields.io/badge/Mosquitto-1.5%2C%201.6%2C%202.0-blue.svg
        :target: https://github.com/eclipse/mosquitto
        :alt: Supported Mosquitto versions

  .. image:: https://img.shields.io/badge/Grafana-5.x%20--%2012.x-blue.svg
        :target: https://github.com/grafana/grafana
        :alt: Supported Grafana versions

  .. image:: https://img.shields.io/badge/InfluxDB-1.6%2C%201.7%2C%201.8-blue.svg
        :target: https://github.com/influxdata/influxdb
        :alt: Supported InfluxDB versions

  .. image:: https://img.shields.io/badge/MongoDB-3.x%20--%208.x-blue.svg
        :target: https://github.com/mongodb/mongo
        :alt: Supported MongoDB versions

  .. image:: https://img.shields.io/pypi/pyversions/kotori.svg
        :target: https://pypi.org/project/kotori/
        :alt: Supported Python versions

----


*****
About
*****

Kotori is a multi-channel, multi-protocol telemetry data acquisition and graphing
toolkit for `time series`_ data processing also known as `data historian`_.

It supports a variety of scenarios in scientific environmental monitoring projects,
for building and operating distributed sensor networks, and for industrial data
acquisition applications.


Details
=======

Kotori is a data and protocol broker within `SCADA`_ / `MDE`_
systems, exclusively built upon industry-grade `free and open-source software`_
like Grafana_, Mosquitto_, or InfluxDB_. It is written in Python_,
and uses the Twisted_ networking library.

The best way to find out what you can do with Kotori, is by looking at
some outlined `scenarios`_ and by reading how others are using it at the
`example gallery <gallery_>`_. To learn more about the technical details, have
a look at the used `technologies`_.


Features
========

- Multi-channel and multi-protocol data-acquisition and -storage. Collect and
  store sensor data from different kinds of devices, data sources, and protocols.
- Built-in sensor adapters, flexible configuration capabilities, durable
  database storage and unattended graph visualization.
- Based on an infrastructure toolkit assembled from different components
  suitable for data-acquisition, -storage, -fusion, -graphing and more.
- Leverage the flexible data acquisition integration framework for building
  telemetry data acquisition and logging systems, test benches, or sensor
  networks for environmental monitoring systems, as well as other kinds of
  data-gathering and -aggregation projects.
- It integrates well with established hardware-, software- and
  data acquisition workflows through flexible adapter interfaces.


************
Installation
************

Kotori can be installed in different ways, see `all installation options`_.
You may prefer using a Debian package, install it from the Python Package
Index (PyPI), or run it within a development environment directly from the
Git repository, see `sandbox installation instructions`_.


********
Synopsis
********

A compact example how to submit measurement data on a specific channel, using
MQTT and HTTP, and export it again.

Data acquisition
================

First, let's define a data acquisition channel::

    CHANNEL=amazonas/ecuador/cuyabeno/1

and some example measurement data::

    DATA='{"temperature": 42.84, "humidity": 83.1}'

Submit with MQTT::

    MQTT_BROKER=daq.example.org
    echo "$DATA" | mosquitto_pub -h $MQTT_BROKER -t $CHANNEL/data.json -l

Submit with HTTP::

    HTTP_URI=https://daq.example.org/api/
    echo "$DATA" | curl --request POST --header 'Content-Type: application/json' --data @- $HTTP_URI/$CHANNEL/data

Data export
===========
Measurement data can be exported in a variety of formats.

This is a straight-forward example for CSV data export::

    http $HTTP_URI/$CHANNEL/data.csv


****************
Acknowledgements
****************

Thanks a stack to all the `contributors`_ who helped to co-create and conceive
Kotori in one way or another. You know who you are.


*******************
Project information
*******************

Contributions
=============

Every kind of contribution, feedback, or patch, is much welcome. `Create an
issue`_ or submit a patch if you think we should include a new feature, or to
report or fix a bug.

Development
===========

In order to setup a development environment on your workstation, please head over
to the `development sandbox`_ documentation. When you see the software tests succeed,
you should be ready to start hacking.

Resources
=========

- `Source code <https://github.com/daq-tools/kotori>`_
- `Documentation <https://getkotori.org/>`_
- `Python Package Index (PyPI) <https://pypi.org/project/kotori/>`_

License
=======

The project is licensed under the terms of the GNU AGPL license, see `LICENSE`_.


************
Supported by
************

.. image:: https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg
    :target: https://jb.gg/OpenSourceSupport

Special thanks to the people at JetBrains s.r.o. for supporting us with
excellent development tooling.


.. _all installation options: https://kotori.readthedocs.io/setup/
.. _Autobahn: https://crossbar.io/autobahn/
.. _contributors: https://kotori.readthedocs.io/project/contributors.html
.. _Create an issue: https://github.com/daq-tools/kotori/issues/new
.. _data historian: https://en.wikipedia.org/wiki/Operational_historian
.. _development sandbox: https://kotori.readthedocs.io/setup/sandbox.html
.. _free and open-source software: https://en.wikipedia.org/wiki/Free_and_open-source_software
.. _gallery: https://kotori.readthedocs.io/gallery/index.html
.. _Grafana: https://en.wikipedia.org/wiki/Grafana
.. _InfluxDB: https://en.wikipedia.org/wiki/InfluxDB
.. _LICENSE: https://github.com/daq-tools/kotori/blob/main/LICENSE
.. _MDE: https://de.wikipedia.org/wiki/Maschinendatenerfassung
.. _MongoDB: https://en.wikipedia.org/wiki/MongoDB
.. _Mosquitto: https://github.com/eclipse/mosquitto
.. _MQTT: https://en.wikipedia.org/wiki/MQTT
.. _Python: https://www.python.org/
.. _sandbox installation instructions: https://kotori.readthedocs.io/setup/sandbox.html
.. _SCADA: https://en.wikipedia.org/wiki/SCADA
.. _scenarios: https://kotori.readthedocs.io/about/scenarios.html
.. _technologies: https://kotori.readthedocs.io/about/technologies.html
.. _time series: https://en.wikipedia.org/wiki/Time_series
.. _Twisted: https://en.wikipedia.org/wiki/Twisted_(software)
