DLB Documentation

Sections

Base URL api/tlm/v1
Query parameters
Authentication
Response
Dokumentacja API telemetrii api/tlm/v2/

Method: GET

Our API also supports seamless integration with all kinds of water, energy, and utility meters. With its super-simple interface, you can read data from any device, anywhere in the world. The platform is designed for easy setup and reliable remote access, making it ideal for large monitoring systems as well as small individual installations.

Base URL api/tlm/v1

https://dlb.com.pl/api/tlm/v1/telemetry.php

Query parameters

Key		Type	Description
ID	Required	string	ID of device
KEY	Required	string	Your own password
payload	Optional<	string	default value -> ?
phone	Optional	string	phone number without char -> '+'
sms	Optional	string	message
mail	Optional	string	address
mail_title	Optional	string	title of e-mail
message	Optional	string	message

Authentication

Providing ID and KEY is also required, you can do it using one of the following methods:

Query parameter
Standard Bearer token in the header: Authorization: Bearer {token}
API KEY in the header: HTTP_X_API_KEY: {token}

Response

{
  MAIL OK
  SMS OK
  25.11.24 18:49:48;;
  25.11.24 21:36:23;ID;123456;KEY;;payload;;error;;
}

Dokumentacja API telemetrii api/tlm/v2/

Wersja: 2

Zgodność: v2

Domyslna strefa czasowa zapisu: Europe/Warsaw

1. Cel rozwiązania

API składa się z dwóch skryptów PHP:

set.php – zapisuje pomiary telemetryczne do pliku JSON,
get.php – odczytuje ostatnie pomiary dla wskazanego urządzenia i charakterystyki.

Każde urządzenie, maszyna lub moduł identyfikowany przez parametr ID ma osobny plik:

data/telemetry_<ID>.json

Przykład dla ID=1234:

data/telemetry_1234.json

W jednym pliku mogą znajdować się różne charakterystyki, np. temperatura, wilgotnosc, cisnienie i predkosc.

2. Wymagania

serwer WWW z obsługą PHP 7.3.31 lub nowszego,
możliwość wykonywania zapytań HTTP/HTTPS metodą GET,
prawo zapisu dla PHP w katalogu, w którym znajduje się set.php,
pliki set.php i get.php umieszczone w tym samym katalogu.

Zalecany układ katalogów:

/api/tlm/v2/
├── set.php
├── get.php
└── data/
    └── telemetry_1234.json

Katalog data zostanie utworzony automatycznie przy pierwszym zapisie. Użytkownik serwera WWW, najczęściej www-data, musi mieć prawo zapisu.

3. Adres bazowy

W przykładach używany jest adres:

https://dlb.com.pl/api/tlm/v2

Należy zastąpić go rzeczywistym adresem serwera.

Adres URL musi używać ukośników /:

https://dlb.com.pl/api/tlm/v2/set.php

Nie należy używać znaków \.

4. Zapis danych – `set.php`

4.1. Endpoint

GET /api/tlm/v2/set.php

4.2. Parametry

Parametr	Wymagany	Opis	Przykład
`ID`	tak	Identyfikator urządzenia. Dozwolone: litery, cyfry, `_`, `-`. Maksymalnie 80 znaków.	`1234`
`value`	tak	Wartość liczbowa. Można użyć kropki lub przecinka dziesiętnego.	`34.5`
`description`	tak	Nazwa mierzonej charakterystyki. Tworzy osobny klucz w JSON.	`temperatura`
`unit`	tak	Jednostka pomiaru.	`stC`

4.3. Najprostszy przykład

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=34&description=temperatura&unit=stC

4.4. Przykłady innych pomiarów

Temperatura:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=23.7&description=temperatura&unit=stC

Wilgotność:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=58&description=wilgotnosc&unit=procent

Ciśnienie:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=6.2&description=cisnienie&unit=bar

Wartość z przecinkiem:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=21,5&description=temperatura&unit=stC

Skrypt zamieni przecinek na kropkę i zapisze wartość jako liczbę.

4.5. Znaki specjalne w adresie

Spacje i znaki specjalne należy kodować zgodnie z URL encoding. Przykład jednostki °C:

unit=%C2%B0C

Pełny adres:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=34&description=temperatura&unit=%C2%B0C

4.6. Przykład wywołania przez `curl`

curl "https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=34&description=temperatura&unit=stC"

4.7. Prawidłowa odpowiedź

{
    "success": true,
    "message": "Dane zostaly zapisane",
    "received_get": {
        "ID": "1234",
        "value": "34",
        "description": "temperatura",
        "unit": "stC"
    },
    "ID": "1234",
    "description": "temperatura",
    "value": 34,
    "unit": "stC",
    "timestamp": "2026-07-14T08:56:13+02:00",
    "records_count": 3,
    "file": "telemetry_1234.json"
}

4.8. Sposób przechowywania

Plik data/telemetry_1234.json może wyglądać następująco:

{
    "ID": "1234",
    "created_at": "2026-07-14T08:48:00+02:00",
    "updated_at": "2026-07-14T08:56:13+02:00",
    "measurements": {
        "temperatura": [
            {
                "timestamp": "2026-07-14T08:56:13+02:00",
                "timestamp_unix": 1784012173,
                "value": 34,
                "unit": "stC"
            }
        ],
        "wilgotnosc": [
            {
                "timestamp": "2026-07-14T08:57:20+02:00",
                "timestamp_unix": 1784012240,
                "value": 58,
                "unit": "procent"
            }
        ]
    }
}

Każda nowa wartość parametru description automatycznie tworzy nowy klucz w measurements.

4.9. Limit przechowywanych rekordów

Limit jest ustawiany w set.php:

define('MAX_RECORDS', 3);

Obecna przesłana wersja przechowuje maksymalnie 3 ostatnie wpisy dla każdej charakterystyki. Aby przechowywać 100 wpisów, należy zmienić linię na:

define('MAX_RECORDS', 100);

Limit działa osobno dla każdego klucza, np. temperatura może mieć 100 wpisów i wilgotnosc również może mieć 100 wpisów.

5. Odczyt danych – `get.php`

5.1. Endpoint

GET /api/tlm/v2/get.php

5.2. Parametry

Parametr	Wymagany	Opis	Wartość domyślna
`ID`	tak	Identyfikator urządzenia, którego plik ma zostać odczytany.	—
`description`	tak	Nazwa charakterystyki, np. `temperatura`.	—
`limit`	nie	Liczba ostatnich rekordów do zwrócenia. Zakres 1–100.	`1`

5.3. Odczyt ostatniej wartości

https://dlb.com.pl/api/tlm/v2/get.php?ID=1234&description=temperatura

Brak parametru limit oznacza limit=1.

5.4. Odczyt ostatnich 2 wartości

https://dlb.com.pl/api/tlm/v2/get.php?ID=1234&description=temperatura&limit=2

5.5. Odczyt ostatnich 10 wartości

https://dlb.com.pl/api/tlm/v2/get.php?ID=1234&description=temperatura&limit=10

Jeżeli w pliku znajduje się mniej wpisów niż wynosi limit, skrypt zwróci wszystkie dostępne wpisy.

5.6. Przykład wywołania przez `curl`

curl "https://dlb.com.pl/api/tlm/v2/get.php?ID=1234&description=temperatura&limit=2"

5.7. Prawidłowa odpowiedź

{
    "status": "ok",
    "ID": "1234",
    "description": "temperatura",
    "count": 2,
    "values": [
        {
            "timestamp": "2026-07-14T08:56:13+02:00",
            "timestamp_unix": 1784012173,
            "value": 34,
            "unit": "stC"
        },
        {
            "timestamp": "2026-07-14T08:56:12+02:00",
            "timestamp_unix": 1784012172,
            "value": 33.8,
            "unit": "stC"
        }
    ]
}

Rekordy są zwracane w kolejności od najnowszego do najstarszego. Pierwszy element values[0] jest zawsze najnowszym dostępnym pomiarem.

6. Znaczenie pól JSON

Pole	Opis
`ID`	Identyfikator urządzenia lub źródła danych.
`created_at`	Czas utworzenia pliku urządzenia.
`updated_at`	Czas ostatniej aktualizacji pliku.
`measurements`	Obiekt zawierający wszystkie charakterystyki.
`timestamp`	Data i czas pomiaru w formacie ISO 8601.
`timestamp_unix`	Czas UNIX w sekundach.
`value`	Wartość pomiaru jako liczba.
`unit`	Jednostka pomiaru.
`count`	Liczba rekordów zwróconych przez `get.php`.
`values`	Tablica zwróconych pomiarów, od najnowszego.

7. Typowe błędy

7.1. Brak parametru

Przykładowa odpowiedź:

{
    "success": false,
    "error": "Brak parametru value",
    "received_get": {
        "ID": "1234"
    }
}

Należy sprawdzić, czy URL zawiera wszystkie parametry: ID, value, description i unit.

7.2. Nieprawidłowe ID

{
    "success": false,
    "error": "Nieprawidlowy format ID"
}

ID może zawierać tylko:

A-Z  a-z  0-9  _  -

Nie należy używać spacji, ukośników ani kropek.

7.3. `value` nie jest liczbą

{
    "success": false,
    "error": "Parametr value musi byc liczba",
    "received_value": "abc"
}

Poprawny przykład: value=34.5 lub value=34,5.

7.4. Nie znaleziono pliku

{
    "status": "error",
    "message": "Nie znaleziono pliku",
    "file": "telemetry_9999.json"
}

Najpierw należy wykonać co najmniej jeden zapis przez set.php dla tego samego ID.

7.5. Nie znaleziono charakterystyki

{
    "status": "error",
    "message": "Nie znaleziono charakterystyki",
    "description": "temperatura2",
    "available": [
        "temperatura",
        "wilgotnosc"
    ]
}

Pole available pokazuje nazwy dostępnych charakterystyk. Nazwa musi być identyczna jak podczas zapisu, łącznie z wielkością liter.

7.6. Brak możliwości zapisu

Jeśli serwer zwraca błąd zapisu, należy sprawdzić uprawnienia katalogu. Przykład dla systemu Debian/Ubuntu:

sudo mkdir -p /var/www/html/api/tlm/v2/data
sudo chown -R www-data:www-data /var/www/html/api/tlm/v2/data
sudo chmod 775 /var/www/html/api/tlm/v2/data

Ścieżkę /var/www/html/api należy dopasować do konfiguracji serwera.

8. Zalecenia eksploatacyjne i bezpieczeństwo

Używaj HTTPS, szczególnie gdy dane są wysyłane przez Internet.
Obecne skrypty nie posiadają uwierzytelniania. Każda osoba znająca adres może zapisywać i odczytywać dane.
W środowisku produkcyjnym zaleca się dodanie klucza API albo ograniczenie dostępu przez firewall/VPN.
Nie używaj danych poufnych w parametrach URL. Adresy GET mogą być zapisywane w logach serwera i historii przeglądarki.
Pliki PHP należy zapisać w kodowaniu UTF-8 bez BOM, aby polskie znaki były wyświetlane prawidłowo.
W przypadku częstych zapisów lub dużej liczby urządzeń lepszym rozwiązaniem będzie baza danych, np. SQLite, MariaDB lub PostgreSQL.
Należy wykonywać kopie zapasowe katalogu data, jeśli historia pomiarów jest istotna.

9. Szybki test działania

Krok 1 – zapis

Otwórz w przeglądarce:

https://dlb.com.pl/api/tlm/v2/set.php?ID=1234&value=34&description=temperatura&unit=stC

Odpowiedź powinna zawierać:

{
    "success": true
}

Krok 2 – odczyt

Otwórz:

https://dlb.com.pl/api/tlm/v2/get.php?ID=1234&description=temperatura&limit=1