Sunday, August 11, 2013

Control Your Projector From Your Computer With Pyjector

I recently bought my first projector, a BenQ w1070. It has an RS-232c port, a type of serial connector.  This serial port allows you to send commands to the projector, controlling everything from brightness to the current source.  Of course, you have to do some work to do anything useful...

The first step is to get a suitable cable. You will likely end up with something like this, a USB to serial adapter. It uses a Prolific chipset, which has a driver included in the Linux kernel - which will save you the headache of trying to get your adapter working, if you are on Linux.  That adapter has a female connector, and most projectors seem to also have female connectors, so you will also need a null modem adapter (a few bucks on Amazon or locally).  If both connectors are the same gender, be sure to get the right adapter - you most likely want a null modem adapter, not just a "gender changer".  You can check the pin-out for your specific device to be sure.

After plugging in the serial adapter, be sure that it is correctly detected by your OS (in my case, Linux). A quick search through the syslog with dmesg | grep Prolific  will show if it was detected. You can then check that you have proper communication between your PC and the projector by using a program called minicom. On my Debian system, I used aptitude install minicom to grab this program. There's a decent tutorial here that will guide you through setting up minicom. I'd use it only to verify you can communicate with your projector - it's not the most convenient program to use.

Now comes the good part, using Python to tell your projector what to do. I created a library called Pyjector to make this easier. You can install it with pip install pyjector. It has two points of interest - the library itself, and a script shipped with it called pyjector_controller.

The pyjector_controller script should be used if you plan to control your projector from the command line. It accepts 4 arguments - device_id, port, command, and action. The device id is used to look up what commands your projector supports, and how to send them. At the moment, "benq" is the only supported device id, which should work for all BenQ models. The "port" is the port your projector is connected to - if you previously used minicom, you should already have this information. The command is... the command you want to run, such as "power" or "mute". The action is a verb like "on" or "off".
Putting it all together, here's a command to turn on the projector:
./pyjector_controller benq "/dev/ttyUSB0" power on

You can also use the Pyjector library in your own Python scripts. Just instantiate it like so:
pyjector = Pyjector(port=port, device_id=device_id)
Pyjector will read the config for the device you specify, and automatically create command methods on itself, so now you can do pyjector.command(action). In practice, that will look like:
You can check what commands are supported with:
and you can check the available actions for a specific command with:
If Pyjector doesn't have the functionality you need, you can also access the underlying PySerial instance:
pyjector.serial.write('some other command here')
On the subject of PySerial, defaults for the device you specify are used to connect to your projector, such as baud rate, parity bits, etc. Your projector might be slightly different, so you can override the defaults when instantiating the Pyjector object. Simply use keyword arguments to provide any options to PySerial (you can see the PySerial docs for details). For example, if your projector uses 115200 baud rate instead of whatever the config uses, you can do:
pyjector = Pyjector(port=port, device_id=device_id, baud_rate=115200)
This should allow you to create scripts to control your projector as you wish. If you have a projector that doesn't have a config in Pyjector, the format is simple enough that you can create your own. There are some instructions in the README for doing so. Please make a pull request if you do, so it can be used by others. Enjoy.