Apache PLC4X
============

Apache PLC4X is an effort to create a set of libraries for communicating with industrial grade programmable logic controllers (PLCs) in a uniform way.
We are planning on shipping libraries for usage in:

1) Java
2) Scala
3) C/C++

As well as provide direct integration into other Apache projects, such as:

1) Apache Calcite
2) Apache Camel
3) Apache Edgent
4) Apache Kafka-Connect
5) Apache Karaf
6) Apache NiFi


Environment
-----------

Currently the project is configured to require the following software:

1) Java 8 JDK: For running Maven in general as well as compiling the Java and Scala modules `JAVA_HOME configured to point to that.
2) libpcap/WinPcap for raw socket tests
3) (Optional) Graphwiz: For generating the graphs in the documentation (http://www.graphviz.org/)


Getting Started
---------------

You must have Java 8 installed on your system and connectivity to Maven Central
(for downloading external third party dependencies). Maven will be automatically
downloaded and installed by the maven wrapper `mvnw`.

Build PLC4X jars and install them in your local maven repository

$ ./mvnw install  # add -DskipTests to omit running the tests

You can now construct applications that use PLC4X. The PLC4X samples
are a good place to start and are available inside the `examples`
directory.


Installing libpcap/WinPcap
--------------------------

Some parts of PLC4X, especially the raw socket support, require installed versions
of libpcap/WinPcap.

You can download the Mac/Linux version from: http://www.tcpdump.org/
The windows version can be found here: https://sourceforge.net/projects/winpcap413-176/
(In order to read PCAPNG files we require a libpcap version 1.1.0 or greater. The default
Windows version is 1.0. At this location is a patched version based on libpcap 1.7.4)


Building the C++ libraries
--------------------------

When building the C++ libraries we require an installed `gcc` compiler.
On Mac and Linux this is usually the case.
On a minimal Ubuntu Linux system the following modules needed to be installed
manually:

- gcc
- g++
- make

On Windows the required compiler is generally not available per default.
The build is optimized for using a gcc-port called MinGW, available from
http://win-builds.org/doku.php/download_and_installation_from_windows
Make sure the `bin` directory containing the executable `mingw32-make.exe`
is on your systems `PATH`.


Licensing
---------

Apache PLC4X is released under the Apache License Version 2.0.

Apache PLC4X is an effort undergoing incubation at The Apache Software Foundation (ASF),
sponsored by the Incubator PMC. Incubation is required of all newly accepted
projects until a further review indicates that the infrastructure, communications,
and decision making process have stabilized in a manner consistent with other
successful ASF projects. While incubation status is not necessarily a reflection
of the completeness or stability of the code, it does indicate that the project
has yet to be fully endorsed by the ASF.