doc/programming/connect.rst
author Edouard Tisserant <edouard.tisserant@gmail.com>
Tue, 03 Dec 2024 21:22:45 +0100
changeset 4057 cf42c3dbdd5c
parent 3936 129202e555e0
permissions -rw-r--r--
IDE: Fix PLCOpenEditor (wxPython4 menus) and drop broken PDF doc support.
3925
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     1
Connect IDE to Runtime
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     2
======================
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     3
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     4
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     5
Connection is described by the *URI_location* in project's configuration.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     6
    ``Open project tree root -> Config tab -> URI_location``
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     7
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     8
eRPC
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
     9
----
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    10
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    11
`eRPC <https://github.com/embeddedrpc/erpc>`_ (Embedded RPC) is an open source
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    12
Remote Procedure Call (RPC) developed by NXP. 
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    13
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    14
In case of Beremiz, Runtime is the eRPC server and IDE is a client. Transport
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    15
can be either TCP/IP or Serial.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    16
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    17
``URI_location`` for eRPC:
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    18
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    19
    * ``ERPC://host[:port]`` unencrypted connection. Default port is 3000.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    20
        This connection is highly unsecure, and should never be used on
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    21
        untrusted network. It is intended to be used on peer to peer connection
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    22
        such as ethernet over USB, for initial pairing with IDE.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    23
    * ``ERPCS://host[:port]`` SSL-PSK encrypted connection.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    24
        Default port is 4000.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    25
    * ``LOCAL://`` starts local runtime and connect with it through TCP/IP
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    26
        bound to Localhost using random port.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    27
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    28
SSL-PSK setup:
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    29
^^^^^^^^^^^^^^
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    30
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    31
In order to provide practical secure communication in between runtime and IDE
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    32
TLS-PSK connection according to rfc4279.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    33
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    34
Server (runtime)
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    35
""""""""""""""""
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    36
.. highlight:: ini
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    37
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    38
PSK ciphersuite avoids the need for public key operations and certificate
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    39
management. It is perfect for a performance-constrained environments with
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    40
limited CPU power as a PLC.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    41
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    42
`Stunnel <https://www.stunnel.org/>`_ is used to wrap unencrypted eRPC server
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    43
into an TLS-PSK SSL socket. Hereafter is ``stunnel.conf``::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    44
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    45
    [ERPCPSK]
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    46
    accept = 4000
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    47
    connect = 127.0.0.1:3000
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    48
    ciphers = PSK
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    49
    sslVersion = TLSv1.2
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    50
    PSKsecrets = psk.txt
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    51
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    52
.. highlight:: text
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    53
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    54
List PSK ciphers available in server's openssl::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    55
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    56
    openssl ciphers -s -psk -tls1_2
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    57
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    58
Launch ``stunnel``::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    59
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    60
    stunnel ./stunnel.conf
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    61
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    62
Client (IDE) 
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    63
""""""""""""
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    64
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    65
Compare client's available openssl PSK ciphers with Server's ciphers. At least
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    66
a few of them should match::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    67
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    68
    openssl ciphers -s -psk -tls1_2
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    69
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    70
Use unencrypted peer-to-peer connection such as network over USB 
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    71
or simple Ethernet cable, connect an obtain PSK::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    72
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    73
    ERPC://hostname[:port]
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    74
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    75
Then use Identity Management dialog in IDE to select matching ID and generate
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    76
``ERPCS`` URI::
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    77
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    78
    ERPCS://hostname[:port]#ID
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    79
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    80
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    81
WAMP
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    82
----
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    83
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    84
`WAMP <https://wamp-proto.org/>`_ is an open standard WebSocket subprotocol that provides two application messaging 
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    85
patterns in one unified protocol: Remote Procedure Calls + Publish & Subscribe.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    86
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    87
Beremiz WAMP connector implementation uses python ``autobahn`` module, from the `crossbar.io <https://github.com/crossbario>`_ project.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    88
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    89
Both IDE and runtime are WAMP clients that connect to ``crossbar`` server through HTTP.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    90
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    91
``URI_location`` for WAMP:
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    92
	* ``WAMP://host[:port]#realm#ID`` Websocket over unencrypted HTTP transport.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    93
	* ``WAMPS://host[:port]#realm#ID`` Websocket over secure HTTPS transport.
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    94
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    95
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    96
..
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    97
    TODO : 
1d383b4c0a23 Doc: re-organize existing, sketch outline, add SVGHMI intro.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents:
diff changeset
    98
        crossbar server setup with example config and minimal backend.
3936
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
    99
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   100
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   101
About Security
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   102
--------------
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   103
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   104
 ..
129202e555e0 More documentation. Work in progress.
Edouard Tisserant <edouard.tisserant@gmail.com>
parents: 3925
diff changeset
   105
    TODO :