Controlling Motion via XML-RPC

Motion version 3.1.12 has got a new exciting feature which is the ability to control Motion while it is running. Motion now has a built in http server called xmlrpc-httpd. This listens on a port specified by the new 'control_port' config file option. The control protocol is called xml-rpc. With Motion there is a small program that can be built and which can be used to control all the new control features of Motion.

Installing XMLRPC-C

First, the xmlrpc stuff we need to install is located here: http://xmlrpc-c.sourceforge.net/downloading.php

Motion has been mainly tested wuth XMLRPC-C version is 0.9.10.

Recently the XML-RPC-C project finally got a new owner after having been abandoned for years. Recently version 1.0 and 1.1 has been released.

Even though these have not been tested with Motion, it is assumed that they work. Please report on the Mailing List if you have success or failure with xmlrpc-c 1.0 or 1.1.

We have not prioritized testing the new xmlrpc versions because the next major Motion releases (3.2.X) will replace the xmlrpc interface by a much simpler and newbie friendly http based remote control interface.

At Sourceforge you find the latest files.

http://sourceforge.net/project/showfiles.php?group_id=16847

XMLRPC-C from RPMs

If you use a distribution using RPM like Red Hat and many other all you need is to download and installed RPMs.

The two RPMs you need are here

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10-1.i386.rpm?download

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-devel-0.9.10-1.i386.rpm?download

Additionally the two RPMs above need w3c-libwww installed. The RPMs for w3c-libwww comes with RedHat but are not installed per default.

There are 2 RPMs: w3c-libwww-5.4.0-4.i386.rpm and w3c-libwww-devel-5.4.0-4.i386.rpm.

Previous versions of RedHat also have the 3 RPMs on the CDs but in earlier versions. They are probably also OK. The version should not be very critical.

XMLRPC-C from Source Files

For those that do not use distribution based on RPM, the source tar.gz is here

http://prdownloads.sourceforge.net/xmlrpc-c/xmlrpc-c-0.9.10.tar.gz?download

There is however a problem with the package above. It will not compile with gcc compiler version 3.1 and later. Kenneth Lavrsen has patched up the sources with patches found on the Sourceforge xmlrpc-c patch tracker. This patched package has been placed in the Motion Sourceforge Files area under "Related Projects" It is recommended that you download and install this instead.

http://prdownloads.sourceforge.net/motion/xmlrpc-c-0.9.10-kjl3.tar.gz?download

The Libwww can be downloaded from here

http://www.w3c.org/Library/

Follow the installation instructions from the websites of the XMLRPC-C and Libwww libraries.

After installation of xmlrpc-c you need to re-install motion going through all the steps ./configure, make and make install

Besides building motion with XML-RPC support it also build a small application called motion-control which is copied to /usr/local/bin.

motion-control

The motion-control program is easy to use. Run it without any parameters and it displays the help.

The commands are shown below. Note the following. If you choose to set configuration parameters for thread 0, all threads will be changed. The individual camera threads are numbered 1,2,3....

Configuration parameters are simply named the same as in the motion.conf file. Parameters that are global and not set in a thread config file can only be read from thread 0. Trying to read a global only value from a camera thread will give no value back (same reply as if you ask for a non-existing value). Once you set a value for a thread other than 0 you can read it again from that thread.

The detection pause feature disables the saving of pictures, snapshots etc but does not stop the webcam server. The motion-control action and detection features do not work globally. I.e. 'motion-control action snapshot 0' does not generate snapshots for all cameras. One exception is 'motion-control action quit' which simply makes motion stop running (all processes quit).

The conf write feature overwrites both the motion.conf and the thread config files in a shorter format with less comments. If you like to keep your config files make sure to save copies of them before you run this control command. If you have changed parameters using the conf set command it is the changed values that get saved to the config files. Global (thread 0) parameters to motion.conf and individual thread values to the thread config files. Files are saved at the same location as they were read from overwriting the existing files.

Command	Description
motion-control info	Brief information about motion version and number of threads running.
motion-control conf list	List all configuration parameters/options with their type and a short help text. Not all parameters have a help text yet.
motion-control conf get [threadnr] [parameter]	Get the value of a configuration parameter for a given thread. Thread 0 means the global or default value. If a parameter is not defined for a given thread then this value will be used instead as a default value.
motion-control conf set [threadnr] [parameter] [value]	Set the value of a configuration parameter for a given thread. Thread 0 means the global or default value. If a parameter is not defined for a given thread then this value will be used instead as a default value.
motion-control conf write	Write all motion config files. Both the motion.conf and all thread config files. Note that this overwrites the original config files. All old comments are lost.
motion-control action makemovie [threadnr]	Make an mpeg movie on a given thread.
motion-control action snapshot [threadnr]	Save a snapshot picture of a given thread.
motion-control action quit	Make motion quit completely. Useful for stopping motion when it runs as a daemon.
motion-control detection pause [threadnr]	Disables the saving of pictures, snapshots etc for a given thread but does not stop the webcam server.
motion-control detection resume [threadnr]	Resume the saving of pictures, snapshots etc for a given thread.
motion-control track auto [threadnr] [value]	Enable auto tracking. 0=disabled, 1=enabled. Auto tracking is always disabled when motion starts. Manual tracking is still possible when auto tracking is turned off.
motion-control track set [threadnr] [value_x] [value_y]	Turn camera to a specific position. Values x and y are in degrees from center. Up and right are positive numbers, Down and left are negative numbers. If you want to move the camera in one dimension and leave the other unchanged set the value for the one to be unchanged to an out of range value such a 1000. For a Logitech Quickcam Sphere/Orbit the range for pan (x) is -69 to 69 degrees and the range for tilt is -30 to 24 degrees.
motion-control track pan [threadnr] [value]	Turn camera to a position in degrees relative to current position. Value is in degrees and positive values means turn right, negative means turn left.. This is a good command for small step sizes like 10-20 degrees. If value is out of range camera will move as far as it can.
motion-control track tilt [threadnr] [value]	Tilt camera to a position in degrees relative to current position. Value is in degrees and positive values means tilt up, negative means tilt down. This is a good command for small step sizes like 5-10 degrees. If value is out of range camera will move as far as it can.

The conf set [threadnr] [parameter] [value] feature is very smart for trying tuning settings and for changing the user defined on screen display.

By setting the option control_localhost to "on" Motion can only be controlled via xml-rpc from the same machine on which Motion is running. If you need more refined access control use your firewall such as ipchains or iptables for it.

As mentioned above there is a config file option called control_port. You should normally set this to 8080. If you need to set it to another port you will also need to change the port number defined in the motion-control source file. Look for the line

#define MOTION_URL "http://localhost:8080".

Same line can be changed to a real URL so that you can control Motion from a remote machine.

Security Warning! Note that this feature also means you have to pay attention to the following.

• Anyone with access to the remote control port (xmlrpc) can alter the values of any options and save files anywhere on your server with the same priviledges as the user running Motion. They can execute any command on your computer with the same priviledges as the user running Motion. You do not protect anything by protecting the motion-control program. Anyone can compile and run their own copy of motion-control and access your control port if you have not either limited access to localhost or limited access using firewalls in the server. You should always have a router between a machine running Motion with remote control enabled and the Internet and make sure the Motion control port is not accessible from the outside.
• If you limit control port to localhost you still need to take care of any user logging into the server with any kind of terminal session or any kind of access to alter PHP programs and CGI scripts. It is easy to write a PHP script or perl script that sends XMLRPC commands.
• It is a good idea to run Motion as a harmless user. Not as root!!

-- KennethLavrsen - 29 Jan 2005