API API documentation

Wstęp

Platforma smartmon.pl przeznaczona jest do zbierania, przechowywania i analizy danych telemetrycznych zbieranych przez czujniki (sensory). Możliwe jest również ustawianie reguł uaktywniających alarmy i informowanie obsługi za pomocą e-mail, SMS o aktywnych alarmach. Sensory pogrupowane są w urządzenia, które to raportują dane przy pomocy różnych protokołów. Przykładowe zastosowania to:
  • Monitoring różnych parametrów środowiska (temperatura, wilgotność, ciśnienie)
  • Monitoring parametrów serwerów (zużycie procesora, pamięci, dysku itd.)

API

API znajduje się pod adresem http://api.smartmon.pl/ . Struktura API odpowiada następującej konwencji:

http://api.smartmon.pl/write/{format}/data/{symbol}/
Gdzie:
  • write - oznacza API do zapisu (nie da się przy pomocy tego API odczytać danych)
  • format - oznacza format w jakim będziemy przyjmować dane [json / arexx]
  • symbol - symbol urządzenia którego dane zapisujemy
Aktualnie obsługiwane są dwa formaty:
  • json - najbardziej rozbudowany i umożliwiający zapis wszystkich danych
  • arexx - obsługujący arexx multilogger (http://www.arexx.com/templogger/html/en/products.php)

Format JSON

Format JSON umożliwia zakodowanie najpełniejszej informacji o urządzeniu oraz czujnikach takich jak jego symbol, nazwa, metadane, struktura danych oraz same dane. Jest używany zarówno do założenia urządzenia i sensorów jak i dodawania danych.

Autoryzacja

W celu zabezpieczenia komunikacji oraz identyfikacji użytkownika zastosowano autoryzację tokenem który można pobrać sobie z panelu użytkownika. Token musi zostać wysłany w nagłówku przy każdym zawołaniu API.

Zapisywanie danych

Zapis danych odbywa się poprzez wywołania API przy pomocy metody POST podpisanej tokenem w nagłówku wiadomości. W celu ułatwienia interakcji z API w dalszych przykładach używać będziemy programu http (dostępny do pobrania na stronie http://httpie.org/). Kolejne wywołania API nadpisują dane zapisane w systemie (w zakresie takim jaki podamy w treści wywołania)

Tworzenie urządzenia

Najprostsze wywołanie API powodujące utworzenie urządzenia o symbolu lab01 wygląda następująco:

http POST http://api.smartmon.pl/write/json/data/lab01/ "Authorization:Token (token)"
W przypadku gdy urządzenie o symbolu lab01 nie istniało w systemie zostanie założone, w przeciwnym wypadku zostanie zaktualizowane (w tym przypadku jedynie czas dostępu do tego urządzenia

Tworzenie / aktualizacja danych urządzenia

Kolejne dane wysyłamy w formacie json. Z racji tego że taki json potrafi być sporych rozmiarów dla zapewnienia czytelności przyjmijmy że za każdym razem zostanie on zapisany w pliku. Aby wysłać taki plik json z danymi do urządzenia używamy przekierowania w shellu.
Przykładowo: 
http POST http://api.smartmon.pl/write/json/data/lab01/ "Authorization:Token (token)" < file.json
wyśle zawartość pliku file.json do urządzenia lab01. W dalszej części opisana będzie tylko zawartość pliku.

Aby utworzyć / zaktualizować urządzenie z pełnymi danymi należy wysłać 
{
    "name": "laboratorium 01",
    "meta": {
        "hostname": "lab01",
        "type":"raspberrypi"
    },
    "attributes": {
        "place": "laboratorium",
        "city": "Warszawa"
    }
}
Każdy z tych kluczy (“name”, “meta”, “attributes”) może zostać pominięty. Wówczas te dane nie zostają dodane / zaktualizowane.

Dodawanie / aktualizacja czujników

Każde urządzenie może posiadać listę czujników. Dodajmy zatem do powyższego jsona kolejny klucz “sensors” z listą czujników 

{
    "name": "laboratorium 01",
    "meta": {
        "hostname": "lab01",
        "type":"raspberrypi"
    },
    "attributes": {
        "place": "laboratorium",
        "city": "Warszawa"
    },
    "sensors": [
        {
            "symbol": "28.3DB42E040000",
            "structure": {"temperature":"float"},
            "name": "Pomieszczenie 1 temperatura",
            "meta": {
                "type": "thermometer",
                "unit": "celcius"
            }
        },
        {
            "symbol": "28.A935B4050000",
            "structure":{"temperature":"float"},
            "name":"Pomieszczenie 2",
            "meta":{
                "type":"thermometer",
                "unit":"celsius"
            }
        }
    ]
}
Powyższe wywołanie spowoduje dodanie / aktualizację urządzenia a także dodanie / aktualizację danych czujników. Podobnie jak w przypadku urządzeń większość kluczy (wszystkie w wyjątkiem “symbol”) w czujniku można pominąć.

Dodawanie wartości (pomiarów)

Aby dodać wartości można rozszerzyć powyższą strukturę czujnika o values. Ponieważ jednak większość z tych kluczy można pominąć w poniższym przykładzie zaprezentujemy strukturę która dodaje/aktualizuje jedynie wartosci czujników. 

{
    "sensors": [
        {
            "symbol": "28.3DB42E040000",
            "values": [
                {
                    "t": "2015-01-05T00:00:00Z",
                    "v": {"temperature": 68}
                },
                {
                    "t": "2015-01-05T00:05:00Z",
                    "v": {"temperature": 67.5}
                }
           ]
        },
        {
            "symbol": "28.A935B4050000",
            "values": [
                {
                    "t": "2015-01-05T00:00:00Z",
                    "v": {"temperature": 71.5}
                },
                {
                    "t": "2015-01-05T00:05:00Z",
                    "v": {"temperature": 70.0}
                }
            ]
        }
    ]
}

Format AREXX

Format AREXX umożliwia przyjmowanie danych z loggerów arexx (http://www.arexx.com/templogger/html/en/products.php), np. BS1000

Aby skonfigurować w urządzeniu BS1000 wysyłanie danych należy:
  • podać adres 
    http://api.smartmon.pl/write/arexx/data/BS1000/
  • metoda: 
    POST
  • podać następujący ciąg konfiguracyjny
    type==$q&&id==$i&&time==$S&&v==$v&&rssi==$r&&token==(token)

Oczywiście (token) podmieniamy na token pobrany z konfiguracji smartmon.pl.

Działanie API można również przetestować ręcznie:

    http POST http://api.smartmon.pl/write/arexx/data/labar01/ token=(token) id=19200 type=1 time=2000 rssi=40 v=10

ESP Easy - Generic HTTP

ESP Easy to oprogramowanie umożliwiające zbieranie i przesyłanie danych z czujników podłączonych do popularnych modułów opartych na ESP8266 (np. Wemos 1D)

Oprogramowanie to można ściągnąć z githuba: https://github.com/letscontrolit/ESPEasy/releases, dokumentacja znajduje się tutaj: https://www.letscontrolit.com/wiki/index.php/ESPEasy

smartmon.pl obsługuje najprostszy format Generic HTTP w dwóch wariantach: token autoryzacyjy można podać w URL lub w basic auth. Aby umożliwić ESP wysyłanie danych do smartmon.pl należy:

  • zainstalowac najnowszą wersję ESPEasy (dokumentacja powstała na podstawie wersji: mega-20180927)
  • skonfigurować podłączone czujniki tak aby ich dane były lokalnie widoczne
  • połączyć się przez przeglądarkę ze swoim ESPEasy
  • wybrać zakładkę "Controllers"
  • są tam trzy sloty na protokoły. należy kliknąć EDIT przy nieużywanym
  • wybrać "Protocol" -> "Generic HTTP"
  • konfigurujemy integrację ustawiając kolejno:
    • Locate Controller: Use hostname
    • Controller Hostname: api.smartmon.pl
    • Controller Port: 80
    • Controller User: token
    • Controller Password: (token)
    • Controller Publish: write/espeasy/generic_http/myesp/?sensor=%tskname%&vname=%valname%&v=%value%&name=%sysname%&rssi=%rssi%&uptime=%uptime%&id=%id%
    • Enabled: zaznaczamy

Oczywiście (token) podmieniamy na token pobrany z konfiguracji smartmon.pl.

Powyższa konfiguracja spowoduje że w panelu smartmon.pl zobaczymy urządzenie o symbolu "myesp" (oczywiście ten symbol możemy sobie zdefiniowac dowolnie). W ramach tego urządzenia pojawią się sensory o symbolach: "(sensor)_(vname)". Obie te wartości można skonfigurować na karcie urządzenia ESP. Pierwsze z nich to "Name" urządzenia, drugie z nichto Name znajdujące się w sekcji Values. Ponieważ używamy do komunikacj metody GET postarajmy się aby te nazwy były jak najkrótsze i nie zawierały spacji oraz znaków specjalnych.

Alternatywie token można przekazać jako zmienna w query string. W tym wypadku nie podajemy go jako Controller User / Controller Password tylko doklejamy do urla w ControllerPublish jako "token=(token)". Rekomendowaną metodą jest jednak podanie go w parametrach integracji gdyż w ten sposób nie jest widoczny w logach oraz nie zabiera nam cennego miejsca w URL