Motion Plugin Requirements

This topic describes the basic requirements for the Motion plugin interface

This topic is not finished yet. It is work in progress. And in this phase it is a proposal!

Purpose

The plugin interface is being introduced in the Motion project to

• Enable more people to contribute with new features
• Enable people to create and share features that have a narrow scope which would not have been accepted as a feature in the current Motion project
• Enable people to make features that may be incompatible with other features.
• Ability to run a more lean Motion program only using the features or interfaces you actually use
• Provide a clean and flexible program structure which can be dynamically configured (and re-configured) through the configuration file

Scope

The plugin interface is made to enhance the interfaces of Motion. The Motion core will still contain code that:

• Reads and writes configuration file
• Does all the Motion detection
• Does all the filtering that ensures what is detected and what is not.
• Provides the http based user interface
• Handles all the events
• Saving jpeg files.
• Provide the video frames for streaming and movies

Plugins will handle.

• Video input (v4l, netcams, files, mpeg)
• Processing of video input before Motion detection.
• Movie output encoding and making movie files.
• Stream output encoding
• Enhanced events (not defined what this actually means)
• GUI

Configuration

Config file

• Plugins must read its config parameters from the motion.conf file. From Motion 4.0 the config file will contain parameters both for the global context and for each thread.
• Configuration files will be in a format which is easy to read and edit by humans without any additional tools.

Parameter naming convention

• Parameters that belong to a specific plugin will be prefixed with the name of the plugin followed by an underscore. I am still in doubt if this is the best way but I have to propose something as a starting point. Example

v4l_input_device /dev/video0

• Option names are always in lower case and with underscore "_" seperating the words. Option names must be descriptive and the syntax as intuitive and newbie friendly as possible.

Common names

• Both Motion core and plugins have access to the common option names.

Do we want to give these a prefix?

Perhaps utilise (internally) a dictionary to contain the current configuration

PerJonsson earlier made a suggestion that a dictionary could be used for configuration. If I understand his suggestion correctly, this means:

• The current internal structure for motion configuration parameters is a structure definition which contains an element for every possible configuration parameter.
• With plugins, there will be a need for configuration parameters which don't currently exist, and so are not present in the structure
• One method to allow for this is to create a "dictionary", at runtime, which contains all of the current parameters (i.e. all the parameters present in the configuration file opened at runtime). Then, whenever code (either in the mainline motion routines, or in the plugin) wants to query (or set) a value in a configuration parameter, rather than look into the context file, it "looks up" the parameter in the dictionary.

API

• The plugin API is described in MotionPluginAPI.
• The Motion API must have a revision number which the plugin and Motion can read and act upon for backwards compatibility.

Plugin building and loading

• Motion must be able to load a plugin without the need to recompile Motion and/or plugin.
• Plugin interface must be well documented and simple so that people with little programming experience can modify a plugin to their need.
• You must be able to build a plugin from Source without having the Motion sources - except for a well defined Motion API header file. This requirement ensures that a plugin is not built for a specific Motion version and that it stays within the defined API. If the API is not adequate - it should be extended and improved.
• Plugins are build as shared libraries and loaded from options in motion.conf.
• Plugin design must be made so that plugins can be built and made with the standard libraries you find in normal distributions. Plugins themselves are allowed to use any exotic library to do their function but the plugin interface itself shall not require any special libraries.

Standard Plugins

Motion ships with a set of standard plugins.

• v4l
• v4l2 (can/should be merged with v4l if possible)
• netcam
• ffmpeg

User Plugins

• The Motion Twiki must have a plugin area where anyone has the right to upload any plugin as long it does not contain hostile code such as vira, trojans, backdoors etc.
• User Plugins TWiki area shall be constructed so that people can make bug reports, discuss the plugin code, appraise the code and upload patches. A construction similar to the one used for Twiki plugins at http://TWiki.org is the starting point for the design.

-- KennethLavrsen - 02 Oct 2005

---

About "The Motion core will still contain code that does all the Motion detection": I think an api to allow motion detection plugins could be considered as well. I develop motion algorithms (soon you'll be able to test them "free as in speech") and I think that if you have 2 cameras in 2 different rooms you could benefit from 2 different algorithms. I think it will not be difficult to define an API for motion detection plugins. A simple solution could be to just a function that gets frames and returns a bitmask containing moving pixels and a pixel count. I would like to wrap my algorithm into a motion plugin.

-- VincenzoDiMassa - 03 Oct 2005

It is hard to argue against this. Make sure you participate in the creation of the MotionPluginAPI. -- KennethLavrsen - 04 Oct 2005

---

About "You must be able to build a plugin from Source without having the Motion sources":

Note, however, that if the plugin wants to call "internal" motion utility routines (e.g. motion_log) it must at least have access to the motion interface api header file which defines those routine.

-- BillBrack - 04 Oct 2005

Yes. That was what I intended to say. I have made it more clear in the text above. Feel free to also edit the requirements directly. It is a Wiki -- KennethLavrsen - 04 Oct 2005

---