README.rst

   1 ********************
   2 Noxon iRadio gateway
   3 ********************
   4 Push your own content onto `Noxon iRadio`__ devices:
   5 RSS feeds, text files and MediaTomb server structures.
   6
   7 This tool makes it possible to push own data into the menu
   8 entries "Internet Radio", "Podcasts" and "My Noxon" without relying
   9 on the official Terratec servers.
  10
  11 __ http://www.noxonradio.de/
  12
  13
  14 .. contents::
  15
  16
  17 ========
  18 Features
  19 ========
  20 - Customize the Noxon iRadio menus "Internet Radio", "Podcasts" and "My Noxon"
  21 - Show Mediatomb UPnP server content in "Internet Radio", so that you
  22   don't have to restart your iRadio because it does not find the UPnP server
  23   after a day of standby
  24 - Display text files and run shell scripts from the menu (home automation)
  25 - Podcast RSS feed support
  26 - Discoverable with your web browser
  27 - Transcoding of non-mp3 file types to ``.mp3`` that iRadios can play
  28 - Single file mode for children that want to listen to a single story
  29   before sleeping
  30 - Paging results with ``?startitems=1&enditems=10`` GET parameters
  31
  32
  33 RSS feed support
  34 ================
  35 Simpy write a podcast's mp3 RSS feed URL into a  ``.url`` file in
  36 the ``var/`` directory structure, and your radio will show you a
  37 folder with all episodes.
  38 Enter an episode to play it.
  39
  40 The Noxon iRadios do only allow a single HTTP redirect when they access a URL
  41 to play, but many podcast feeds send you for tracking purposes through 3 or
  42 more redirects until you reach the final mp3 URL.
  43
  44 noxon-gateway resolves the redirections for the iRadio, so that this will
  45 not be a problem.
  46
  47
  48 Creating an RSS feed
  49 --------------------
  50 You have to know the URL to the podcast's mp3 RSS feed, e.g.
  51 ``http://cast.example.org/news.rss``.
  52
  53 Create a file ``Cast News.url`` in ``var/podcasts/`` and write the RSS URL
  54 into it.
  55 That's all.
  56
  57 When accessing the "Podcasts" menu from your noxon iRadio, you'll see a
  58 directory ``Cast News`` that contains all podcast episodes.
  59
  60
  61 Single file mode
  62 ================
  63 Your kid only wants to listen to this one single story before sleeping.
  64 You start it, set the 15 minute sleep timer and leave the room.
  65
  66 After 15 minutes the child comes out and complains that the radio switched
  67 off within the second story and it wants to hear it to the end.
  68
  69 To get around such issues, you can enable "single file directories"
  70 for certain folders.
  71
  72 Each folder with audio files within this configured paths have a special
  73 directory "Einzeln" (single), which have separate folders for each audio
  74 file. Each of this separate folders only have the single audio file in them.
  75
  76 When playing this file, the iRadio will stop playing after the one file
  77 is over.
  78
  79
  80 Supported radios
  81 ================
  82 This is the list of iRadios known to work with ``noxon-gateway``:
  83
  84 - `Noxon iRadio`__ (original white version)
  85 - `Noxon iRadio cube`__
  86
  87 Others should work.
  88 If you know of unlisted radios that do work with this tool, please tell me.
  89
  90 __ http://ftp.noxonradio.de/index.php?dir=NOXON%2FNOXON_iRadio%2F
  91 __ http://ftp.noxonradio.de/index.php?dir=NOXON%2FNOXON_iRadio_Cube%2F
  92
  93
  94 Web browser support
  95 ===================
  96 You can discover the noxon-gateway contents with your web browser.
  97 Point your browser to the gateway's domain and start browsing:
  98
  99 .. image:: docs/screenshots/browsing.png
 100
 101 This works because the XML files delivered by noxon-gateway contain the
 102 link to an XSLT__ file that converts the XML structure to HTML that
 103 browsers understand.
 104
 105 Works at least with Firefox 42 and Chromium 45.
 106
 107 __ http://www.w3.org/TR/xslt
 108
 109
 110 ===================================
 111 Customizing the directory structure
 112 ===================================
 113 The ``var/`` directory contains three directories you can fill with
 114 your own content.
 115
 116 ================ ==================
 117 Menu item        ``var/`` Directory
 118 ================ ==================
 119 Internet Radio   ``internetradio``
 120 Podcasts         ``podcasts``
 121 My Noxon         ``mynoxon``
 122 ================ ==================
 123
 124 You can put folders and files into this directories.
 125
 126 The ``internetradio`` directory is hard-coded to display the contents
 127 of a MediaTomb UPnP server.
 128 You can remove the check in ``index.php#handleRequest()`` if you do not
 129 want this.
 130
 131
 132 File types
 133 ==========
 134 Directory
 135   A directory is browsable by your Noxon radio
 136 ``.txt`` file
 137   Text files are rendered as un-actionable lists, one list item per line.
 138
 139   Empty lines get removed, consecutive spaces get collapsed.
 140 ``.url`` file
 141   Podcast feed URL file.
 142
 143   Simply contains the URL to the podcast's MP3 RSS feed.
 144 executable file
 145   Script is shown as directory and gets executed when navigating
 146   into it.
 147   Output is shown as it is for ``.txt`` files.
 148
 149   I use it to control my house's heating system from the radio.
 150 ``*.auto*`` (executable)
 151   Script gets executed when browsing the folder.
 152   The output is integrated into the directory listing with the same
 153   rules as for ``.txt`` files.
 154
 155   You can use this to show the current time within the directory listing.
 156 ``nocache``
 157   Disables menu caching.
 158
 159 File extensions get removed for display purposes.
 160
 161
 162 Sorting
 163 =======
 164 Files and directory are sorted alphabetically and get listed
 165 in this order.
 166
 167 You can prefix your files and directories with ``[0-9]+_``,
 168 which lets you influence sorting and gets removed in the
 169 listings.
 170
 171 Consider the following files::
 172
 173     01_temp.auto.sh
 174     02_warmer.sh
 175     03_colder.sh
 176
 177 Would render as::
 178
 179     Temperature: 23°C
 180     warmer
 181     colder
 182
 183 (given that ``01_temp.auto.sh`` outputs the temperature string)
 184
 185
 186 Caching
 187 =======
 188 When going back in the menu strucutre with the left arrow button,
 189 Noxon iRadios display a cached version of the menu.
 190
 191 If you do not want this - because a script modified values that are
 192 displayed in the parent menu, or because the script that displays
 193 the time should always be run - you may disable caching.
 194
 195 Caching is disabled when a file named ``nocache`` is found in the directory.
 196
 197
 198 =====
 199 Setup
 200 =====
 201
 202 Basic setup
 203 ===========
 204 #. You need a web server (Apache) with PHP.
 205
 206    Using nginx, lighttpd or others is possible, but you need to translate
 207    the redirects in the ``www/.htaccess`` file into their respective format.
 208
 209 #. Clone the Git repository of this noxon-gateway software::
 210
 211      $ git clone https://git.cweiske.de/noxon-gateway.git
 212
 213 #. Configure your network's DNS server/router, see the "Hosts" section.
 214
 215 #. Point your web server's (virtual host) document root to the ``www``
 216    directory.
 217
 218    Let your web server handle the domain names.
 219
 220 #. Open http://gatekeeper.my-noxon.net/ in your browser.
 221    You should see the noxon gateway software.
 222
 223    If your browser supports XSLT, you will not see XML, but clickable HTML
 224    links.
 225
 226
 227 Hosts
 228 =====
 229 The following hosts must point to your server and be handled
 230 by this tool::
 231
 232     radio567.vtuner.com
 233     radio5672.vtuner.com
 234     gatekeeper.my-noxon.net
 235
 236
 237 Configure this in your router or the DNS server your iRadio devices use.
 238
 239
 240 MediaTomb
 241 =========
 242 To be able to browse a MediaTomb server, copy ``data/config.php.dist`` to
 243 ``data/config.php`` and fill it with mediatomb web interface credentials.
 244
 245 You also have to install the `Services_Mediatomb`__ library via `PEAR`__::
 246
 247     $ pear channel-discover zustellzentrum.cweiske.de
 248     $ pear install zz/services_mediatomb-alpha
 249
 250 __ http://zustellzentrum.cweiske.de/index.php?package=Services_MediaTomb
 251 __ http://pear.php.net/
 252
 253
 254 Transcoding
 255 ===========
 256 If you have non-mp3 files in your audio collection, install `ffmpeg`__
 257 on the noxon-gateway server.
 258 Transcoding will start automatically when the player accesses a file
 259 that is not in ``audio/mpeg`` format.
 260
 261 __ http://ffmpeg.org/
 262
 263
 264 ===================
 265 About noxon-gateway
 266 ===================
 267
 268 Homepage
 269 ========
 270 ``noxon-gateway`` lives at http://cweiske.de/noxon-gateway.htm
 271
 272 The source code is available at http://git.cweiske.de/noxon-gateway.git/
 273 and mirrored at https://github.com/cweiske/noxon-gateway.
 274
 275
 276 License
 277 =======
 278 This application is available under the `AGPL v3`__ or later.
 279
 280 __ http://www.gnu.org/licenses/agpl.html
 281
 282
 283 Author
 284 ======
 285 Written by `Christian Weiske`__, cweiske@cweiske.de
 286
 287 __ http://cweiske.de/