From Rayshobby Wiki
Jump to: navigation, search

Contents

Python Interval Program for OpenSprinkler Pi

Background

This program, written by Dan Kimberling, is a Python port of the Arduino based micro-controller OpenSprinkler interval program originally written by Ray Wang.

It is designed to run on a Raspberry Pi with a current release of the Raspbian operating system installed.

Despite the difference in spelling, the “Pi“ in the name Raspberry Pi is derived from Python and this was a logical choice for the programming language since it is included with the operating system.

A major goal in the design of this program was to avoid having to install additional software or require the user to compile code. The program uses very basic, standard Python modules plus the Python GPIO module which is also included with recent distros of Raspbian. The only other non-standard Python module is web.py which enables the web interface of the program including a built-in web server. Web.py is in the public domain and is included in the program download as the /web directory. You will also need to have git installed on your Pi but resent releases of the Raspbian operating system include git. No other software is required.

History

Jun 09, 2014, Version 2.0 was released. This included Jonathan Marsh's improved UI.

Apr 04, 2014, The first version of the program with plugin architecture was released. This enables anyone to easily add new features to the program without having to modify the core program.

Jun 09, 2013, The initial release was announced by Ray on the OpenSprinkler forum. It was equivalent to version 1.8.2 of the micro-controller firmware. This was followed by a series of updates based on user feedback. For details, see the README.md file in the program directory or on GhtHub: https://github.com/Dan-in-CA/OSPi

Installation

Note: If you are updating an existing installation of the program, see the Updating the program section below.

Requirements:

  1. A suitable SD memory card that has been flashed with an up to date rev of the Raspbian operating system. See the Raspberry Pi Quick Start Guide for instructions. Be sure the system is properly set up with the correct time zone for your location.
  2. An internet connection

Install git:

Note: If you are running a resent version of the Raspbian operating system, git should already be installed. You can test this by typing 'git' (without quotes) in a terminal window. If git is installed you will see a help screen showing git commands. Otherwise follow these instructions.

With the Raspberry Pi connected to the internet, open a terminal window (command line). enter the following command:

sudo apt-get install git

After a couple of seconds, you may be asked if you want to proceed, answer yes by typing y and the installation should finish within a minute or two.

Quick Program Installation:

Be sure you are in the Pi user's home directory ([email protected] ~ $).
Clone the OSPi directory from GitHub by issuing the following command:

git clone https://github.com/Dan-in-CA/OSPi

The program is now ready to run. To start the program execute:

cd OSPi
sudo python ospi.py

Detailed instructions:

Download the program from GitHub.

  1. Open a terminal window or connect to the pi via ssh.
  2. Type the command:
    git clone https://github.com/Dan-in-CA/OSPi

    followed by the enter key.

    The program file should start downloading from the GitHub server.

    If you get an error message, carefully retype the command and double check that it is exactly as shown above. Also be sure the pi is connected to the internet.
  3. Check that the OSPi directory was created in the proper location by typing ls (that's lower case LS). You should see the directory (OSPi) listed as a sub-directory.

Start the program for testing

  1. Log into the OSPi sub-directory by typing:
    cd OSPi
    followed by the enter key.
  2. start the program by typing the following command:
    sudo python ospi.py

    followed by the enter key.

    You should see a message from the program “Starting timing loop” and a URL.

Open the program in a web browser

On a device connected to your local network, enter the URL of your Raspberry Pi with port number 8080. For example, on my test system, the URL would be http://192.168.1.22:8080. The URL of your Raspberry Pi will be different. Don't forget to include the colon (:) before the port number.

You should now see the interval program's home page in your browser. Congratulations! The program is now installed and running.

Note: If you start the program while logged in via SSH and then log out of SSH, the program will be stopped. If you then try to access the program from your browser you will get an error message.

Using the native web interface

Instructions for using the original firmware based web interface can be found at the Ray's Hobby web site.

Instructions for using the updated web interface standard in V 2.0.0+ are under development but are similar to the original interface instructions described at the link above.

Updating the program

From version 2.1.0 or later that was installed using git

This includes recent installations from the pre-configured image file.

  1. Log into your OSPi directory and issue the command:
    git pull 
    The updates should be installed automatically and your settings should remain intact.

  2. Reboot the Pi:
    sudo reboot

    Or
    If you are using the init.d script to auto-run the program:
    restart the program with:

    sudo service ospi restart

From an earlier version

The recommended way to update to this version from a pre 2.1.0 rev. is to issue the following commands from the program directory (OSPi) :

  1. make sure you are on the master branch
    git checkout master

  2. fetch the new version form GitHub
    git fetch

  3. reset to the new version
    git reset --hard origin/master

  4. Reboot the Pi:
    sudo reboot

    Or
    If you are using the init.d script to auto-run the program:
    restart the program with:

    sudo service ospi restart

From an older version not installed using git

If you are updating the program from an installation that was not installed using git, or was installed prior to August 25, 2013, follow the instructions bellow.
You can check the date of the files in your installation by issuing the command:

 ls -l OSPi

The dates of the files will appear in the listing as e.g.:

-rw-r--r-- 1 pi   pi   40512 Aug 25 16:08 ospi.py
  1. install git: (Newer versions of rasbian have git pre-installed.)
    sudo apt-get install git
    After a couple of seconds, you may be asked if you want to proceed, answer yes by typing y and the installation should finish in a minute or two.

  2. Rename your existing OSPi directory to something like OSPi-old:
    mv OSPi OSPi-old
  3. Clone the new OSPi directory from git hub:
    git clone https://github.com/Dan-in-CA/OSPi
    This will create a new directory named OSPi containing the latest program files.
  4. Copy your data (config) files from your old installation to the new one:
    cp -f ./OSPi-old/data/*.* ./OSPi/data/
  5. If you have a customized ospi_addon.py file, copy it to the new installation:
    cp -f ./OSPi-old/ospi_addon.py ./OSPi/
  6. Reboot the Pi and you should now be running the latest update with your old settings intact.
  7. sudo reboot

Starting the program automatically

Once the program is installed, you will probably want it to start automatically when the Raspberry Pi boots up. This will ensure that the program will be running even after recovering from a power outage.

There are a couple of ways to accomplish this. The simplest is to add some start-up commands to a file named “rc.local” which is in a directory named “/etc”. However, the recommended method is to use a script in /etc/init.d. See the Recommended method below.

Quick instructions:

  1. Edit the file /etc/rc.local and add the following before the “exit 0” line:
     ### Start the OSPi interval program
     cd /home/pi/OSPi/
     python ospi.py &
  2. Reboot the Pi.
    sudo reboot

Detailed instructions:

Nano is the name of a light weight text editor that is included with the Raspbian operating system. It is used to edit various configuration files including the rc.local file that can be used to start the Python interval program when the Pi boots up.

  1. In a terminal window type the following command:
    sudo nano /etc/rc.local

    followed by the enter key.

    This will open the file in the editor.

    You can use the keyboard arrow keys to move around and the Enter key to add new lines in the editor.

    Use the down arrow key on your keyboard to move the cursor (which appears as a highlighted box) down past most of the text to a blank line just before the line “exit 0”.
  2. Carefully type in the following:
     ### Start the OSPi interval program
     cd /home/pi/OSPi/
     python ospi.py & 

    Be sure to include all spaces and punctuation just as shown above.

    The first line is a comment that is there as a reminder of what the code does but doesn't actually perform any action.

    The third line is what actually starts the interval program. If you ever need to disable the automatic start, you can “comment out” this line by editing the file and placing a # character at the start of the line. You can then re-enable automatic start by removing the # character.

  3. After you have entered the lines as shown above, save the file by typing Ctrl + o. (that's the control key and the letter o together) followed by the Enter key.
  4. Exit the editor by typing Ctrl + x.
  5. Once you have exited the editor, reboot the Pi by typing:
    sudo reboot
    followed by the Enter key.

After the Pi has rebooted you should be able to go to the URL of your Pi from a device connected to your local network and access the interval program's web interface.

If you open a terminal window on the Pi, or access the Pi via ssh you will not see any indication that the program is running. It started as “root” and is not visible to the standard Pi user. You can use the Pi as if the program wasn't running but be aware that a lot of additional activity may cause timing problems with the interval program.

The recommended method:

Starting ospy.py from a script in /etc/init.d

Here's a better way to automatically start opsy.py on boot instead of using /etc/rc.local. This is the preferred method and a file (ospi.sh) is included with the program distribution to make setup easy.

The advantage of using an /etc/init.d script is that you can easily stop, start, and check the status of ospi.py. Since /etc/rc.local is only executed on boot up, it's a little awkward to stop ospi.py and start it again without rebooting or a typing bunch of commands. The script was adapted from the Debian skeleton template in /etc/init.d.

  1. Move the script file to /etc/init.d and rename it to ospi (without the .sh extension). Log into the OSPi directory and run the command:
    sudo mv ospi.sh /etc/init.d/ospi
  2. Make the script executable:
    sudo chmod +x /etc/init.d/ospi
  3. Activate auto start on boot:
    sudo update-rc.d ospi defaults

If you want to disable the auto-start, use:

sudo update-rc.d ospi remove

If you are developing new features in the code you will find the restart command (see below) a quick way to check your changes.

Check status, start, stop, and restart ospi.py

If you are using the ospi script in /etc/init.d, as described above, you can check if the interval program is running by executing the command:

/etc/init.d/ospi status

To start the interval program, execute:

sudo /etc/init.d/ospi start

To stop the interval program, execute:

sudo /etc/init.d/ospi stop

To quickly restart the program after making changes, execute:

sudo /etc/init.d/ospi restart

Logging

The logging feature included with the Python Interval program is disabled by default. This is to prevent the uncontrolled accumulation of log data. It also eliminates unnecessary redundancy if you are using another logging method such as the one provided by Samer's web app.

To enable logging:

Click the “Options” button at the top of the page. On the Options page click the triangle next to "Log" on the menu. You will be presented with a dialog containing a check box for enabling the feature.

Set the maximum number of records to keep:

It is set to 100 records by default but you can change the value to whatever you like. When the maximum number of records has been reached, new records will continue to be added to the top of the list and the oldest records deleted from the bottom.

Setting the maximum to zero (no maximum) will allow records to accumulate until all available storage space is filled. This may effect system performance if the number of records becomes very large but it has been tested with over 1100 records without a noticeable problem. A practical setting might be the number of records you would get in a period of time such as a week.

Archiving log data:

The Log page contains a link that allows you to download log data as a spread sheet friendly, comma separated values, (csv) text file to another device, e. g. a laptop. This provides a means of keeping a permanent archive of irrigation data in manageable size chunks. Once the file has been downloaded it can be imported in to your favorite spread sheet program for viewing, sorting, etc.

Plugins

In keeping with the open source, do it yourself, spirit of the OpenSprinkler Pi, some users have been adding new features to the Python program. This is highly encouraged. Among the reasons for choosing Python as the programming language for this project are it's ease of learning and readable code.

It is possible to add functionality to the Python interval program without modifying the program itself by writing a “module” that will be automatically imported into the program when it starts. All Python programs are considered modules and can be imported by other programs.

There are a couple of example files located in the plugin directory named “monthly_adj.py” and "relay.py" which you can use as a starting point for creating your own custom feature(s) for the interval program.

Plugins are python scripts that reside in the ./OSPi/plugins directory. The main ospi.py file will attempt to load any .py file it finds in that directory as long as the execute bit is set for the group attribute. While working on plugins, it might be convenient have attributes set to 777 (rwx for all) until the plugin is stable.

In your plugin code, you will most likely want to import the global variables from ospi - do that by importing gv

import gv

If you want to extend the UI via web pages, you should do that by extending the URL list. from urls import urls

urls.extend(['/myurl', 'plugins.myplugin.myui'])

Your module needs to be named myplugin and implement the myui class that will be instantiated by the main ospi module. You can browse to your plugin by going to http://ospi:8080/myurl.

You can also add your plugin to the menu that is opened when the "Plugins" button on the Home page of the program's native web UI is clicked. To add a link for your plugin you must have imported the "gv" module as described above. Then you only need to add a single line of Python code to your plugin like this example:

gv.plugin_menu.append(['Menu Text', 'url'])

where "Nemu Text" is the name of your plugin or other text you want to appear on the menu and "url" is the url for the link. for example, in the Relay example plugin, the line is "gv.plugin_menu.append(['Test Relay', '/tr'])".

To debug your plugin, you're going to want to stop the ospi service from running in the background and instead run ospi from the command line and watch for debug output.

sudo service ospi stop
sudo python ospi

If your plugin uses web.py to display web pages, your template should go into ./OSPi/templates

Adding Python Modules

You can add new capabilities to Python by installing additional modules. The instructions that follow will get you started.

Install Python setup tools

From the Pi's command line, enter:

sudo apt-get install python-setuptools

this will install some basic tools including easy_install which can be used to install modules. However a tool named pip is more advanced and is the preferred one to use.

Install Pip:

sudo easy_install pip

You can now install and remove modules as needed for your plugin. For example:

sudo pip install [module-name]

Substituting the name of the module you wish to install for [module-name].