Email timers to Topfield PVR 5100

Version History

v0.2 - 2006-06-18 - version history - download
v0.1 - 2006-06-09 - Initial release - released to public domain - download

Background

With this Python script you can send timers to Topfield 5100PVR (and similar) set-top-box and get back the list of programmed timers by email. I have created this little script purely for my own personal usage and in order to learn Python programming. I have release it here to public domain in hope that someone may find it more or less useful but it is my first real Python application. So beware. Caveat Emptor.

It seems to work ok in my setup with some peculiarities. See the section Known bugs, Limitations and Other Misfeatures for some idea what you might expect if you use this.

Idea to this script comes from really cool application SMSTimer by Petri Niemi. With SMSTimer you can send timers with SMS message but you need a mobile phone attached to Toppy. Also, it does not work with Nokia phones and unfortunately I have no other phones. Another way to remote control your Toppy is to use Toppy-Web but it requires you to open a hole to your firewall and expose the Toppy to cruel world. My email solution requires only that your Toppy, or more accurately Slug or PC it is connected to, can connect periodically to your IMAP email server. You can even program it to check emails once a night when it is uploading latest EPG information anyway. However, my little program is nowhere near enough to finished and polished application. The current version is 0.2 and it seems to work, at least in my environment. I will continue to develop it further but mostly for my own delight. That said, if you do have any suggestions what to do next, check first the To Do section and email me to ike@iki.fi.

Installation

This application is still rather immature so the setup is still bit complicated. Here are instructions how to get it work with Slug and Topfield 5100PVR. Instructions are mainly for Slug usage since that is what I have. However, I created the script with Windows XP so it should work in it too as long as you have some means of transferring files to Toppy.

Requirements

Here are the requirements you need to have before you can use email2toppy.py

Topfield 5100PVR (or any of its sister models) connected to PC or Slug.
Python interpreter. Installing Python for the Slug is very easy, ssh or telnet to its shell and give the command:
ipkg install python
For Windows go to official Python web site to download and install it.
IMAP email account. POP is not supported, at least for now. IMAP servers support retreiving messages based on subject and other data. Email2Toppy.py asks email server to return only messages that have a certain string on the subject line. This way you can use your regular email account to receive Topfield timers but I do recommend having a dedicated email account for Topfield.
Jag's EPG version 2.7 or later. Email2toppy.py sends timer commands using Jag's EPG remote commands. I may support later EPG Uploader command files since Jag's EPG does not give you much feedback how the commands succeeded.
Puppy (or ftp or some other means) to transfer commands to Toppy.

Download

Download email2toppy.py

Setup the configuration file

Before you can use the email2toppy.py, you must set up the correct configuration. The zip file in download section above contains default configuration file but you must set at least [imap] and [smtp] sections. Here is the default configuration file with some explanations what each setting means.

[general]

# password
can have spaces. Emails sento Toppy must contain the value set here

pin=very big secret   
       
[imap]

# user
name for IMAP account

user=imap_user_name   
       
# IMAP
password. Warning! not encrypted anyway

password=xxx   
      
# IMAP server
name

server=imap.server.example    

# this tag must appear in the subject of
the email

tag=[ToppyCmd]   
       
[smtp]

# smtp server
address used to send reply

server=smtp.server.example    

# email address shown in reply

from=your@email.example   
   
# email address where the reply is sent

replyto=answer@address   
    
# subject of the reply
message

subject=Reply From Topfield   

[transfer]

# %(name)s is evaluated to the value of the setting 'name'

# writecmd is the command used to sent the Jag's EPG remote command to
Toppy

writecmd=/opt/bin/puppy -c put "%(localdir)s%(commandfile)s"
"%(toppydir)s%(commandfile)s"

# readcmd is the command used to read the Jag's EPG timerlist

readcmd=/opt/bin/puppy -c get "%(toppydir)s%(returnfile)s"
"%(localdir)s%(returnfile)s"

# after successful read, this command is used to delte the
timerlist 

deletecmd=/opt/bin/puppy -c delete "%(toppydir)s%(returnfile)s"

# commandfile must be Jags_EPG.Command.ini for Jag's EPG commandfile

commandfile=Jags_EPG.Command.ini

# returnfile tells what file to read from Toppy

returnfile=Timer_List.txt

# toppydir must be ProgramFiles\Auto Start. This is where the
commandfile is put. 

# Remeber to add trailing '\'

toppydir=ProgramFiles\Auto Start\

# localdir tells the local directory where the timerlist stored

localdir=/root/

[log]

# loglevel defines how much messages are generated. The bigger the
number less messages are

# written into the log file.

# >= 50 Only CRITICAL messages

# >= 40 above + ERROR messages

# >= 30 above + WARNING messages

# >= 20 above + INFO messages

# >= 10 above + DEBUG messages

loglevel=40  

# logfile is file where email2toppy.py messages are written

logfile=/share/hdd/data/Data/media/Topfield/EmailTimers/email2toppy-slug.log

# if append=false exists old log file is deleted 

append=true

Once the configuration file is set, you need to arrange email2toppy.py to be run every now and then. In Slug, you need to add one line to /etc/crontab file. On Windows use Scheduled Tasks in the control panel. Email2toppy.py takes on command line argument telling its configuration file. An example crontab entry to read emails every 15 minutes could be like this:

5,20,35,50 * * * * root /usr/bin/python /root/email2toppy.py /root/email2toppy.cfg

Since puppy needs to be run as root also email2toppy.py needs to be run with root rights.
Remember also to turn on remote commands in Jag's EPG setup (item 44). Jag's EPG should read remote commands more often that the script is run. If the script is run again before Jag's EPG has processed the remote command, new commands overwrite old ones.

Email structure

Here is an example email containing a timer command.

Subject: [ToppyCmd]

PIN=very big secret

command=AddTimer

channel=0001

date=2006-06-11

start=11:10

duration=01:11

type=Rec

repeat=OT

name=my recording

log=yes

Subject line of the email must contain the tag specified in the IMAP section of the configuration file.
Each parameter for timer must be in the body of the email and on its own line. The order of lines is not important except if same parameter is defined more than once, the latest is used. Parameters are send to Jag's EPG exactly as they are received without any checking. Check its manual for more details.

PIN=very big secret. This is the password and it must be same as defined in the configuration file. This provides some low level security and prevents spammers to fill up your Topfield.
command=AddTimer. So far, only AddTimer is supported. I have plans to include more.
channel=0001 is the channel to be recorded. It must be four characters long and contain leading zeros.
date=2006-06-11 is the recording date in format: yyyy-mm-dd
start=11:10 is the start time for the recording in 24 hour clock.
duration=00:11 is the length of the recording in hours:minutes format.
type=Rec This can be either 'Rec' for recording or '-P-'
repeat=OT Possible values: 'OT' = one time, 'ED' = every day, 'WE' = week ends and 'WD' = week days
name=my recording is a name for the recording.
log=yes. If the log parameter exists and its value is yes, the log that was created while running the email2toppy.py is sent back to reply address of the email requesting it. The log is also sent to address specified in the configuration file.

If you only need to check timers and not create new ones, send a message with PIN only.

Known Bugs, Limitations and Other Misfeatures

This is not complete application and it has its own peculiarities. I am working on these but I do this on my freetime and there is no quarantee when they are fixed.

Email2toppy.py is a stateless application. This means that when it runs again it has no recollection what happened last time. That's why it will always check if there is timerlist available in Toppy even if a command to create it has never been issued. Stateless applications are bit easiet to create but have other problems like seen here.
Timer commands are tried to transfer to Toppy only once. If it fails, the timer is lost. Since IMAP server has already returned the email once it no longer thinks it is a new message. This means email2toppy.py will see all emails exactly once and if transfering commands fail for some reason, like the Toppy was not powered on, email is lost and the timer command is never tried again.
Replies are send address given in configuration file, only. Since email2toppy.py forgets everything that happened last time, it does not know where the emails came from.
There can be only one timer per email but you can send as many emails as you wish.
email2toppy.py must be run as root if used with Puppy since Puppy needs root rights.
Comments in configuration file must be on their own lines. Don't put them to same line with items.

Todo

Here is a list of things I am considering to do after fixing the problems mentioned in the previous section. These are in no particular order and if you think something is more important than something else, just let me know. I don't promise anything but you never know.

POP3 support. Using POP3 bit awkward since it doesn't have searching capabilites but it is so ubiquitous and all ISPs support it. Perhaps I can do it by assuming all POP3 emails are directed to Toppy.
More commands: deleting timers, at least
Also some sanity check to parameters.