Project home: https://bues.ch/a/awlsim Original repository at: https://git.bues.ch/git/awlsim.git https://bues.ch/a/awlsim

Michael Buesch 92e07ae454 Update to putty 0.71 3 days ago
awlsim 591f77c3ca Bump version 3 days ago
awlsim_loader a3cab72468 loader/cython: Improve import error message 4 months ago
awlsimhw_debug ed481e3ddd Add container type for memory objects 6 months ago
awlsimhw_dummy 608c2af02f cython: Add central cython support definitions 9 months ago
awlsimhw_linuxcnc faf5590718 coverage: Add more coverage annotations 7 months ago
awlsimhw_pixtend f43a7c4775 hw/pixtend: Add support for PWM1 6 months ago
awlsimhw_pyprofibus faf5590718 coverage: Add more coverage annotations 7 months ago
awlsimhw_rpigpio d7437a1998 hw/rpigpio: Implement direct I/O 2 months ago
debian 591f77c3ca Bump version 3 days ago
doc ec423ac1a3 pilc/doc: Add connection failure help 2 months ago
examples 42556e698c examples/pixtend: Use FUP timers 1 month ago
libs 1f168fc8c7 Add endianness helpers for Win build 6 months ago
maintenance d13baa56a8 bench: Regenerate AWL code 1 month ago
misc 7c62e45f00 setup/cython: Add support for ubsan 1 month ago
pilc d4e1311090 pilc: Install raspi-gpio package 5 days ago
progs 92e07ae454 Update to putty 0.71 3 days ago
submodules 44c96d20d9 pyprofibus: Update 4 months ago
tests 775506fdea Allow block numbers up to 0xFFFF 1 month ago
.gitignore 465f14daec doc: Do not generate PDF and PS docs 1 year ago
.gitmodules 80da6e14c3 Remove pilc-hat 1 year ago
COMPATIBILITY.md 9c2919739b Add development documentation 7 months ago
COPYING.txt 193467d27e Clarify license conditions (GPL2+) 4 years ago
DEVELOPMENT.md 487c1ff84d cython: Add posix/win annotations 6 months ago
MANIFEST.in 754975d489 manifest: Add PILC.md 1 month ago
PILC.md ec423ac1a3 pilc/doc: Add connection failure help 2 months ago
QUICK-START.md 9c2919739b Add development documentation 7 months ago
README.md 7c62e45f00 setup/cython: Add support for ubsan 1 month ago
TODO.md 3e3e5c66da Update TODO list 4 months ago
awlsim-client ccef7e1670 coreserver: Add support for instruction time measurements 1 month ago
awlsim-covreport faf5590718 coverage: Add more coverage annotations 7 months ago
awlsim-gui 250f25803b Update copyright 3 years ago
awlsim-linuxcnc-hal 9303873178 Move options to cpuconf structure 9 months ago
awlsim-proupgrade a104ac167a awlsim-proupgrade: Add option to regenerate all UUIDs 9 months ago
awlsim-server 226e28c114 Add option to shutdown or reboot coreserver system 1 month ago
awlsim-server.service.in 226e28c114 Add option to shutdown or reboot coreserver system 1 month ago
awlsim-symtab 21e6cad1f8 ASC: Strip white space in ASC files 1 year ago
awlsim-test ccef7e1670 coreserver: Add support for instruction time measurements 1 month ago
awlsim-win.cmd f87bdab51c awlsim-win wrapper: Add Cython option 6 months ago
awlsimhw_pyprofibus.conf a2825f0256 hw/pyprofibus/conf: Fix py2 compatibility 2 years ago
setup.py 7c62e45f00 setup/cython: Add support for ubsan 1 month ago

README.md

Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS)

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 latest version of Awlsim can be downloaded at the official Awlsim site.

Awlsim - Programmable Logic Controller (PLC/SPS)

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.

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.

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 and TODO documentation files.

Quick start tutorial

See the quick start tutorial 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.

Example project

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.

PiLC - The Raspberry Pi PLC

If you want to use PiLC, please also see the PiLC documentation.

Git repository

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

git clone https://git.bues.ch/git/awlsim.git
cd awlsim

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

./maintenance/update-submodules

Dependencies

Awlsim depends on

These packages can be installed with pip:

pip3 install --upgrade PyQt5
pip3 install --upgrade cffi

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

pip3 install --upgrade Cython

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.

Directory structure

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.

  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.

Documentation

These files and directories contain useful information about Awlsim.

  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.
  DEVELOPMENT.md|html       : How to enhance and develop Awlsim.
  QUICK-START.md|html       : Quick start tutorial.
  README.md|html            : Main README document.
  TODO.md|html              : TODO list.

Main modules

The main modules implement most of Awlsim's functionality.

  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

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).

  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.

Misc

  awlsim-server.service.in  : Systemd unit template for awlsim-server.
  debian/                   : Debian packaging support.
  maintenance/              : Maintainer scripts.
  misc/                     : Miscellaneous scripts and files.
  pilc/                     : PiLC distribution build scripts.
  setup.py                  : Python package build script. This also builds the Cython modules.

FUP - Funktionsplan - Function block diagram

Awlsim supports programming in an S7-FUP like language. See the FUP documentation for more information about Awlsim's implementation of FUP.

Environment variables

The following environment variables control Awlsim's basic behavior:

  • AWLSIM_GUI
    =auto Automatically select the best GUI framework (default)
    =pyside Use PySide as GUI framework.
    =pyqt Use PyQt as GUI framework.

  • AWLSIM_CYTHON
    =0 Do not attempt to use Cython core (default)
    =1 Attempt to use Cython core, but fall back to Python
    =2 Enforce Cython core

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

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

  • AWLSIM_AFFINITY
    =0,2,... Comma separated list of host CPU cores to run on. Default: all cores.

  • AWLSIM_PROFILE
    =0 Disable profiling (default)
    =1 Enable core cycle profiling
    =2 Enable full core profiling (including startup)

  • AWLSIM_COVERAGE
    =DATAFILE Enable code coverage tracing.

  • AWLSIM_GCMODE
    =realtime Enable manual garbage collection, if realtime scheduling is enabled. (default)
    =auto Always use automatic garbage collection.
    =manual Always use manual garbage collection.

  • AWLSIM_GCTHRES
    =700,1,1
    A comma separated string with up to 3 integers.
    Each integer corresponding to the Python garbage collector generation 0 to 2 thresholds for manual garbage collection.
    A threshold value of 0 disables garbage collection. (not recommended)

  • AWLSIM_GCCYCLE
    =64
    The number of OB1 cycles it takes to trigger a manual garbage collection.

Environment variables during build (setup.py)

The following environment variables control Awlsim's build (setup.py) behavior:

  • AWLSIM_FULL_BUILD
    =0 Do not include scripts that are not necessary on this platform. (default)
    =1 Include all scripts; also those that aren't required on the platform.

  • AWLSIM_CYTHON_BUILD
    =0 Do not build any Cython modules. (default on non-Posix)
    =1 Build Cython modules.
    =2 Build Cython modules only, if setup.py is being executed by Python 2.
    =3 Build Cython modules only, if setup.py is being executed by Python 3. (default on Posix)

  • AWLSIM_CYTHON_PARALLEL
    =0 Do not use parallel compilation for Cython modules.
    =1 Invoke multiple compilers in parallel (faster on multicore). (default)
    =2 Invoke multiple compilers only, if setup.py is being executed by Python 2.
    =3 Invoke multiple compilers only, if setup.py is being executed by Python 3.

  • AWLSIM_PROFILE
    =0 Do not enable profiling support in compiled Cython modules. (default)
    =1 Enable profiling support in compiled Cython modules.

  • AWLSIM_DEBUG_BUILD
    =0 Do not enable debugging support in compiled Cython modules. (default)
    =1 Enable debugging support in compiled Cython modules.

Building Awlsim

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.

Building Debian / Raspbian / PiLC .deb packages

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:

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

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

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

Development

Information about Awlsim development can be found in the Awlsim development documentation.

License / Copyright

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.