While I'll give you the full tour [Hack #35] in a bit, a quick mention of what's where is probably in order:
/dev/hdX4 and /dev/hdX7
These two directories should look pretty similar to each other, while also looking remarkably similar to the / directory on a Linux system. This should come as no surprise, since that's exactly what TiVo is! You should see familiar directories like /etc, /dev, and /bin, but here they are called /mnt4/etc, /mnt7/etc, and so forth. That's only because we have the hard drive mounted in this odd way temporarily.
/dev/hdX9
This is what gets mounted as the /var directory when your TiVo is running. Files in the /var directory constantly change when the system is running. Notice the /var/log directory containing TiVo's log files. You'll also notice that the /tmp directory is located here too.
Go To
If your intent was to enable the Bash shell over serial port, move on to [Hack #30].
Top
Hack 30 Enabling Bash over the Serial Port
The simplest way to get a prompt on your TiVo is to activate the serial port and connect your TiVo to your PC.
Since the days of yore, one of the most common and simple methods for hooking together two PCs has been to use the serial port. A garden-variety serial cable (I've collected a case of them over the years) plus a $5 null modem adapter will provide a fine, albeit slow, connection between the two machines. Fire up just about any terminal program (e.g., Windows' HyperTerm), and you can flow text from one machine to the other.
Enabling the Bash shell so that it's available to the serial port the next time your TiVo boots requires command-line access to your TiVo drive. Yes, we know it's a catch-22—one solved by mounting the right drive partitions [Hack
#29] and turning on the Bash shell. This hack assumes you've already mounted the drive partitions.
You'll be editing the rc.sysinit script that controls what processes and programs are started when TiVo boots up.
But first, it serves you well to make backup copies of files you'll be editing, just in case something goes wrong. Type the following commands to get to and make a copy of rc.sysinit as rc.sysinit.orig (as in "original"):
# cd /mnt4/etc/rc.d
# cp rc.sysinit rc.sysinit.orig
If, in [Hack #29], you found that you don't have a partition 4, replace mnt4 in the previous command with mnt7.
Next, we'll append (the >> bit) a command-line incantation to get the Bash shell running to the end of the rc.sysinit file:
# echo '/bin/bash --login < /dev/ttyS3 >& /dev/ttyS3 &' >> rc.sysinit
You're asking Bash to take its input from (< /dev/ttyS3) and send its output to (>& /dev/ttyS3) the serial port (/dev/ttyS3), instead of from the command line.
At this point, all should be set. You can delete that backup file, or not—it's up to you:
# rm rc.sysinit.orig
Most of you should have both a partition 4 and partition 7 [Hack #29]. If you do, it's a good practice to mirror a change made to the active partition on the backup partition. Perform all the previously mentioned command-line steps again, replacing mnt4 with mnt7, like so:
# cd / mnt7 /etc/rc.d
# cp rc.sysinit rc.sysinit.orig
# echo '/bin/bash --login < /dev/ttyS3 >& /dev/ttyS3 &' >> rc.sysinit
# rm rc.sysinit.orig
Again, removing the backup rc.sysinit.orig file is optional.
Instead of the commands recommended in this hack, many guides found on the Internet recommend that you run this:
echo '/bin/bash < /dev/ttyS3 >& /dev/ttyS3 &' >> rc.sysinit
While it is completely up to you, I recommend the one with --login on the command line, as that will evaluate /.profile when the TiVo starts up.
Go To
All that remains is a little cleanup and a shut down [Hack #32]. But, before you go, it behooves you to copy over a few useful Unix utilities [Hack #31].
Top
Hack 31 Copying Unix Binaries to TiVo
The shell is nothing without its utilities. What's a work environment worth if you can't do anything while you're there?
The default installation of the TiVo OS has a Bash shell and little else in the way of the utilities necessary to do anything of any use. How exciting, after all, is:
bash-2.02# echo *
Beyond the first few minutes, that is. ;-).
While you have your box open and drives mounted on your PC [Hack #29], now's a good time to bring over some of the common utilities most Unix jockeys simply assume to be there.
You are going to need a DOS- or Windows-formatted floppy disk for this one. Steve Jenkins's Newbie TiVo Hacker site offers a complete archive of useful Unix utilities for the Series 1 TiVo (
http://tivo.stevejenkins.com/downloads/tbin.tar.gz), including head, tail, rmdir, strace, touch, and, most importantly, ls. Copy the .tar.gz file to the floppy. Don't run this file through any decompression programs, just copy it over as is.
Now, let's make a directory on the TiVo drive into which to put the Unix binaries. While we're at it, we'll make this the home of all our program hacks throughout the rest of this book. There are two partitions that are good
candidates: /dev/hdX4 or /dev/hdX7 (these two are effectively the same, one being the backup of the other), and /dev/hdX9.
As one of /dev/hdX4 and /dev/hdX7 is always in deep sleep while the other is running, this is probably not the best place to keep these files and your future hacks. The next time your TiVo software is upgraded, the active partition is relegated to a backup partition and will no longer be visible to your TiVo. Not to mention that the
backup-partition-to-be could very well be wiped clean during a software upgrade. Poof! Any hacking you've done is history. So we'll rule out partitions 4 and 7.
Partition 9, /dev/hdX9, on the other hand, is always visible to your TiVo and therefore appears to be a clear winner.
There is, however, one caveat: if you overfill this partition, TiVo will summarily delete it and recreate it from scratch.
So, there doesn't appear to be any perfect choice. In my opinion, the lesser of two evils is to use /dev/hdX9. Yes, we're taking the chance that we might overfill the partition and lose our work, but for the remainder of this book, this is the chance we're going to take. If, for some reason, you find that your hacks are gone, at least you'll know why.
As it stands, there is no truly "safe" place to keep hacks on your TiVo, but Mike Baker (a.k.a. "embeem") suggests a more involved method for keeping your hacks persistent. He suggests creating another partition on your TiVo, convincing your TiVo to boot from that partition, and then moving on to TiVo's native partitions—all without TiVo really knowing anything about the initial bootstrap partition. Implementing these changes can be a little tricky, however. If you are interested, you'll find his post on the topic at
http://alt.org/forum/index.php?t=msg&th=17.
Assuming you choose to use /dev/hdb9, create a directory to house hacks, utilities, etc., like so:
# mkdir /mnt9/hack
Insert the floppy disk holding the tivobin.tar.gz file into your floppy drive, mount it, and copy the file over to the /mnt9/hack directory:
# mkdir /floppy
# mount /dev/fd0 /floppy
# cp /floppy/tivobin.tar.gz /mnt9/hack
While of course you can go ahead and decompress the archive and install the Unix binaries now, let's wait to do so via the TiVo Bash shell itself [Hack #34]. This way, you'll be using real paths, rather than fiddling about with temporary mount points (/mnt9 et al). There is no reason why you couldn't do that from here. However, by postponing it, you have a better shot at figuring out what is going wrong with your Bash prompt if you can't get it to show up.
Go To
You'll finish up [Hack #34] in just a moment. First, you need to clean up and shut down your PC [Hack #32], return TiVo's drives to where they belong, and get to the Bash prompt [Hack #33] over the serial line.
Top
Hack 32 Clean Up and Shut Down
After mounting TiVo's drives in your PC and fiddling with configuration files, you need to carefully clean up and shut down the PC to preserve your changes.
If you've made any changes to TiVo's configuration files, you must carefully unmount the TiVo partitions and shut down the PC to which your drives are connected, in order to make sure everything's saved as it should be. Do not just turn off your machine, or you risk leaving changes uncommitted and—worse still—leaving your TiVo partitions in an unusable state.
Unmount the partitions you mounted before, like so:
# cd /
# umount /mnt4 /mnt7 /mnt9
Of course, you should bother to unmount only the partitions you mounted in the first place; if you did not mount partition 4 at /mnt4 or partition 7 to /mnt7, leave them out of the previous command line.
If you mounted your floppy drive to copy across the Unix utilities [Hack #31], don't forget to unmount that drive too:
# umount /floppy
Notice that the command is umount (pronounced "yoo-mount") not unmount ("un-mount") as one might expect.
Now, you can issue an exit command to log you out of the Linux shell and return you to the Linux login prompt:
# exit
At this point, it's safe to Control-Alt-Delete your PC, watch it reboot, and, at the first sign it is returning to life (beginning to boot up again), turn it off.
Go To
Now you're ready to reinstall your TiVo's drives back into TiVo [Hack #27]. That done, if your goal has been to get the Bash shell over serial connection, carry on to connecting to your TiVo with the serial cable [Hack #33].
Top
Hack 33 Connecting to TiVo Serially
With your TiVo offering a Bash shell prompt over its serial port, let's tap your computer into that flow of bits.
With Bash-over-serial [Hack #30] enabled, your TiVo is spitting bits over its serial port into the ether, just waiting for someone to access its Bash prompt. Your mission, if you choose to accept it, is to get those bits to your computer.
Go on, you've already done the hard bits.
On the back of your TiVo is a port labeled "serial," which is just about, but not quite, like the RS-232 serial ports on the back of a PC. The only real difference is the connector; rather than a standard serial port, TiVo's resembles a headphone jack.
For some of you, TiVo's serial port might already be in use, to connect your TiVo unit to a cable box or satellite receiver. Unfortunately, you can't use the port simultaneously for both purposes. You can enable the prompt when you want to get access, and disable it later, but that can get to be a real hassle. There are other ways in; take a gander at [Hack #49].
First, let's make sure that you have the right cable to wire your TiVo to your computer. You need to get a hold of the serial control cable that shipped with your TiVo; it has a standard RS-232 serial connector on one end and what looks like a headphone plug on the other (see Figure 3-1). You're also going to need a null modem adapter (also shown in Figure 3-1), available at your local computer or electronics store. Lastly, you may also need a gender bender to get the end that attaches to your serial port to be female.
Figure 3-1. TiVo serial control cable and a null modem adapter
If you are contemplating connecting your TiVo to your Mac, then you will also need a serial-to-USB adapter,
because your Mac does not have any serial ports. I recommend the Keyspan "High Speed" USB Adapter (
http://www.keyspan.com/products/usb/USA19W/). Moving forward, I'll assume you are using such an adapter and have the appropriate Macintosh drivers installed.
Now that we have all the hardware we need, let's plug in and get those bits flowing. Plug the headphone-like end of the serial cable into TiVo's serial port. Connect the null modem adapter to the other end, and connect the other end of the null modem adapter to the serial port on the back of your PC. If you are connecting to a Mac, the null modem adapter plugs into your serial-to-USB adapter, which, in turn, plugs into the USB port on your Mac.
And that's it for hardware.
To talk serially to your TiVo and, thereby, the Bash shell, you are going to need the help of a simple terminal
program. Use your favorite. If you don't have a favorite, there are a few popular choices: Windows has SecureCRT ( http://www.vandyke.com) or the inferior, but preinstalled, Hyperterminal; Macs have ZTerm (
http://homepage.mac.com/dalverson/zterm/), which runs under both OS 9 and OS X; and Linux has Minicom ( http://packages.debian.org/stable/comm/minicom.html). Any one of these will do just fine.
TiVo is set up to talk at 9,600 baud and 8N1 (that's 8 data bits, 1 stop bit, and no parity bits) with no flow control.
Now we'll instruct your terminal program to attach to the right port on your computer and speak the same language.