Klient HTTP¶

Klient HTTP umożliwia wysyłanie żądań HTTP do zewnętrznych serwerów. Może być wykorzystywany zarówno do cyklicznego wysyłania danych, jak i do wysyłania żądań HTTP w ramach funkcji Zdarzenia.

Od wersji oprogramowania SW 1.36 klient HTTP obsługuje różne metody HTTP, własne nagłówki oraz treść żądania.

Elementy strony¶

Formularz konfiguracji klienta HTTP zawiera następujące opcje:

używanie podwójnego znaku % do wstawiania odczytów z urządzenia (umożliwia wprowadzanie znaku %),
używanie uwierzytelniania Digest Authentication,
konfigurację cyklicznego wysyłania:
- włączenie funkcji,
- okres wysyłania,
- URL,
- metodę HTTP (dostępne od SW 1.36),
- nagłówki żądania (dostępne od SW 1.36),
- treść żądania (dostępne od SW 1.36),
konfigurację wysyłania żądań HTTP w ramach funkcji Zdarzenia – cztery sekcje (HTTP1–HTTP4), każda z dwoma wariantami:
- wysyłanie po spełnieniu warunku,
- wysyłanie po przestaniu spełniania warunku,
dla których można ustawić:
- URL,
- metodę HTTP (dostępne od SW 1.36),
- nagłówki żądania (dostępne od SW 1.36),
- treść żądania (dostępne od SW 1.36).

Opcja wysyłania żądań za pośrednictwem modułu LTE została usunięta w wersji SW 1.22.
Więcej na temat tej zmiany na stronie Modem LTE.

Konfiguracja klienta HTTP¶

Klient HTTP umożliwia wysyłanie żądań HTTP do wskazanego serwera w określonych odstępach czasu lub w odpowiedzi na spełnienie warunków w funkcji Zdarzenia.

Uwierzytelnianie¶

Klient HTTP obsługuje uwierzytelnianie Basic Authentication oraz Digest Authentication.

Preferowanym sposobem konfiguracji jest podanie danych uwierzytelniania w polu URL w postaci:

http(s)://username:password@domena:port/ścieżka

Na tej podstawie klient HTTP generuje nagłówek Authorization wykorzystywany do obsługi Basic Authentication.
Jeżeli serwer wymaga Digest Authentication, zostanie ono obsłużone w drugim żądaniu.

Uwaga:
Zdefiniowanie własnego nagłówka Authorization powoduje pominięcie mechanizmu uwierzytelniania opartego na danych username:password zawartych w polu URL.

Digest Authentication¶

Po włączeniu opcji Użyj Digest Authentication zmienia się sposób działania klienta HTTP.

Pierwsze żądanie wysyłane jest bez danych uwierzytelniania. Następnie, w zależności od wymagań serwera, wysyłane jest kolejne żądanie z użyciem Digest Authentication lub Basic Authentication.

Metoda HTTP¶

Domyślną metodą jest GET. Od wersji SW 1.36 dostępne są również metody:

POST
PUT
PATCH

Metody inne niż GET umożliwiają przesyłanie danych w treści żądania.

Nagłówki HTTP¶

Od wersji SW 1.36 możliwe jest definiowanie własnych nagłówków HTTP, np.:

Content-Type
Authorization

Nagłówki należy podawać w formacie tekstowym Nazwa: wartość, przy czym każdy nagłówek powinien być zdefiniowany w osobnej linii.

Treść żądania (Body)¶

Od wersji SW 1.36 możliwe jest zdefiniowanie treści żądania dla metod POST, PUT oraz PATCH.

obsługiwana jest wyłącznie treść tekstowa (np. JSON, XML),
nie są obsługiwane dane binarne.

Wstawianie odczytów z urządzenia¶

W URL oraz treści żądania można używać bieżących odczytów z urządzenia, korzystając ze specjalnego formatu %XXXA.

Szczegóły dotyczące kodów odczytów znajdują się w sekcji Kody odczytów.

Przykłady użycia¶

Przykład: wysyłanie danych do serwera ThingSpeak¶

Poniższy przykład pokazuje konfigurację cyklicznego wysyłania zapytań HTTP GET do serwera ThingSpeak z wykorzystaniem odczytu temperatury.

W sekcji cyklicznego wysyłania należy:

wybrać GET w polu Metoda żądania,
wpisać w polu URL:
http://api.thingspeak.com:80/update?api_key=H2PN0O35KRVRG6Q0&field1=%0101

W efekcie do serwera wysyłane jest zapytanie:

GET /update?api_key=H2PN0O35KRVRG6Q0&field1=26.3 HTTP/1.0
Host: api.thingspeak.com
Connection: close

To samo zapytanie można wysłać ręcznie, wpisując w przeglądarce:

http://api.thingspeak.com/update?api_key=H2PN0O35KRVRG6Q0&field1=26.3

Przykład: wykorzystanie klienta HTTP z kamerą Dahua¶

Klient HTTP może zostać wykorzystany do wysyłania danych (np. odczytów z czujników) w celu wyświetlenia ich na obrazie z kamery Dahua.

W tym celu należy:

zaznaczyć Użyj Digest Authentication (od wersji SW 1.36 nie jest to konieczne),
w sekcji Cykliczne wysyłanie:
- wybierz GET w Metodzie żądania,
- w polu URL wpisać:
```
http://<NAZWA_UŻYTKOWNIKA>:<HASŁO>@<ADRES_IP_KAMERY>:80/cgi-bin/configManager.cgi?action=setConfig&ChannelTitle[0].Name=<TEKST>
```
  Przykład:
```
http://admin:admin@192.168.1.14:80/cgi-bin/configManager.cgi?action=setConfig&ChannelTitle[0].Name=T %0101 H %0111|U %0470
```
  gdzie: - %0101 – odczyt T1 (temperatura), - %0111 – odczyt H1 (wilgotność), - %0470 – czas pracy urządzenia (uptime).
- zaznaczyć Włącz cykliczne wysyłanie,
- ustawić Okres wysyłania, np. 30 sekund.

W efekcie na obrazie z kamery będzie wyświetlany tekst aktualizowany co określony czas.

Jeżeli na kamerze włączony jest dostęp HTTPS (System > Safety > HTTPS), w URL należy użyć https zamiast http.

Przykład: wysyłanie wiadomości przez Telegram¶

Od wersji SW 1.27 klient HTTP może być wykorzystywany do wysyłania żądań do API Telegram, co pozwala na otrzymywanie powiadomień z tcPDU w postaci wiadomości Telegram.

W poniższym przykładzie wykorzystane zostanie konto bota. Instrukcję tworzenia bota można znaleźć w dokumentacji Telegram.
W skrócie polega to na wysłaniu komendy /newbot w czacie z @BotFather oraz podaniu wymaganych danych.

W efekcie zostanie wygenerowany token, niezbędny do autoryzacji bota i wysyłania żądań do Bot API. Token ma postać ciągu cyfr połączonego z ciągiem znaków a-zA-Z0-9_, rozdzielonych znakiem :.

Następnie należy otworzyć czat z utworzonym botem – może to być czat bezpośredni lub grupowy – i wysłać wiadomość /start. W odpowiedzi otrzymany zostanie identyfikator czatu (ID) w postaci ciągu cyfr, zwykle poprzedzonych znakiem -.

Po uzyskaniu wymaganych danych można przejść do konfiguracji klienta HTTP na tcPDU w celu wykorzystania go w funkcji Zdarzenia.

W formularzu konfiguracji należy:

wybrać GET w polu Metoda żądania,

w polu URL wprowadzić adres (tekst w nawiasach [] należy zastąpić uzyskanymi wcześniej danymi lub własnym tekstem):

https://api.telegram.org:443/bot[TOKEN DOSTĘPOWY BOTA]/sendMessage?chat_id=[ID CZATU]&text=[TEKST WIADOMOŚCI DO WYSŁANIA]

Przykład:

https://api.telegram.org:443/bot110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw/sendMessage?chat_id=-3188255240076&text=Temperatura w biurze wynosi %0101 C.

Po skonfigurowaniu odpowiedniego wpisu w funkcji Zdarzenia, wiadomości z tcPDU będą wysyłane bezpośrednio na wskazany czat Telegram.

Kody odczytów¶

Bieżące odczyty z czujników oraz wybrane parametry urządzenia mogą być wykorzystywane w:

zapytaniach klienta HTTP (URL oraz treść żądań),
wyświetlaczu OLED,
treściach wiadomości e-mail,
wiadomościach SMS.

Format kodu odczytu¶

Format wstawiania odczytów ma postać %XXXA, gdzie:

% – znak rozpoczynający specjalny format,
XXX – numer odczytu zapisany jako trzycyfrowa wartość (lista kodów poniżej),
A – parametr określający sposób formatowania wartości.

Parametr `A`¶

Parametr A przyjmuje wartości z zakresu 0–3. W większości przypadków określa liczbę miejsc po przecinku, jednak dla wybranych odczytów ma specjalne znaczenie:

0 – brak miejsc dziesiętnych,
1 – jedno miejsce dziesiętne,
2 – dwa miejsca dziesiętne,
3 – trzy miejsca dziesiętne.

Specjalne działanie parametru A dla wybranych odczytów

Dla niektórych odczytów parametr A ma inne znaczenie:

UPTIME
- 0 – wartość w sekundach
- 1 – wartość w minutach
- 2 – wartość w godzinach
- 3 – wartość w formacie dd-hh:mm:ss
Time
- 0 – hh:mm:ss
- 1 – hhmmss
Date
- 0 – yyyy-mm-dd
- 1 – yyyymmdd
OUT1–OUT7, VAR1–VAR8, INPD1–INPD2 (tylko OLED)
- 0 – tekst 0 lub 1
- 1 – graficzna reprezentacja stanu

Zalecane wartości parametru A

Aby zachować format wartości zgodny z prezentacją na stronie urządzenia, zaleca się stosowanie następujących ustawień parametru A:

0 dla: OUT, INPD (iDValue),
1 dla: T1 (i2cTemp), H1 (i2cHum), DS, UAC,
2 dla: IAC,
3 dla: POWER, ENERGY, DIFF.

Lista kodów odczytów¶

Pełna lista dostępnych kodów odczytów znajduje się poniżej.

{
    '000': 'UAC',
    '001': 'IAC',
    '002': 'DS1',
    '003': 'DS2',
    '004': 'DS3',
    '005': 'DS4',
    '006': 'DS5',
    '007': 'DS6',
    '008': 'DS7',
    '009': 'DS8',
    '010': 'T1',
    '011': 'H1',
    '012': 'DIFF1',
    '013': 'DIFF2',
    '014': 'DIFF3',
    '015': 'DIFF4',
    '016': 'DIFF5',
    '017': 'DIFF6',
    '018': 'INPD1',
    '019': 'INPD2',
    '020': 'OUT1',
    '021': 'OUT2',
    '022': 'OUT3',
    '023': 'OUT4',
    '024': 'OUT5',
    '025': 'OUT6',
    '026': 'OUT7',
    '027': 'POWER1',
    '028': 'POWER2',
    '029': 'POWER3',
    '030': 'POWER4',
    '031': 'POWER5',
    '032': 'POWER6',
    '033': 'ENERGY1',
    '034': 'ENERGY2',
    '035': 'ENERGY3',
    '036': 'ENERGY4',
    '037': 'ENERGY5',
    '038': 'ENERGY6',
    '039': 'VAR1',
    '040': 'VAR2',
    '041': 'VAR3',
    '042': 'VAR4',
    '043': 'VAR5',
    '044': 'VAR6',
    '045': 'VAR7',
    '046': 'VAR8',
    '047': 'UPTIME',
    '048': 'IP',
    '049': 'Time',
    '050': 'Date',
    '051': 'Dew Point', // dodane w SW 1.14
}

Aktualna lista kodów odczytów jest również dostępna bezpośrednio na stronie urządzenia w sekcjach, w których może być wykorzystywana (Klient HTTP, OLED, E-mail, Modem LTE).