PLC-EMU is a Programmable Logic Controller EMUlator for automation applications on linux with digital/analog IO cards, with C functions, Ladder Diagrams,or IEC61131-compliant Instruction List/Structured Text. It is a cheap and open alternative to PLCs. 

### Table of contents
[OVERVIEW](#OVERVIEW)   
[DEPENDENCIES](#DEPENDENCIES)   
[YAML](#YAML)   
[Messaging](#Messaging )   
[INSTALLATION](#INSTALLATION)   
[CONFIGURATION](#CONFIGURATION)   
[INTERFACE](#INTERFACE)    
[Command Line](#CommandLine )    
[Distributed UI](#DistributedUI )  
[ISSUES](#ISSUES)  

# OVERVIEW

PLC-EMU stands for Programmable Logic Controller EMUlator. This means PLC-EMU is a tool for emulating PLCs on a Linux box, using I/O cards. This way you can build a cheap alternative to PLC's, for use with automation applications. 

# DEPENDENCIES

## LibreLogic
PLC-EMU is based around LibreLogic, a free PLC library.
See https://github.com/kalamara/librelogic for reference.


## NACS
The project configuration is done with NACS, Not Another Configuration System.
See https://github.com/kalamara/nacs for reference.


## Messaging 
From version 2 onwards there are extensions for network distribution. Serialization of all network messages is done in YAML format, and the messaging layer is implemented using ZeroMQ. 
Although networking extensions are disabled by default, to enable networking ZeroMQ is required.
See http://zeromq.org/ for details.

## Build system
CMAKE 2.22 is required. 
ninja is used but other build tools can also be supported.
Compilation is done currently on GCC 9 

## Operating system

Currently only Linux is supported.

# INSTALLATION 
Checkout a snapshot from github, or alternatively
download the tarball from www.sourceforge.net/projects/plcemu and unzip the source files in a directory. 

Then run 
./Config.sh to configure the sources and then ./Build.sh to build. 

This should create an executable named "plcemu" and a text file named "config.yml"


# CONFIGURATION

Edit a config.yml file, which holds configuration variables and 
their values in yml format. 

An example config.yml as included:

    STEP:         10        #time cycle in milliseconds
    PIPE:         plcpipe   #UNIX path of named pipe polled for commands

    #hardware
    HW:         STDI/O      #just a text tag that appears in a footer

    #user space interface:
    USPACE: 
    BASE:      50176            #hardware address base
    WR:        4               #write offset
    RD:        0                #read offset


    #COMEDI interface:
    COMEDI: 
    FILE:     0           #device and subdevice nodes of comedi driver.
    SUBDEV: 
        IN: 0
        OUT: 1
    

    #SIMULATION IO
    SIM: 
    INPUT:   sim.in
    OUTPUT:  sim.out

    #PROGRAM   
    PROGRAM:
    - 2 
    - INDEX: 0
      ID: "gcd.il"
    
    #Digital Inputs
    DI:
    - 16
    - INDEX: 0
      BYTE: 0
      ID: A
    - INDEX: 1
      BYTE: 0
      ID: B
    
    #Digital outputs
    DQ: 
    - 2
    - INDEX: 0
      BYTE: 0
      ID: OUTPUT
        
    #Memory registers (integers)
    MREG:
    - 4
    - INDEX: 0
      ID: RESULT
      VALUE: 64   
     
    - INDEX: 1
      ID: TEMP

    #Memory variables (real numbers) 
    MVAR:
    - 6
    - INDEX :     0    
      ID    :     N
      VALUE :     1.0
    - INDEX :     1    
      ID    : MEAN
    - INDEX :     2    
      ID    : M2
    - INDEX :     3    
      ID    : DELTA
    - INDEX :     4    
      ID    : ONE
      VALUE :      1.0
   
    #Timers
    TIMERS:
    - 2  
    - INDEX: 1
      RESOLUTION: 10
      PRESET: 10
    
    #Blinking timers        
    PULSES:
    - 2


Everything up to the PROGRAM tag, is system configuration.

The sequences from the PROGRAM tag onwards represent the logic blocks of the PLC. 
 
The number after the block name represents the size of the block sequence, ie. how many block instances are allocated.

The key - value pairs after the size are the blocks' parameters.

INDEX represents the position of the specific block in the sequence, eg. input 5 would have INDEX: 5  

ID is a unique string identifier for the specific block. 

The rest are block - specific parameters.

These parameters can be edited in runtime.


# INTERFACE

Executing plcemu from the command line

    Usage: plcemu [-c config file] [-h] 
    Options:
    -c uses a configuration file like the one described in section 5, other than config.yml
    -h displays this help file


## Command Line    
The default UI for version 2.0 onwards is command line based.

This is just a std prompt where the PLC's internal state in YAML format is monitored, while PLC commands can be issued. 

Supported commands:

   START   

start plc loop
   
   STOP   

stop plc loop
   
   HELP   

display help message

   QUIT  

close the UI

    EDIT <sequence><index><key: value>

Edit a configuration for any input, output or other sequence block.
The key: value pair can be any of the parameters in the configuration of the specific block.

    FORCE<sequence><index><value>

This will force a value on a sequence block for debugging purposes.

    UNFORCE<sequence><index>

Reverts the FORCE command.


### Distributed UI
Optionally any kind of UI and any number of UI instances can be connected over zeromq sockets, locally or remotely. 
The UI should continuously receive the PLC state in YML format in a PUB / SUB configuration, and asynchronously send commands in a REQUEST / REPLY fashion.


#### Example UI client
See cli-zmq.c for an example command line remote UI client that implements the same functionality as the default command line interface.

### Legacy (ncurses)
There are plans for reimplementing a ncurses based zeromq client with the same functionality as the legacy PLC-EMU UI. 
Currently no ncurses dependency exists.