PyScada Documentation

Release 0.6.17b2

Martin Schröder

April 04, 2016

 Using the Frontend

1 Installation 3
1.1 Add a new system-user for Pyscada (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Install Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Create a MySql Database (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Create a new Django Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.5 Initialize Database And Copy Static Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.6 Add a Admin User To Your Django Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.7 Setup of Nginx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.8 Add Init.d Scripts for SysV-Init (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.9 Add Init.d Scripts for systemd (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.10 Start the Django Development Server on Windows (optional) . . . . . . . . . . . . . . . . . . . . . 7
1.11 Add/Start the PyScada Services on Windows (optional) . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Django Settings 9
2.1 urls.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 settings.py . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 Nginx Setup 13
3.1 nginx configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

4 Command-line 15
4.1 Start the PyScada Daemons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Start Gunicorn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3 Get Installed PyScada Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.4 Export Database Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

5 Features 17

6 Dependencies 19

7 Contribute 21

8 License 23

i
ii
 PyScada Documentation, Release 0.6.17b2

A Open Source SCADA System with HTML5 HMI, build using the Django framework. If you like to setup your own
_SCADA_ system head over to the Installation section.
• Using the Frontend
• backend-docs

Using the Frontend 1

PyScada Documentation, Release 0.6.17b2

2 Using the Frontend

 CHAPTER 1

Installation

The installation of PyScada 0.6.x on Debian based Linux systems using MySQL as Database, Gunicorn as WSGI
HTTP Server and nginx as HTTP Server.
The installation of PyScada 0.6.x on Fedora 22/23 based Linux systems using MySQL as Database, Gunicorn as WSGI
HTTP Server and nginx as HTTP Server.
The installation of PyScada 0.6.x on Raspbian Linux systems using SQLite as Database, Gunicorn as WSGI HTTP
Server and nginx as HTTP Server.
The installation of PyScada 0.6.x on Microsoft Windows systems using SQLite as Database and the the Django De-
velopment Server as HTTP/WSGI Server.

1.1 Add a new system-user for Pyscada (optional)

Add a dedicated user for pyscada and add the home directory for static/media files and setup a virtual environemt.
sudo -i
useradd -r pyscada
mkdir -p /var/www/pyscada/http
chown -R pyscada:pyscada /var/www/pyscada
mkdir -p /home/pyscada
chown -R pyscada:pyscada /home/pyscada
ln -s /var/www/pyscada/ ~/www_pyscada
cd ~/
#virtualenv -p /usr/bin/python2.7 venv
#source venv/bin/activate

1.2 Install Dependencies

1.2.1 Debian 7

sudo apt-get update

sudo apt-get upgrade
sudo apt-get install mysql-server python-mysqldb python-pip libhdf5-7 libhdf5-dev python-dev nginx gu
sudo pip install cython
sudo pip install numpy
sudo pip install h5py
sudo pip install git+https://github.com/trombastic/PyScada.git@dev/0.6.x

3
PyScada Documentation, Release 0.6.17b2

1.2.2 Debian 8

sudo apt-get update

sudo apt-get upgrade
sudo apt-get install mysql-server python-mysqldb python-pip libhdf5-8 libhdf5-dev python-dev nginx gu
sudo pip install cython
sudo pip install numpy
# for 64bit
sudo HDF5_DIR=/usr/lib/x86_64-linux-gnu/hdf5/serial/ sudo pip install h5py
# for 32 bit
sudo pip install git+https://github.com/trombastic/PyScada.git@dev/0.6.x

1.2.3 Fedora 22/23

# as root
sudo dnf install libjpeg-turbo-devel-1.4.1-2.fc23 nginx mysql-server mysql-devel
#
sudo pip install cython
sudo pip install numpy
sudo pip install h5py
sudo pip install git+https://github.com/trombastic/PyScada.git@dev/0.6.x
sudo pip install gunicorn
sudo pip install MySQL-python

1.2.4 Raspberry Pi (RASPBIAN, Jessie)

sudo apt-get update

sudo apt-get upgrade
sudo apt-get install python-pip libhdf5-dev python-dev nginx gunicorn
sudo pip install cython
sudo pip install numpy
sudo HDF5_DIR=/usr/lib/arm-linux-gnueabihf/hdf5/serial/ sudo pip install h5py
sudo pip install git+https://github.com/trombastic/PyScada.git@dev/0.6.x

1.2.5 Windows

• Python 2.7 for Windows https://www.python.org/downloads/windows/

• Microsoft Visual C++ Comiler for Python 2.7 https://www.microsoft.com/en-
us/download/details.aspx?id=44266
• h5py https://pypi.python.org/pypi/h5py/2.5.0
• h5py for 64bit Windows http://www.lfd.uci.edu/~gohlke/pythonlibs/#h5py
Open a Shell (cmd.exe) and install the folowing packages via pip.
pip install gunicorn
pip install django">=1.7,<1.8"
pip install numpy
pip install python-daemon
pip install pyscada

4 Chapter 1. Installation
 PyScada Documentation, Release 0.6.17b2

1.3 Create a MySql Database (optional)

Create the Database and grand the nessesery permission. Replace PyScada_db, PyScada-user and PyScada-user-
password.
mysql -uroot -p -e "CREATE DATABASE PyScada_db CHARACTER SET utf8;"
mysql -uroot -p -e "GRANT ALL PRIVILEGES ON PyScada_db.* TO 'PyScada-user'@'localhost' IDENTIFIED BY

1.4 Create a new Django Project

# Linux/OSX
cd /var/www/pyscada/
sudo -u pyscada django-admin.py startproject PyScadaServer
# Windows
cd C:/Users/_YOUR_USERNAME_/www
python django-admin.py startproject PyScadaServer

see Django Settings

1.5 Initialize Database And Copy Static Files

# linux
cd /var/www/pyscada/PyScadaServer # linux
sudo -u pyscada python manage.py migrate
sudo -u pyscada python manage.py collectstatic
# Windows
cd C:/Users/_YOUR_USERNAME_/www/PyScadaServer
python manage.py migrate
python manage.py collectstatic

1.6 Add a Admin User To Your Django Project

cd /var/www/pyscada/PyScadaServer # linux
cd C:/Users/_YOUR_USERNAME_/www/PyScadaServer # Windows
# both
python manage.py createsuperuser

1.7 Setup of Nginx

see Nginx Setup

1.8 Add Init.d Scripts for SysV-Init (optional)

To start the Dataaquasition daemon(s) and guinicorn, there are two example scripts in the git repository. Copy them to
the init.d path of your machine and make them executible.

1.3. Create a MySql Database (optional) 5

PyScada Documentation, Release 0.6.17b2

sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/SysV-init/pys

sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/SysV-init/gun
sudo chmod +x /etc/init.d/pyscada_daemon
sudo chmod +x /etc/init.d/gunicorn_django

add a configuration file for every script.

sudo nano /etc/default/pyscada_daemon

Fill in the full path to the django project dir (were the manage.py is located). Replace the four spaces between the
daemon (modbus) and the path with a tab.
#!/bin/sh
#/etc/default/pyscada_daemon
DAEMONS=(
'modbus /var/www/pyscada/PyScadaServer/'
)
RUN_AS='pyscada'

Edit the gunicorn init.d script.

sudo nano /etc/default/gunicorn_django

Also fill in the path to your django project dir and replace the four spaces between the django projectname
(PyScadaserver) the project path and the number of workers (10) with tabs.
#!/bin/sh
#/etc/default/gunicorn_django
SERVERS=(
'PyScadaServer /var/www/pyscada/PyScadaServer 5'
)
RUN_AS='pyscada'

(optinal) install System-V style init script links

sudo update-rc.d pyscada_daemon defaults
sudo update-rc.d gunicorn_django defaults

1.9 Add Init.d Scripts for systemd (optional)

Download the sample Unit-Files for systemd.

sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/pysca
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/pysca
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/pysca
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/pysca
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/gunic
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/systemd/gunic
# enable the services
sudo systemctl enable gunicorn
sudo systemctl enable pyscada_daq
sudo systemctl enable pyscada_event
sudo systemctl enable pyscada_mail
sudo systemctl enable pyscada_export

6 Chapter 1. Installation
 PyScada Documentation, Release 0.6.17b2

1.10 Start the Django Development Server on Windows (optional)

Open a Windows Command-line (cmd.exe) and start the Django Development Server.
cd C:/Users/_YOUR_USERNAME_/www/PyScadaServer # Windows
python manage.py runserver --insecure

1.11 Add/Start the PyScada Services on Windows (optional)

Using pyscada background daemons in Windows is currently not supported, to start the daemons in foreground open
a Windows Command-line (cmd.exe) for every daemon and start it with the following command.
cd C:/Users/_YOUR_USERNAME_/www/PyScadaServer
python manage.py PyScadaWindowsDaemonHandler daemon_name

It is also posible to register the modbus daemon as an windows service, to do this download the from registratioen skript
from https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/service/windows/register_windows_service_modbus.py
and copy it to the project root folder.
cd C:/Users/_YOUR_USERNAME_/www/PyScadaServer
python register_windows_service_modbus.py

1.10. Start the Django Development Server on Windows (optional) 7

PyScada Documentation, Release 0.6.17b2

8 Chapter 1. Installation
 CHAPTER 2

Django Settings

2.1 urls.py

Open the urls configuration file and add the nesseary rewrite rule to the django URL dispatcher.
nano /var/www/pyscada/PyScadaServer/PyScadaServer/urls.py
...
url(r'^admin/', include(admin.site.urls)),
url(r'^', include('pyscada.hmi.urls')),
...

2.2 settings.py

Open the django settings file and make the following modifications. See also the django documentation for more
Information.
nano /var/www/pyscada/PyScadaServer/PyScadaServer/settings.py

First deaktivate the debuging, if debuging is active django will keep all SQL queries in the ram, the dataaquasition
runs many queries so your system will run fast out of memory. Keep in mind to restart guinicorn and all dataaquasion
daemons after you change the debuging state.
DEBUG = False
TEMPLATE_DEBUG = DEBUG

Add the host/domain of your machine, is this case every url that point to a ip of the machine is allowed.
ALLOWED_HOSTS = ['*']

Add the PyScada and the subapps to the installed apps list.
INSTALLED_APPS = (
...
'pyscada',
'pyscada.modbus',
'pyscada.hmi',
'pyscada.systemstat',
'pyscada.export'
)

To use the MySQL Database, fill in the database, the user and password as selected in the create Database section.

9
PyScada Documentation, Release 0.6.17b2

DATABASES = {
'default': {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'PyScada_db',
'USER': 'PyScada-user',
'PASSWORD': 'PyScada-user-password'
}
}

Set the static file and media dir as followes.

...
# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/1.6/howto/static-files/

STATIC_URL = '/static/'

STATIC_ROOT = '/var/www/pyscada/http/static/'

MEDIA_URL = '/media/'

MEDIA_ROOT = '/var/www/pyscada/http/media/'

Add all PyScada specific settings, keep in mind to set the file right source file encoding in the settings.py file header
(see also https://www.python.org/dev/peps/pep-0263/).
#!/usr/bin/python
# -*- coding: <encoding name> -*-

# PyScada settings
# https://github.com/trombastic/PyScada

# folder were the daemon pid files are stored

PID_ROOT = BASE_DIR + '/run/'

# email settings
DEFAULT_FROM_EMAIL = 'example@host.com'
EMAIL_HOST = 'mail.host.com'
EMAIL_PORT = 587
EMAIL_HOST_USER = 'pyscada@host.com'
EMAIL_USE_TLS = True
EMAIL_USE_SSL = False
EMAIL_HOST_PASSWORD = 'password'
EMAIL_SUBJECT_PREFIX = 'PREFIX' # Mail subject will be "PREFIX subjecttext"

# global
PYSCADA = {
'mail_count_limit': 20, # number of mails per emailadress per day
}
# meta informations
#
PYSCADA_META = {
'name':'A SHORT NAME',
'description':'A SHORT DESCRIPTION',
}

# export properties
#
PYSCADA_EXPORT = {

10 Chapter 2. Django Settings

 PyScada Documentation, Release 0.6.17b2

'file_prefix':'PREFIX_',
'output_folder':'~/measurement_data_dumps',
}

# parameters for the Modbus and Systemstat Device

# polling_interval how often the modbus device requests data
# from devices and write to the cache
#
# recording_intervall how often the data is written to the database

PYSCADA_MODBUS = {
'polling_interval':5,
'recording_interval':5,
}

PYSCADA_SYSTEMSTAT = {
'polling_interval':5,
'recording_interval':5,
}

2.2. settings.py 11
PyScada Documentation, Release 0.6.17b2

12 Chapter 2. Django Settings

 CHAPTER 3

Nginx Setup

3.1 nginx configuration

# debian
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/nginx_sample.conf -O
sudo nano /etc/nginx/sites-available/pyscada.conf
# Fedora
sudo wget https://raw.githubusercontent.com/trombastic/PyScada/dev/0.6.x/extras/nginx_sample.conf -O
sudo nano /etc/nginx/conf.d/pyscada.conf

after editing, enable the configuration and restart nginx, optionaly remove the default configuration
# debian
sudo ln -s /etc/nginx/sites-available/pyscada.conf /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default

now it’s time to [re]start nginx.

# SysV-Init
sudo service nginx restart
# systemd
systemctl enable nginx.service # enable autostart on boot
sudo systemctl restart nginx

for Fedora you have to allow nginx to serve the static and media folder.
sudo chcon -Rt httpd_sys_content_t /var/www/pyscada/http/

13
PyScada Documentation, Release 0.6.17b2

14 Chapter 3. Nginx Setup

 CHAPTER 4

Command-line

4.1 Start the PyScada Daemons

SysV-init and upstart:

service pyscada_daemon start

systemd:
systemctl start pyscada_daemon_name.service

Django manage command:

python manage.py PyScadaDaemonHandler daemon_name start

4.2 Start Gunicorn

SysV-init and upstart:

service gunicorn_django start

systemd:
systemctl start gunicorn.service

4.3 Get Installed PyScada Version

cd ~/www/PyScadaServer
python manage.py shell
import pyscada
pyscada.__version__
exit()

15
PyScada Documentation, Release 0.6.17b2

4.4 Export Database Tables

python manage.py PyScadaExportData # last 24 houres
python manage.py PyScadaExportData "01-Mar-2015 00:00:00" # from 01. of March until now
# from 01. of March until now, with the given filename
python manage.py PyScadaExportData "01-Mar-2015 00:00:00" "filename.h5"
# from 01. of March until 10. of March, with the given filename
python manage.py PyScadaExportData "01-Mar-2015 00:00:00" "filename.h5" "10-Mar-2015 00:00:00"

16 Chapter 4. Command-line
 CHAPTER 5

Features

• HTML5 based HMI

• Supports the following industrial Protocols
– Modbus TCP/IP
– Modbus RTU
– Modbus ASCII
– Modbus Binary
– BACNet/IP (in development)
– Meter-Bus, MBus (in development)
• very low Hardware requirements for the Server

17
PyScada Documentation, Release 0.6.17b2

18 Chapter 5. Features
 CHAPTER 6

Dependencies

• core/HMI
– python 2.7
– django>=1.7
– numpy>=1.6.0
– pillow
– python-daemon
• ModbusMaster
– pymodbus>=1.2
• HDF5Export
– h5py>=2.1.1
• SystemStatistics
– psutil
• BACNet/IP
– bacpypes

19
PyScada Documentation, Release 0.6.17b2

20 Chapter 6. Dependencies
 CHAPTER 7

Contribute

• Issue Tracker: https://github.com/trombastic/PyScada/issues

• Source Code: https://github.com/trombastic/PyScada

21
PyScada Documentation, Release 0.6.17b2

22 Chapter 7. Contribute
 CHAPTER 8

License

The project is licensed under the _GNU General Public License v3 (GPLv3)_.

23