Apparaten aansturen via HTTP

Heel wat apparaten bedien je tegenwoordig via een mobiele app of een webinterface. Vaak zijn die devices ook aan te sturen via HTTP-requests. In dit artikel bekijken we hoe dat in zijn werk gaat voor een Yamaha AV-receiver.

Een receiver bedienen via je smartphone klinkt leuk, maar laten we eerlijk zijn: de meeste apps bieden nauwelijks meerwaarde tegenover de klassieke afstandsbediening. Wil je een avondje tv-kijken via je mediacenter, dan moet je nog steeds op verschillende knoppen drukken om de juiste bron te selecteren, het volume in te stellen, enzovoorts. Dat kan toch beter? Gelukkig is dat in het geval van onze Yamaha AV-receiver niet zo moeilijk. De communicatie tussen de app (of je browser indien je de webinterface gebruikt) en de receiver verloopt immers via HTTP POST-requests. Dergelijke requests kan je ook zelf versturen met een commandline tool zoals curl. Zo is het kinderspel om allerlei taken te automatiseren, zodra je de juiste syntax kent!

XML-commando’s

Yamaha’s officiële documentatie rept helaas met geen woord over de HTTP POST-requests. Op http://bit.ly/1BmcBB6 vind je wel een Excel-bestand met daarin de volledige XML-structuur van de ondersteunde commando’s. Open het tabblad “func tree for comp functions” en klik op de plusjes links van de sheet om de verschillende elementen uit te klappen. Bedenk wel dat niet alle functies op alle AV-receivers aanwezig zijn. Zo bevat onze RX-V671 slechts 2 output zones (Main_Zone en Zone_2): de Zone_3- en Zone_4-functies zijn dus niet beschikbaar. Laat je niet overweldigen door de ingewikkelde structuur (tot 8 niveaus diep!), enkele voorbeelden zullen veel verduidelijken.

In afbeelding 1 versturen we met curl’s –data-optie het commando om de Main_Zone in te schakelen. De commando’s beginnen en eindigen steeds met <YAMAHA_AV cmd=”PUT”> en </YAMAHA_AV>. (Commando’s om informatie op te vragen beginnen met <YAMAHA_AV cmd=”GET”>, maar die hebben we voorlopig niet nodig.) Tussen die tags plaats je de correcte XML-structuur voor het gewenste commando. Tot slot geef je de url op om de receiver aan te sturen. Dat is het IP-adres van je receiver (in ons geval 192.168.1.13), gevolgd door /YamahaRemoteControl/ctrl. Lukt het niet om met dit commando je receiver in te schakelen? Zoek dan in de instellingen van je receiver naar het correcte IP-adres en controleer ook of de optie Network Standy is ingeschakeld.

Sniffen

Ook met de Excel-sheet blijft het soms lastig om de juiste syntax voor een commando te vinden. Vaak zijn er verschillende opties bij een commando, waarvan sommige optioneel en anderen verplicht zijn. Of werken bepaalde opties slechts correct in combinatie met andere opties. Daarom hebben we in tabel 1 een aantal courante opdrachten op een rijtje gezet. Bij elke opdracht moet je wel nog de tags voor de gewenste zone errond plaatsen, bijvoorbeeld <Main_Zone>…</Main_Zone>. Voor de Input_Sel- en Program_Sel-commando’s moet je eerst even kijken in de webinterface van je receiver. De mogelijke waardes voor die commando’s vind je daar in de dropdown-lijsten INPUT en SURROUND.

Zone inschakelen:

<Power_Control><Power>On</Power></Power_Control>

Zone uitschakelen:

<Power_Control><Power>Standby</Power></Power_Control>

HDMI1 als input kiezen:

<Input><Input_Sel>HDMI1</Input_Sel></Input>

Volume 2 dB zachter instellen:

<Volume><Lvl><Val>Down 2 dB</Val><Exp></Exp><Unit></Unit></Lvl></Volume>

Volume 2 dB luider instellen:

<Volume><Lvl><Val>Up 2 dB</Val><Exp></Exp><Unit></Unit></Lvl></Volume>

Volume instellen op -56dB:

<Volume><Lvl><Val>-560</Val><Exp>1</Exp><Unit>dB</Unit></Lvl></Volume>

Mute inschakelen:

<Volume><Mute>On</Mute></Volume>

Mute uitschakelen:

<Volume><Mute>Off</Mute></Volume>

Geluidsprogramma kiezen:

<Surround><Program_Sel><Current><Straight>Off</Straight><Sound_Program>7ch Stereo</Sound_Program></Current></Program_Sel></Surround>

Vind je ondanks bovenstaande informatie nog steeds niet de correcte syntax voor een bepaald commando? Dan is het tijd om het netwerkverkeer tussen jouw pc en je receiver te sniffen! Zo zie je welke HTTP POST-commando’s er verstuurd worden naar de receiver. Installeer om te beginnen de pakketten ‘tcpdump’ en ‘wireshark’. Vervolgens open je een shell en voer je het commando uit afbeelding 2 uit. Vergeet daarbij niet om het correcte IP-adres van jouw receiver in te vullen (in plaats van 192.168.1.13). Vervang ook wlan0 door eth0 indien jouw computer een bekabelde in plaats van een draadloze netwerkverbinding heeft.

Laat de shell op de achtergrond draaien en voer nu in de webinterface de acties uit die je wilt automatiseren. Zodra je daarmee klaar bent, druk je op Ctrl-C in het terminalvenster om tcpdump af te breken. Het bestand yamaha.pcap bevat nu de HTTP POST-commando’s die je via de webinterface uitgevoerd hebt. Open dit .pcap-bestand in Wireshark. Om irrelevante data weg te filteren, vul je volgende tekst in bij “Filter”: http.request.method==POST. Selecteer nu in het bovenste venster de eerste regel en klik in het middelste venster op de driehoekjes naast “eXtensible Markup Language” om het XML-commando volledig te bekijken. Door terug in het bovenste venster te klikken en met de pijltjes naar beneden te navigeren, krijg je de verstuurde commando’s één voor één te zien (zie afbeelding 3). Heb je het commando gevonden waarnaar je zocht? Rechtsklik dan op de lijn “eXtensible Markup Language” en kies de optie “Copy” > “Bytes” > “Printable Text Only” om het XML-commando te kopiëren naar de terminal of een script.

OpenELEC

Twee voorbeelden illustreren wat allemaal mogelijk is. Het script in afbeelding 4 kan je gebruiken in OpenELEC, bijvoorbeeld op een Raspberry Pi. Het zorgt ervoor dat bij het starten van OpenELEC je receiver meteen wordt ingeschakeld met de juiste instellingen:

–        HDMI1 als input (onze Pi is aangesloten op HDMI1);

–        Volume op -24dB (het outputvolume van de Pi is aanmerkelijk lager dan het volume van bijvoorbeeld de Net Radio-input);

–        Surroundgeluid met preset “Standard Movie”.

De uit te voeren commando’s plaats je allemaal na elkaar tussen enkele aanhalingstekens (commands=’…’). Let op dat je tussen de verschillende commando’s minstens één spatie overlaat, anders werkt het script niet. Om de leesbaarheid te verhogen, hebben we elk commando ook op een aparte regel geplaatst, maar dat hoeft niet. Het systemctl-commando bleek nodig te zijn om XBMC opnieuw te starten na het inschakelen van de receiver. Zonder dit commando kregen we geen beeld te zien.

Je eigen wekker

Tegenwoordig hebben weinig receivers nog een wekfunctie, maar dan schrijf je die toch gewoon zelf? Start het script uit afbeelding 5 via cron op, bijvoorbeeld een Raspberry Pi of BeagleBone Black die 24×7 aanstaat, en je verslaapt je nooit meer! Met het script spelen we een internetradio af op volume -56dB en verhogen we dit volume elke 30 seconden (SLEEP) met 1dB (VOLINC). Het script stopt zodra je de receiver hebt uitgeschakeld (dit is de while-loop aan het einde). Het radiostation kiezen is wel een beetje omslachtig. Je moet namelijk letterlijk de navigatiecommando’s geven die je in de webinterface zou gebruiken. In dit voorbeeld gaan we eerst naar het startscherm, selecteren we daar het tweede menu (My Added Stations), waaruit we de eerste zender kiezen. Tussen elk commando wachten we 1 seconde (de receiver voerde anders enkele commando’s niet uit).

We hopen dat deze voorbeelden je nieuwsgierigheid genoeg geprikkeld hebben om zelf aan de slag te gaan. En vergeet niet dat je de technieken uit deze workshop ook op andere devices kan toepassen. Met tcpdump, Wireshark en curl kan je immers elk apparaat met een webinterface scripten!