Metadata-Version: 2.4
Name: pym2v
Version: 0.2.0
Summary: Python wrapper to interact with the Eurogard m2v IoT platform
Keywords: eurogard,m2v,iot,iiot,api
Author: Stefan Langenbach
Author-email: Stefan Langenbach <stefan.langenbach@bytecare.tech>
License-Expression: AGPL-3.0-only
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.0
Requires-Dist: httpx-auth>=0.23.0
Requires-Dist: polars>=1.0.0
Requires-Dist: pydantic-settings>=2.6.1
Requires-Dist: tenacity>=9.0.0
Requires-Dist: tqdm>=4.67.1
Maintainer: Stefan Langenbach
Maintainer-email: Stefan Langenbach <stefan.langenbach@bytecare.tech>
Requires-Python: >=3.12, <3.14
Project-URL: Homepage, https://www.bytecare.tech
Project-URL: Documentation, https://www.bytecare.tech/pym2v
Project-URL: Repository, https://github.com/bytecaretech/pym2v
Description-Content-Type: text/markdown

# pym2v

![CI](https://github.com/bytecaretech/pym2v/actions/workflows/ci.yml/badge.svg)
![Docs](https://github.com/bytecaretech/pym2v/actions/workflows/docs.yml/badge.svg)
![PyPI](https://img.shields.io/pypi/v/pym2v)

Python wrapper to interact with [m2v][1] industrial IoT platform from [Eurogard][2].

## Prerequisites

- Python 3.12+
- Programmatic access to the Eurogard API

## Installation

pym2v is available as a Python package and can be installed via pip or [uv][3].

### Via pip

1. Create a virtual environment: `python3 -m venv .venv`
1. Activate the virtual environment: `source .venv/bin/active`
1. Install pym2v via pip: `pip install pym2v`

### Via uv

1. Install pym2v via uv: `uv add pym2v`

## Configuration

To authenticate with the Eurogard API, you need to provide the following credentials:

- Username
- Password
- Client ID
- Client Secret

You can do this either by using an `.env` file or by setting environment variables directly.

### Using an .env file

Rename the `.env.example` at the root of the project to `.env`, and replace the placeholder values with your actual credentials.

```
EUROGARD_BASEURL=https://eurogard.cloud
EUROGARD_USERNAME=your_username_here
EUROGARD_PASSWORD=your_password_here
EUROGARD_CLIENT_ID=your_client_id_here
EUROGARD_CLIENT_SECRET=your_client_secret_here
```

## Usage

Import the `EurogardAPI` object and create an instance of it

```python
from datetime import datetime, timedelta

from pym2v.api import EurogardAPI


api = EurogardAPI()
```

Retrieve a list of machines

```python
machines = api.get_machines()
```

Get the UUID of the machine your are interested in

```python
MACHINE_NAME = "1337Machine"

machine_uuid = api.get_machine_uuid(MACHINE_NAME, machines)
```

Get the names of measurements for which you like to pull data

```python
result = api.get_machine_measurement_names(machine_uuid)
```

Turn the data returned by the API into a DataFrame for easier handling

```python
import polars as pl

measurement_names_df = pl.DataFrame(result["entities"])
```

Get actual data

```python
START_DATE = datetime(2025, 1, 1)
END_DATE = datetime(2025, 1, 13)
INTERVAL = timedelta(seconds=60)
MAX_FRAME_LENGTH = timedelta(days=30)
NAMES = [col.strip() for col in measurement_names_df.get_column("name").to_list()]

data_df = api.get_long_frame_from_names(
    machine_uuid=machine_uuid,
    names=NAMES,
    start=START_DATE,
    end=END_DATE,
    interval=INTERVAL,
    max_frame_length=MAX_FRAME_LENGTH,
)
```

## Contributing

Check out [CONTRIBUTING.md](CONTRIBUTING.md) for further information.


[1]: https://eurogard.de
[2]: https://eurogard.de/software/m2v/
[3]: https://docs.astral.sh/uv/
