Metadata-Version: 2.4
Name: meterlog-sdk
Version: 1.1.0
Summary: SATEC MeterLog SDK: export data logs, event logs and diagnostics from EM133/EM235 power meters to CSV over Modbus TCP
Author: SATEC Australia
License: Commercial
Keywords: satec,modbus,power-meter,em133,em235,energy,datalog
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# MeterLog SDK for Python

Read live values and export data logs, event logs and diagnostics from SATEC
EM133 and EM235 power meters over Modbus TCP. Includes the `meterlog`
command-line tool.

Requires Python 3.9+ on Windows x64, Linux x64, Linux arm64 or macOS Apple
Silicon. The meter must be reachable on TCP port 502.

## Install

```bash
pip install meterlog-sdk
```

Recent Linux distributions and macOS block system-wide pip installs. Use a
virtual environment:

```bash
python3 -m venv venv && source venv/bin/activate
pip install meterlog-sdk
```

## Quick Start

Command line — replace the address with your meter's IP:

```bash
meterlog live    --meter em133 --host 192.168.1.203
meterlog datalog --meter em133 --host 192.168.1.203 --file-id 1 --out datalog1.csv
```

Python:

```python
from meterlog import MeterLogClient

client = MeterLogClient()

live = client.read_live("192.168.1.203", "em133")
print(live.timestamp, live["Total kW"].value, "kW", live["Frequency"].value, "Hz")

rows = client.export_datalog("192.168.1.203", "em133", 1, "datalog1.csv")
print(f"Exported {rows} rows")
```

## Command Line

```bash
meterlog live              --meter em133 --host HOST [--json] [--interval 5 [--count 12]] [--out live.csv]
meterlog datalog           --meter em133 --host HOST --file-id 1  --out datalog1.csv
meterlog datalog           --meter em235 --host HOST --file-id 13 --out datalog13.csv
meterlog eventlog          --meter em133 --host HOST --file-id 0  --out eventlog.csv
meterlog em133-all         --host HOST --out-dir ./output [--sync-rtc] [--meter-password 0]
meterlog em235-diagnostics --host HOST --unit-id 1 --start-reg 44327 --count 2 --word-order HI_FIRST --out diag.csv
```

| Flag | Meaning |
|------|---------|
| `--meter` | `em133` or `em235` |
| `--host` | Meter IPv4 address |
| `--file-id` | Log number. EM133 data logs `1`–`3`, EM235 data logs e.g. `13`/`14`, event log `0` |
| `--out`, `--out-dir` | Output CSV file, or output directory (must exist) |
| `--interval`, `--count` | `live` only: repeat every N seconds, optionally stopping after N readings. Ctrl+C stops |
| `--json` | `live` only: print a JSON document per reading instead of a table |
| `--sync-rtc` | Set the meter clock before the bulk export. Off by default |
| `--meter-password` | Meter write password, only used with `--sync-rtc` |

`meterlog live --out live.csv --interval 60` is a simple logger: one row per
minute, timestamp first, one column per value with its unit in the header.

## API

`MeterLogClient(lib_path=None)` — the bundled native library is used unless
`lib_path` or the `METERLOG_LIB_PATH` environment variable points elsewhere.

| Method | Returns |
|--------|---------|
| `version()` | SDK version string |
| `read_live(host, meter)` | `LiveReadings` |
| `export_datalog(host, meter, file_id, csv_path)` | Rows written |
| `export_eventlog(host, meter, file_id, csv_path)` | Events written |
| `export_em133_all(host, sync_rtc, out_dir, meter_password=0)` | Total records written across data logs 1–3 and the event log |
| `export_em235_diagnostics(host, unit_id, start_reg, count, word_order, csv_path)` | Rows written |

`meter` is `"em133"` or `"em235"`. `word_order` is `"HI_FIRST"` or
`"LO_FIRST"`. All methods raise `MeterLogError` with the meter's message on
failure.

### Live readings

`LiveReadings` has `meter`, `host`, `timestamp` (ISO 8601 UTC) and
`readings`, a list of `Reading(name, value, unit)` in the meter's order.
`live["Total kW"]` and `live.get("Frequency")` look a reading up by name;
`live.as_dict()` gives `{name: value}`.

| Group | Names |
|-------|-------|
| Per phase | `V1`–`V3`, `V12`/`V23`/`V31`, `I1`–`I3`, `kW L1`–`L3`, `kvar L1`–`L3`, `kVA L1`–`L3`, `PF L1`–`L3`, `V1 THD`…, `I1 THD`…, `I1 K-Factor`…, `I1 TDD`… |
| Totals | `Total kW`, `Total kvar`, `Total kVA`, `Total PF`, `Total PF lag`, `Total PF lead`, `Total kW import`/`export`, `Total kvar import`/`export`, `V avg`, `V L-L avg`, `I avg` |
| Auxiliary | `In`, `Frequency`, `V unbalance`, `I unbalance`; EM235 also `I4`, `I leakage` |
| Energy | `kWh import`, `kWh export`, `kvarh import`, `kvarh export`, `kVAh total`; EM235 also `kWh net`, `kWh total`, `kvarh net`, `kvarh total` |

## Output

- Values are in engineering units (V, A, kW, kWh, Hz, …) with the decimal
  places defined by the meter's Modbus reference guide. Data log column
  headers come from the parameters configured in each log. If the meter's
  scaling registers cannot be read, raw register values are written instead.
- Timestamps are UTC.
- The whole log file is read from the oldest record; records are
  de-duplicated by sequence number.

## Troubleshooting

| Message | Fix |
|---------|-----|
| `No matching distribution found for meterlog-sdk` | Python is older than 3.9, or the platform is not one of the four supported |
| `externally-managed-environment` | Install inside a virtual environment (see Install) |
| `meterlog: command not found` | Activate the virtual environment the package was installed into |
| `Cannot connect to <host>:502` | Check the IP, `ping` the meter, and allow outbound TCP 502 through any firewall |
| `Invalid IPv4 host` | Pass a dotted-decimal address, not a hostname |
| Export times out after ~30 s | The meter is offline or busy |
