MQTT broker – od czego zacząć, jak uruchomić i jak połączyć urządzenia?

MQTT (Message Queuing Telemetry Transport) to lekki, szybki i elastyczny protokół komunikacyjny, który zdobywa coraz większą popularność w ekosystemie smart home. Jeśli chcesz budować zaawansowaną automatykę domową, integrować różne urządzenia IoT czy tworzyć system do przesyłania danych do chmury, MQTT to narzędzie, które na pewno będziesz potrzebować.

Ale zanim rozpoczniesz pracę z protokołem MQTT, musisz zrozumieć jedną kluczową rzecz: MQTT nie działa sam z siebie. Do jego działania potrzebujesz brokera – oprogramowania, które pośredniczy w komunikacji między wszystkimi podłączonymi urządzeniami i aplikacjami. Broker MQTT to serce systemu, które odbiera wiadomości od wydawców i dystrybuuje je do subskrybentów.

W tym artykule pokażemy Ci, jak zainstalować broker MQTT, prawidłowo go skonfigurować, zabezpieczyć dostęp i ostatecznie podłączyć pierwsze urządzenia. Niezależnie od tego, czy pracujesz z Home Assistant, czy chcesz postawić broker na własnym serwerze, znajdziesz tutaj wszystkie niezbędne informacje.

Część 1 – podstawowe pojęcia – co musisz wiedzieć

Jak działa MQTT?

MQTT opiera się na modelu publikowania i subskrypcji (publish–subscribe). Oto kluczowe elementy komunikacji:

• broker MQTT – centralny serwer, który zarządza całą komunikacją;
• wydawcy (publishers) – urządzenia lub aplikacje, które wysyłają wiadomości na określone tematy (topics);
• subskrybenci (subscribers) – urządzenia lub aplikacje, które słuchają wiadomości na określonych tematach;
• tematy (topics) – hierarchiczne kanały komunikacji, np. dom/salon/temperatura lub dom/kuchnia/swiatlo.

Korzyści MQTT

Poniżej znajdziesz najważniejsze powody, dla których MQTT sprawdza się w IoT i smart home:

• niska przepustowość – idealny dla urządzeń z ograniczoną mocą obliczeniową;
• niska latencja – dane przesyłają się bardzo szybko;
• niezawodność – protokół zapewnia dostarczenie wiadomości;
• elastyczność – łatwo dodawać nowe urządzenia i tematy;
• bezpieczeństwo – obsługuje szyfrowanie i uwierzytelnianie.

Część 2 – instalacja brokera MQTT – Mosquitto

Najczęściej wybieranym brokerem MQTT jest Eclipse Mosquitto – open‑source’owe, lekkie i bardzo popularne rozwiązanie. Poniżej pokażemy Ci, jak go zainstalować na różnych platformach.

Instalacja na Ubuntu/Debian

Instalacja Mosquitto na systemach opartych na Debianie jest niezwykle prosta. Wykonaj kolejno te polecenia:

sudo add-apt-repository ppa:mosquitto-dev/mosquitto-ppa
sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients


Powyższe kroki dodają repozytorium z najnowszą wersją Mosquitto, aktualizują listę pakietów oraz instalują zarówno serwer brokera, jak i narzędzia klienckie do testowania.

Instalacja w systemie Windows

Aby zainstalować Mosquitto w Windows, postępuj według poniższych kroków:

1. Przejdź na oficjalną stronę projektu Mosquitto: https://mosquitto.org/download/
2. Pobierz instalator dla Windows.
3. Uruchom instalator i postępuj zgodnie z instrukcjami.
4. Mosquitto zainstaluje się jako usługa systemowa.

Instalacja w Home Assistant

Jeśli korzystasz z Home Assistant, instalacja jest jeszcze prostsza. Wykonaj następujące kroki:

1. Przejdź do Ustawienia → Dodatki → Sklep z dodatkami.
2. Wyszukaj dodatek o nazwie Mosquitto Broker.
3. Kliknij na dodatek i naciśnij Zainstaluj.
4. Po zainstalowaniu przejdź do sekcji konfiguracji.

Część 3 – konfiguracja brokera Mosquitto

To etap, który gwarantuje bezpieczeństwo i stabilność Twojego systemu. Po instalacji przejdź do konfiguracji.

Plik konfiguracyjny

Główny plik konfiguracyjny Mosquitto znajdziesz w tych lokalizacjach:

Linux – ścieżka do pliku:

/etc/mosquitto/mosquitto.conf


Windows – ścieżka do pliku:

C:\Program Files\mosquitto\mosquitto.conf


Podstawowa konfiguracja

Otwórz plik konfiguracyjny i zwróć uwagę na poniższe parametry:

# Port nasłuchiwania (domyślnie 1883)
port 1883

# Rejestrowanie aktywności
log_dest file /var/log/mosquitto/mosquitto.log
log_dest stdout
log_type all

# Maksymalna liczba połączeń
max_connections -1

# Zachowaj wiadomości offline
persistence true
persistence_location /var/lib/mosquitto/

# Plik z danymi sesji
persistence_file mosquitto.db

Konfiguracja uwierzytelniania i bezpieczeństwa

Dla domowego użytku podstawowa konfiguracja jest zazwyczaj wystarczająca, ale zdecydowanie zalecamy włączenie uwierzytelniania oraz szyfrowania dla dodatkowego bezpieczeństwa.

Tworzenie użytkownika

Aby dodać pierwszego użytkownika z hasłem, wykonaj komendę:

sudo mosquitto_passwd -c /etc/mosquitto/passwd nazwa_uzytkownika


System poprosi Cię o hasło. Aby dodać kolejnego użytkownika, użyj:

sudo mosquitto_passwd /etc/mosquitto/passwd kolejny_uzytkownik


Włączenie uwierzytelniania

Dodaj poniższe linie do pliku konfiguracyjnego:

# Włącz uwierzytelnianie
password_file /etc/mosquitto/passwd
# Wymagaj uwierzytelniania dla wszystkich klientów
allow_anonymous false


Szyfrowanie komunikacji (TLS/SSL)

Aby dodatkowo zabezpieczyć komunikację, skonfiguruj szyfrowanie TLS (zalecane w środowiskach produkcyjnych):

# Domyślny port z TLS (1883 bez TLS, 8883 z TLS)
listener 8883
tls_version tlsv1.2
certfile /etc/mosquitto/certs/cert.pem
keyfile /etc/mosquitto/certs/key.pem

# Opcjonalnie: dodatkowy listener bez szyfrowania dla testów
listener 1883
allow_anonymous true

Certyfikaty możesz wygenerować samodzielnie za pomocą OpenSSL lub pobrać z zaufanego źródła.

Konfiguracja w Home Assistant

Jeśli instalujesz Mosquitto w Home Assistant, konfiguracja jest graficzna i prosta. W sekcji konfiguracji dodatku ustaw username i password dla konta, z którego będą korzystać klienci MQTT.

Następnie zaznacz opcje Obserwator (automatyczne odczyty logów) oraz Automatyczna aktualizacja (bieżące aktualizacje dodatku). Po zapisaniu ustawień kliknij Uruchom, a broker będzie gotowy do pracy.

Część 4 – uruchomienie brokera

W systemie Linux

Aby uruchomić brokera po instalacji i konfiguracji, użyj:

sudo systemctl start mosquitto


Aby sprawdzić, czy broker działa prawidłowo, skorzystaj z:

sudo systemctl status mosquitto


Status „active (running)” potwierdza, że usługa działa.

Aby broker startował automatycznie wraz z systemem, włącz autostart:

sudo systemctl enable mosquitto


W systemie Windows

Po instalacji Mosquitto działa jako usługa systemowa. Oto przydatne akcje:

• automatyczny start – usługa uruchamia się wraz z systemem;
• zarządzanie usługą – skorzystaj z Usługi (Services) w Panelu sterowania;
• ręczny start z wiersza poleceń – wpisz komendę poniżej.

net start mosquitto


W Home Assistant

Po zainstalowaniu i skonfigurowaniu dodatku wystarczy kliknąć Uruchom w panelu dodatku.

Część 5 – testowanie brokera

Subskrypcja tematu

W jednym oknie terminala zasubskrybuj temat, aby obserwować napływające wiadomości:

mosquitto_sub -h localhost -u nazwa_uzytkownika -P haslo -t "dom/salon/#"


Znaczenie najważniejszych parametrów:

• -h – adres brokera (np. localhost dla lokalnego testowania);
• -u – nazwa użytkownika do uwierzytelniania;
• -P – hasło użytkownika;
• -t – temat, na który subskrybujesz (# oznacza wszystkie podtematy).

Publikacja wiadomości

W drugim oknie terminala opublikuj przykładową wiadomość na wybrany temat:

mosquitto_pub -h localhost -u nazwa_uzytkownika -P haslo -t "dom/salon/temperatura" -m "22.5"


Jeśli w pierwszym oknie zobaczysz wiadomość „22.5”, broker działa prawidłowo.

Część 6 – łączenie urządzeń z brokerem MQTT

Gdy broker jest uruchomiony i przetestowany, możesz podłączać klientów i urządzenia.

Wybór klientów MQTT

Klienci MQTT są dostępni dla wielu platform i języków programowania:

• Python – biblioteka paho-mqtt;
• Arduino/ESP8266/ESP32 – biblioteka PubSubClient;
• JavaScript/Node.js – biblioteka mqtt;
• C/C++ – biblioteka libmosquitto;
• Home Assistant – wbudowana integracja MQTT;
• smartfony – aplikacje mobilne do testów i podglądu;
• routery IoT – wiele modeli obsługuje MQTT.

Przykład – podłączenie urządzenia z Arduino/ESP32

Najpopularniejszym wyborem dla początkujących jest mikrokontroler ESP32 lub Arduino z modułem Wi‑Fi. Poniżej znajdziesz przykład połączenia i publikacji danych.

Instalacja biblioteki

W środowisku Arduino IDE wykonaj te kroki:

1. Przejdź do Sketch → Include Library → Manage Libraries.
2. Wyszukaj PubSubClient (autor Nick O’Leary).
3. Zainstaluj bibliotekę.

Przykładowy kod

Skopiuj i wgraj poniższy kod, uzupełniając dane sieci Wi‑Fi i parametry MQTT:

#include <WiFi.h>
#include <PubSubClient.h>

// Dane WiFi
const char* ssid = "TWOJA_SIEC_WIFI";
const char* password = "TWOJE_HASLO_WIFI";

// Dane MQTT
const char* mqtt_server = "192.168.1.100"; // IP brokera
const char* mqtt_user = "nazwa_uzytkownika";
const char* mqtt_password = "haslo";
const int mqtt_port = 1883;

WiFiClient espClient;
PubSubClient client(espClient);

void setup() {
Serial.begin(115200);
setup_wifi();
client.setServer(mqtt_server, mqtt_port);
client.setCallback(callback);
}

void setup_wifi() {
delay(10);
Serial.println();
Serial.print("Łączę się z WiFi: ");
Serial.println(ssid);
WiFi.mode(WIFI_STA);
WiFi.begin(ssid, password);
int attempts = 0;
while (WiFi.status() != WL_CONNECTED && attempts < 20) {
delay(500);
Serial.print(".");
attempts++;
}
Serial.println();
Serial.println("WiFi połączony");
Serial.println(WiFi.localIP());
}

void callback(char* topic, byte* payload, unsigned int length) {
Serial.print("Wiadomość na temat: ");
Serial.println(topic);
String message = "";
for (int i = 0; i < length; i++) {
message += (char)payload[i];
}
Serial.println(message);
}

void reconnect() {
while (!client.connected()) {
Serial.print("Łączę się z MQTT...");
if (client.connect("ESP32_Client", mqtt_user, mqtt_password)) {
Serial.println("Połączony!");
client.subscribe("dom/komendy/#");
} else {
Serial.print("Połączenie nieudane, kod: ");
Serial.println(client.state());
delay(5000);
}
}
}

void loop() {
if (!client.connected()) {
reconnect();
}
client.loop();

// Publikuj temperaturę co 30 sekund
delay(30000);
float temperatura = 22.5; // Odczytana z czujnika
client.publish("dom/salon/temperatura", String(temperatura).c_str());
}

Integracja z Home Assistant

Aby podłączyć MQTT do Home Assistant, wykonaj następujące kroki:

1. Przejdź do Ustawienia → Urządzenia i usługi.
2. Dodaj integrację MQTT.
3. Wpisz dane do połączenia.

W konfiguracji integracji podaj kluczowe parametry:

• Broker – adres IP brokera (np. 192.168.1.100);
• Port – 1883 (lub 8883 z TLS);
• Username – nazwa użytkownika do logowania;
• Password – hasło dla użytkownika.

Home Assistant może automatycznie odkrywać urządzenia publikujące przez MQTT, a następnie wykorzystywać je w integracjach i automatyzacjach.

Część 7 – zaawansowana konfiguracja – most MQTT

Co to jest most MQTT?

Most pozwala dwóm (lub większej liczbie) brokerom MQTT na wymianę wiadomości. Jeden broker działa jako główny, drugi jako zdalny, a wybrane tematy są replikowane pomiędzy nimi.

Konfiguracja

Aby skonfigurować most w Mosquitto, dodaj poniższe wpisy do pliku /etc/mosquitto/mosquitto.conf:

# Definicja mostu
connection bridge-to-remote
address zdalny-broker.example.com:1883
remote_username nazwa_uzytkownika
remote_password haslo

# Tematy do replikacji
topic dom/# both 0

# Identyfikator klienta dla mostu
remote_clientid mostek-mqtt

Po wprowadzeniu zmian przeładuj usługę Mosquitto:

sudo systemctl restart mosquitto


Część 8 – bezpieczeństwo – dobre praktyki

Obowiązkowe kroki bezpieczeństwa

1. Zawsze zmień hasła domyślne – jeśli broker lub dodatek mają konta domyślne, zmień je natychmiast;
2. Włącz uwierzytelnianie – nigdy nie uruchamiaj brokera z allow_anonymous true w sieci produkcyjnej;
3. Używaj szyfrowania TLS – zabezpiecz komunikację między brokerem a klientami;
4. Skonfiguruj zaporę sieciową – ogranicz dostęp do portów 1883/8883 wyłącznie dla zaufanych urządzeń;
5. Twórz regularne kopie zapasowe – wykonuj backup pliku mosquitto.db oraz konfiguracji;
6. Monitoruj logi – regularnie analizuj logi brokera pod kątem podejrzanej aktywności.

Przykład bezpiecznej konfiguracji

Poniżej znajdziesz minimalny zestaw ustawień zwiększających bezpieczeństwo:

# Wyłącz anonimowy dostęp
allow_anonymous false

# Wymagaj uwierzytelniania
password_file /etc/mosquitto/passwd

# Użyj portu z TLS
listener 8883
tls_version tlsv1.2
certfile /etc/mosquitto/certs/cert.pem
keyfile /etc/mosquitto/certs/key.pem

# Logowanie
log_dest file /var/log/mosquitto/mosquitto.log
log_type all

Część 9 – rozwiązywanie problemów

Broker nie startuje

Problem – polecenie systemctl start mosquitto zwraca błąd.

Rozwiązanie – wykonaj poniższe kroki diagnostyczne:

1. Sprawdź składnię pliku: mosquitto -c /etc/mosquitto/mosquitto.conf -t.
2. Zweryfikuj uprawnienia do katalogów/plików: sudo chmod 755 /etc/mosquitto/.
3. Przejrzyj logi systemowe: sudo journalctl -u mosquitto -n 50.

Nie mogę się połączyć

Problem – klient nie może nawiązać połączenia z brokerem.

Rozwiązanie – sprawdź najczęstsze przyczyny:

1. Czy broker nasłuchuje na porcie: sudo netstat -tlnp | grep mosquitto (lub ss -tlnp)?
2. Czy zapora sieciowa przepuszcza porty: sudo ufw allow 1883 lub sudo ufw allow 8883?
3. Czy dane logowania (użytkownik/hasło) są poprawne i odpowiadają wpisom w password_file?
4. Czy adres IP brokera jest prawidłowy w sieci lokalnej: hostname -I?

Duże opóźnienia

Problem – wiadomości są dostarczane z zauważalnym opóźnieniem.

Rozwiązanie – zoptymalizuj środowisko i konfigurację:

1. Sprawdź obciążenie serwera (CPU/RAM) i procesów towarzyszących;
2. Zmniejsz szczegółowość logowania: log_type none;
3. Skaluj limity połączeń: max_connections -1 (brak limitu);
4. Zweryfikuj jakość sieci (opóźnienia, utrata pakietów, przepustowość).