home@slashpaf ~ $

MQTT / Home Assistant

<- terug naar de documentatie root  

Wat MQTT doet voor Audio Forge

MQTT laat Audio Forge praten met je slimme huis zodat je:

  • Kunt zien wat Audio Forge aan het doen is (welke bibliotheek, of Muziek/Ambiance spelen).
  • Afspelen kunt activeren vanaf Home Assistant, Node-RED, of een ander MQTT-geschikt hulpmiddel.
  • Audio Forge kunt verbinden met automatiseringen zoals lichten, rookmachines, scènewissels, en meer.

Als je al een MQTT-broker draait (Mosquitto, de ingebouwde broker van Home Assistant, enz.), kan Audio Forge ermee verbinden en zijn status publiceren terwijl het luistert naar commando’s.

MQTT inschakelen in Instellingen

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

Je kunt 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 tenzij je weet dat je een aangepaste nodig hebt).
  • Basis Onderwerp (standaard: audioforge/<apparaat-naam-of-id>; bijvoorbeeld audioforge/mijn-pc).
  • QoS (0/1/2; 1 is een goede standaard).
  • Of je de status wilt behouden, automatisch wilt verbinden bij opstarten, staat wilt publiceren, en commando’s wilt abonneren.
  • MQTT-ontdekking en een optionele Ontdekking prefix (meestal homeassistant).
  • Geavanceerde opties om Ambiance schakelaars bloot te stellen, categorie volumes bloot te stellen, en Echo knoppen bloot te stellen als extra entiteiten.

Eenmaal verbonden zal Audio Forge zijn beschikbaarheid en status publiceren naar je broker en (optioneel) luisteren naar commando’s.

Gallery image 1 of 1

Hoofdonderwerpen

Uitgaande van je basis onderwerp audioforge/mijn-pc, gebruikt Audio Forge:

  • audioforge/my-pc/availability – online / offline status (behouden).
  • audioforge/my-pc/state – JSON-overzicht van de huidige afspeelstatus (behouden als je Status behouden inschakelt).
  • audioforge/my-pc/catalog – JSON-catalogus van alle bibliotheken en hun categorieën (behouden).
  • audioforge/my-pc/cmd – waar je JSON-commando’s stuurt om af te spelen.
  • audioforge/my-pc/result – optionele JSON-antwoorden (succes / fout).
  • audioforge/my-pc/events/echo – eenmalige “echo” gebeurtenissen (niet behouden).

De status payload omvat zaken als:

  • deviceId, libraryUuid, libraryName.
  • Of Muziek of Ambiance speelt, plus hun basisvolumes.
  • Welke categorieën momenteel spelen (musicCategories / ambianceCategories).
  • Geluidsniveaus per categorie (categoryVolume mapping).
  • De laatst afgespeelde eenmalige (Echo) en de huidige volumeTransitionMs.

Basisbediening vanuit Home Assistant

Je kunt Home Assistant op twee manieren gebruiken:

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

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

  • Binaire sensoren (Beschikbaar, Muziek Spelend, Ambiance Spelend).
  • Sensoren (Bibliotheek naam, Muziek/Ambiance categorieën, Laatste Echo).
  • Knoppen (Afspelen / Pauzeren / Stoppen voor Muziek en Ambiance).
  • Selecties (kies Muziek/Ambiance categorieën, wissel bibliotheken).
  • Nummers (Muziek/Ambiance volume, volumetransitietijd, optioneel per categorie volumes).
  • Optionele schakelaars (één per Ambiance categorie indien 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 commando’s

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

Speel een hele sectie af:

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

Speel een specifieke categorie op naam af:

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

Pauzeer of stop:

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

Stel volume in (0.0–1.0):

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

Wissel van bibliotheek:

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

Speel een eenmalige Echo af:

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

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

{"command": "restoreState", "link": "<status-link-van-app>"}

Als een commando 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 helper 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ène wijzigen, fysieke knoppen, stream deck knoppen, etc.).