stbt-run: Let a test script access its real path

If a test script is executed with `python` (without stbt):
- the script's directory is added to the beginning of `sys.path`, therefore
  it's possible to import a module from the script's directory;
- the script's path is accessible through the `__file__` special variable.

If a test script is executed with `stbt run`:
- stbt-run's directory is iserted to `sys.path`, therefore it's not
  possible to import a module from the script's directory;
- `__file__` variable contains the path of `stbt-run`.

To let a test script access its real path just like it was executed without
stb-tester, add the script's directory to `sys.path`, and override `__file__`
variable to contain the test script's path.
stbt.press: Cleanup: Remove `return` statement that always returns `None`

NullRemote.press, VideoTestSrcControl.press, VirtualRemote.press,
LircRemote.press, TCPLircRemote.press, and IRNetBoxRemote.press all
return `None` (implicitly; none of them have a `return` statement).

This cleanup will make the next commit easier.
stbt.press: Don't draw keypress on output video if `press` failed

If `_control.press` raises an exception (see the next commit), which
might be caught and handled by the caller of `stbt.press`, we don't want
to draw the key name on the output video because the keypress wasn't
actually sent to the device under test.
stbt.press: Raise exception when irNetBox returns error

I have no idea if our irNetBox is ever replying with NACKs, but if it
did, our scripts would have silently ignored the NACK and proceeded.
With this change, we can be more certain that ignored keypresses are
genuine faults in the system under test, and not failures of the test
infrastructure's infrared emission.

We may need to do a similar fix for the LIRC-based control. The existing
LIRC control implementation will raise an exception for errors at the
socket level, but it doesn't wait for the response from LIRC so it might
ignore application-level errors.

test_that_press_fails_on_irnetbox_error is a new test that passes
correctly with the existing irnetbox.py implementation.

test_that_press_fails_on_irnetbox_nack is a new test that would
fail with the existing irnetbox.py implementation, but this commit
also fixes irnetbox.py to raise an exception in that case.
stbt.press: Wait for irNetBox "Asynchronous IR Output Complete" message

This eliminates one source of latency variability when using a script
like this to measure performance of the system under test:

    press("channel_up")
    start = time.time()
    wait_for_match("new channel.png")
    end = time.time()
    print "duration: %f" % (end - start)

This still has a low precision, limited to how long it takes
`wait_for_match` to process a single frame†. But at least it guarantees
that the time between the system-under-test receiving the infrared
signal and our `start = time()` call, is at most the time it takes for
the confirmation message to travel from the irNetBox to our PC. Since
the irNetBox and the PC are probably on the same local network this
should be minimal (compared to the time it takes a set-top box to change
channels, for example); at least it's more predictable than that same
network delay *plus* the irNetBox's delay in sending the infrared
signal.

This will hold open a TCP connection to the irNetBox until the
asynchronous completion message is received; other clients won't be able
to use the irNetBox during that time because the irNetBox only accepts a
single TCP connection at a time. If this is a problem, use the
`irnetbox-proxy` script in this same directory.

Note that I removed the `sleep(0.5)` from `stbt.IRNetBoxRemote.press`.
This isn't necessary now that we wait for the irNetBox to have sent the
infrared signal before sending the next request. I've tested against my
YouView set-top box, with a series of `stbt.press` calls one after the
other (sending 1 0 3 to change channel, or 2 2 2 to enter the letter "C"
in a text box) and the set-top box registers all keypresses correctly.

† There is work in progress to improve performance measurements, by
processing *every* frame (instead of dropping the frames we can't
process in real time) and by using the frame timestamps from the video
stream instead of wall time. See
https://github.com/drothlis/stb-tester/pull/31
irnetbox-proxy: Preserve endianness in response message forwarded to client

The "sequence number" field of the following three messages is defined
by the spec† to be big endian:

1. Asynchronous IR Signal Output request (message 48 client->irNetBox)
2. Asynchronous IR Signal Output response (message 48 irNetBox->client)
3. Asynchronous IR Output Complete (message 49 irNetBox->client)

(#2 is sent synchronously, as an ack or nack, as soon as #1 is received.

But there is a bug in the irNetBox device, confirmed by Chris Dodge at
RedRat, such that the sequence number in #2 is actually little endian.
`irnetbox-proxy` used the correct (little endian) format for decoding
the received response, but then re-encoded it incorrectly when sending
the response to the client. The proxy must behave just like a real
irNetBox, so that the same client code can use (or not use) the proxy,
so the proxy must implement the same bugs as the irNetBox.

† http://www.redrat.co.uk/products/IRNetBox_Comms-V3.0.pdf

This bug was found by the test test_irnetbox_proxy, which started
failing after commit 92164a9c.
irnetbox.py: Raise exception on unexpected response types

I don't believe this is happening, but if it did happen it would be very
confusing to behave in any way other than raising an Exception.
stbt.press raises exception if irNetBox doesn't reply

10 seconds should be plenty of time for the irNetBox to send the
infrared signal and return the "Asynchronous IR Output Complete"
message. Since `stbt.press` always waits for the response from the
irNetBox before returning, there won't be any queued-up signal emissions
to delay the next `stbt.press` call.

I have seen some isolated cases where `stbt run` has hung indefinitely
inside the call to `socket.recv` from irnetbox.py's `_read_responses`. I
haven't investigated what led to those situations, but at least with
this commit if it happens again the test will fail (allowing other tests
to run) instead of hanging forever.
irnetbox.py, irnetbox-proxy: Update comment re. endianness bug

Chris Dodge of RedRat confirmed that the endianness of "sequence number"
field of the "Asynchronous IR Signal Output" response message is a bug.
It can never be fixed, to keep compatibility with existing software.
He will update the documentation.

The sequence number is big-endian in the *request* message, and in the
"Asynchronous IR Output Complete" message (which is a message sent
asynchronously). The endianness bug is in the synchronous response to
the request message.
irnetbox.py: "Asynchronous IR Output Complete" payload contains 4 bytes

Section 6.1.3 of the spec† says "the only data it contains is the
message sequence number of the IR Output message as a ushort" but in
practice the irNetBox sends 4 bytes, not 2, of data in this message.
The last 2 bytes are both "0".

This fixes the error "unpack requires a string argument of length 2"
introduced in 92164a9c. Before 92164a9c we ignored the contents of
this message so this bug didn't manifest.

† http://www.redrat.co.uk/products/IRNetBox_Comms-V3.0.pdf
Merge branch 'press-error-handling'

* press-error-handling:
  irnetbox.py: "Asynchronous IR Output Complete" payload contains 4 bytes
  irnetbox.py, irnetbox-proxy: Update comment re. endianness bug
  stbt.press raises exception if irNetBox doesn't reply
  irnetbox.py: Raise exception on unexpected response types
  irnetbox-proxy: Preserve endianness in response message forwarded to client
  stbt.press: Wait for irNetBox "Asynchronous IR Output Complete" message
  stbt.press: Raise exception when irNetBox returns error
  stbt.press: Don't draw keypress on output video if `press` failed
  stbt.press: Cleanup: Remove `return` statement that always returns `None`
`make install` & Fedora rpm: Install irnetbox-proxy to $prefix/bin

This tool is essential if you're using the RedRat irNetBox (a
network-controlled infrared emitter) with multiple clients, because the
irNetBox only accepts a single TCP connection at a time. It won't hurt
to install it for users who don't need or care about it. It doesn't have
any dependencies outside of the python standard library.
Add a public `stbt.draw_text` api

Based on the previously internal Display.draw_text, but now made
publicly available.
The draw_text method is now imported for use with stbt-run.
A unit test has also been added to confirm that the text is drawn
correctly.
test_draw_text: Disable on Mac OS X

Because the GStreamer elements vp8enc and webmmux don't work on OS X
so this test would always fail.
test_draw_text: Cleanup: Wrap long lines

And reorder arguments for consistency with the other tests.
test_draw_text: Cleanup: Use `--save-video` instead of explicit sink pipeline

The effect is the same; this is just simpler.
test_draw_text: Don't continue with test if early steps fail

If the first `stbt-run` fails, the second `stbt-run` is bound to fail
too, so the test would correctly report a failure both with and without
this commit. However the log output from the second `stbt-run` would be
confusing; this way you only see the relevant error from the first
`stbt-run`.
test_draw_text: Use "live" videotestsrc

videotestsrc generates frames as fast as it can, which on a typical
system is much faster than 24 frames per second. The `duration_secs`
parameter of `stbt.draw_frames` acts on the timestamps from the video
stream, not the wall-clock time, so using `duration_secs=3` resulted
in the text being displayed only for a very brief period of time (too
fast to even see it).

Though the previous implementation did work, it might give the
impression that `duration_secs` takes a number in milliseconds.

There are two ways to slow down the videotestsrc to real time: Set the
sink to `sync=true` (we use `sync=false`; see `sink_pipeline` in
tests/stbt.conf), or set videotestsrc's `is-live` property. `sync=true`
causes other problems (due to the delays and jitter introduced by the
image processing) so we use `videotestsrc is-live=true`.
stbt-run: Don't bring `draw_text` into script's namespace

We want to encourage users to explicitly `import stbt` in their scripts,
because it's more pythonic and less "magical", and it allows running
pylint over the scripts. Other recent new functions like `frames` and
`get_config` weren't added to this list for the same reason.

This was added in b6a6c015, but was never part of a tagged release so we
can still remove it from the public API. We'll eventually deprecate
these, and later remove this code altogether, but for now it remains for
compatibility with existing user scripts.
Document `stbt.draw_text` in the official API doc

Note that the change to README.rst is the result of running `make doc`
after the change to api-doc.sh.

I edited the docstring so that it displayed nicely in the generated
manpage (the docstrings and README are in reStructuredText format, so
you need a double linebreak in the source to get a new paragraph in the
output).