📡 Broker MQTT

Documentació completa del servidor MQTT 3.1.1

Versió 1.0 - Abril 2026

Índex de continguts:

Tòpics i Comandos
Integració BD
Solució de Problemes
Exemples Complets

🎯 Tòpics i comandes

Estructura de tòpics

scaperoom/[type]/[command]
scaperoom/[type]/[command]/response

1️⃣ Partides (Gestió de partides)

scaperoom/partida/nueva

Payload: {"nompartida": "Escape Room 1"}

Resposta: "OK: Partida 1 creada"

scaperoom/partida/actual

Payload: (buit)

Resposta: "Partida actual: ID=1, nom=Escape Room 1"

2️⃣ Usuaris (Gestió d'usuaris)

scaperoom/usuario/registrar

Payload:

{
  "nom": "Joan",
  "cognoms": "Santasusagna",
  "edat": 25,
  "correu": "joan@example.com",
  "telefon": "555111111",
  "instagram": "joan_s",
  "password": "secret123"
}
            

Resposta: "OK: Usuari 1 registrat"

scaperoom/usuario/listar

Payload: (buit)

Resposta: JSON array amb tots els usuaris

[
  {"id": 1, "nom": "Joan", "cognoms": "Santasusagna", "edat": 25, "correu": "joan@example.com"},
  {"id": 2, "nom": "Maria", "cognoms": "Garcia", "edat": 23, "correu": "maria@example.com"}
]
            

scaperoom/usuario/partida/listar

Payload:

{
  "idpartida": 1
}
            

Resposta: JSON array amb usuaris de la partida

[
  {"id": 1, "nom": "Joan", "cognoms": "Santasusagna", "idusuari": 1, "idpolsera": "polsera_001"},
  {"id": 2, "nom": "Maria", "cognoms": "Garcia", "idusuari": 2, "idpolsera": "polsera_002"}
]
            

scaperoom/usuario/partida

Payload:

{
  "idpartida": 1,
  "idusuario": 1,
  "idpolsera": "polsera_001"
}
            

Resposta: "OK: Usuari afegit a partida"

3️⃣ Punts (Gestió de la puntuació)

scaperoom/puntos/asignar

Payload: {"id": 1, "userid": 1, "punts": 100}

scaperoom/puntos/sumar

Payload: {"id": 1, "userid": 1, "punts": 50}

scaperoom/puntos/restar

Payload: {"id": 1, "userid": 1, "punts": 10}

scaperoom/puntos/consultar

Payload: {"id": 1, "userid": 1}

Resposta: "Punts: 140"

4️⃣ Admin (Gestió de privilegis)

scaperoom/admin/set

Payload: {"idusuario": 2}

scaperoom/admin/unset

Payload: {"idusuario": 2}

🐛 Solució de problemes

❌ "Temps d'espera excedit (timeout)"
Causa: El port 5009 està bloquejat pel tallafocs
Solució: Obre el port o utilitza localhost en lloc de la IP pública

❌ "JSON invàlid a la comanda"
Causa: Format incorrecte al payload
Solució: Verifica els paràmetres del JSON

🎓 Exemples complets

Exemple 1: Crear una partida i registrar usuaris

from paho.mqtt.client import Client
import json
import time

client = Client()
client.connect("localhost", 5009)
client.loop_start()
time.sleep(1)

# Crear partida
payload = json.dumps({"nompartida": "Escape Room Nivell 1"})
client.publish("scaperoom/partida/nueva", payload, qos=1)

time.sleep(1)

# Registrar usuari
payload = json.dumps({
    "nom": "Joan",
    "cognoms": "Santasusagna",
    "password": "secret123"
})
client.publish("scaperoom/usuario/registrar", payload, qos=1)

time.sleep(2)
client.loop_stop()
        

Exemple 2: Subscriure's a les respostes

def on_message(client, userdata, msg):
    print(f"[{msg.topic}] {msg.payload.decode()}")

client = Client()
client.on_message = on_message
client.connect("localhost", 5009)
client.subscribe("scaperoom/#")
client.loop_forever()
        

Rendiment

Mètrica	Valor
Clients concurrents	100+
Missatges per segon	1000+
Latència	<10ms (localhost)
Ús de memòria	~50MB