edouard@3925: Connect IDE to Runtime
edouard@3925: ======================
edouard@3925: 
edouard@3925: 
edouard@3925: Connection is described by the *URI_location* in project's configuration.
edouard@3925:     ``Open project tree root -> Config tab -> URI_location``
edouard@3925: 
edouard@3925: eRPC
edouard@3925: ----
edouard@3925: 
edouard@3925: `eRPC <https://github.com/embeddedrpc/erpc>`_ (Embedded RPC) is an open source
edouard@3925: Remote Procedure Call (RPC) developed by NXP. 
edouard@3925: 
edouard@3925: In case of Beremiz, Runtime is the eRPC server and IDE is a client. Transport
edouard@3925: can be either TCP/IP or Serial.
edouard@3925: 
edouard@3925: ``URI_location`` for eRPC:
edouard@3925: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
edouard@3925:     * ``ERPC://host[:port]`` unencrypted connection. Default port is 3000.
edouard@3925:         This connection is highly unsecure, and should never be used on
edouard@3925:         untrusted network. It is intended to be used on peer to peer connection
edouard@3925:         such as ethernet over USB, for initial pairing with IDE.
edouard@3925:     * ``ERPCS://host[:port]`` SSL-PSK encrypted connection.
edouard@3925:         Default port is 4000.
edouard@3925:     * ``LOCAL://`` starts local runtime and connect with it through TCP/IP
edouard@3925:         bound to Localhost using random port.
edouard@3925: 
edouard@3925: SSL-PSK setup:
edouard@3925: ^^^^^^^^^^^^^^
edouard@3925: 
edouard@3925: In order to provide practical secure communication in between runtime and IDE
edouard@3925: TLS-PSK connection according to rfc4279.
edouard@3925: 
edouard@3925: Server (runtime)
edouard@3925: """"""""""""""""
edouard@3925: .. highlight:: ini
edouard@3925: 
edouard@3925: PSK ciphersuite avoids the need for public key operations and certificate
edouard@3925: management. It is perfect for a performance-constrained environments with
edouard@3925: limited CPU power as a PLC.
edouard@3925: 
edouard@3925: `Stunnel <https://www.stunnel.org/>`_ is used to wrap unencrypted eRPC server
edouard@3925: into an TLS-PSK SSL socket. Hereafter is ``stunnel.conf``::
edouard@3925: 
edouard@3925:     [ERPCPSK]
edouard@3925:     accept = 4000
edouard@3925:     connect = 127.0.0.1:3000
edouard@3925:     ciphers = PSK
edouard@3925:     sslVersion = TLSv1.2
edouard@3925:     PSKsecrets = psk.txt
edouard@3925: 
edouard@3925: .. highlight:: text
edouard@3925: 
edouard@3925: List PSK ciphers available in server's openssl::
edouard@3925: 
edouard@3925:     openssl ciphers -s -psk -tls1_2
edouard@3925: 
edouard@3925: Launch ``stunnel``::
edouard@3925: 
edouard@3925:     stunnel ./stunnel.conf
edouard@3925: 
edouard@3925: Client (IDE) 
edouard@3925: """"""""""""
edouard@3925: 
edouard@3925: Compare client's available openssl PSK ciphers with Server's ciphers. At least
edouard@3925: a few of them should match::
edouard@3925: 
edouard@3925:     openssl ciphers -s -psk -tls1_2
edouard@3925: 
edouard@3925: Use unencrypted peer-to-peer connection such as network over USB 
edouard@3925: or simple Ethernet cable, connect an obtain PSK::
edouard@3925: 
edouard@3925:     ERPC://hostname[:port]
edouard@3925: 
edouard@3925: Then use Identity Management dialog in IDE to select matching ID and generate
edouard@3925: ``ERPCS`` URI::
edouard@3925: 
edouard@3925:     ERPCS://hostname[:port]#ID
edouard@3925: 
edouard@3925: 
edouard@3925: WAMP
edouard@3925: ----
edouard@3925: 
edouard@3925: `WAMP <https://wamp-proto.org/>`_ is an open standard WebSocket subprotocol that provides two application messaging 
edouard@3925: patterns in one unified protocol: Remote Procedure Calls + Publish & Subscribe.
edouard@3925: 
edouard@3925: Beremiz WAMP connector implementation uses python ``autobahn`` module, from the `crossbar.io <https://github.com/crossbario>`_ project.
edouard@3925: 
edouard@3925: Both IDE and runtime are WAMP clients that connect to ``crossbar`` server through HTTP.
edouard@3925: 
edouard@3925: ``URI_location`` for WAMP:
edouard@3925: 	* ``WAMP://host[:port]#realm#ID`` Websocket over unencrypted HTTP transport.
edouard@3925: 	* ``WAMPS://host[:port]#realm#ID`` Websocket over secure HTTPS transport.
edouard@3925: 
edouard@3925: 
edouard@3925: ..
edouard@3925:     TODO : 
edouard@3925:         crossbar server setup with example config and minimal backend.