From 98c715874527ef6c96b346da180e7fb323c20148 Mon Sep 17 00:00:00 2001
From: ulrich <undisclosed>
Date: Fri, 26 Jan 2018 08:05:18 +0000
Subject: [PATCH] ..
---
README.md | 214 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 208 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index 327106e..b4b04e2 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,7 @@
## Prototyp
-Diese Anwendung ist zur Zeit im Bau. Der aktuelle Prototyp zum Stand des Codes in diesem Repository ist hier zu sehen:
-[Link zum Prototyp](/data/ulrich/test/radio-ui).
+Diese Anwendung ist zur Zeit im Bau. Der aktuelle Prototyp zum Stand des Codes in diesem Repository ist hier zu sehen: [Link zum Prototyp](/data/ulrich/test/radio-ui).
## Vorgesehene Funktionen
@@ -13,13 +12,55 @@
Radiosender können hinzugefügt, geändert und gelöscht werden. Ein Suchfeld ermöglicht das Einschränken der Übersicht auf bestimmte Sender.
-Das Abspiel-Ziel ist konfigurierbar: Ein Radionsender kann entweder auf dem Gerät abgespielt werden, auf dem das radio-ui läuft oder auf einem anderen Gerät wie z.B. einem Raspberry Pi.
+Das Abspiel-Ziel ist konfigurierbar: Ein Radionsender kann entweder auf dem Gerät abgespielt werden, auf dem das radio-ui im Browser läuft oder auf einem anderen Gerät wie z.B. einem Raspberry Pi.
Zum Abspielen auf einem Raspberry Pi ist die Nutzung der Anwendung [pirc](/gitblit/docs/pirc.git) vorgesehen, die zum Spielen von Audiostreams den [omxplayer](https://elinux.org/Omxplayer) mit einer unter [Tomcat](https://de.wikipedia.org/wiki/Apache_Tomcat) laufenden Fernbedienung kombiniert, die per HTTP gesteuert werden kann.
-## Nutzung von Vorlagen
+## Beispielcharakter
-Die Anwendung radio-ui ist ein Beispiel für die Nutzung von Vorlagen in Webanwendungen. Die Datei `index.html` definiert Bereiche einer HTML-Seite als `div`-Elemente die während der Ausführung des Programmes dynamisch mit wechselnden Inhalten gefüllt werden.
+Neben dem praktischen Nutzen veranschaulicht das radio-ui verschiedene Aspekte des Baus von Webanwendungen:
+
++ app-layout
++ Vorlagen
++ app-menu
++ CRUD-Muster (Create, Read, Update, Delete)
+
+Wie in der Anwendung radio-ui die obigen Themen umgesetzt sind, ist nachfolgend kurz betrachtet.
+
+### app-layout
+
+Das radio-ui verwendet das [app-layout](/gitblit/docs/web!app-layout.git), das mit Hilfe von HTML und CSS die Grundlage einer für Webanwendungen geeigneten Bedienoberfläche schafft.
+
+### Nutzung von Vorlagen
+
+Die Datei `index.html` definiert Bereiche einer HTML-Seite als `div`-Elemente, die während der Ausführung des Programmes dynamisch mit wechselnden Inhalten gefüllt werden.
+
+Inhalte werden dabei mit Hilfe von [Mustache](https://github.com/janl/mustache.js) aus einer Vorlage und einer Inhaltsbeschreibung in [JSON](https://de.wikipedia.org/wiki/JavaScript_Object_Notation) zu [HTML](https://de.wikipedia.org/wiki/Hypertext_Markup_Language) zusammengesetzt.
+
+Durch die Nutzung von Vorlagen lassen sich dynamische und statische Inhalte sowie deren Gestaltung und Struktur optimal und frei von Redundanzen zusammenführen.
+
+### app-menu
+
+Das [app-menu](/gitblit/docs/web!app-menu.git) setzt auf die Nutzung von Vorlagen auf und fügt dem radio-ui ein Menü zur Bedienung der Anwendung hinzu. Es ist zudem eingebettet in die Funktion des app-layout. Das radio-ui zeigt so den Einsatz des app-menu und mithin das Zusammenspiel von Vorlagen, app-layout und Menü am praktischen Beispiel.
+
+### CRUD-Muster
+
+CRUD (Create, Read, Update, Delete) ist ein häufig vorkommendes Nutzungsmuster von Anwendungen, Daten werden erzeugt, gelesen, bearbeitet und gelöscht. Bei Webanwendungen zerfällt es in einen Teil, der auf dem Server ausgeführt wird und einen, der im Browser abläuft (Bedienoberfläche).
+
+Allein bezogen auf den Umgang mit den Daten auf der Serverseite ist das CRUD-Muster schnell umgesetzt. Eine Datenstruktur wird erzeugt, gelesen, gespeichert und gelöscht. Eine Bedienoberfläche zur Ausführung dieser Operationen erfordert allerdings mehr als nur den Anstoß der jeweiligen Operation.
+
+Beim radio-ui wird beispielsweise mit den Daten der Radiosender auf diese Weise umgegangen. Die folgende Tabelle veranschaulicht die benötigten Funktionen.
+
+| Operation | Bedienoberfläche (radio-ui) | Server |
+| ------------- |-------------| -----|
+| Create | Funktion zum Auslösen der Erstellung eines neuen Senders, Dialog zur Eingabe der Daten, Funktion zum Senden der neuen Daten | Speichern eines neuen Senders |
+| Read | Funktion zum Abruf der Senderliste, Lesen der Senderliste, Darstellen der Liste als Kacheln | Ausgeben einer Liste von Sendern |
+| Update | Funktion zum Auslösen der Änderung an einem Sender, Funktion zur Auswahl eines Senders aus einer Liste, Darstellen der Daten des gewählten Senders in einem Dialog zum Bearbeiten, Funktion zum Senden der Änderungen | Speichern von Änderungen an einem bestehenden Sender |
+| Delete | Funktion zum Auslösen der Löschfunktion, Funktion zur Auswahl eines Senders oder mehrerer Sender aus einer Liste, Funktion zum Senden einer Liste zu löschender Sender, Funktion zur Absicherung gegenüber versehentlichem Löschen | Löschen eines Senders oder mehrerer Sender |
+
+Die Tabelle läßt ahnen, dass der größere Aufwand zur Herstellung eines CRUD-Musters auf die Bedienoberfläche entfällt.
+
+Mit seinen Menüfunktionen und der Art, wie mit Daten als Liste und als einzelnem Datensatz umgegangen wird sowie der Kombination dieser Funktionen mit der Verwendung von Vorlagen zeigt das radio-ui einen generischen Lösungsansatz, der sich für die Wiederverwendung in anderen Anwendungen eignet und dabei wenige Abhängigkeiten erfordert.
## Abhängigkeiten
@@ -32,7 +73,6 @@
Diese sind in der Datei `index.html` über die folgenden Einträge eingebunden.
````
-<link rel="stylesheet" type="text/css" href="../jslib/app-menu/nav-toggle.css">
<link rel="stylesheet" type="text/css" href="../jslib/app-menu/app-menu.css">
<script src="../jslib/jquery-1.11.1/jquery-1.11.1.min.js"></script>
<script src="../jslib/mustache/mustache.min.js"></script>
@@ -40,6 +80,44 @@
````
Sollen einzelne Komponenten von einem anderen Ort wie beispielsweise einem Content Delivery Network (CDN) eingebunden werden, müssen nur die obigen Einträge entsprechend angepasst werden.
+
+## Kombination von pirc und radio-ui
+
+Zur Verwendung des radio-ui mit [pirc](/gitblit/docs/pirc.git) kann die Anwendung radio-ui direkt auf einen Raspberry Pi installiert werden, beispielsweise ähnlich wie pirc als Webanwendung für Tomcat. Stattdessen kann radio-ui auch von einer anderen Maschine aus die pirc-Instanz auf einen Raspberry Pi aufrufen.
+
+### Abspielen auf dem Raspberry Pi
+
+Kommandos an [pirc](/gitblit/docs/pirc.git) werden via HTTP an die betreffende Maschine gesendet und bestehen aus einem Klassennamen `c`, einem Methodennamen `m` und einem Parameter `p`. Ein Kommando setzt sich wie folgt zusammen
+
+1. `http://raspi:8080/` - URL der Maschine
+1. `pirc/` - Name des Kontext, unter dem die Anwendung pirc läuft
+1. `sys/rpc` - Service-Endpunkt der pirc-API
+1. `c=de.uhilger.pirc.App` - Name der Klasse von pirc, die die Abspielmethode enthält
+1. `m=abspielen` - Name der Methode zum Abspielen
+1. `p=Sender-URL` - der Parameter mit dem URL zum Audiostream des Webradiosenders
+
+Zum Aufruf des Kommandos mit dem radio-ui kann es weitgehend unverändert bleiben. Nur der Teil 6. mit dem URL des Senders muss veränderlich gestaltet sein.
+
+#### Beispiel Abspielen
+
+Ist die Fernbedienung pirc auf einem Raspberry Pi installiert, lautet das Kommando zum Abspielen des Webradiosenders radiobob (vgl. Senderliste weiter unten) wie folgt
+
+````
+http://raspi:8080/pirc/sys/rpc?c=de.uhilger.pirc.App&m=abspielen&p=http://bob.hoerradar.de/radiobob-live-mp3-hq&p=
+````
+
+Das obige Kommando geht davon aus, dass der betreffende Raspberry Pi unter dem Namen `raspi` auf Port `8080` über `HTTP` erreichbar ist und dass auf dem Pi die Anwendung pirc unter dem Kontextnamen `pirc` installiert wurde. Es bewirkt, dass auf dem betreffenden Raspberry Pi eine Instanz des omxplayer gestartet wird und diese fortlaufend den Webradio-Stream unter der angegebenen Adresse abspielt.
+
+#### Beispiel Stoppen
+
+Zum Stoppen des zur Zeit abgespielten Webradios dient das folgende Kommando
+
+````
+http://raspi:8080/sys/rpc?c=de.uhilger.pirc.App&m=kommando&p=q
+````
+
+Mit dem obigen Aufruf wird das Kommando `q` an den laufenden Prozess des omxplayer gesendet. Das bewirkt, dass der omxplayer das Abspielen stoppt und der laufende omxplayer-Prozess endet.
+
## Radiostreams
@@ -69,6 +147,14 @@
Mobile Nutzung: http://bob.hoerradar.de/aac-radiobob
+#### Test der Bandbreite
+
+Spielt man den URL 'hq' von Radiobob im Browser zeigt der Netzwerkmonitor von Linux eine Netznutzung von 24-32 kbit/s. Das ergibt die folgende Betrachtung:
+
++ 32 kBit/s
++ 115.20.000 Bit/Std (kBit x 3600 x 1000)
++ 13,74 MB pro Stunde (Bit : 8 : 1.024 : 1.024)
+
### FFH
[Livestream-Übersicht](https://www.ffh.de/musik/webradios/stream-adressen.html)
@@ -76,3 +162,119 @@
128kbps http://mp3.ffh.de/radioffh/hqlivestream.mp3
48kbps http://mp3.ffh.de/radioffh/livestream.aac
+
+## Noch zu erledigen
+
+### Templates für Mustache dynamisch laden
+
+Spart Ladezeit zu Beginn. Lösungsansatz: Eine Funktion, die als Parameter das Element erhält, dessen html mit dem gerenderten Template ersetzt werden soll und den zu rendernden Inhalt. Die dynamische Ladefunktion
+
+1. prüft, ob das Template schon im cache ist
+1. Lädt das Template, wenn nicht
+1. wartet, bis das Template geladen ist
+1. rendert das Template mit dem übergebenen Inhalt
+1. schreibt das Ergebnis ins html des übergebenen Elements
+
+Der letzte Teil des Ablaufs muss asynchron gefasst sein, damit auf das Laden gewartet werden kann.
+
+## Schnittstellenbeschreibung
+
+Für den Prototyp des radio-ui können verschiedene Arten des Umgangs mit Sendern und Abspielern hergestellt werden. Die folgenden Angaben zeigen die Punkte auf, an denen eine konkrete Implementierung ansetzen kann.
+
+### Sender
+
+#### Senderliste lesen
+
+Aufruf
+
+````
+data/sender.json
+````
+
+Antwort
+
+````
+{
+ "senderliste": {
+ "titel": "Senderliste",
+ "inhalt": [
+ {
+ "senderid": 1,
+ "sendername": "hr info",
+ "senderurl": "http://hr-hrinfo-live.cast.addradio.de/hr/hrinfo/live/mp3/128/stream.mp3",
+ "senderlogo": "../bilder/hr-info.png"
+ },
+ {
+ "senderid": 2,
+ "sendername": "radiobob",
+ "senderurl": "http://bob.hoerradar.de/radiobob-live-mp3-hq",
+ "senderlogo": "../bilder/radio-bob-logo-80.png"
+ },
+ usw.
+ ]
+ }
+}
+````
+
+#### Neuen Sender speichern
+
+Noch nicht realisiert.
+
+#### Änderungen an einem Sender speichern
+
+Noch nicht realisiert.
+
+#### Sender löschen
+
+Noch nicht realisiert.
+
+### Abspieler
+
+#### Abspielerliste lesen
+
+Aufruf
+
+````
+data/abspieler.json
+````
+
+Antwort
+
+````
+{
+ "abspielerliste": {
+ "titel": "Abspielerliste",
+ "inhalt": [
+ {
+ "abspielerid": 1,
+ "abspielername": "dieses Gerät",
+ "abspielerurl": "",
+ "abspielertyp":"lokal",
+ "abspielerbild": "",
+ "abspielerzustand":""
+ },
+ {
+ "abspielerid": 2,
+ "abspielername": "Raspberry Pi Wohnzimmer",
+ "abspielerurl": "",
+ "abspielertyp":"pirc",
+ "abspielerbild": "",
+ "abspielerzustand":"selected"
+ },
+ usw.
+ ]
+ }
+}
+````
+
+#### Neuen Abspieler speichern
+
+Noch nicht realisiert.
+
+#### Änderungen an einem Abspieler speichern
+
+Noch nicht realisiert.
+
+#### Abspieler löschen
+
+Noch nicht realisiert.
--
Gitblit v1.9.3