r@1455: Beremiz and Beremiz_service connectors 
r@1455: ======================================
r@1455: 
r@1455: To connect a PLC, Beremiz provides 2 types of connectors :
r@1455:  * a Pyro connector
r@1455:  * a WAMP connector
r@1455: 
r@1455: To configure the connection, you have to set the *URI_location* in your project Config tab according to this documentation. 
r@1455: 
r@1455: The Pyro connector
r@1455: ----------------------------
r@1455: 
r@1455: Pyro is an advanced and powerful Distributed Object Technology system written entirely in Python.
r@1455: Beremiz_service spawns a Pyro server, serving a PLCObject (see runtime/PLCObject.py). Therefore, Beremiz acts as a Pyro client.
r@1455: 
r@1455: TODO:: link to PLCObject API documentation
r@1455: 
r@1455: URI_location :
r@1455:  * LOCAL:// is a facility that starts the PLC service locally and connect Beremiz to it via Pyro.
r@1455:    This is intended for use in development stage.
r@1455:  * PYRO://<ip:port> normal connection to a remote PLC. PLC default port is 3000.
r@1455:  * PYROS://<ip:port> SSL connection to a remote PLC, see below.
r@1455: 
r@1455: more information about Pyro can be found on http://pythonhosted.org//Pyro/1-intro.html
r@1455: 
r@1455: ===========================
r@1455: Setup a Pyro SSL connection
r@1455: ===========================
r@1455: 
r@1455: Pyro v3 has a limited TLS/SSL support based on m2crypto. Pyro v4 had dropped it.
r@1455: In order to have a full and reliable SSL, we recommand to use a TLS/SSL wrapper as nginx, stub or stunnel.
r@1455: 
r@1455: --------------------
r@1455: TLS-PSK with stunnel
r@1455: --------------------
r@1455: 
r@1455: In this example, we setup a simple TLS-PSK connection according to rfc4279.
r@1455: This ciphersuite avoid the need for public key operations and certificate management.
r@1455: It is perfect for a performance-constrained environments with limited CPU power as a PLC.
r@1455: 
r@1455: 
r@1455: Needed :
r@1455:  * stunnel >= 5.09
r@1455: 
r@1455: verify openssl support for PSK cipher::
r@1455: 
r@1455:     openssl ciphers -v 'PSK'
r@1455: 
r@1455: ----------------------
r@1455: Client setup (Beremiz)
r@1455: ----------------------
r@1455: 
r@1455: You need to choose an identity for your client, here *client1*.
r@1455: generate a valid and strong key::
r@1455: 
r@1455:     $ echo client1:$(openssl rand -base64 48) > pskclient1.txt
r@1455: 
r@1455: write a stunnel client configuration file *stunnel-client.conf*::
r@1455: 
r@1455:     output = stunnel-client.log
r@1455:     client = yes
r@1455:     
r@1455:     [beremiz]
r@1455:     accept = 3002
r@1455:     connect = [PLC]:3001
r@1455:     PSKidentity = client1
r@1455:     PSKsecrets = pskclient1.txt
r@1455: 
r@1455: start stunnel client side::
r@1455: 
r@1455:     stunnel stunnel-client.conf
r@1455: 
r@1455: You could now connect beremiz with classic URI_location = PYRO://127.0.0.1:3002
r@1455: 
r@1455: --------------------
r@1455: Server setup (PLC)
r@1455: --------------------
r@1455: 
r@1455: import the client key in a keyfile psk.txt, concatening all client key.
r@1455: 
r@1455: write a stunnel server  configuration file *stunnel-server.conf*::
r@1455: 
r@1455:     output = stunnel-server.log
r@1455:     
r@1455:     [beremiz]
r@1455:     accept = 3001
r@1455:     connect = 127.0.0.1:3000
r@1455:     PSKsecrets = psk.txt
r@1455: 
r@1455: start stunnel server side::
r@1455: 
r@1455:     stunnel stunnel-server.conf
r@1455:     
r@1455: more documentation on stunnel http://www.stunnel.org/docs.html
r@1455: 
r@1455: The WAMP connector
r@1455: ------------------
r@1455: 
r@1455: WAMP is an open standard WebSocket subprotocol that provides two application messaging 
r@1455: patterns in one unified protocol: Remote Procedure Calls + Publish & Subscribe.
r@1455: 
r@1455: Beremiz WAMP connector implementation uses Autobahn and crossbar.
r@1455: 
r@1455: URI_location :
r@1455: 	* WAMP://127.0.0.1:8888#Automation#2534667845
r@1455: 
r@1455: more information about WAMP can be found on http://wamp.ws/