app-value

Opis

Bloczek app-value służy do udostępniania jednej wartości liczbowej pomiędzy logiką projektu a interfejsem użytkownika. Może pełnić rolę zadajnika temperatury, procentu, zwykłej wartości liczbowej albo czasu.

Bloczek posiada jedno wejście i jedno wyjście. Nie wymaga stosowania wejść oznaczanych za pomocą bloczka tag.

Aktualna wartość może być zmieniana na dwa sposoby:

• przez zdarzenia doprowadzone do wejścia bloczka
• z poziomu aplikacji mobilnej albo interfejsu WWW powiązanego z tym bloczkiem

Bloczek przechowuje jedną bieżącą wartość. Każda poprawna zmiana aktualizuje opis widoczny pod bloczkiem oraz stan prezentowany w aplikacji i WWW.

Parametry konfiguracyjne

Nazwa parametru	Wartość
name	Parametr opcjonalny. Określa nazwę widoczną dla użytkownika w aplikacji mobilnej i WWW. Brak tego parametru nie blokuje pracy bloczka.
value_type	Parametr obowiązkowy określający typ wartości. Obsługiwane są wartości: temperature, percentage, numeric, time.
extended_precision	Parametr obowiązkowy dla typów temperature, percentage i numeric. Przy wartości true bloczek pracuje z precyzją 0.1. Przy wartości false akceptuje tylko pełne liczby. Dla typu time parametr nie jest używany, ponieważ czas zawsze jest obsługiwany z dokładnością do 1 sekundy.
minimum_value	Parametr obowiązkowy określający minimalną dopuszczalną wartość. Dla typów temperature, percentage i numeric dozwolony zakres wynosi od -20000000.0 do 20000000.0. Dla typu time dozwolony zakres wynosi od 0 do 864000 sekund, czyli do 240 godzin. Wartość musi być zgodna z wybraną precyzją: pełne liczby dla extended_precision = false albo wielokrotności 0.1 dla extended_precision = true.
maximum_value	Parametr obowiązkowy określający maksymalną dopuszczalną wartość. Obowiązują te same ograniczenia jak dla minimum_value. Wartość maximum_value musi być większa od minimum_value.
step_value	Parametr obowiązkowy dla typów temperature, percentage i numeric. Określa krok regulacji udostępniany interfejsowi użytkownika. Musi być zgodny z wybraną precyzją, czyli być pełną liczbą albo wielokrotnością 0.1. Dla typu time krok nie jest konfigurowany i zawsze wynosi 1 sekundę.
persistent_state	Parametr opcjonalny typu logicznego true albo false. Gdy ustawione jest true, bloczek próbuje po ponownym uruchomieniu projektu przywrócić ostatnią utrwaloną wartość. Zapis trwały nie następuje od razu, tylko około 10 minut po ostatniej zmianie. Jeśli restart albo zanik zasilania nastąpi wcześniej, może zostać przywrócona wcześniejsza wartość.
block_pass_thru_io	Parametr opcjonalny typu logicznego true albo false. Domyślnie ma wartość false. Gdy ustawione jest false, poprawna zmiana odebrana na wejściu aktualizuje bieżącą wartość i jest wysyłana dalej na wyjście. Gdy ustawione jest true, poprawna zmiana odebrana na wejściu aktualizuje bieżącą wartość, ale nie jest przekazywana dalej na wyjście z tego zdarzenia wejściowego.

Obsługa wejścia

Bloczek reaguje wyłącznie na wartości numeryczne. Akceptowane są więc wejścia liczbowe, w tym także wartości temperatury i procentów. Wartości nienumeryczne, takie jak tekst, true, false albo null, są ignorowane.

Szczegółowe zasady działania:

• odebrana wartość jest najpierw zaokrąglana do precyzji wynikającej z konfiguracji
• dla extended_precision = true zaokrąglenie następuje do 0.1
• dla extended_precision = false zaokrąglenie następuje do pełnej liczby
• dla typu time zaokrąglenie zawsze następuje do pełnej sekundy
• jeśli wartość po zaokrągleniu jest mniejsza od minimum_value albo większa od maximum_value, bloczek ignoruje takie zdarzenie
• jeśli nowa poprawna wartość różni się od poprzedniej, bloczek zapisuje ją jako bieżącą, aktualizuje opis pod bloczkiem oraz stan widoczny w aplikacji i WWW
• jeśli block_pass_thru_io = false, poprawna zmiana odebrana na wejściu jest dodatkowo wysyłana na wyjście bloczka
• jeśli block_pass_thru_io = true, zmiana odebrana na wejściu nie jest emitowana na wyjście, ale nadal zmienia bieżącą wartość bloczka

Bloczek nie wymaga połączenia wejściowego, aby działać. Może być używany także wyłącznie jako zadajnik obsługiwany z aplikacji mobilnej albo WWW.

Jeśli włączono persistent_state i wcześniej udało się utrwalić stan bloczka, to po uruchomieniu projektu bloczek odtworzy tę wartość i wyśle ją ponownie na wyjście.

Wyjście bloczka

Bloczek posiada jedno wyjście.

Na wyjściu pojawia się bieżąca wartość bloczka w typie wynikającym z parametru value_type:

• dla temperature jest to wartość temperatury
• dla percentage jest to wartość procentowa
• dla numeric jest to zwykła wartość liczbowa bez jednostki
• dla time jest to wartość czasu

Opis widoczny pod bloczkiem pokazuje bieżącą wartość w standardowej reprezentacji tekstowej. Przykładowo może to być:

• 21.5°C dla temperatury
• 55% dla wartości procentowej
• 12.3 dla zwykłej wartości liczbowej
• 1h 30m 0s dla czasu
• null, jeśli bloczek nie ma jeszcze ustawionej bieżącej wartości

Błędy zwracane przez bloczek

Bloczek może zwracać następujące błędy:

Kod błędu	Opis błędu
Invalid value type configuration.	Parametr value_type nie został podany albo ma wartość inną niż temperature, percentage, numeric lub time.
Invalid extended precision configuration.	Dla typu temperature, percentage albo numeric nie podano poprawnej wartości parametru extended_precision.
Invalid minimum value configuration.	Parametr minimum_value jest niepoprawny, ma zły typ, jest spoza dozwolonego zakresu albo nie zgadza się z wybraną precyzją.
Invalid maximum value configuration.	Parametr maximum_value jest niepoprawny, ma zły typ, jest spoza dozwolonego zakresu albo nie zgadza się z wybraną precyzją.
Minimum value greater/equal than maximum.	Wartość minimum_value jest większa od maximum_value albo jest z nią równa.
Invalid step configuration.	Parametr step_value jest niepoprawny albo nie zgadza się z wybraną precyzją.

Przykłady działania

• Jeśli value_type = temperature, extended_precision = true, minimum_value = 18.0, maximum_value = 25.0, a na wejście dotrze wartość 21.26, to bloczek zapisze i wyemituje wartość 21.3°C.
• Jeśli value_type = numeric, extended_precision = false, minimum_value = 0, maximum_value = 10, a na wejście dotrze wartość 7.6, to bloczek zaokrągli ją do 8.
• Jeśli value_type = time, minimum_value = 0, maximum_value = 3600, a na wejście dotrze wartość 90.8, to bloczek zaokrągli ją do 91 sekund i pokaże opis 1m 31s.
• Jeśli block_pass_thru_io = true, a na wejście dotrze poprawna nowa wartość, to bieżąca wartość bloczka zostanie zmieniona, ale samo to zdarzenie wejściowe nie zostanie przekazane na wyjście.
• Jeśli na wejście dotrze wartość spoza zakresu, na przykład 120 przy konfiguracji minimum_value = 0 i maximum_value = 100, to zdarzenie zostanie zignorowane.