Raspberry Pi and the HD PVR.. streaming and recording, Part III

It's been a little under 2 months since I posted last, and I've been busy working on a new build of the code, with a web interface, and other such useful things. I kept meaning to post about it, but kept going back to add yet another little tweak.

So, finally, it's time to release the latest version! read on to find out how to use it..



I've setup a github repository to handle the code, although you'll still need to compile it up yourself.

The repository is at :
http://github.com/BarDweller/HD-PiVR

You'll still want to follow the instructions at http://dwellertech.blogspot.co.uk/2013/05/raspberry-pi-and-hd-pvr-streaming-and.html to compile it (swap hdpvr.c for hd-pivr.c)

Once built, you can run it as before, it will write recordings to the directory you are in when you run it.

There are now two interfaces, the original simple Http Get interface...
  start - http://ip.of.pi;1101/startrec
  stop - http://ip.of.pi:1101/stoprec
  status - http://ip.of.pi:1101/status
  video - http://ip.of.pi:1101/video (open in vlc)

...and the new Http Post interface, that lets you request status/start/stop, but also, add scheduled events =) It includes the worlds simplest http server, I wouldn't go letting this thing be internet facing, but it's good enough to let the app host its own web user interface.

The Post requests should all be made to http://ip.of.pi:1101/action with the post data carrying the arguments saying the type of request, and any argument payloads.

The simplest Post request is a status request, simply send the argument 'action=status' to receive the same response as you'd get back from the http://ip.of.pi:1101/status request. Not all that useful, it would be more handy if it returned JSON ;p instead, so try sending argument 'action=jstatus' and shiny json responses are yours.

Start and Stop have Post request versions too.. just send 'action=startrec' or 'action=stoprec' to start and stop recording respectively.

Which leads us to the new event engine, which allows you to schedule a start, or a stop for the future. They also allow you to schedule messages to be output as handy test events, and will (almost but not quite yet) allow you to schedule execution of a script with specified arguments, which I hope to use for channel change in the not too distant future.

But first, a few basics about events...

Every event has 2 id's, one owned by engine 'intId' and one owned by the interface 'extId', when you add events, you can specify these, which you'll need if you want to remove the event later. If you omit the intId when creating an event, the engine will assign one for you.

The idea is to schedule a channel change, then a start recording, then a stop recording.. if they share the same IntId, they can be deleted as a group later. The start event will carry the filename to use as part of its arguments. If you set a recording to overlap (note this really only makes sense if the shows are on the same channel) then the data will be written to both files during the overlap. Bear in mind that writing to two files will use more resources than writing to a single file. I've successfully tested writing to two files over a network share though, so I'd be interested to hear how you get on =)

Ok, so here's the Post api to use with events =)

  action=addevent        - requests adding event
  type=(0,1,2,3)           - 0=echo, 1=startrec, 2=stoprec, 3=channelchange
  time=2 Jan 2010 12:45:20     - the time the event should trigger, it MUST be in this format.
  intId=1234567890     - intId to use, if this parm is omitted, one is assigned for you.
  extId=my.ext.id         - extId to use, set this to something you will use to identify this event later.
  data=message            - valid for type=0, and type=3, text to be output, or used as args to script.
  filename=myrec.ts     - valid for type=1, the filename to record into.
  showid=tt01234567   - additional data for recording, can be left empty if not used.

Adding an event in the past will mean it will trigger immediately. When you add an event, the response is in JSON format, and will include the intId of the added event, and the updated state of the event list. The date parser really is very very daft, so keep your dates exactly in the format expected. Expect 404 responses with error messages if you leave out fields that are required.

Also remember all times are in Pi time. This most likely means if your Pi is running UTC clock, that you'll need to convert times to that clock before adding the events.. check what time your Pi thinks it is by using the date command at the command line.

  action=removeevent   - requests removal of an event
  intId=1234567890      - the intId of the event to remove. 
  extId=my.ext.id          - the extId of the event to remove, if omitted, only intId is matched.

Removing an event will respond with the updated list in JSON format.

  action=listevents         - requests JSON content of current event list.

The current list is returned.. handy for populating tables etc.

  action=startrec            - requests start recording immediately
  intId=1234567890      - if omitted, the fixed id UI.Int.Id is used.
  extId=my.ext.id          - if omitted, the fixed if UI.Ext.Id is used.

All recordings have associated intId/extId's, so any clashes with scheduled events can be managed.. even if the recorder is already recording, sending startrec with a different intId/extId pair will cause a parallel recording to be made.

  action=stoprec           - requests stop recording immediately
  intId=1234567890      - if omitted, the fixed id UI.Int.Id is used.
  extId=my.ext.id          - if omitted, the fixed if UI.Ext.Id is used.

Similar to action=startrec, this can be used to terminate a recording already in progress. This action has one last trick though, if you send an empty string as the value for intId and extId, ALL recordings in progress will be terminated.

And that's pretty much it for the API at the moment ;p

By now, if you're still reading you're either already off reading up on DOJO/JQuery etc to build an awesome web page to control all of this.. or slightly bemused and hoping I've already done that for you =)

Good news, I've included 2 fairly simple interfaces to let you experiment & schedule events =)

The extremely simple webserver built into the hd-pvr command will serve any content in the directory you are in when you run the command, under the url http://ip.of.pi:1101/web/

Eg, if you have the file readme.txt in the current directory when you run hd-pivr, http://ip.of.pi:1101/web/readme.txt will serve the page to the browser.

In the repository, there are 4 html files.
  ui.html        - a simple HTTP form based ui, more useful for testing than actual usage. 
  video.html   - used by ui.html to embed the VLC player in a browser.
  dojo.html    - the simplest little ui I could come up with
  status.html  - used by dojo.html to display Pi time to you, recording status, and no of connections

Access these as http://ip.of.pi:1101/web/ui.html or http://ip.of.pi:1101/web/dojo.html

If you come up with a better UI, just let me know =) I'm happy to include them, my javascript skills are rusty at best ;p

I'm still working on the html/javascript side of stuff, and still plan to get the channel change script running.. and have a simple 'add recording' option that combines channelchange, start & stop creation into one action.. but I figured it was worth getting this version out sooner =) especially since it appears there are actually people using it now!