From 03c85e4adca6a0402262aa391c78dfdb294d2c07 Mon Sep 17 00:00:00 2001 From: dafik Date: Sat, 25 Nov 2023 09:14:32 +0100 Subject: [PATCH] readme grammar, fixes and update --- README.md | 121 ++++++++++++++++++++++++++---------------------------- 1 file changed, 59 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 1de22a1..7574f37 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,9 @@ Raspberry Pi, Odroid, BeagleBone, Orange Pi, [wiecej](https://www.diozero.com/#s System przeznaczony jest dla następujących grup użytkowników: -- **Właściciele [BoneIo Black](https://boneio.eu/#boneio-black)**: System służy jako projekt bazowy dla tych użytkowników, zapewniając im potężne możliwości - platformę do kontrolowania i zarządzania operacjami wejścia/wyjścia urządzeń. +- **Właściciele [BoneIo Black](https://boneio.eu/#boneio-black)**: System zapewnia im potężną +platformę do kontrolowania i zarządzania operacjami wejścia/wyjścia urządzenia. + - **Użytkownicy Home Assistant zainstalowani na Raspberry Pi**: Dla tych użytkowników system działa jako dodatek do Home Assistant, umożliwiający pełne wykorzystanie możliwości sprzętowych Pi, w tym GPIO, PWM, UART i SPI. @@ -38,10 +39,10 @@ System przeznaczony jest dla następujących grup użytkowników: ## Funkcje -Sbc2ha zostało początkowo opracowany jako port oryginalnego oprogramowania [BoneIo Black](https://github.com/boneIO-eu/app_black), +Sbc2ha zostało początkowo opracowane jako port oryginalnego oprogramowania [BoneIo Black](https://github.com/boneIO-eu/app_black), które zostało napisane w języku Python i było dostępne wyłącznie dla platformy BeagleBone. -Obecny system jest jednak napisany w silnie typowanym języku programowania JAVA — dzięki temu jest przenaszalny pomiędzy różnymi platformami (SBC). -Oprogramowanie opiera się na wspaniałej biblioteki [diozero](https://www.diozero.com/), zawiera również małe wstawki w języku C (JNI) do komunikacji z systemem Linux. +Obecny system jest jednak napisany w mocno typowanym języku programowania JAVA — dzięki temu może być przenoszony pomiędzy różnymi platformami (SBC). +Oprogramowanie opiera się na świetnej bibliotece [diozero](https://www.diozero.com/), zawiera również małe wstawki w języku C (JNI) do komunikacji z systemem Linux. Z biegiem czasu oprogramowanie znacznie ewoluowało, rozwiązując i korygując mniej udane wybory dokonane przez twórców oryginalnego oprogramowania. Obecnie oferuje ono wsparcie dla większej liczby czujników i siłowników, dzięki wykorzystaniu biblioteki diozero i standaryzacji obsługi urządzeń. @@ -57,23 +58,22 @@ System może pochwalić się szeroką gamą funkcjonalności, w tym: przeglądania dzienników urządzeń na żywo, kontrolowania i monitorowania urządzeń oraz zarządzania systemem. - **Łatwa integracja dodatkowego sprzętu**: Jeśli obsługa sprzętowa tych komponentów została już napisana - w diozero, można je łątwo zintegrować z systemem. Ta funkcja znacznie zwiększa wszechstronność systemu + w diozero, można je łatwo zintegrować z systemem. Ta funkcja znacznie zwiększa wszechstronność systemu i możliwości adaptacji, czyniąc z niego potężne narzędzie do szerokiego zakresu zastosowań. -- **Tryb autonomiczny**: W trybie autonomicznym system umożliwia bezpośrednie sterowanie podłączonymi urządzeniami w oparciu o różne zdarzenia i odczyty. - różnych zdarzeń i odczytów. Jest to najbardziej podstawowy tryb pracy dla wieloplatformowego systemu kontroli wejść/wyjść urządzeń. - System. +- **Tryb autonomiczny**: W trybie autonomicznym system umożliwia bezpośrednie sterowanie podłączonymi urządzeniami na podstawie różnych zdarzeń i odczytów. + Jest to najbardziej podstawowy tryb pracy dla wieloplatformowego systemu kontroli wejść/wyjść urządzeń. -- **Integracja MQTT**: System może nasłuchiwać tematów MQTT i wykonywać działania w oparciu, o otrzymywane wiadomości. - Może również publikować wiadomości do tematów MQTT, gdy wystąpią zdarzenia lub zmienią się odczyty czujników +- **Integracja MQTT**: System może nasłuchiwać tematów MQTT i wykonywać działania w oparciu o otrzymywane wiadomości. + Może również publikować wiadomości do tematów MQTT, gdy wystąpią zdarzenia lub zmienią się odczyty czujników. - **Integracja z Home Assistant**: W trybie Home Assistant system płynnie integruje się z Home Assistant, - popularna platforma automatyki domowej typu open source. Pozwala to na sterowanie i monitorowanie tych urządzeń bezpośrednio z pulpitu - Home Assistant, wraz z innymi inteligentnymi urządzeniami w domu. + popularną platformą automatyki domowej typu open source. Pozwala to na sterowanie i monitorowanie tych urządzeń bezpośrednio z pulpitu + Home Assistant wraz z innymi inteligentnymi urządzeniami w domu. ## Tryby działania -Sbc2ha może działa w trzech różnych trybach: +Sbc2ha może działać w trzech różnych trybach: 1. [Tryb autonomiczny](#tryb-samodzielny) 2. [Tryb MQTT](#tryb-mqtt) @@ -82,9 +82,9 @@ Sbc2ha może działa w trzech różnych trybach: ### Tryb samodzielny Tryb autonomiczny jest najbardziej podstawowym trybem działania sbc2ha. -Pozwala on na bezpośrednie sterowanie podłączonymi urządzeniami w oparciu, o różne zdarzenia i odczyty. +Pozwala on na bezpośrednie sterowanie podłączonymi urządzeniami w oparciu o różne zdarzenia i odczyty. W tym trybie nie są wymagane żadnie inne komponenty do jego działania. -Obecnie obsługiwane są sensory binary i button (switch) oraz actuator relay. +W lokalnej logice obsługiwane są obecnie następujące sensory: binary i button (switch) oraz actuator relay. #### Kontrola oparta na zdarzeniach @@ -116,18 +116,18 @@ System może odczytywać dane z różnych typów czujników: - **Czujniki analogowe**: Obejmują one czujniki napięcia, czujniki rezystancyjne (Ohm) i termometry NTC. -- **Urządzenia 1-Wire**: Urządzenia te komunikują się za pomocą jednego przewodu i obejmują urządzenia takie jak termometr DS18B20. The - system obsługuje urządzenia 1-Wire podłączone bezpośrednio do pinów GPIO lub poprzez interfejs Ds2482 (1-wire@i2c). +- **Urządzenia 1-Wire**: Urządzenia te komunikują się za pomocą jednego przewodu i obejmują urządzenia takie jak termometr DS18B20. + System obsługuje urządzenia 1-Wire podłączone bezpośrednio do pinów GPIO lub poprzez interfejs Ds2482 (1-wire@i2c). -- **Urządzenia I2C/SPI**: Te urządzenia komunikują się za pośrednictwem protokoły I2C lub SPI. Obsługiwane urządzenia obejmują Mcp23017 ( +- **Urządzenia I2C/SPI**: Urządzenia te komunikują się za pośrednictwem protokołów I2C lub SPI. Obsługiwane urządzenia obejmują Mcp23017 ( ekspander wejść/wyjść) i PCA9685 (16-kanałowe wyjście PWM). -- **Urządzenia Modbus**: Urządzenia te komunikują się za pośrednictwem protokół Modbus. Należy pamiętać, że konieczne będzie zdefiniowanie - adresy podłączonych urządzeń Modbus. +- **Urządzenia Modbus**: Urządzenia te komunikują się za pośrednictwem protokołu Modbus. Należy pamiętać, że konieczne będzie zdefiniowanie + adresów podłączonych urządzeń Modbus. - **Termometry cyfrowe**: Obejmują one urządzenia takie jak termometr LM75, który komunikuje się za pośrednictwem protokołu I2C. -Odczyty czujników sa dostępne w interfejsie GUI, a także przez websocket. +Odczyty czujników są dostępne w interfejsie GUI, a także przez websocket. ### Tryb MQTT @@ -135,7 +135,7 @@ Odczyty czujników sa dostępne w interfejsie GUI, a także przez websocket. MQTT (Message Queuing Telemetry Transport) to lekki protokół przesyłania wiadomości używany do komunikacji między urządzeniami w konfiguracji Internetu rzeczy (IoT). Tryb MQTT umożliwia sbc2ha komunikowanie się z innymi systemami za pomocą protokołu MQTT. -Ten tryb rozszerza tryb samodzielny, wszystkie funkcjonalności są dostępne. +Ten tryb rozszerza tryb samodzielny, wszystkie jego funkcjonalności są dostępne. W tym trybie system publikuje wiadomości do tematów MQTT, gdy wystąpią zdarzenia lub zmienią się odczyty czujników. Inne systemy mogą subskrybować te tematy i wykonywać działania na podstawie otrzymanych wiadomości. @@ -152,23 +152,23 @@ Należy również skonfigurować ustawienia MQTT w systemie, w tym adres brokera **Zdarzenia MQTT**: System może nasłuchiwać tematów MQTT i wykonywać akcje na podstawie otrzymywanych wiadomości. 📡 #### Odczyty czujnika -Wszystkie odczyty czujników są udostępniane w za pośrednictwem protokołu i brokera MQTT, umożliwiając innym systemom dostęp do danych. +Wszystkie odczyty czujników są udostępniane za pośrednictwem protokołu i brokera MQTT, umożliwiając innym systemom dostęp do danych. #### Sterowanie urządzeniami wykonawczymi -System może sterować urządzeniami wykonawczymi, takimi jak przekaźniki i urządzenia PWM. -Nasłuchuje przychodzących komunikatów MQTT i zmienia stan urządzeń wykonawczych na podstawie tych komunikatów. +System może sterować urządzeniami wykonawczymi takimi jak przekaźniki i urządzenia PWM, +nasłuchiwać przychodzących komunikatów MQTT i zmieniać stan urządzeń wykonawczych na podstawie tych komunikatów. ### Tryb HomeAssistant -W trybie Home Assistant sbc2ha bezproblemowo integruje się z Home Assistant, popularną platformą automatyki domowej typu open source. -Tryb ten wykorzystuje protokół MQTT do informowania Home Assistant o urządzeniach kontrolowanych przez system. do Home Assistant. +W tym trybie sbc2ha bezproblemowo integruje się z Home Assistant, popularną platformą automatyki domowej typu open source. +Tryb ten wykorzystuje protokół MQTT do informowania Home Assistant o urządzeniach kontrolowanych przez system. Urządzenia są ogłaszane przez MQTT za pośrednictwem funkcji Autodiscovery. Autodiscovery to funkcja aplikacji Home Assistant, która automatycznie wykrywa i dodaje urządzenia do pulpitu Home Assistant. -Urządzenia, które można wykryć to m.in. czujniki binarne, rolety, wyzwalacze urządzeń, światła i czujniki. +Urządzenia, które można wykryć to m.in. czujniki binarne, rolety, przełączniki ścienne, światła i czujniki. Po ogłoszeniu urządzeń są one automatycznie rozpoznawane i dodawane do Home Assistant. Umożliwia to kontrolować i monitorować te urządzenia bezpośrednio z pulpitu Home Assistant, @@ -194,16 +194,16 @@ Istnieją trzy metody główne metody instalacji: W przypadku instalacji natywnej na urządzeniu wykonaj następujące kroki: -1. Zainstaluj środowisko wykonawcze [Java w wersji 17](https://adoptium.net/blog/2021/12/eclipse-temurin-linux-installers-available) lub większej. +1. Zainstaluj środowisko wykonawcze [Java w wersji 17](https://adoptium.net/blog/2021/12/eclipse-temurin-linux-installers-available) lub wyższej. 2. Przejdź do repozytorium GitHub do sekcji [Packages](https://github.com/dafik?tab=packages&repo_name=sbc2ha) 3. Wejdź w pakiet com.dfi.sbc2ha.app. -4. Pobierz pakiet sbc2ha w interesujacej Cie wersji z zależnościami np. app-0.0.5-with-dep.jar i zachowaj go na urządzeniu w preferowanym miejscu. +4. Pobierz pakiet sbc2ha w interesującej Cię wersji z zależnościami np. app-0.0.7-with-dep.jar i zachowaj go na urządzeniu w preferowanym miejscu. 5. Pobierz przykładowy [plik konfiguracji](https://github.com/dafik/sbc2ha/blob/master/docker/std/config.yaml) z repozytorium i zachowaj go w tym samym miejscu, co poprzedni plik. 6. uruchom aplikacje ```bash - java -jar app-0.0.5-with-dep.jar config.yaml + java -jar app-0.0.7-with-dep.jar config.yaml ``` -7. Interfejs GUI bedzie nasłuchiwał na porcie 8080 urządzenia, na którym została uruchomiona aplikacja. +7. Interfejs GUI będzie nasłuchiwał na porcie 8080 urządzenia, na którym została uruchomiona aplikacja. 8. W katalogu [tools](https://github.com/dafik/sbc2ha/tree/master/app/tools) repozytorium znajdują się dwa katalogi bin i service. Zawierają przykładowy plik demona system.d **sbc2ha.service** uruchamianego w trakcie startu systemu, skrypt **addService** do instalacji i włączenia tego serwisu, @@ -244,7 +244,7 @@ Sbc2ha można zainstalować jako dodatek do Home Assistant, popularnej platformy Pozwala to kontrolować i monitorować urządzenia podłączone do systemu bezpośrednio z pulpitu Home Assistant, wraz z innymi inteligentnymi urządzeniami w domu. -Sbc2ha wymaga zainstalowanego dodatku piGpio który można zainstalować z repozytorium [Poeschl](https://github.com/Poeschl/Hassio-Addons) +Sbc2ha wymaga zainstalowanego dodatku piGpio, który można zainstalować z repozytorium [Poeschl](https://github.com/Poeschl/Hassio-Addons) Poniżej przedstawiono szczegółowe kroki instalacji sbc2ha jako dodatku do aplikacji Home Assistant: @@ -266,8 +266,7 @@ Poniżej przedstawiono szczegółowe kroki instalacji sbc2ha jako dodatku do apl Może to potrwać kilka minut. 5. **Konfiguracja dodatku**: Po zainstalowaniu dodatku należy go skonfigurować. - Kliknij "Konfiguracja" na stronie szczegółów dodatku i zmień w razie potrzeby port, - na którym będzie dostępny interfejs sieciowy sbc2ha. + Kliknij "Konfiguracja" na stronie szczegółów dodatku wpisz adres dodatku piGpio, może to być adres IP hosta, lub nazwa kontenera. 6. **Uruchom dodatek**: Po skonfigurowaniu dodatku można go uruchomić, klikając "Start" na stronie szczegółów dodatku. sbc2ha uruchomi się i rozpocznie sterowanie urządzeniami. @@ -278,7 +277,7 @@ Poniżej przedstawiono szczegółowe kroki instalacji sbc2ha jako dodatku do apl 8. **Użyj dodatku**: Dodatek sbc2ha jest teraz zainstalowany i uruchomiony. Możesz kontrolować i monitorować swoje urządzenia z pulpitu Home Assistant. - Klikajac "Otwórz interfejs użytkownika" przejdź do panelu dodatku. + Klikając "Otwórz interfejs użytkownika" przejdź do panelu dodatku. Dodatek będzie również udostępniał urządzenia dla Home Assistant MQTT Autodiscovery, umożliwiając ich automatyczne dodawanie do pulpitu Home Assistant. @@ -295,13 +294,13 @@ na którym działa sbc2ha, po którym następuje numer portu (np. `http://192.16 Interfejs sieciowy zapewnia graficzny interfejs użytkownika do zarządzania konfiguracją systemu. Obejmuje to: - **Kreator nowej konfiguracji**: Kreator ten prowadzi użytkownika przez proces tworzenia nowej konfiguracji systemu. - konfiguracji systemu. Pyta o niezbędne informacje i tworzy plik konfiguracyjny na podstawie wprowadzonych danych. + Pyta o niezbędne informacje i tworzy plik konfiguracyjny na podstawie wprowadzonych danych. - **Edycja bieżącej konfiguracji**: Można przeglądać i edytować bieżącą konfigurację systemu. Pozwala to na dodawanie, usuwanie lub modyfikowanie urządzeń bez konieczności ręcznej edycji pliku konfiguracyjnego. - **Konwersja konfiguracji**: W przypadku migracji z oprogramowania BoneIo, - system może przekonwertować istniejącą konfigurację BoneIo do formatu zgodnego z sbc2ha + system może przekonwertować istniejącą konfigurację BoneIo do formatu zgodnego z sbc2ha (do wersji 0.6). ### 2. Podgląd dziennika urządzenia na żywo @@ -312,7 +311,7 @@ Umożliwia to monitorowanie działania systemu w czasie rzeczywistym i pomaga w Interfejs sieciowy umożliwia sterowanie i monitorowanie urządzeń: -- **Widok stanu czujnika**: Można wyświetlić aktualny stan czujników. Obejmuje to bieżące odczyty z +- **Widok stanu czujnika**: Można wyświetlić aktualny stan czujników. Obejmuje to bieżące odczyty z czujników analogowych, stan czujników binarnych oraz stan urządzeń 1-Wire, I2C/SPI i Modbus. - **Edycja statusu urządzenia wykonawczego**: Możesz kontrolować urządzenia wykonawcze, takie jak przekaźniki, bezpośrednio z interfejsu internetowego. @@ -325,29 +324,27 @@ Interfejs sieciowy umożliwia sterowanie i monitorowanie urządzeń: Interfejs WWW udostępnia kilka narzędzi do zarządzania systemem: -- **Przeładowanie konfiguracji**: Jeśli dokonałeś zmian w pliku konfiguracyjnym, możesz użyć tej opcji, aby ponownie załadować +- **Przeładowanie konfiguracji**: Jeśli została dokonana zmiana w pliku konfiguracyjnym, można użyć tej opcji, aby ponownie załadować konfigurację bez konieczności ponownego uruchamiania całego systemu. -- **Przeładuj aplikację**: Ta opcja umożliwia ponowne uruchomienie systemu. Może to być przydatne, jeśli dokonałeś zmian w pliku +- **Przeładuj aplikację**: Ta opcja umożliwia ponowne uruchomienie systemu. Może to być przydatne, jeśli zostały dokonane zmiany w pliku ustawień systemu lub jeśli system nie działa prawidłowo. -- **Zatrzymanie aplikacji**: Ta opcja umożliwia zatrzymanie systemu. Może to być przydatne, jeśli chcesz zamknąć - system do konserwacji lub rozwiązywania problemów. - -- **Kasowanie zapamiętanych stanów**: Jeśli używasz elementów wykonawczych, które pamiętają swój stan (takich jak przekaźniki), - możesz użyj tej opcji, aby wyczyścić zapamiętane stany. - Może to być przydatne, jeśli chcesz zresetować siłowniki do znanego stanu. +- **Zatrzymanie aplikacji**: Ta opcja umożliwia zatrzymanie systemu. Może to być przydatne, jeśli wystąpi potrzeba zamknięcia + system w celu konserwacji lub rozwiązywania problemów. +- **Kasowanie zapamiętanych stanów**: Jeśli używane są elementy wykonawcze, które pamiętają swój stan (takich jak przekaźniki), + można użyć tej opcji, aby wyczyścić zapamiętane stany. + - **Czyszczenie pamięci podręcznej konfiguracji**: System buforuje bieżącą konfigurację w celu szybszego działania. - Jeśli doświadczasz problemów, możesz użyć tej opcji, aby wyczyścić pamięć podręczną konfiguracji. + Jeśli występują problemy, możesz użyć tej opcji, aby wyczyścić pamięć podręczną konfiguracji. -- **Zapisywanie konfiguracji w pamięci podręcznej**: Jeśli dokonałeś zmian w konfiguracji i jesteś z nich zadowolony, możesz z tego skorzystać - opcja zapisania bieżącej konfiguracji do pamięci podręcznej. - +- **Zapisywanie konfiguracji w pamięci podręcznej**: Jeśli została dokonana zmiana w konfiguracji, można ją zapisać + w pamięci podręcznej, nie modyfikując oryginalnego pliku konfiguracji (np. w celu testu) -- **Zapisywanie w oryginalnej konfiguracji**: Jeśli dokonałeś zmian w konfiguracji i chcesz, aby były one trwałe, możesz - można użyć tej opcji, aby zapisać bieżącą konfigurację z powrotem do oryginalnego pliku konfiguracyjnego. Spowoduje to zastąpienie - istniejącego pliku konfiguracyjny z bieżącą konfiguracją. +- **Zapisywanie w oryginalnej konfiguracji**: Jeśli dokonani zmian w konfiguracji, można + zapisać bieżącą konfigurację z powrotem do oryginalnego pliku konfiguracyjnego. Spowoduje to zastąpienie + istniejącego pliku konfiguracyjny z bieżącą konfiguracją, a zmiany będą trwałe. ### [DEMO ](https://sbc2ha.mieszkadlo.eu/app/) tylko panel @@ -359,21 +356,21 @@ Wkład w projekt jest mile widziany. Prześlij pull request lub utwórz problem, **P1: Jak dodać urządzenie do sbc2ha?** -Aby dodać urządzenie należy utworzyć plik konfiguracyjny urządzenia. Plik ten określa typ urządzenia, pin GPIO lub -inny interfejs, z którego korzysta, oraz stan początkowy urządzenia. Po utworzeniu pliku konfiguracyjnego możesz go dodać -do systemu poprzez interfejs WWW. Przejdź do sekcji konfiguracji, kliknij „Dodaj urządzenie” i prześlij plik +Aby dodać urządzenie, należy utworzyć plik konfiguracyjny urządzenia. Plik ten określa typ urządzenia, pin GPIO lub +inny interfejs, z którego korzysta, oraz stan początkowy urządzenia. Po utworzeniu pliku konfiguracyjnego można go dodać +do systemu poprzez interfejs WWW. Następnie należy przejść do sekcji konfiguracji, kliknąć „Dodaj urządzenie” i przesłać plik konfiguracyjny. **Pyt. 2: Jak sterować urządzeniem za pomocą sbc2ha?** Istnieją dwa główne sposoby sterowania urządzeniem: -1. **Interfejs sieciowy**: Interfejs sieciowy zapewnia graficzny interfejs użytkownika umożliwiający sterowanie urządzeniami. Możesz obejrzeć - status swoich urządzeń, steruj urządzeniaami wykonawczymi, takimi jak przekaźniki, i emuluj zdarzenia dla przełączników i czujników binarnych. +1. **Interfejs sieciowy**: Interfejs sieciowy zapewnia graficzny interfejs użytkownika umożliwiający sterowanie urządzeniami. Można obejrzeć + status swoich urządzeń, sterować urządzeniami wykonawczymi, takimi jak przekaźniki, i emulować zdarzenia dla przełączników i czujników binarnych. -2. **Protokół MQTT**: Jeśli używasz systemu w trybie MQTT lub w trybie Home Assistant, możesz sterować swoimi urządzeniami za pomocą +2. **Protokół MQTT**: Jeśli używany jest tryb MQTT lub w tryb Home Assistant, można sterować swoimi urządzeniami za pomocą Wiadomości MQTT. System nasłuchuje przychodzących komunikatów MQTT i na ich podstawie zmienia stan urządzeń - wiadomości. Możesz opublikować wiadomość MQTT w temacie powiązanym z urządzeniem, którym chcesz sterować. + wiadomości. Można opublikować wiadomość MQTT w temacie powiązanym z urządzeniem, którym chcesz sterować. **Pyt. 3: Jak uzyskać pomoc, jeśli napotkam problemy z sbc2ha?**