README.md 11.2 KB
Newer Older
1
# Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS)
2

Michael Büsch's avatar
Michael Büsch committed
3
Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python.
4

Michael Büsch's avatar
Michael Büsch committed
5
The latest version of Awlsim can be downloaded at the [official Awlsim site](https://awlsim.de).
6 7


8
## Awlsim - Programmable Logic Controller (PLC/SPS)
9

Michael Büsch's avatar
Michael Büsch committed
10
Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python. The speed of execution ranges from several ten thousand AWL/STL instructions per second on slow embedded machines to a couple of million instructions per second on faster computers.
11 12 13

AWL/STL programs on PLCs are used for automation of industrial processes. However Awlsim is very flexible, so it can be used for other purposes beyond industrial applications, too. Awlsim aims to be compatible with the industry standard S7 software on the AWL/STL level.

Michael Büsch's avatar
Michael Büsch committed
14
Awlsim can emulate CPUs with two and four accumulator registers (S7-3xx and S7-4xx). Compatibility to S7 hardware is a task taken seriously by the Awlsim project. We want to be as close as possible to the real PLC hardware with our AWL/STL code execution. For this reason Awlsim ships an extensive selftest suite. Missing features and differences between Awlsim and Step 7 are documented in the [COMPATIBILITY documentation](COMPATIBILITY.html) and [TODO documentation](TODO.html) files.
15 16


17
## Quick start tutorial
18

Michael Büsch's avatar
Michael Büsch committed
19
See the [quick start tutorial](QUICK-START.html) for a simple example on how to use Awlsim in simulator mode. In simulator mode Awlsim can be run on any desktop PC. No special hardware is required.
20 21


22
## Example project
23 24 25 26

If you don't know where to start, you can find an example project in the `examples` directory as `EXAMPLE.awlpro`. You can easily run this example in simulation mode without the need for special hardware.


27
## Git repository
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

The latest development version of Awlsim can be fetched with git:

<pre>
git clone https://git.bues.ch/git/awlsim.git
cd awlsim
</pre>

After cloning the main repository the git submodules must also be fetched. The following helper script can be used:

<pre>
./maintenance/update-submodules
</pre>


43
## Dependencies
44

45
Awlsim depends on
46

47 48 49
* [Python](https://python.org) 3.4 or later or alternatively Python 2.7
* [PyQT 5](https://www.riverbankcomputing.com/software/pyqt/intro) or alternatively [PySide](https://wiki.qt.io/PySide)
* [CFFI](http://cffi.readthedocs.org/)
50 51 52 53 54

These packages can be installed with pip:

<pre>
pip3 install --upgrade PyQt5
55
pip3 install --upgrade cffi
56 57 58 59 60 61 62 63
</pre>

If building and using Awlsim with Cython acceleration is desired, Cython must also be installed:

<pre>
pip3 install --upgrade Cython
</pre>

64 65 66
On Windows all Awlsim dependencies can be installed by double clicking the shipped installer script: *maintenance\win-install-dependencies.cmd*

For Debian Linux users the script *maintenance/deb-dependencies-install.sh* installs all required and optional runtime and build dependencies.
67

68
## Directory structure
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93

The Awlsim Git repository and source archive `awlsim-x.yz.tar.bz2` contain lots of files and directories. Here is an overview of the main files and directories and their purpose:

### Main executables
User interface executables. The main user executable is `awlsim-gui`.
<pre>
  awlsim-client             : Command line client tool.
  awlsim-gui                : Graphical user interface. This is the main user frontend.
  awlsim-linuxcnc-hal       : LinuxCNC HAL module executable.
  awlsim-proupgrade         : Command line tool to update .awlpro file formats.
  awlsim-server             : Command line server tool.
  awlsim-symtab             : Command line tool to parse symbol tables (.ASC).
  awlsim-test               : Command line tool for unit testing.
                              See tests/run.sh for execution of unit tests.
  awlsim-win.cmd            : Windows wrapper for awlsim-gui.
</pre>

### Documentation
These files and directories contain useful information about Awlsim.
<pre>
  doc/                      : Main documentation.
  doc/fup/                  : Awlsim FUP language and editor documentation.
  examples/                 : Various example projects and feature demonstrations.
  COMPATIBILITY.md|html     : S7 compatibility documentation.
  COPYING.txt               : Main license.
94
  DEVELOPMENT.md|html       : How to enhance and develop Awlsim.
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143
  QUICK-START.md|html       : Quick start tutorial.
  README.md|html            : Main README document.
  TODO.md|html              : TODO list.
</pre>

### Main modules
The main modules implement most of Awlsim's functionality.
<pre>
  awlsim/                   : Main Awlsim Python-module directory. This is where the magic happens.
  awlsim/awlcompiler        : AWL compiler.
  awlsim/awloptimizer       : AWL optimizer.
  awlsim/common             : Common libraries, modules and helper functions.
  awlsim/core               : AWL interpreter core. This is where the AWL program is executed.
  awlsim/core/instructions  : Implementation of AWL instructions.
  awlsim/core/systemblocks  : Implementation of SFCs and SFBs.
  awlsim/coreclient         : Client library to connect to coreserver.
  awlsim/coreserver         : Server library to provide AWL interpreter core access via networking.
  awlsim/fupcompiler        : FUP compiler.
  awlsim/gui                : Graphical user interface implementation (Qt).
  awlsim/library            : AWL block (FC and FB) libraries.
  awlsim/library/iec        : Implementation of IEC FCs and FBs.
  awlsim_loader/            : Import wrapper for the main Awlsim Python-module.
                              This is used to automatically load Cython optimized modules.
  libs/                     : External libraries used for running or testing Awlsim.
  progs/                    : External programs used in Awlsim.
  submodules/               : Git submodules used for running Awlsim.
                              See  man git-submodule  for general help about Git submodules.
  submodules/pyprofibus/    : PROFIBUS-DP implementation.
  tests/                    : Unit test cases.
  tests/run.sh              : Main interface to run unit tests. Please see --help
</pre>

### Hardware support modules
The hardware modules are the glue between the Awlsim core and the real world. The hardware modules are invoked before and after running the user cycle (OB 1).
<pre>
  awlsimhw_debug/           : Hardware module for unit tests. Do not use in production.
  awlsimhw_dummy/           : Dummy no-operation hardware module for testing, debugging or simulation.
  awlsimhw_linuxcnc/        : LinuxCNC hardware support module.
  awlsimhw_pixtend/         : PiXtend hardware support module.
  awlsimhw_pyprofibus/      : PROFIBUS-DP hardware support module.
  awlsimhw_pyprofibus.conf  : Configuration file for awlsimhw_pyprofibus.
  awlsimhw_rpigpio/         : Raspberry Pi GPIO hardware support module.
</pre>

### Misc
<pre>
  awlsim-server.service.in  : Systemd unit template for awlsim-server.
  debian/                   : Debian packaging support.
  maintenance/              : Maintainer scripts.
Michael Büsch's avatar
Michael Büsch committed
144
  misc/                     : Miscellaneous scripts and files.
145 146 147 148 149
  pilc/                     : PiLC distribution build scripts.
  setup.py                  : Python package build script. This also builds the Cython modules.
</pre>


150
## FUP - Funktionsplan - Function block diagram
151 152 153 154

Awlsim supports programming in an S7-FUP like language. See [the FUP documentation](doc/fup/FUP.html) for more information about Awlsim's implementation of FUP.


155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192
## Environment variables

The following environment variables control Awlsim's basic behavior:

* `AWLSIM_GUI`<br />
  `=auto`    Automatically select the best GUI framework (default)<br />
  `=pyside`  Use PySide as GUI framework.<br />
  `=pyqt`    Use PyQt as GUI framework.<br />

* `AWLSIM_CYTHON`<br />
  `=0`  Do not attempt to use Cython core (default)<br />
  `=1`  Attempt to use Cython core, but fall back to Python<br />
  `=2`  Enforce Cython core<br />

* `AWLSIM_SCHED`<br />
  `=default`   Do not change the scheduling policy. Keep the policy that was assigned to Awlsim by the operating system. (default)<br />
  `=normal`    Use the normal non-realtime OS scheduling.<br />
  `=fifo`      Use FIFO realtime scheduling (`SCHED_FIFO`).<br />
  `=rr`        Use Round-robin realtime scheduling (`SCHED_RR`).<br />
  `=deadline`  Use Deadline realtime scheduling (`SCHED_DEADLINE`).<br />
  `=realtime`  Use a realtime scheduling algorithm that performs best in most situations. The actual algorithm selection might change between Awlsim releases.<br />

* `AWLSIM_PRIO`<br />
  `=default`  Do not change the priority (default).<br />
  `=1-99`     Set the scheduling priority. The meaning of the priority depends on the operating system and the selected scheduling algorithm. See `AWLSIM_SCHED`.<br />

* `AWLSIM_AFFINITY`<br />
  `=0,2,...`  Comma separated list of host CPU cores to run on. Default: all cores.<br />

* `AWLSIM_PROFILE`<br />
  `=0`  Disable profiling (default)<br />
  `=1`  Enable core cycle profiling<br />
  `=2`  Enable full core profiling (including startup)<br />

* `AWLSIM_COVERAGE`<br />
  `=DATAFILE`  Enable code coverage tracing.<br />


193
## Building Awlsim
Michael Büsch's avatar
Michael Büsch committed
194 195 196 197 198 199 200 201 202 203

Awlsim can be run from the source directory in interpreted Python mode without building it. Just `cd` into the Awlsim source directory and execute the desired main executable (e.g. `./awlsim-gui` or `./awlsim-server` etc...).

The accelerated Cython libraries can be built with the standard Python `./setup.py build` command.

For convenience there also is a helper script `./maintenance/build.sh`, which will do everything right to build Awlsim. That can be used instead of calling setup.py directly.

There also is `./maintenance/build-noopt.sh`. That builds Cython modules without optimization. The build is much faster, but the resulting Cython libraries will be much slower. This is useful for development. Do not use this for production.


204
## Building Debian / Raspbian / PiLC .deb packages
Michael Büsch's avatar
Michael Büsch committed
205 206 207 208 209 210 211 212 213 214 215 216 217

Installing or upgrading Awlsim on a Debian based system is easy.
The `debuild` can be used to build the .deb packages. Just run the following commands to build all Awlsim .deb packages:

<pre>
cd path/to/awlsim                                 # Go to Awlsim source directory
sudo ./maintenance/deb-dependencies-install.sh    # This installs all dependencies
debuild -uc -us                                   # Build all Awlsim .deb packages
sudo ./maintenance/deb-install.sh ..              # Install or upgrade all Awlsim .deb packages
</pre>

The .deb files will be put into the parent directory of the Awlsim source directory.

218 219 220 221 222 223 224 225
If you get the following build failure during build:

`/usr/include/features.h:xxx:xx: fatal error: sys/cdefs.h: No such file or directory`

this can be fixed by re-installing the libc development package:

`sudo apt install --reinstall libc-dev`

Michael Büsch's avatar
Michael Büsch committed
226

227
## Development
228

229
Information about Awlsim development can be found in [the Awlsim development documentation](DEVELOPMENT.html).
230 231


232
## License / Copyright
233 234 235 236

Copyright (C) Michael Büsch / et al.

Awlsim is Open Source Free Software licensed under the GNU General Public License v2+. That means it's available in full source code and you are encouraged to improve it and contribute your changes back to the community. Awlsim is free of charge, too.