You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@plc4x.apache.org by cd...@apache.org on 2020/10/30 16:08:40 UTC
[plc4x] branch feature/plc4go updated: - Started updating the site
in preparation for the first getting-started guide fro go
This is an automated email from the ASF dual-hosted git repository.
cdutz pushed a commit to branch feature/plc4go
in repository https://gitbox.apache.org/repos/asf/plc4x.git
The following commit(s) were added to refs/heads/feature/plc4go by this push:
new c2999ce - Started updating the site in preparation for the first getting-started guide fro go
c2999ce is described below
commit c2999cebd9fdc2181b8f52ac14feb8f841b33511
Author: Christofer Dutz <ch...@c-ware.de>
AuthorDate: Fri Oct 30 17:08:32 2020 +0100
- Started updating the site in preparation for the first getting-started guide fro go
---
src/site/asciidoc/plc4go/index.adoc | 147 +++++++++++++++++++++
.../general-concepts.adoc | 0
.../plc4go.adoc} | 8 +-
.../plc4j.adoc} | 4 +-
.../{plc4j => getting-started}/virtual-modbus.adoc | 0
src/site/asciidoc/users/gettingstarted.adoc | 6 +-
src/site/site.xml | 7 +-
7 files changed, 162 insertions(+), 10 deletions(-)
diff --git a/src/site/asciidoc/plc4go/index.adoc b/src/site/asciidoc/plc4go/index.adoc
new file mode 100644
index 0000000..7396abe
--- /dev/null
+++ b/src/site/asciidoc/plc4go/index.adoc
@@ -0,0 +1,147 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one or more
+// contributor license agreements. See the NOTICE file distributed with
+// this work for additional information regarding copyright ownership.
+// The ASF licenses this file to You under the Apache License, Version 2.0
+// (the "License"); you may not use this file except in compliance with
+// the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+:imagesdir: ../images/
+
+== About PLC4Go
+
+`PLC4Go` is a sub-project of `PLC4X` with implementations based on `Go`.
+
+One of PLC4X's core principals is, that an application using PLC4X should be independent of the PLC or protocol being used.
+
+When addressing a resource on a remote there are two parts that are dependent on the protocol and the type of PLC:
+
+- Addressing the PLC itself
+- Addressing a resource on the PLC
+
+Providing this independence to addressing the PLC itself is completely handled by the `PlcDriverManager` the application requests a connection from.
+
+Hereby the design of the `url string` passed to the `getConnection` method is greatly inspired by `JDBC`.
+
+The protocol prefix of the url specifies the type of driver being used.
+
+For example, when connecting to a Siemens PLC using the S7/Step7 Protocol, the url: `s7://192.42.0.98/1/2` causes the driver manager to create a S7 connection instance.
+The part behind the `:` is hereby used by the driver implementation to configure that particular connection.
+
+For a S7 connection, for example, this is `IP address/host name`/`rack number`/`slot number`. For different types of connections this url structure will greatly differ.
+
+As mentioned above, the second platform dependent information is the address of resources on a PLC.
+The format of an address greatly depends on the type of connection. Therefore `parseAddress` is one of the only methods defined in the `PlcConnection` interface any connection has to implement.
+
+This method returns an object implementing the `Address` interface which then can be used by the same connection to identify remote resources.
+
+[ditaa,plc4x-architecture]
+....
++----------------------------------------------------------------------------------------------+
+|c05A |
+| |
+| User Application |
+| |
+| |
+| +-----------+------------------+------------------+------------------+------+
+| | | | | |
+| | | | | |
+| | v v v v
+| | +-------------+ +-------------+ +-------------+ +-------------+
+| | |c0BA | |c0BA | |c0BA | |c0BA |
+| | | Apache | | Apache | | Apache | | Apache |
+| | | Kafka | | Camel | | Edgent | | Nifi |
+| | | Connect | | Integration | | Integration | | Integration |
+| | | | | | | | | |
++---------+--------+ +------+------+ +------+------+ +------+------+ +------+------+
+ | | | | |
+ | | | | |
+ v v v v v
++----------------------------------------------------------------------------------------------+
+|cAAA |
+| |
+| PLC4X API |
+| |
+| |
++------+---------------+---------------+---------------+---------------+---------------+-------+
+ | | | | | |
+ | | | | | |
+ v v v v v v
+ +-----------+ +-----------+ +-----------+ +-----------+ +-----------+ +-----------+
+ |c0BA | |c0BA | |c0BA | |c0BA | |c0BA | |c05A |
+ | Siemens | | Beckhoff | | Modbus | | OPC UA | | Emerson | | User |
+ | S7 | | ADS | | Driver | | Driver | | DeltaV | | Driver |
+ | Driver | | Driver | | | | | | Driver | | |
+ | | | | | | | | | | | |
+ +-----------+ +-----------+ +-----------+ +-----------+ +-----------+ +-----------+
+....
+
+=== Usage
+
+Below code example connects to a remote Siemens S7 PLC using the S7/Step7 protocol and then reads the state of the `inputs` and `outputs` from this.
+
+[source,go]
+----
+func HellpPlc4go() {
+ driverManager := plc4go.NewPlcDriverManager()
+ driverManager.RegisterDriver(modbus.NewModbusDriver())
+ driverManager.RegisterTransport(tcp.NewTcpTransport())
+
+ // Get a connection to a remote PLC
+ crc := driverManager.GetConnection("modbus://192.168.23.30")
+
+ // Wait for the driver to connect (or not)
+ connectionResult := <-crc
+ if connectionResult.Err != nil {
+ t.Errorf("error connecting to PLC: %s", connectionResult.Err.Error())
+ return
+ }
+ connection := connectionResult.Connection
+
+ // Try to ping the remote device (This block is just optional)
+ pingResultChannel := connection.Ping()
+ pingResult := <-pingResultChannel
+ if pingResult.Err != nil {
+ t.Errorf("couldn't ping device: %s", pingResult.Err.Error())
+ return
+ }
+
+ // Make sure the connection is closed at the end
+ defer connection.Close()
+
+ // Prepare a read-request
+ rrb := connection.ReadRequestBuilder()
+ rrb.AddItem("field1", "holding-register:1:REAL")
+ rrb.AddItem("field2", "holding-register:3:REAL")
+ readRequest, err := rrb.Build()
+ if err != nil {
+ t.Errorf("error preparing read-request: %s", connectionResult.Err.Error())
+ return
+ }
+
+ // Execute a read-request
+ rrc := readRequest.Execute()
+
+ // Wait for the response to finish
+ rrr := <-rrc
+ if rrr.Err != nil {
+ t.Errorf("error executing read-request: %s", rrr.Err.Error())
+ return
+ }
+
+ // Do something with the response
+ value := rrr.Response.GetValue("field")
+
+ // Do something sensible with the information
+ fmt.Printf("\n\nResult: %f\n", value)
+}
+----
+
diff --git a/src/site/asciidoc/users/plc4j/general-concepts.adoc b/src/site/asciidoc/users/getting-started/general-concepts.adoc
similarity index 100%
rename from src/site/asciidoc/users/plc4j/general-concepts.adoc
rename to src/site/asciidoc/users/getting-started/general-concepts.adoc
diff --git a/src/site/asciidoc/users/plc4j/gettingstarted.adoc b/src/site/asciidoc/users/getting-started/plc4go.adoc
similarity index 96%
copy from src/site/asciidoc/users/plc4j/gettingstarted.adoc
copy to src/site/asciidoc/users/getting-started/plc4go.adoc
index 0b59388..e82c81d 100644
--- a/src/site/asciidoc/users/plc4j/gettingstarted.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4go.adoc
@@ -17,10 +17,10 @@
== Getting Started
-=== Using the PLC4X API directly
+=== Using the PLC4Go API directly
-In order to write a valid PLC4X Java application, all you need, is to add a dependency to the `api module`.
-When using Maven, all you need to do is add this dependency:
+In order to write a valid PLC4X Go application, all you need, is to add a dependency to the `plc4go module`.
+When using Go, all you need to do is add the following line to your `go.mod` file:
[subs=attributes+]
----
@@ -32,7 +32,7 @@ When using Maven, all you need to do is add this dependency:
----
This will allow you to write a valid application, that compiles fine.
-However in order to actually connect to a device using a given protocol, you need to add this protocol implementation to the classpath.
+However, in order to actually connect to a device using a given protocol, you need to add this protocol implementation to the classpath.
For example in order to communicate with an `S7 device` using the `S7 Protocol`, you would need to add the following dependency:
diff --git a/src/site/asciidoc/users/plc4j/gettingstarted.adoc b/src/site/asciidoc/users/getting-started/plc4j.adoc
similarity index 98%
rename from src/site/asciidoc/users/plc4j/gettingstarted.adoc
rename to src/site/asciidoc/users/getting-started/plc4j.adoc
index 0b59388..1a1507e 100644
--- a/src/site/asciidoc/users/plc4j/gettingstarted.adoc
+++ b/src/site/asciidoc/users/getting-started/plc4j.adoc
@@ -17,7 +17,7 @@
== Getting Started
-=== Using the PLC4X API directly
+=== Using the PLC4J API directly
In order to write a valid PLC4X Java application, all you need, is to add a dependency to the `api module`.
When using Maven, all you need to do is add this dependency:
@@ -32,7 +32,7 @@ When using Maven, all you need to do is add this dependency:
----
This will allow you to write a valid application, that compiles fine.
-However in order to actually connect to a device using a given protocol, you need to add this protocol implementation to the classpath.
+However, in order to actually connect to a device using a given protocol, you need to add this protocol implementation to the classpath.
For example in order to communicate with an `S7 device` using the `S7 Protocol`, you would need to add the following dependency:
diff --git a/src/site/asciidoc/users/plc4j/virtual-modbus.adoc b/src/site/asciidoc/users/getting-started/virtual-modbus.adoc
similarity index 100%
rename from src/site/asciidoc/users/plc4j/virtual-modbus.adoc
rename to src/site/asciidoc/users/getting-started/virtual-modbus.adoc
diff --git a/src/site/asciidoc/users/gettingstarted.adoc b/src/site/asciidoc/users/gettingstarted.adoc
index e1771d4..d0e83b1 100644
--- a/src/site/asciidoc/users/gettingstarted.adoc
+++ b/src/site/asciidoc/users/gettingstarted.adoc
@@ -19,6 +19,10 @@
Depending on the programming language, the usage will differ, therefore please go to the `Getting Started` version of the language of choice.
+//=== Go/Golang
+//
+//For guides on how to write PLC4X applications with Go, please go to the link:getting-started/plc4go.html[Go Getting Started]
+//
=== Java
-For guides on how to write PLC4X applications with Java, please go to the link:plc4j/gettingstarted.html[Java Getting Started]
\ No newline at end of file
+For guides on how to write PLC4X applications with Java, please go to the link:getting-started/plc4j.html[Java Getting Started]
\ No newline at end of file
diff --git a/src/site/site.xml b/src/site/site.xml
index f5bf84c..e2118ac 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -51,9 +51,10 @@
<item name="Download" href="users/download.html"/>
<item name="Adopters" href="users/adopters.html"/>
<item name="Getting Started" href="users/gettingstarted.html">
- <item name="Java" href="users/plc4j/gettingstarted.html"/>
- <item name="General Concepts" href="users/plc4j/general-concepts.html"/>
- <item name="Virtual Modbus" href="users/plc4j/virtual-modbus.html"/>
+ <!--item name="Go" href="users/getting-started/plc4go.html"/-->
+ <item name="Java" href="users/getting-started/plc4j.html"/>
+ <item name="General Concepts" href="users/getting-started/general-concepts.html"/>
+ <item name="Virtual Modbus" href="users/getting-started/virtual-modbus.html"/>
</item>
<item name="Blogs, Videos and Slides" href="users/blogs-videos-and-slides.html"/>
<item name="Protocols" href="users/protocols/index.html">