Metadata-Version: 1.2
Name: ioppytest-agent
Version: 0.1.8
Summary: Component for setting up user's environment for the tests
Home-page: https://gitlab.f-interop.eu/f-interop-contributors/agent
Author: Federico Sismondi
Author-email: federicosismondi@gmail.com
Maintainer: Federico Sismondi
Maintainer-email: federicosismondi@gmail.com
License: GPLv3+
Description: Agent for the f-interop platform (ioppytest-agent)
        --------------------------------------------------
        
        About
        -----
        Agent (~VPN client) is a component which connects the environment where
        the IUT runs to testing tool using the AMQP bus.
        This component is part of the ioppytest framework ecosystem.
        This components needs to run in the user's host and must share some
        kind on interface with the implementation under test (IUT), it will
        enable the creation of a private network between all devices in the
        session.
        
        
        Installation
        ------------
        
        create virtual env for not messing up your current environment
        ```
        pip install virtualenv
        virtualenv -p /usr/bin/python2.7 my_venv
        source my_venv/bin/activate
        ```
        
        install ioppytest-agent using pip
        ```
        pip install ioppytest-agent
        ```
        
        Design
        ------
        An agent is made of different processes that connect to AMQP message
        broker and exchange messages (in and out) with other components using
        the same AMQP broker.
        
        Note well
        ----
        Agent is only supported by python2 -> tun librarires py2 only
        
        Core
        ----
        When started, the agent starts up the core module. This component is in
        charge of launching all the other components.
        If new components needs to be added they just need to be launched
        from this component.
        
        Error handling
        --------------
        When there is a user interrupt signal (Ctrl-C) the agent should kill
        all other components and disconnect as gracefully as possible.
        
        
        Serial mode (with 802.15.4 probe)
        ---------------------------------
        The following diagram describes how the agent the interfaces and
        interactions using serial mode (--serial option)
        
        TODO:
        add link to source code for probe
        
        **IMPORTANT**:
        This mode of functioning assumes the following IEEE802.15.4 settings:
        
        1. Channel, modulation, data-rate (Channels 11-26 at 2.4 GHz).
        2. MAC mode is beaconless.
        3. Security is off
        
        
        # Agent combined with active-probe
        ----------------------------------
        This mode can be used for connecting two remote (geographically distant)
        802.15.4 based devices.
        
        Active mode probe automatically ACKs messages received by the user
        device, the 802.15.4 are not forwarded to the AMQP connection.
        
        ## Running the agent
        export AMQP connection variables, and USB params for the serial connection
        
        env vars:
        `
        export AMQP_EXCHANGE='amq.topic'
        export AMQP_URL="amqp://someUser:somePassword@f-interop.rennes.inria.fr/sessionXX"
        `
        
        check usb port, with for example with `ls /dev/tty*`
        
        `
        export FINTEROP_CONNECTOR_SERIAL_PORT=/dev/tty.XXX
        export FINTEROP_CONNECTOR_BAUDRATE=115200
        `
        
        then execute (e.g. for a coap_server running under the agent):
        `
        python -m agent connect  --url $AMQP_URL --name coap_server --serial
        `
        
        ```
        
                                   +----------------+
                                   |                |
                                   |   AMQP broker  |
                                   |                |
                                   |                |
                                   +----------------+
        
        
                                         ^     +
                                         |     |
        data.serial.fromAgent.agent_name |     | data.serial.toAgent.agent_name
                                         |     |
                                         +     v
        
                                   +----------------+
                                   |                |
                                   |                |
                                   |     Agent      |
                                   | (serial mode)  |
                                   |                |
                                   |                |
                                   +-------+--------+
                                           | USB interface
                                           | (SLIP protocol)
                                   +-------+--------+                        +---------------+
                                   |                |     802.15.4 frame     |               |
                                   |                |  <-----------------+   |   802.15.4    |
                                   |    probe mote  |                        |     user      |
                                   |  (active mode) |  +----------------->   |    device     |
                                   |                |                        |               |
                                   |                |                        |               |
                                   +----------------+                        +---------------+
        ```
        
        
        
        # Agent combined with passive-probe
        -----------------------------------
        This mode can be used for forwarding all sniffed packet in a 802.15.4 network to AMQP broker
        and eventually other tools listening to the correct routing keys/topics.
        
        ## Running the agent
        **TBD**
        
        ```
        
                                +----------------+
                                |                |
                                |   AMQP broker  |
                                |                |
                                |                |
                                +----------------+
        
                                         ^
                                         |
        data.serial.fromAgent.agent_name |
                                         |
                                         +
        
                                 +----------------+
                                 |                |
                                 |                |
                                 |     Agent      |
                                 | (serial mode)  |
                                 |                |
                                 |                |
                                 +-------+--------+
                                         | USB interface
                                         | (SLIP protocol)
                                 +-------+--------+
                                 |                |
                                 |                |
                                 |    probe mote  |
                                 |  (passive mode)|
                                 |                |
                                 |                |
                                 +-------+--------+
                                         |
                                         |
                                         |
                                         |
        +---------------+                |              +---------------+
        |               |                |              |               |
        |   802.15.4    |       <--------+--------+     |   802.15.4    |
        |     user      |         802.15.4 frames       |     user      |
        |    device     |       +----------------->     |    device     |
        |               |                               |               |
        |               |                               |               |
        +---------------+                               +---------------+
        
        ```
        
        
        
        IP tunneling mode (active-probe)
        --------------------------------
        This mode can be used for communicating two IPv6-based implementations
        tunneling all traffic through AMQP messages.
        
        ## Running the agent
        For running the agent you will need privileges on the machine, basically
        cause we need to open a virtual interface to tunnel the packets.
        
        The command for executing it will be provided to you by the
        GUI or AMQP broker sys admin, it should look something like this:
        
        ```
        sudo python -m agent connect  --url amqp://someUser:somePassword@f-interop.rennes.inria.fr/sessionXX --name coap_client
        ```
        
        for more info
        ```
        python agent.py --help
        python agent.py connect --help
        ```
        
        
        
        ```
                                  +----------------+
                                  |                |
                                  |   AMQP broker  |
                                  |                |
                                  |                |
                                  +----------------+
        
        
                                        ^     +
                                        |     |
        data.tun.fromAgent.agent_name   |     |  data.tun.toAgent.agent_name
                                        |     |
                                        +     v
        
                         +---------------------------------+
                         |                                 |
                         |               Agent             |
                         |                                 |
                         |             (tun mode)          |
                         |                                 |
                         |                                 |
                         |   +------tun interface--------+ |
                         |                                 |
                         |  +----------------------------+ |
                         |  |         IPv6-based         | |
                         |  |        communicating       | |
                         |  |      piece of software     | |
                         |  |      (e.g. coap client)    | |
                         |  |                            | |
                         |  +----------------------------+ |
                         +---------------------------------+
        
        ```
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
