home@slashpaf ~ $

MQTT / Home Assistant

<- terug naar doc root  

Wat MQTT doet voor Audio Forge

MQTT stelt Audio Forge in staat om met je slimme huis te communiceren, zodat je:

  • Kunt zien wat Audio Forge doet (welke bibliotheek, of Muziek/Sfeer speelt).
  • Afspelen kunt activeren vanuit Home Assistant, Node-RED of andere MQTT-compatibele tools.
  • Audio Forge kunt integreren in automatiseringen met lichten, rookmachines, scène schakelaars en meer.

Als je al een MQTT-broker hebt draaien (Mosquitto, de ingebouwde broker van Home Assistant, enz.), kan Audio Forge hiermee verbinding maken en zijn status publiceren terwijl het luistert naar opdrachten.

MQTT inschakelen in Instellingen

Ga in Audio Forge naar Instellingen → MQTT-integratie en schakel de functie in.

Je kunt het volgende configureren:

  • Host en Poort (standaard 1883, of 8883 voor TLS).
  • TLS/SSL schakelaar.
  • Gebruikersnaam / Wachtwoord als je broker deze vereist.
  • Client ID (laat de standaard staan, tenzij je weet dat je een aangepaste nodig hebt).
  • Base Topic (standaard: audioforge/<apparaat-naam-of-id>; bijvoorbeeld audioforge/mijn-pc).
  • QoS (0/1/2; 1 is een goede standaard).
  • Of je de status wilt bewaren, automatisch wilt verbinden bij het opstarten, status wilt publiceren en opdrachten wilt abonneren.
  • MQTT Discovery en een optioneel Discovery voorvoegsel (meestal homeassistant).
  • Geavanceerde opties om Sfeer-schakelaars bloot te stellen, categorievolumes bloot te stellen en Echo-knoppen bloot te stellen als extra entiteiten.

Zodra verbinding is gemaakt, zal Audio Forge zijn beschikbaarheid en status publiceren naar je broker en (optioneel) luisteren naar opdrachten.

Gallery image 1 of 1

Belangrijkste onderwerpen

Stel dat je basistopic audioforge/mijn-pc is, dan gebruikt Audio Forge:

  • audioforge/mijn-pc/availability – online / offline status (behouden).
  • audioforge/mijn-pc/state – JSON-snapshot van de huidige afspeelstatus (behouden als je status bewaren inschakelt).
  • audioforge/mijn-pc/catalog – JSON-catalogus van alle bibliotheken en hun categorieën (behouden).
  • audioforge/mijn-pc/cmd – waar je JSON-opdrachten naartoe stuurt om afspelen te bedienen.
  • audioforge/mijn-pc/result – optionele JSON-antwoorden (succes / fout).
  • audioforge/mijn-pc/events/echo – eenmalige “echo” evenementen (niet behouden).

De status-payload bevat zaken als:

  • deviceId, libraryUuid, libraryName.
  • Of Muziek of Sfeer speelt, plus hun basisvolumes.
  • De momenteel spelende categorieën (musicCategories / ambianceCategories).
  • Per-categorie volume factoren (categoryVolume mapping).
  • De laatst gespeelde eenmalige (Echo) en de huidige volumeTransitionMs.

Basisbediening vanuit Home Assistant

Je kunt Home Assistant op twee manieren gebruiken:

  1. Handmatige MQTT-entiteiten: creeër sensoren/knoppen in YAML (of de UI) die van state lezen en naar cmd publiceren.
  2. MQTT Discovery (aanbevolen): schakel “MQTT Discovery” in de app in en Audio Forge maakt automatisch entiteiten voor je aan.

Wanneer discovery is ingeschakeld, zie je een Audio Forge apparaat met:

  • Binaire sensoren (Beschikbaar, Muziek speelt, Sfeer speelt).
  • Sensoren (Bibliotheeknaam, Muziek/Sfeer categorieën, Laatste Echo).
  • Knoppen (Afspelen / Pauzeren / Stop voor Muziek en Sfeer).
  • Selecties (kies Muziek/Sfeer categorieën, wissel bibliotheken).
  • Nummers (Muziek/Sfeer volume, volumetransitietijd, optionele per-categorie volumes).
  • Optionele schakelaars (één per Sfeer-categorie als je ervoor kiest ze bloot te stellen).
  • Optionele Echo-knoppen (één per Echo-categorie wanneer Echo-knoppen worden blootgesteld).
Gallery image 1 of 1

Veelvoorkomende opdrachten

Opdrachten zijn kleine JSON-objecten die naar <base>/cmd worden gepubliceerd. Hier zijn een paar nuttige voorbeelden:

Speel een hele sectie:

{"command": "play", "section": "Music"}

Speel een specifieke categorie op naam:

{"command": "play", "section": "Music", "categoryName": "Battle"}

Pauzeer of stop:

{"command": "pause", "section": "Ambiance"}
{"command": "stop",  "section": "Music"}

Volume instellen (0.0–1.0):

{"command": "setVolume", "section": "Music", "value": 0.65}

Wissel van bibliotheek:

{"command": "setActiveLibrary", "libraryName": "My Library"}

Speel een eenmalige Echo:

{"command": "playEcho", "section": "Ambiance", "categoryName": "Chime"}

Herstel een opgeslagen status van een door de app gemaakte link:

{"command": "restoreState", "link": "<state-link-from-app>"}

Als een opdracht niet kan worden uitgevoerd (bijvoorbeeld, een categorienaam bestaat niet), publiceert Audio Forge een fout op <base>/result.

Voorbeeld: eenvoudige Home Assistant automatisering

Hier is een minimale Home Assistant automatisering die een “Battle” categorie in Muziek start wanneer een hulp-schakelaar wordt ingeschakeld:

alias: Speel Battle in Audio Forge
trigger:
  - platform: state
    entity_id: input_boolean.play_battle
    to: "on"
action:
  - service: mqtt.publish
    data:
      topic: "audioforge/my-pc/cmd"
      payload: >
        {"command":"play","section":"Music","categoryName":"Battle"}
  - service: input_boolean.turn_off
    target:
      entity_id: input_boolean.play_battle

Dit is slechts één voorbeeld; je kunt Audio Forge verbinden met welke gebeurtenissen je maar wilt (scènewijzigingen, fysieke knoppen, stream deck knoppen, enz.).