1

<!---

     2

[![docs](https://readthedocs.org/projects/beremiz/badge/?version=latest)](https://beremiz.readthedocs.io)

     3

-->

     4

[![CI Automated testing](https://github.com/beremiz/beremiz/actions/workflows/run_tests_in_docker.yml/badge.svg?branch=python3)](https://github.com/beremiz/beremiz/actions/workflows/run_tests_in_docker.yml)

     5

     6

# Beremiz #

     7

     8

Beremiz is an integrated development environment for machine automation. It is Free Software, conforming to IEC-61131 among other standards.

     9

    10

It relies on open standards to be independent of the targeted device, and let you turn any processor into a PLC. Beremiz includes tools to create HMI, and to connect your PLC programs to existing supervisions, databases, or fieldbuses.

    11

    12

With Beremiz, you conform to standards, avoid vendor lock, and contribute to the better future of Automation. 

    13

    14

Beremiz consists of two components:

    15

    16

* Integrated Development Environment (IDE), Beremiz.py. It is running on user's computer and is used to write/compile/debug PLC programs and control PLC runtime.

    17

* Reference runtime implementation in python, Beremiz_service.py. It's running on target platform, communicates with I/O and executes PLC program.

    18

    19

See official [Beremiz website](http://www.beremiz.org/) for more information.

    20

    21

## Install latest release ##

    22

    23

Windows installer and Snap package for Linux are available in [Github releases](https://github.com/beremiz/beremiz/releases) and [Snapcraft's store](https://snapcraft.io/beremiz)

    24

    25

## Tutorials and examples ##

    26

    27

In IDE, find menu "File>Tutorials and examples" to quickly open examples that should run as-is.

    28

    29

There are more examples in `tests/projects` and `exemples` directories.

    30

    31

Some example and test are shown on [Beremiz youtube channel](https://www.youtube.com/channel/UCcE4KYI0p1f6CmSwtzyg-ZA).

    32

    33

## Development with Beremiz ##

    34

    35

Developers are invited to subscribe to [mailing list](https://sourceforge.net/p/beremiz/mailman/beremiz-devel/) (beremiz-devel@lists.sourceforge.net).

    36

    37

The list is moderated and requires subscription before posting.

    38

    39

To subscribe to the mailing list go [here](https://sourceforge.net/p/beremiz/mailman/beremiz-devel/).

    40

    41

Searchable archive using search engine of your choice is available [here](http://beremiz-devel.2374573.n4.nabble.com/).

    42

    43

## Build on Linux (developer setup) ##

    44

    45

### System prerequisites (Ubuntu 22.04) :

    46

```

    47

# install required system packages as root

    48

sudo apt-get install \

    49

  build-essential automake flex bison mercurial \

    50

  libgtk-3-dev libgl1-mesa-dev libglu1-mesa-dev \

    51

  libpython3.10-dev libssl-dev \

    52

  python3.10 virtualenv cmake git mercurial

    53

```

    54

    55

    56

### Prepare build directory

    57

    58

All commands hereafter assume that selected directory to contain all downloaded source code and build results is `~/Beremiz`

    59

    60

```

    61

mkdir ~/Beremiz

    62

cd ~/Beremiz

    63

```

    64

    65

### Get Source Code (Mercurial)

    66

    67

```

    68

cd ~/Beremiz

    69

hg clone https://hg.beremiz.org/beremiz

    70

hg clone https://hg.beremiz.org/matiec

    71

```

    72

    73

### Get Source Code (Git)

    74

    75

```

    76

cd ~/Beremiz

    77

git clone https://github.com/beremiz/beremiz

    78

git clone https://github.com/beremiz/matiec

    79

```

    80

    81

### Python prerequisites (virtualenv) :

    82

```

    83

# setup isolated python environment

    84

virtualenv ~/Beremiz/venv

    85

    86

# install required python packages

    87

~/Beremiz/venv/bin/pip install -r ~/Beremiz/beremiz/requirements.txt

    88

    89

```

    90

    91

### Build MatIEC compiler

    92

    93

```

    94

cd ~/Beremiz/matiec

    95

autoreconf -i

    96

./configure

    97

make

    98

```

    99

   100

### Build CanFestival (optional)

   101

   102

Only needed for CANopen support. Please read CanFestival manual to choose CAN interface other than `virtual`.

   103

   104

```

   105

cd ~/Beremiz

   106

   107

hg clone http://hg.beremiz.org/canfestival

   108

#  -- or --

   109

git clone https://github.com/beremiz/canfestival

   110

   111

cd ~/Beremiz/canfestival

   112

./configure --can=virtual

   113

make

   114

```

   115

   116

### Build Modbus library (optional)

   117

   118

Only needed for Modbus support.

   119

   120

```

   121

cd ~/Beremiz

   122

   123

hg clone http://hg.beremiz.org/Modbus

   124

#  -- or --

   125

git clone https://github.com/beremiz/Modbus

   126

   127

cd ~/Beremiz/Modbus

   128

make

   129

```

   130

   131

### Build BACnet (optional)

   132

   133

Only needed for BACnet support.

   134

   135

```

   136

cd ~/Beremiz

   137

svn checkout https://svn.code.sf.net/p/bacnet/code/trunk/bacnet-stack/ BACnet

   138

cd BACnet

   139

make MAKE_DEFINE='-fPIC' MY_BACNET_DEFINES='-DPRINT_ENABLED=1 -DBACAPP_ALL -DBACFILE -DINTRINSIC_REPORTING -DBACNET_TIME_MASTER -DBACNET_PROPERTY_LISTS=1 -DBACNET_PROTOCOL_REVISION=16' library

   140

```

   141

   142

### Launch Beremiz IDE

   143

   144

```

   145

~/Beremiz/venv/bin/python ~/Beremiz/beremiz/Beremiz.py

   146

```

   147

   148

## Run standalone Beremiz runtime ##

   149

   150

* Start standalone Beremiz service

   151

   152

```

   153

mkdir ~/beremiz_runtime_workdir

   154

~/Beremiz/venv/bin/python ~/Beremiz/beremiz/Beremiz_service.py -p 61194 -i localhost -x 0 -a 1 ~/beremiz_runtime_workdir

   155

```

   156

   157

To connect IDE with runtime, enter target location URI in project's settings (project->Config->BeremizRoot/URI_location) pointed to your running Beremiz service in this case :

   158

   159

```

   160

PYRO://127.0.0.1:61194

   161

```

   162

   163

If project's URL is 'LOCAL://', then IDE launches on demand a local instance of Beremiz python runtime working on a temporary directory.

   164

   165

## Build documentation

   166

   167

Source code for documentation is stored in `doc` directory in project's source tree.

   168

It's written in reStructuredText (ReST) and uses Sphinx to generate documentation in different formats.

   169

   170

To build documentation you need following packages on Ubuntu/Debian:

   171

   172

```

   173

sudo apt-get install build-essential python-sphynx

   174

```

   175

   176

### Documentation in HTML

   177

   178

Build documentation

   179

   180

```

   181

cd ~/Beremiz/doc

   182

make all

   183

```

   184

   185

Result documentation is stored in directories `doc/_build/dirhtml*`.

   186

   187

### Documentation in PDF

   188

   189

To build pdf documentation you have to install additional packages on Ubuntu/Debian:

   190

   191

```

   192

sudo apt-get install textlive-latex-base texlive-latex-recommended \

   193

     texlive-fonts-recommended texlive-latex-extra

   194

```

   195

   196

Build documentation

   197

   198

```

   199

cd ~/Beremiz/doc

   200

make latexpdf

   201

```

   202

   203

Result documentation is stored in `doc/_build/latex/Beremiz.pdf`.

   204

   205

## Documentation ##

   206

   207

 * See [Beremiz youtube channel](https://www.youtube.com/channel/UCcE4KYI0p1f6CmSwtzyg-ZA) to get quick information how to use Beremiz IDE.

   208

   209

 * [Official documentation](http://beremiz.readthedocs.io/) is built from sources in doc directory.

   210

   Documentation does not cover all aspects of Beremiz use yet.

   211

   Contribution are very welcome!

   212

   213

 * [User manual](http://www.sm1820.ru/files/beremiz/beremiz_manual.pdf) from INEUM (Russian).

   214

   Be aware that it contains some information about functions available only in INEUM's fork of Beremiz.

   215

   216

 * [User manual](http://www.beremiz.org/LpcManager_UserManual.pdf) from Smarteh (English).

   217

   Be aware that it contains some information about functions available only in Smarteh's fork of Beremiz.

   218

   219

 * Outdated short [user manual](https://www.scribd.com/document/76101511/Manual-Beremiz#scribd) from LOLI Tech (English).

   220

   221

 * See official [Beremiz website](http://www.beremiz.org/) for more information.

   222