setup howto

[noxon-gateway.git] / README.rst

diff --git a/README.rst b/README.rst
index 89936224cf40568f68c0f4d000253100ec67bccf..89b7d8dba14f2aa7a22a8efa54f03883453d87d5 100644 (file)
--- a/README.rst
+++ b/README.rst
@@ -27,6 +27,7 @@ Features
 - Transcoding of non-mp3 file types to ``.mp3`` that iRadios can play
 - Single file mode for children that want to listen to a single story
   before sleeping
+- Paging results with ``?startitems=1&enditems=10`` GET parameters
 
 
 RSS feed support
@@ -58,7 +59,7 @@ directory ``Cast News`` that contains all podcast episodes.
 
 
 Single file mode
-----------------
+================
 Your kid only wants to listen to this one single story before sleeping.
 You start it, set the 15 minute sleep timer and leave the room.
 
@@ -132,26 +133,28 @@ File types
 ==========
 Directory
   A directory is browsable by your Noxon radio
-``.sh`` file
-  Shell script which is shown as directory and which gets executed
-  when navigating into it.
-  Output is shown as it is for ``.txt`` files.
-
-  I use it to control my house's heating system from the radio.
-``.auto.sh``
-  Shell script which gets executed when browsing the folder.
-  The output is integrated into the directory listing with the same
-  rules as for ``.txt`` files.
-
-  You can use this to show the current time within the directory listing.
 ``.txt`` file
-  Text files are rendered as un-actionable lists.
+  Text files are rendered as un-actionable lists, one list item per line.
 
   Empty lines get removed, consecutive spaces get collapsed.
 ``.url`` file
   Podcast feed URL file.
 
   Simply contains the URL to the podcast's MP3 RSS feed.
+executable file
+  Script is shown as directory and gets executed when navigating
+  into it.
+  Output is shown as it is for ``.txt`` files.
+
+  I use it to control my house's heating system from the radio.
+``*.auto*`` (executable)
+  Script gets executed when browsing the folder.
+  The output is integrated into the directory listing with the same
+  rules as for ``.txt`` files.
+
+  You can use this to show the current time within the directory listing.
+``nocache``
+  Disables menu caching.
 
 File extensions get removed for display purposes.
 
@@ -180,10 +183,47 @@ Would render as::
 (given that ``01_temp.auto.sh`` outputs the temperature string)
 
 
+Caching
+=======
+When going back in the menu strucutre with the left arrow button,
+Noxon iRadios display a cached version of the menu.
+
+If you do not want this - because a script modified values that are
+displayed in the parent menu, or because the script that displays
+the time should always be run - you may disable caching.
+
+Caching is disabled when a file named ``nocache`` is found in the directory.
+
+
 =====
 Setup
 =====
 
+Basic setup
+===========
+#. You need a web server (Apache) with PHP.
+
+   Using nginx, lighttpd or others is possible, but you need to translate
+   the redirects in the ``www/.htaccess`` file into their respective format.
+
+#. Clone the Git repository of this noxon-gateway software::
+
+     $ git clone https://git.cweiske.de/noxon-gateway.git
+
+#. Configure your network's DNS server/router, see the "Hosts" section.
+
+#. Point your web server's (virtual host) document root to the ``www``
+   directory.
+
+   Let your web server handle the domain names.
+
+#. Open http://gatekeeper.my-noxon.net/ in your browser.
+   You should see the noxon gateway software.
+
+   If your browser supports XSLT, you will not see XML, but clickable HTML
+   links.
+
+
 Hosts
 =====
 The following hosts must point to your server and be handled
@@ -227,6 +267,8 @@ About noxon-gateway
 
 Homepage
 ========
+``noxon-gateway`` lives at http://cweiske.de/noxon-gateway.htm
+
 The source code is available at http://git.cweiske.de/noxon-gateway.git/
 and mirrored at https://github.com/cweiske/noxon-gateway.