Motion Plugin API

This is the Application Programming Interface for plugins used in Motion 4+

This topic is not complete at all.

Introduction

Conceptually, there is a virtual wall between the Plugin and the motion mainline code (and also between separate Plugins!). This means that if any communication is requred between the two, there must be some commonly-accessible entity to provide a link between them.

Motion is already designed around a "context" structure. There is a main "context" (established by the startup code), and a separate "context" for each camera thread. Therefore, it makes sense (to me) to use this "motion context" as the means to provide the linkage between motion mainline code and the Plugin. In order to accomplish this, when the Plugin is first initiated it needs to be given a pointer to the context structure which it will use. Conversely, anything which the Plugin needs to know from the motion mainline code must be able to be obtained from the context.

In the sections below, it is assumed this basic approach is being used. This is not meant to be a "mandate", but only pointing out that if we decide to adopt a somewhat different approach, much of the following may need to be changed simultaneously. -- BillBrack - 04 Oct 2005

Location of Plugins

Some "Standard Plugins" are included within the Motion distribution. The source files for these plugins are located in the subdirectory "plugins". When you configure, compile and install Motion, by default the results will be placed in (standard) subdirectories under /usr/local. The standard subdirectory for the plugins will be /usr/local/lib/motion.

If you want to install the Motion files in a different location, you can use parameters to the configure program to specify that, e.g. --prefix = {path}. In this case, plugins will be installed in {prefix}/lib/motion.

The specfile for RedHat/Fedora RPM will place plugins in /usr/lib/motion

A plugin will be used whenever it is specified within the Motion configuration file. The configuration parameter for the plugin includes the location where the plugin can be found. If there is no pathname included in the location, the plugin will be loaded from the directory which was specified during configuration. If an absolute pathname is supplied (absolute path meaning starting with '/') that full pathname will be used. If a relative path is given (the pathname does not start with '/') the plugins are loaded from a directory relative to the directory given by configure. Motion will not try and load plugins from other places (i.e. it will not try and load from the standard system shared libary path, as this can cause unpredictable results with multiple installations of Motion - e.g. snap releases from sources and an older RPM).

Note: It has not yet been decided whether to allow the plugin to be specified with just a name and no extension (i.e. v4l_plugin instead of the actual full filename v4l_plugin.so), in which case Motion would automatically add the ".so". If an extension is supplied with the parameter, that would be used (with nothing added) in any event.

Configuration Options

Plugin specific options

Common options

Initialization

Video Source

• The video interface to the Motion core is YUV420P.

Note several people have requested RGB to enhance video quality. So maybe we should define the API so that we can pipe an RGB24 stream through Motion to an output plugin. The standard plugins that comes with Motion should NOT implement this.

Video Stream Feed

• The video stream feed format is YUV420P

Video Movie Files

• The video frame format to the video movie plugins is YUV420P

Events

• Todays event interface only handles forking a shell. We need a more generic interface.

Tracking

• We need a tracking API.

Motion detection

• If motion detection plugins will be enabled they will need at least a function call which:
  • Takes every frame as input
  • Returns a bitmask of moved pixels
  • Returns the number of moved pixels

Common Functions in Motion Available to Plugins

In order to more fully understand how plugins could be implemented, some experimental code was written to "try it out". That code is certainly not a "de-facto standard", but can provide some useful information. Here are the motion functions which were found to be needed in order to convert the existing v4l and netcam video input modules into plugins:

• motion_log
• mymalloc
• myrealloc
• rotate_map

The actual implementation of this approach is to assure the addresses of the required routines are present within the context structure. In order to keep a reasonably clean configuration file layout, a new structure was defined to contain pointers to all of the functions which could be called by plugin. This new structure was added within the main context structure, and the applicable addresses were "filled in" during motion startup (when a new camera thread structure is created, the data is simply copied from the main context).

Additionally it was found to be convenient to provide access to four motion "global variables" by providing pointers to them within the motion context structure:

• debug_level (for controlling debug printing)
• threads_running (for changing whenever a plugin starts or stops an additional thread)
• global_lock (for controlling multi-thread access to threads_running)
• tls_key_threadnr (for setting whenever a plugin starts an additional thread)

-- BillBrack - 04 Oct 2005

Errors / Warning

Messages to Console

Setup Mode

Memory allocation

Many more to come

Termination

• How to terminate the plugin when Motion stops or restarts.

-- KennethLavrsen - 02 Oct 2005