Skip to content

Configuration

Jump to bottom
Tomasz Jablonowski edited this page Sep 30, 2025 · 1 revision

SmartESS Client — Strona główna

Krótko: minimalny klient do odczytu rejestrów z dataloggera SmartESS / Dessmonitor.
Program wysyła UDP notify, akceptuje połączenie TCP od dataloggera i tuneluje żądania Modbus RTU przez Modbus TCP, zwracając wynik jako JSON.

Szybkie linki:

Dla developerów i szczegółów technicznych zobacz README.md w repozytorium.

Getting Started

W kilku krokach uruchomienia:

  1. Sklonuj repozytorium:
git clone <repo-url>
  1. (Opcjonalnie) utwórz i aktywuj virtualenv (Windows):
python -m venv venv
venv\Scripts\activate
  1. Uruchom przykład (przykładowy IP i rejestr):
python smartess_client.py 192.168.1.50 100 --count 2

Wymagania:

  • Python 3.7+
  • Komputer i datalogger w tej samej sieci LAN (lub skonfigurowany routing / przekierowanie portów)

Uwaga: projekt nie używa zewnętrznych pakietów (standardowa biblioteka Pythona).

Usage — opcje CLI

Wywołanie:

python smartess_client.py <IP_DATALOGGERA> <REGISTER> [--count N] [--localip X.X.X.X] [--tcp-port 502] [--udp-port 58899] [--debug]

Argumenty:

  • IP_DATALOGGERA — adres IP urządzenia SmartESS
  • REGISTER — adres startowy rejestru (liczba całkowita)
  • --count — liczba rejestrów do odczytu (domyślnie 1)
  • --localip — wymuszony lokalny adres interfejsu (autodetekcja jeśli brak)
  • --tcp-port — port TCP Anenji (domyślnie 502)
  • --udp-port — port UDP (domyślnie 58899)
  • --debug — włącza dodatkowe logi

Przykład wynikowego JSON:

{ "ts": "2025-09-30T12:00:00", "100": 123, "101": -5 }

Opis działania:

  1. Skrypt wysyła UDP notify do dataloggera (port domyślny 58899).
  2. Otwiera nasłuch TCP (domyślnie port 502) i akceptuje połączenie, które inicjuje datalogger.
  3. Wysyła tunelowaną ramkę Modbus (funkcja 3 — odczyt holding registers) i parsuje odpowiedź.
  4. Zwraca wynik jako JSON z timestampem.

Configuration

Parametry i uwagi techniczne:

  • --localip — jeśli host ma wiele interfejsów, użyj tej opcji by wskazać adres źródłowy (jeśli brak, skrypt próbuje autodetekcji).
  • --tcp-port — port, na który skrypt nasłuchuje połączenia od dataloggera (domyślnie 502). Upewnij się, że port jest otwarty i nieblokowany przez system/firewall.
  • --udp-port — port, na który skrypt wysyła notify (domyślnie 58899).
  • --debug — włącza szczegółowe logi (przydatne do debugowania połączeń i ramek).

Protokół i specyfika:

  • SmartESS przesyła tunelowane ramki: MBAP + prefiks 0x04 0x01 zawierający RTU PDU + CRC RTU. Oznacza to, że nie można traktować ruchu jako czysty Modbus TCP — skrypt uwzględnia prefiks i CRC.
  • Jeśli host jest za NAT, uruchom skrypt w tej samej sieci co datalogger lub skonfiguruj przekierowania portów/publiczny adres.

CRC16 (MODBUS) — jak to działa w projekcie:

  • Algorytm CRC używany w Modbus RTU:
    • Inicjalna wartość CRC = 0xFFFF.
    • Dla każdego bajtu: XOR z bieżącym CRC, następnie 8 iteracji przesunięcia w prawo; jeśli najmłodszy bit był ustawiony, XOR z polinomem 0xA001.
    • Rezultat to 16-bitowa wartość CRC zapisana w porządku little-endian (LSB pierwsze) przy dołączaniu do ramki.
  • W tym repozytorium funkcja obliczająca CRC to crc16_modbus(data: bytes) -> int w smartess_client.py. Przy budowie tunelowanej ramki CRC jest dopisywane jako struct.pack("<H", crc).
  • Przykład użycia (w kodzie): przy budowie PDU obliczamy CRC po bajcie Unit ID (0x01) + RTU-PDU i dołączamy w little-endian:
crc = crc16_modbus(b"\x01" + fn_addr_qty)
pdu = b"\x04\x01" + fn_addr_qty + struct.pack("<H", crc)
  • Uwaga praktyczna: podczas parsowania odpowiedzi warto weryfikować długość PDU uwzględniając CRC (2 bajty) i oczekiwaną liczbę danych.

FAQ / Troubleshooting

Q: Skrypt nie otrzymuje połączenia TCP — co sprawdzić?

  • Sprawdź, czy firewall na hoście nie blokuje portu 502.
  • Upewnij się, że komputer i datalogger są w tej samej sieci lub skonfigurowany jest odpowiedni routing/NAT.

Q: Czy potrzebuję dodatkowych bibliotek Pythona?

  • Nie — projekt używa tylko standardowej biblioteki (Python 3.7+).

Q: Co oznacza tunelowanie w kontekście SmartESS?

  • Datalogger używa MBAP nagłówka, ale PDU zawiera prefiks 0x04 0x01 i wewnątrz znajduje się RTU PDU wraz z CRC — stąd specyficzne parsowanie i budowa ramek.

Q: Gdzie znaleźć szczegółowe informacje techniczne?

  • Dla programistów i szczegółowych opisów funkcji sprawdź README.md w repozytorium.

Contributing

Chętnie przyjmujemy poprawki i małe PR-y.

Zasady:

  • Preferuj małe, jedna-logiczna-zmiana na Pull Request.
  • Dobrze opisuj tytuł PR i opisuj co i dlaczego zmieniasz.
  • Testuj lokalnie jeśli to możliwe.

Edycja dokumentacji Wiki:

  • Możesz edytować przez UI GitHub lub sklonować repozytorium wiki:
git clone https://github.com/<user>/<repo>.wiki.git

Następnie commit → push. Jeśli pracujesz nad kodem, utwórz branch w głównym repo i otwórz PR tam.

Kontakt:

  • Zgłaszaj błędy i propozycje przez Issues w głównym repozytorium.

CHANGELOG

1.0 — pierwsze wydanie

  • Podstawowy klient do odczytu rejestrów z dataloggera SmartESS/Dessmonitor.
  • Wysyłanie UDP notify, akceptacja połączenia TCP, tunelowanie Modbus RTU przez Modbus TCP.
  • Wyjście w formacie JSON z timestampem.

_Sidebar

Clone this wiki locally