Skip to content

Commit 9c6e648

Browse files
splatchsplatch
committed
Update of fatek binding documentation.
Signed-off-by: Łukasz Dywicki <[email protected]>
1 parent 3e2b068 commit 9c6e648

File tree

18 files changed

+325
-16
lines changed

18 files changed

+325
-16
lines changed

‎bundles/org.connectorio.addons.binding.fatek/README.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# ConnectorIO® Fatek binding
2+
3+
This directory contains sources of Fatek binding which is compatible with openHAB project.
4+
5+
Rendered documentation is available at http://docs.connectorio.com.
6+
7+
Documentation sources are stored in this location [docs/fatek/fatek.adoc](docs/fatek/fatek.adoc)

‎bundles/org.connectorio.addons.binding.fatek/docs/examples/fatek/fatek.things

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Bridge co7io-fatek:tcp:my-connection "My PLC#1" [
2+
host="10.10.10.2",
3+
port=500
4+
] {
5+
6+
Thing plc station1 "Station 1 of PLC" [
7+
stationNumber=1
8+
] {
9+
Channels:
10+
Type discrete : X1 [ register="X", index=1 ]
11+
Type discrete : Y1 [ register="Y", index=1 ]
12+
Type discrete : M1 [ register="M", index=1 ]
13+
Type discrete : S1 [ register="S", index=1 ]
14+
Type discrete : T1 [ register="T", index=1 ]
15+
Type discrete : C1 [ register="C", index=1 ]
16+
}
17+
18+
}

‎bundles/org.connectorio.addons.binding.fatek/docs/examples/fatek/fatek.yaml

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
things:
3+
- kind: "Bridge"
4+
UID: "co7io-fatek:tcp:my-connection"
5+
label: "My PLC#1"
6+
configuration:
7+
host: "10.10.10.2"
8+
port: 500
9+
things:
10+
- id: "station1"
11+
type: "co7io-fatek:plc"
12+
label: "Station 1 of PLC"
13+
configuration:
14+
stationNumber: 1
15+
channels:
16+
- id: "X1"
17+
type: "discrete"
18+
configuration:
19+
index: 1
20+
register: "X"
21+
- id: "Y1"
22+
type: "discrete"
23+
configuration:
24+
index: 1
25+
register: "Y"
26+
- id: "M1"
27+
type: "discrete"
28+
configuration:
29+
index: 1
30+
register: "M"
31+
- id: "S1"
32+
type: "discrete"
33+
configuration:
34+
index: 1
35+
register: "S"
36+
- id: "T1"
37+
type: "discrete"
38+
configuration:
39+
index: 1
40+
register: "T"
41+
- id: "C1"
42+
type: "discrete"
43+
configuration:
44+
index: 1
45+
register: "C"

‎bundles/org.connectorio.addons.binding.fatek/docs/fatek/descriptors/bridge-types.adoc

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
2+
= Bridge types
3+
4+
[width="100%",cols="1,1,2"]
5+
|===
6+
|Bridge | Label ^|Description
7+
8+
| co7io-fatek:tcp
9+
| TCP Bridge
10+
| Connection to PLC via network socket.
11+
12+
<<co7io-fatek:tcp>>
13+
14+
| co7io-fatek:serial
15+
| Serial Bridge
16+
| Connection through RS232/RS485 or USB interfaces.
17+
18+
<<co7io-fatek:serial>>
19+
20+
|===
21+
22+
23+
[[co7io-fatek:tcp]]
24+
== Bridge `co7io-fatek:tcp`
25+
26+
Below table contains complete configuration of `co7io-fatek:tcp`.
27+
28+
29+
30+
31+
32+
[[co7io-fatek:serial]]
33+
== Bridge `co7io-fatek:serial`
34+
35+
Below table contains complete configuration of `co7io-fatek:serial`.
36+
37+
38+
39+
40+
41+

‎bundles/org.connectorio.addons.binding.fatek/docs/fatek/descriptors/channel-types.adoc

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
2+
= Channel types
3+
4+
[cols="1,2,4"]
5+
|===
6+
|Channel type | Label ^|Description
7+
8+
| co7io-fatek:discrete
9+
| Discrete register
10+
| Discrete register of connected PLC.
11+
12+
<<co7io-fatek:discrete>>
13+
14+
|===
15+
16+
17+
[[co7io-fatek:discrete]]
18+
== Configuration of `co7io-fatek:discrete`
19+
20+
Below table contain configuration parameters which can be assigned to channels of type `co7io-fatek:discrete`.
21+
22+
[width="100%",caption="Channel type discrete configuration",cols="1,1,1,2"]
23+
|===
24+
|Name | Type | Label ^|Description
25+
26+
| register
27+
| TEXT
28+
| Register symbol
29+
| Symbol (kind) of register to read
30+
31+
| index
32+
| INTEGER
33+
| Register index
34+
| Index of register used to retrieve data.
35+
36+
| invert
37+
| BOOLEAN
38+
| Invert
39+
| Invert logical representation of related register (0->1, 1->0).
40+
41+
|===
42+
43+
44+

‎bundles/org.connectorio.addons.binding.fatek/docs/fatek/descriptors/config-descriptions.adoc

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
2+
= Config descriptions
3+
4+
5+
[[channel-type:co7io-fatek:binary]]
6+
== Config `channel-type:co7io-fatek:binary`
7+
[width="100%",caption="channel-type:co7io-fatek:binary configuration",cols="1,1,1,2"]
8+
|===
9+
|Name | Type | Label ^|Description
10+
11+
| register
12+
| TEXT
13+
| Register symbol
14+
| Symbol (kind) of register to read
15+
16+
| index
17+
| INTEGER
18+
| Register index
19+
| Index of register used to retrieve data.
20+
21+
| invert
22+
| BOOLEAN
23+
| Invert
24+
| Invert logical representation of related register (0->1, 1->0).
25+
26+
|===
27+
28+

‎bundles/org.connectorio.addons.binding.fatek/docs/fatek/descriptors/thing-types.adoc

+32
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
2+
= Thing types
3+
4+
[width="100%",cols="1,1,2"]
5+
|===
6+
|Thing | Label ^|Description
7+
8+
| co7io-fatek:plc
9+
| Fatek PLC (FBs)
10+
| Fatek PLC communicating using facon protocol.
11+
12+
<<co7io-fatek:plc>>
13+
14+
|===
15+
16+
17+
[[co7io-fatek:plc]]
18+
== Thing `co7io-fatek:plc`
19+
20+
Below table contains complete configuration of `co7io-fatek:plc`.
21+
22+
Supported bridges:
23+
24+
* xref:./bridge-types.adoc#co7io-fatek:serial[co7io-fatek:serial]
25+
26+
* xref:./bridge-types.adoc#co7io-fatek:tcp[co7io-fatek:tcp]
27+
28+
29+
30+
31+
32+

‎bundles/org.connectorio.addons.binding.fatek/docs/fatek/fatek.adoc

+78
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
= Fatek / Facom
2+
3+
This binding integrates Taiwanese brand of PLC called Fatek.
4+
Fatek is recognized and known worldwide.
5+
One of this brand uniqueness comes from its own engineering software and programming in leather.
6+
7+
Fatek has its own protocol which description is published.
8+
This protocol is sometimes (quite rarely) named Facom.
9+
Since it is used only by this brand it remains proprietary to this firm.
10+
It is possible to interface Fatek with other systems through Modbus (supported by PLCs at no cost).
11+
There are several BUS couplers which allow to pair it with other equipment or even modems.
12+
13+
Facom can utilize several transports - most common ones are TCP and serial.
14+
Protocol payload remains the same.
15+
16+
.Fatek binding capability table
17+
|===
18+
|Device discovery| Channel discovery |Read | Write | Subscribe
19+
20+
|Yes
21+
|No
22+
|Yes
23+
|Yes
24+
|No
25+
|===
26+
27+
The Facom protocol does not provide a subscription operation.
28+
All states have to be polled in cyclic manner.
29+
30+
== Device discovery
31+
Binding supports an undocumented discovery feature of the protocol.
32+
It is able to detect all compatible devices within IP network through broadcasts.
33+
Once devices are found binding attempts to scan available station ids to identify reachable endpoints.
34+
35+
== Thing and Channel discovery
36+
Binding is able to discover _Thing_, with all necessary connection parameters, but it can not discover channels.
37+
38+
== Supported hardware
39+
While Facom seem to be a common protocol used across different product lines this binding is confirmed to work with Fatek FBs series.
40+
Other product groups have not been tested.
41+
Most of Fatek PLCs include serial port which can be used for programming.
42+
This port can be also used for serial communication and integration with binding.
43+
44+
In order to start reading data you need to create at least one `tcp` or `serial` connection (_Bridge_).
45+
The `tcp` connection usually rely on port 500, however it can be amended in PLC configuration.
46+
47+
Because of protocol limitations configuration needs to be prepared manually based on known register addresses.
48+
There are several kinds of addresses defined by protocol.
49+
50+
.Register kinds supported by Fatek binding:
51+
|===
52+
|Register |Description |Command/State type
53+
54+
| `X` | (DI) Digital input | `ON` and `OFF` (`OnOffType`)
55+
| `Y` | (DO) Digital output | `ON` and `OFF` (`OnOffType`)
56+
| `M` | Internal relay | `ON` and `OFF` (`OnOffType`)
57+
| `S` | Step relay | `ON` and `OFF` (`OnOffType`)
58+
| `T` | Timer contact | `ON` and `OFF` (`OnOffType`)
59+
| `C` | Counter contact | `ON` and `OFF` (`OnOffType`)
60+
|===
61+
62+
== Textual configuration
63+
64+
Below is example of a text configuration which you can use as a started.
65+
Keeping configuration in a file allows to use a regular version control system to track changes over time.
66+
The same can be done via user interface.
67+
68+
[source,indent=0,subs="verbatim,attributes",role="primary"]
69+
.dsl
70+
----
71+
include::{examplesdir}/fatek/fatek.things[]
72+
----
73+
74+
[source,yaml,indent=0,subs="verbatim,attributes",role="secondary"]
75+
.yaml
76+
----
77+
include::{examplesdir}/fatek/fatek.yaml[]
78+
----

‎bundles/org.connectorio.addons.binding.fatek/docs/index.adoc

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:examplesdir: ../examples/
2+
3+
include::fatek/fatek.adoc[]
4+
5+
include::descriptors/bridge-types.adoc[]
6+
include::descriptors/thing-types.adoc[]
7+
include::descriptors/channel-types.adoc[]
8+
include::descriptors/config-descriptions.adoc[]

‎bundles/org.connectorio.addons.binding.fatek/pom.xml

+4
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,10 @@
3232
<name>ConnectorIO - Addons - Binding - Fatek</name>
3333
<description>Fatek PLC integration.</description>
3434

35+
<properties>
36+
<documentation.reference>fatek</documentation.reference>
37+
</properties>
38+
3539
<dependencies>
3640
<dependency>
3741
<groupId>org.connectorio.addons</groupId>

‎bundles/org.connectorio.addons.binding.fatek/src/main/java/org/connectorio/addons/binding/fatek/config/BridgeConfig.java

-2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,4 @@
2121

2222
public abstract class BridgeConfig extends PollingConfiguration {
2323

24-
public int discoveryTimeToLive;
25-
2624
}

‎bundles/org.connectorio.addons.binding.fatek/src/main/java/org/connectorio/addons/binding/fatek/config/TcpBridgeConfig.java

+1-2
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,9 @@
1717
*/
1818
package org.connectorio.addons.binding.fatek.config;
1919

20-
import org.connectorio.addons.binding.config.PollingConfiguration;
2120
public class TcpBridgeConfig extends BridgeConfig {
2221

23-
public String hostAddress;
22+
public String host;
2423
public int port;
2524
public int connectionTimeout;
2625
}

‎bundles/org.connectorio.addons.binding.fatek/src/main/java/org/connectorio/addons/binding/fatek/internal/handler/FatekTcpBridgeHandler.java

+3-5
Original file line numberDiff line numberDiff line change
@@ -20,15 +20,13 @@
2020
import java.io.IOException;
2121
import java.util.concurrent.CompletableFuture;
2222
import java.util.concurrent.CompletionStage;
23-
import java.util.concurrent.Executor;
2423
import java.util.concurrent.ExecutorService;
2524
import java.util.concurrent.Executors;
2625
import org.connectorio.addons.binding.fatek.internal.transport.JFatekTcpFaconConnection;
2726
import org.connectorio.addons.binding.fatek.transport.FaconConnection;
2827
import org.connectorio.addons.binding.handler.GenericBridgeHandlerBase;
2928
import org.connectorio.addons.binding.fatek.config.TcpBridgeConfig;
3029
import org.connectorio.addons.binding.fatek.internal.discovery.DiscoveryCoordinator;
31-
import org.openhab.core.common.ThreadPoolManager;
3230
import org.openhab.core.thing.Bridge;
3331
import org.openhab.core.thing.ChannelUID;
3432
import org.openhab.core.thing.ThingStatus;
@@ -64,7 +62,7 @@ public void initialize() {
6462
}
6563

6664
scheduler.execute(() -> {
67-
if (config.hostAddress == null || config.hostAddress.trim().isEmpty()) {
65+
if (config.host == null || config.host.trim().isEmpty()) {
6866
updateStatus(ThingStatus.OFFLINE, ThingStatusDetail.CONFIGURATION_PENDING, "Missing host address");
6967
return;
7068
}
@@ -73,10 +71,10 @@ public void initialize() {
7371
return;
7472
}
7573
int timeout = config.connectionTimeout != 0 ? config.connectionTimeout : 5000;
76-
executor = Executors.newFixedThreadPool(2, (runnable) -> new Thread(runnable, "fatek-connection-" + config.hostAddress));
74+
executor = Executors.newFixedThreadPool(2, (runnable) -> new Thread(runnable, "fatek-connection-" + config.host));
7775

7876
try {
79-
JFatekTcpFaconConnection faconConnection = new JFatekTcpFaconConnection(executor, config.hostAddress, config.port, timeout);
77+
JFatekTcpFaconConnection faconConnection = new JFatekTcpFaconConnection(executor, config.host, config.port, timeout);
8078
this.refreshInterval = config.refreshInterval;
8179
connection.complete(faconConnection);
8280
updateStatus(ThingStatus.ONLINE);

‎bundles/org.connectorio.addons.binding.fatek/src/main/resources/OH-INF/thing/bridge.xml

+3-3
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,9 @@
2626
<description>Connection to PLC via network socket.</description>
2727

2828
<config-description>
29-
<parameter name="hostAddress" type="text" required="true">
30-
<label>Hot address</label>
31-
<description>Server address to which binding should connect to receive data.</description>
29+
<parameter name="host" type="text" required="true">
30+
<label>Host address</label>
31+
<description>Server address to which binding should connect to receive data, IP or hostname.</description>
3232
<context>network</context>
3333
</parameter>
3434
<parameter name="port" type="integer" required="true">

0 commit comments

Comments
 (0)