#lang racket/base
;; Copyright Neil Van Dyke.  See file "info.rkt".

(require (planet neil/mcfly))

(doc (section #:tag "introduction" "Introduction")

     (para (italic "This is a pre-alpha release, of possible interest only to
     (para (deftech "RackOut")
           " is a ``living room appliance'' software project.  RackOut is
intended to run on a fairly arbitrary cheap PC plugged into a large-ish display
monitor of some kind, and to be controlled via smartphones.  RackOut is in
development, and its current feature set consists of playing DVDs.  RackOut is
hobbyist-oriented, and you currently won't be able to get it to work unless you
are a techie.")
     (para "RackOut is Free Software, in the Free Software Foundation sense.
RackOut is currently developed in a combination of the Racket programming
language, including various Racket PLaneT packages, and also uses some
off-the-shelf software such as VideoLAN VLC.")

     (para "There is also "
           (deftech "RackOut Live")
           ", which is a complete bootable firmware image for 32-bit x86 PCs
that can be installed on a USB flash drive.  RackOut Live is based on a careful
configuration of Debian GNU/Linux, with some software specific to
RackOut.  (You probably only want to use RackOut through RackOut Live, but most
of the RackOut software can also be run from the command line or DrRacket on
most GNU/Linux-ish workstations, and possibly non-GNU/Linux-ish ones, as well.)
The code to build a RackOut Live image is actually included with RackOut.  In
addition to RackOut Live, we plan an attempt at RackOut Pie, for the Raspberry
Pi computer, once Pi hardware arrives.")
     (para "Some goals and guiding principles for RackOut:")
     (itemlist (item "The original impetus: have a DVD player that doesn't
force one to watch minutes of obnoxious advertisements every time one tries to
play the yoga DVD that one paid good money for, on the equipment that one paid
good money for.")
               (item "Use the Racket language, because we like it, and also
because we like to demonstrate things like mobile apps using Racket.")
               (item "Be Free Software, because we like Free Software, and very
good things have come from it.")
               (item "Work with PC hardware one has kicking around, such as
5-year-old laptops and current smartphones, because this seemed consistent with
the hobbyist spirit of RackOut.  Think ``poor (wo)man's home theatre.''")
               (item "Don't be evil, because we actually mean it.  No spyware,
no attempted lock-ins to commercial services, etc.")
               (item "No piracy, because RackOut users are goody-two-shoes
types.  And fabulously good-looking.")
               (item "Lean towards traditional (well, American 1950s through
'90s or so) living room shared experience, around a shared screen, rather than
everyone doing their own thing on individual iPads.  This is because we want
teenagers to suffer."))
     (para "In case it's not already clear, virtually everything about RackOut
is opposite of what you'd do if you wanted a marketable product.  Consider the
image of a stereotypical young MBA who desperately wants to pair your techie
know-how with his business ``leadership''... the RackOut philosophy is to
frustrate the MBA to the point that he's ready to leadership his Bimmer off a
cliff.  Don't worry, he'll be OK, and he'll decide to turn his life around and
become a positive contributor to society.")
     (para "Goals for ongoing development of RackOut:")
     (itemlist (item "Try to make a RackOut Pie alternative to RackOut Live,
for running on the Raspberry Pi instead of x86 PCs.")

               (item "Finalize the installer/updater.  A lot of work has gone
into this already, and the next bit is to have it automatically create the
persistent "
                     (filepath "/home")
                     " partition.")
               (item "Make DVD-playing work more smoothly.  For example, get
around VLC bug regarding confused Play and Pause state.")
               (item "Throw out this quick brain dump documentation and write
better documentation someday.")
               (item "Add music library playing, first based on Ogg Vorbis and
Flac.  Some work has already been done for this, including the "
                     (tt "mediafile")
                     " Racket library.")
               (item "Add CD ripping.  We have a proof-of-concept for a very
simple approach that uses a particular configuration of "
                     (tt "abcde")
                     " to do almost all the work, and just have to write a UI
for that, probably after the music library is spec'ed out fully.")

               (item "Look into streaming video playing from devices, such as smartphones.")

               (item "Look into media server to devices such as smartphones.")
               (item "Look into playing free video streams, such as from
various countries' public television.")

               (item "Add video library, using almost the exact same
implementation as for music library.")
               (item "Look into working with TV tuner/receiver devices, for RF
broadcast and cable TV.")
               (item "Consider games for groups in a living room.  For example,
party games with a big screen component, and perhaps each person or team uses a

               (item "Once sufficient functionality has been fleshed-out, make
a plugin architecture.")))

(doc (section #:tag "hardware" "Picking your Hardware")
     (para "To run RackOut Live, you'll probably want:")
     (itemlist (item "A PC capable of running 32-bit x86, probably faster than
500 MHz.  For example, RackOut was first run on a 6-year old laptop.")
               (item "A big screen of some kind, which could be a PC monitor, a
projector, or a TV.")
               (item "Some speakers, which might be integrated into the
monitor, or separate PC speakers, or speakers in laptop, or headphones, or an
old-school stereo setup, or an expensive audiophile setup.")
               (item "Any modern smartphone or tablet computer with a Web
browser, to run the RackOut remote control.  Or you can use a laptop, but
that's not as suave when you have a hot date.")

               (item "A USB flash drive of at least 512MB, and preferably at
least 1GB.  The RackOut Live firmware image is currently a bit under 400MB, and
we'd like to allocate about 700MB total (about the most we could fit on a CD-R)
in case later versions of the firmware are bigger.  Plus you'll want at least a
little space for a mutable "
                     (filepath "/home")
                     " partition, so that you can store configuration, and
perhaps add many GB of space for a music and video library.")
               (item "Any furniture for keeping the PC together with the big
screen.  If PC is a laptop, you'll probably want to run with the lid open, so
laptop doesn't overheat, so some place to hide the laptop out of view would be

(doc (section "How to be Free Software Hardcore")

     (para "If you run RackOut Live (or run RackOut on a Debian or Ubuntu
system), you might notice that the main screen has dreaded red text at the
bottom, such as: ``Ahem. Free Software faux pas... This machine has 8 non-free
packages installed, and has files in /lib/firmware.''")

     (para "RackOut Live is set up in the spirit of "
           (hyperlink "http://www.fsf.org/" "Free Software")
           ".  It permits a user to install non-Free software, but tries to
avoid the common situation in which a user of say, a GNU/Linux distribution,
runs non-Free software "
           (italic "unknowingly")
           ".  Hence the red message.")

     (para "Sometimes, to avoid having to install non-Free downloadable
firmware blobs for WiFi and video display, you have to accept poorer
performance or pick hardware that does not require these blobs.  For example,
the author's current RackOut Live living room PC is a several-year-old Pentium
4 box, to which he added three bits of hardware that work well with open drivers
and don't required closed firmware blobs, just because: an "
           (tt "ath9k")
           "-based Radeon HD 4350 video card, a TP-Link TL-WN781ND wireless
card, and a SoundBlaster Live card.")

     (para "If, however, you "
           (italic "want")
           " to install firmware blobs on RackOut Live, you can put them in the
persistent "
           (filepath "/home/user/lib/firmware")
           " directory, which is the same as putting them in "
           (filepath "/lib/firmware")
           " on a normal Debian GNU/Linux machine.  This is a feature that
RackOut Live has set up so that it avoids the unspeakable shame of distributing
non-Free software in its read-only image, yet permits the user to add to "
           (filepath "/lib/firmware")
           " indirectly, if they really want to.  RackOut doesn't judge.  OK,
it does."))

(doc (section "Building and Installing RackOut Live")

     (para "At time of this writing, RackOut Live disk images are not
distributed (because it's an early snapshot release), so before you can install
RackOut Live, you need to build an image.")
     (para "First, you'll need a Debian "
           (tt "squeeze")
           " GNU/Linux 32-bit x86 install, with all the software necessary to
build a Debian Live image, plus Racket 5.3.1 and a few other tools, like "
           (tt "parted")
           ".  Then you'll probably need to install the "
           (tt "neil/rackout")
           " package from PLaneT, and then copy the "
           (filepath "rackout")
           " source directory tree out of your PLaneT cache, to somewhere you can work
with it easier.")

     (para "From the source directory, there's a "
           (filepath "Makefile")
           ", which lets you do things like "
           (tt "make live")
           ", to make an image in "
           (filepath "rackout-live-build-dir/binary.img")
           ".  Another command, "
           (tt "make live-clean-burn-stick")
           ", will build an image, burn it to a USB flash drive, and then boot
the image in KVM (so it's ready to try when you return from elsewhere).  See "
           (filepath "Makefile")
           " for other commands.  For some commands to work, you might need to
create a "
           (filepath "Makefile-options")
           " file, for setting "
           (tt "PLT_BIN_DIR")
           " or "
           (tt "USB_DRIVE")

     (para "Note that the "
           (filepath "Makefile")
           " burns to the USB flash drive using a custom program, "
           (tt "raco rackout-live-install")
           ", which performs some checks and preserves existing partitions in
some cases.  The idea is that the RackOut Live firmware is the non-persistent "
           (filepath "/")
           " filesystem, and that the "
           (filepath "/home")
           " filesystem is persistent.  So updating to a new RackOut version is
intentionally a complete reinstall, not incremental changes atop customizations
that a user might have made.  Any persistent customizations are under the "
           (filepath "/home")
           " filesystem, and limited.  To create this magical "
           (filepath "/home")
           " filesystem, a future version of the installer will do it for you,
but for now, after you do the initial burn of the RackOut image to a USB flash
drive, use a program like "
           (filepath "gparted")
           " to add a "
           (filepath "/home")
           " partition with an "
           (tt "ext3")
           " filesystem, and the label "
           (tt "home-rw")
           ".  The first time you boot RackOut, a "
           (filepath "user")
           " directory on that partition will be created automatically.")

     (para "If you want to play most DVDs, there is currently an unfortunate extra step, which is to install "
           (tt "dvdcss2")
           " files (see "
           (url "http://wiki.debian.org/MultimediaCodecs")
           ").  You will need the version for Debian "
           (tt "squeeze")
           ", to extract the library files from the "
           (tt ".deb")
           " and to copy the library files into "
           (filepath "/home/user/lib/")
           " on your USB flash drive after that directory has been created by
booting RackOut Live.  This manual step is necessary until we figure out
whether and how we can bundle the library with RackOut Live.  We haven't had
time to look into it.")

     (para "If you want to run RackOut Live on an old PC that can't boot from
USB flash drives, you can install RackOut Live to the PC's hard disk drive by
simply copying the same USB flash drive image to the hard drive.  (Of course,
this will lose anything previously on the hard drive, including the boot
sector.)  One lazy way to do this is to boot some GNU/Linux on the PC, and then
simply do a "
           (tt "dd")
           " from the USB flash drive device to the hard drive device.  (Note
that we could alternatively make a bootable CD-R image for RackOut Live, but
possibly no one would ever use it, especially since RackOut currently needs a
DVD-ROM drive free for playing DVDs.)"))

(doc (section "Running RackOut Live")

     (para "To run RackOut Live, boot from the USB flash drive (or hard drive,
if that's where you installed it), wait a short while for the main screen to
appear, and the network to come up.  Ideally, it works the first time, and you
see a screen that tells you to point your handheld Web browser at "
           (tt "rackout.lan")

     (para "If the main screen complains that it can't find the network, and
you're using WiFi, then probably you need to tell it the wireless AP SSID, and
possibly a key.  If this is the case, then press the WindowsLogo-Shift-Enter
key combination to open a shell window, and then run "
           (tt "wicd-gtk --no-tray")
           ".  You might also have to go to preferences in this program, and
tell it your wireless device is "
           (tt "wlan0")
           ".  If it can't find your wireless device, then maybe you need a
firmware blob; check "
           (tt "dmesg")
           " for possibly helpful messages.  This should be a one-time
configuration, since RackOut Live should put changes made through this program
onto the persistent "
           (filepath "/home")

     (para "Once you have a screen that says ``Point your handheld Web browser
at...,'' then do what it says.  You should then see a remote control in your
device's Web browser, for running the DVD player.  If you don't see this, then
make sure that your your device is getting its Internet through the same LAN as
your RackOut Live box.")

     (para "Once you have the remote control in your Web browser, feel free to press the "
           (bold "DVD")
           " button to play DVDs, and the "
           (bold "About")
           " to view information about versions and your hardware.")

     (para "If you have trouble playing DVDs, make sure that you installed "
           (tt "dvdcss2")
           " as mentioned earlier, and then try running VLC from the
shell (press WindowsLogo-Shift-Enter to get a shell) and changing the
preferences there (such as changing the video device to X11 from XVideo, or
selecting the appropriate ALSA device).")

     (para "If RackOut chooses the wrong resolution for your monitor, or it
picks the wrong monitor on a multi-monitor system (e.g., you have a big screen
plugged into your laptop, but it chooses to use the laptop screen instead of
the big screen), please send "
           (tt "xrandr")
           " output to the author, or look at the code in "
           (filepath "rackout-xrandr.rkt")

     (para "If you have further trouble, note that your RackOut Live box is
secretly also a Debian GNU/Linux workstation.  It's also running a
slightly-modified XMonad tiling window manager, with the WindowsLogo key as the
modifier key, so hack away."))

(doc (section "Support")

     (para "You can email the author about RackOut.  Keep in mind that this
version is not intended to be used by anyone.  It's being released only because
the author wants to snapshot the code publicly somewhere, before focusing on
money-making activities, in case he gets hit by a bus before he can return to
tinkering with RackOut."))

(doc history 
     (#:planet 1:0 #:date "2013-01-08"
                (item "Snapshot release to PLaneT, while in development."))))