Getting started

#Getting Started as a Plugin Author

Keep in mind that plugin authoring is supposed to be an enjoyable and rewarding endevor.
The important thing is the result. Not how you got there.

Even if you are not familiar with Python programming it is an easy language to learn and supports multiple programming styles (paradimes). There are many excellent resources on the internet for quickly learning how to accomplish almost any programming task.

####The first step in creating a plugin is to have a clear idea of what you want the plugin to do.

Most plugins are written to solve a specific problem or add a desired feature. If you write a short statement describing the plugin's purpose, you have now created a specification for your new plugin.

####The next step is to choose a development strategy.
This can include:

• Modifying an existing plugin that does something similar to what you want
• You can build a new plugin from the proto example plugin or,
• If you have the programming experience, you can write one from scratch.

You will need to decide how the plugin will interact with the core program. The gvReference.txt file in the SIP directory contains information about the variables, functions, files and signals that plugins can use to communicate with and control the core SIP program.

####What you will need

• Code editor (See the resources page)
• Working SIP installation
• Copy of the Proto plugin
• Internet connection
• git and GitHub repository (if you want to share your creation with the community)

##Usig the proto plugin The proto plugin consists of the following files:

• proto.py The python program that does the actual work of the plugin. Location: SIP/plugins
• proto.html A web.py template that provides a user interface for the plugin. It includes both Python code and web page markup. Location: SIP/templates
• proto-docs.html Provides documentation for the plugin including any special hardware needed and set up instructions. Location: SIP/static/docs/plugins
• proto.manifest A simple text file containing a list of each of the plugin’s files with the path to it’s location. The manifest is used by the plugin manager to install and uninstall the plugin. The file can also contain information about the plugin such as author, brief description, requirements, etc. Location: SIP/plugins/manifests
• proto.json An optional file used for persistant storage of plugin settings. It is created by the plugin the first time it is run and is not installed with the other files. This allows for software updates without overwriting existing settings. Location: SIP/data

The first two files are the core of the plugin. Proto.py is the only one required to make a working plugin.

Creating a new plugin from proto

Start your new plugin by copying the proto files and giving them a new name. For example useing the command line from the pi home directory:
sudo cp SIP/plugins/proto.py SIP/plugins/my_plugin.py
sudo cp SIP/templates/proto.html SIP/templates/my_plugin.html

Repeat this procedure for the other proto files you will be using.

This will create a new plugin. In SIP open Plugins > Manage Plugins and you should see your new plugin listed. Enable it if not already enabled.

Adding your new plugin to the Plugins menu

Edit my_plugin.py and make the following changes:

1. on lines 12 and 13 replace each ocurrence of "proto" with the name of your new plugin. e.g.
   '/proto-sp', 'plugins.proto.settings', is changed to '/my_plugin-sp', 'plugins.my_plugin.settings',
'/proto-save', 'plugins.proto.save_settings' is changed to '/my_plugin-save', 'plugins.my_plugin.save_settings'

2. On line 18 change
   gv.plugin_menu.append(['Proto Plugin', '/proto-sp']) to gv.plugin_menu.append(['My Plugin', '/my_plugin-sp'])

3. On lines 35 and 39 replace proto with my_plugin.

4. Restart SIP. From the command line use sudo service sip restart or from the SIP menu Options > System Restart > RESTART. After the restart your new plugin should appear on the Plugins menu

5. Edit my_plugin.html (in the templates folder). On lines 4 and 26, edit $var title: $_('SIP Proto Plugin') and replace SIP Proto Plugin with an appropriat title for your new plugin.

6. Read through the code in the HTML file and look for comments that begin with Edit and make changes appropriate to your new plugin.

Testing your new plugin

If you have SIP set up to auto-start when the Pi boots up, stop it running with the command:
sudo service sip stop
Then start the program manually from the SIP directory with:
cd SIP
sudo python sip.py
You will now be able to see messages from the program that can help you debug any problems.

Next steps

• Read through the code in my_plugin.py, my_plugin.html and the other plugin files and look for comments that describe what the various parts do.

• Look for other plugins on the GitHub SIP plugins repository that may have similar capabilities to what you want your plugin to do and see how they work.

• Ask questions on the SIP forum about how to implement specific functions: