Raspberry Pi: instalacja ze skryptem

Ta ścieżka przygotowuje nową kartę na komputerze z Windows, a aplikacje instaluje podczas pierwszego uruchomienia Raspberry Pi. Potrzebujesz Pi obsługującego system 64-bit, karty microSD z miejscem na system i aplikacje, czytnika, zasilacza oraz internetu dla komputera i Pi. Zrzuty pokazują interfejs Imagera po angielsku; ich opisy są po polsku.

Jeśli masz już działający system, przejdź do instalacji na istniejącym systemie. Jeśli przygotowujesz kartę na macOS lub Linuksie, nagraj system Imagerem, uruchom Pi i użyj tam skryptu przez SSH; nie uruchamiaj .cmd na tych platformach.

Pobierz Imagera i instalator NQ2

Pobierz i zainstaluj Raspberry Pi Imager z oficjalnej strony Raspberry Pi. Wybierz wersję dla swojego komputera. Opis producenta znajdziesz w instrukcji przygotowania systemu.

Pobierz również poniższy pakiet instalatora NQ2, a nie sam ZIP aplikacji. To pakiet ze skryptem raspianimager.cmd i plikiem config.yaml.

Nagraj system i przygotuj kartę

Wykonuj kroki w podanej kolejności. Skrypt NQ2 dodajesz po zapisie i weryfikacji systemu, przed pierwszym startem Pi. Każdy zrzut można kliknąć, aby otworzyć go w pełnej wielkości.

1. Wybierz swoje Raspberry Pi

Wybierz model, który posiadasz, np. Raspberry Pi 4 lub 5. Model na zrzutach jest przykładem — nie zmienia posiadanego sprzętu.

2. Otwórz warianty Raspberry Pi OS

Na liście systemów otwórz Raspberry Pi OS (other).

3. Wybierz Raspberry Pi OS Lite (64-bit)

Wybierz Raspberry Pi OS Lite (64-bit) oparte na Trixie, z cloud-init. Wersja Lite nie potrzebuje pulpitu. Kreator przygotowania karty oczekuje cmdline.txt oraz pliku cloud-init user-data; nie jest uniwersalnym edytorem wszystkich starszych obrazów.

4. Wybierz kartę microSD

Wybierz czytnik i sprawdź pojemność karty. E: na ilustracji jest tylko przykładem — u Ciebie litera może być inna. Nagrywanie systemu usuwa dane ze wskazanego urządzenia.

5. Ustaw nazwę hosta

Wpisz np. nq2, bez .local. W sieci obsługującej mDNS po instalacji będzie można użyć adresu nq2.local. Możesz wybrać inną nazwę; uwzględnij ją w dalszych krokach.

6. Ustaw lokalizację

Wybierz kraj, strefę czasową i układ klawiatury dla miejsca instalacji. Zrzut pokazuje Warszawę i polską klawiaturę — ustaw wartości odpowiednie dla siebie.

7. Utwórz konto Linuksa

Wybierz nazwę użytkownika i hasło Linuksa oraz zapamiętaj je do SSH. nq2 jest przykładowym kontem; inny zwykły użytkownik również działa. Aplikacje i PM2 korzystają z istniejącego konta z Imagera. To hasło jest niezależne od hasła MQTT i administratora NQ2.

8. Skonfiguruj Wi-Fi albo użyj Ethernetu

Dla Wi-Fi wpisz dokładne SSID i hasło, wybierz odpowiedni typ sieci, a Hidden SSID zaznacz tylko dla sieci ukrytej. Dla sieci otwartej wybierz Open network. Możesz zamiast tego użyć kabla Ethernet. Są to ustawienia sieci Raspberry Pi; kreator NQ2 o nie nie pyta i ich nie nadpisuje.

9. Włącz SSH

Włącz SSH, aby móc sprawdzić postęp instalacji. Przykład używa logowania hasłem konta z poprzednich kroków. Jeśli wybierzesz klucz publiczny, skonfiguruj swój klucz SSH w Imagerze i użyj go przy połączeniu.

10. Zdecyduj o Raspberry Pi Connect

Raspberry Pi Connect jest opcjonalny i nie jest wymagany do instalacji NQ2. Możesz pozostawić go wyłączonego, jak na ilustracji.

11. Sprawdź podsumowanie

Sprawdź model Pi, system Lite 64-bit, właściwą kartę, hostname, konto, sieć i SSH. Przed kliknięciem Write popraw wszystko, co nie pasuje do docelowego urządzenia.

12. Potwierdź usunięcie danych z karty

Potwierdź dopiero po sprawdzeniu karty docelowej. Operacja usuwa istniejące dane z tej karty.

13. Poczekaj na zapis i weryfikację

Nie odłączaj karty, dopóki Imager nie zakończy zapisu i weryfikacji. Nie uruchamiaj kreatora karty NQ2 w trakcie nagrywania. Po zakończeniu zostaw kartę w komputerze. Jeśli Imager ją odmontował, włóż ją ponownie, aby partycja startowa była widoczna; nie uruchamiaj jeszcze Raspberry Pi.

14. Rozpakuj pakiet instalatora

Rozpakuj ZIP instalatora NQ2 na komputerze i otwórz nq2-installation. Zachowaj razem core, windows, ubuntu, raspbian, docs oraz config.yaml; nie kopiuj samego skryptu. Zrzut pokazuje kopię deweloperską z dodatkowymi katalogami dist, tests i tools; tych dodatków nie ma w ZIP-ie dla klientów. Windows może ukrywać rozszerzenia i pokazywać config.yaml jako config.

15. Uruchom kreator przygotowania karty

Otwórz windows i kliknij dwukrotnie raspianimager.cmd. Na zrzucie może być samo raspianimager, ponieważ Windows ukrywa rozszerzenia. W tym kroku nie wybieraj install.cmd: ten plik instaluje aplikacje na komputerze z Windows. Skrypt przygotowania karty jest dostępny tylko dla Windows; skrypty Ubuntu i Raspberry Pi OS instalują na już działającym Linuksie.

W kreatorze:

1. Wybierz EN lub PL.
2. Wpisz literę partycji startowej bootfs, np. E. Sprawdź, czy to karta z Imagera. Partycja powinna zawierać cmdline.txt i user-data; nie formatuj linuksowej partycji, jeśli Windows zaproponuje formatowanie.
3. Wybierz instalację Nginxa, Mosquitto i Zigbee2MQTT. Domyślnie wszystkie są włączone.
4. Jeśli instalujesz Mosquitto, określ, czy inne urządzenia mają się z nim łączyć. Domyślne false oznacza dostęp tylko z samego Pi; true pozwala łączyć się przez IP Pi z loginem i hasłem. To opcja mqtt_allow_remote w config.yaml.
5. Podaj login i hasło MQTT oraz e-mail i hasło administratora NQ2. Jeśli pomijasz Mosquitto, ale instalujesz Zigbee2MQTT, podaj adres istniejącego brokera.
6. Poczekaj na potwierdzenie sukcesu. Kreator zapisze konfigurację i instalator oraz doda autostart. Błędna litera, brak wymaganych plików lub już przygotowana karta zatrzymają przygotowanie zamiast nadpisania danych.

Nie musisz instalować Pythona na Windows. Możesz wcześniej zmienić wartości domyślne w angielsko opisanym config.yaml. Kreator nie zmienia SSID, hasła Wi-Fi, hostname, konta Linuksa ani SSH ustawionych w Imagerze. Instalator wyłącza oszczędzanie energii Wi-Fi na docelowym Linuksie korzystającym z NetworkManagera.

16. Wysuń kartę dopiero po zakończeniu kreatora NQ2

Gdy kreator NQ2 potwierdzi sukces i zakończą się wszystkie operacje zapisu, bezpiecznie wysuń kartę w Imagerze lub systemie operacyjnym. Nie wyjmuj jej od razu po nagraniu systemu, jeśli kreator NQ2 jeszcze jej nie przygotował. Włóż kartę do Raspberry Pi, podłącz zasilanie i skonfigurowaną sieć.

Pierwsze uruchomienie i kontrola

Po włożeniu przygotowanej karty i włączeniu Raspberry Pi odczekaj zwykle od około 5 do 30 minut na pełną instalację. Urządzenie musi mieć dostęp do internetu, aby pobrać i zainstalować zależności. Czas zależy od Raspberry Pi, karty i połączenia; przy wolniejszym internecie instalacja może potrwać dłużej. Przez cały proces pozostaw urządzenie włączone.

Użyj dobrego, stabilnego zasilacza odpowiedniego dla swojego modelu Raspberry Pi. Zbyt słaby lub niskiej jakości zasilacz może powodować niestabilne działanie, nieoczekiwane restarty i problemy z instalacją.

Po zakończeniu instalacji otwórz http://nq2.local w przeglądarce na komputerze podłączonym do tej samej sieci co Raspberry Pi. Ten adres zakłada hostname nq2 ustawiony w Imagerze i włączony Nginx, jak w domyślnej konfiguracji. Jeśli wybrałeś inną nazwę hosta, użyj jej zamiast nq2; bez Nginxa dodaj :8080. Przy prawidłowej instalacji nie musisz łączyć się przez SSH.

Zaloguj się danymi administratora NQ2 wybranymi w kreatorze. Jeśli instalowałeś Zigbee2MQTT, jego panel działa pod http://nq2.local:8090 (lub wybraną nazwą hosta); w razie potrzeby dokończ tam konfigurację koordynatora i MQTT.

Wi-Fi: wyłącz oszczędzanie energii

Jeśli Raspberry Pi lub serwer Linux korzysta z Wi-Fi, wyłącz oszczędzanie energii Wi-Fi, aby ograniczyć okresowe rozłączanie po bezczynności. Urządzenie może wtedy wyglądać na wyłączone, mimo że nadal działa. Aktualny instalator NQ2 ustawia to automatycznie w systemie z NetworkManagerem. Przy instalacji ręcznej lub starszym pakiecie wykonaj instrukcję ustawienia i kontroli Wi-Fi. Dla Ethernetu ta zmiana nie jest potrzebna.

Jeśli strona się nie otwiera

Jeśli po przewidywanym czasie instalacji NQ2 nadal jest niedostępne, najpierw sprawdź stabilne zasilanie, internet oraz ustawienia Wi-Fi/Ethernetu z Imagera. IP przydziela router; instalator nie narzuca adresu 192.168.1.100. Jeżeli komputer nie rozpoznaje nazwy .local, znajdź adres Pi w routerze i spróbuj http://IP_PI (albo http://IP_PI:8080 bez Nginxa).

Do dalszej diagnostyki połącz się z Pi przez SSH, np. programem PuTTY lub terminalem. W PuTTY wpisz IP albo nazwę hosta Pi, wybierz SSH na porcie 22 i zaloguj się kontem Linuksa ustawionym w Imagerze, a nie kontem administratora aplikacji NQ2. W terminalu podstaw własne konto i adres urządzenia:

ssh YOUR_USER@PI_ADDRESS

Po zalogowaniu wyświetl logi instalatora, aby zobaczyć bieżący etap lub błąd:

sudo journalctl -u nq2-firstboot -f

Ctrl+C kończy podgląd logów, nie instalację. Możesz też sprawdzić status instalatora i procesy aplikacji:

sudo systemctl status nq2-firstboot --no-pager
pm2 list
pm2 logs nq2 --lines 100

• pm2 list wykonuj jako zwykły użytkownik z Imagera. sudo pm2 list pokazuje listę innego konta.
• Brak urządzenia w routerze oznacza konieczność sprawdzenia zasilania, startu systemu i sieci z Imagera. Usługa NQ2 nie naprawia błędnego SSID lub hasła; podłącz Ethernet albo monitor, aby zdiagnozować problem.
• Błąd pobierania lub instalacji powoduje ponowienie usługi po 120 sekundach. Logi pokazują przyczynę. Usługa jest włączona także po restarcie systemu, ale uszkodzenie karty wskutek utraty zasilania może wymagać osobnej naprawy.
• Po usunięciu przyczyny błędu użyj sudo systemctl restart nq2-firstboot. Po sukcesie znacznik zakończenia blokuje ponowną instalację; nie jest to mechanizm aktualizacji.

Dostęp MQTT z innych urządzeń opisuje główna instrukcja instalacji. Jeśli chcesz wykonać czynności samodzielnie, wybierz instalację ręczną zamiast dodawania skryptu do karty.

Konfiguracja aplikacji w .env

Instalator tworzy /opt/nq2/.env w Linuksie lub C:\ProgramData\NQ2\apps\nq2\.env w Windows. Zapisuje tam NODE_ENV, PORT, ADMIN_EMAIL, ADMIN_PASSWORD, korzystając z danych kreatora / config.yaml. PM2 uruchamia NQ2 bezpośrednio (pm2 start index.js --name nq2 dla paczki z index.js), a Zigbee2MQTT dodaje osobno na końcu. pm2 save zapisuje listę do autostartu. Nie powstaje plik ecosystem. Zmiana dotyczy nowych instalacji; istniejąca instalacja nie jest automatycznie migrowana.

Usuń początkowe dane administratora po zalogowaniu

Po pierwszym uruchomieniu i udanym zalogowaniu do NQ2 usuń ADMIN_EMAIL i ADMIN_PASSWORD z pliku .env aplikacji. Są potrzebne tylko podczas pierwszego uruchomienia do utworzenia konta administratora. Pozostaw ustawienia działania aplikacji, na przykład:

NODE_ENV=production
PORT=8080

W Linuksie edytuj /opt/nq2/.env, a w domyślnej instalacji Windows C:\ProgramData\NQ2\apps\nq2\.env. Zrób to dopiero po potwierdzeniu, że logowanie administratora działa.