Package: wotemu
WoTemuAn emulator for Python applications to help in the design ofIoT deploymentsbased on theedge computingmodel. It is focused on theWeb of Thingsparadigm by offering extended support for applications programmed withWoTPy.As an emulator, WoTemu demands significantly higher computation resources than simulators in the same domain, it is, however, able to run real code, which simplifies the design process and provides more meaningful insights into the target architecture.The main output of an emulation experiment is an HTML report describing the observed behaviour of the stack. Please see ademo report here.DesignThis project leveragesDocker Swarm Modeto offer simple horizontal scaling across heterogeneous nodes; this enables the emulation of scenarios with hundreds of actors.The following image shows a high-level view of a simple emulation stack. This serves to illustrate the main design choices behind WoTemu.All communications for the supported protocols (HTTP, CoAP, Websockets and MQTT) go through the networkgateways; these use NetEm to shape the traffic and emulate real network conditions. This redirection is based oniptablesand is invisible to the application.Allnodesreport their metrics to a central Redis store in a periodic fashion; this will be later used to build the final HTML report.Thanks to the capabilities of Docker Swarm, multiple replicas of a single node can be created easily and will automatically recover from errors.Nodescould be interpreted astemplates, while each replica is an actual real instance of the node.ADocker API proxyservice based onTecnativa/docker-socket-proxyis always deployed in amanagernode to enablenodesto access stack metadata (e.g. container IDs of other nodes in the same network).System requirementsPython 3.6+Docker Engine 20.10.0+ (swap limit capabilities should be enabled)Docker Compose 1.27.0+WoTemu(install withpip:pip install wotemu)Such a recent version of the Docker Engine is required to ensure thatcap_addis supported in Swarm Mode.QuickstartEmulation experiments are represented by instances ofwotemu.topology.models.Topology.The recommended workflow to run an experiment is as follows:Create aTopology.Build the Compose file that describes the stack of thatTopology.Run the stack on the Docker Swarm cluster.Stop the stack after an arbitrary amount of time.Build the final report from the collected data contained in the central Redis store.Please note that the commands in this section should be executed in a Swarmmanager.(Optional) Create a development Swarm clusterThere is aVagrantconfiguration file (Vagrantfile) in this repository that may be used to quickly create a Swarm cluster consisting of three virtual machines (onemanagerand twoworkers) for development and test purposes. All dependencies for WoTemu are installed in theprovision stage.Runvagrant upin your host to create and provision the three guest machines. Please note that you must manually run the/vagrant/scripts/join-swarm.shscript once in bothworker1andworker2to join the swarm.Describe the topologyTopologies can be defined in a Python file exposing atopologyfunction that takes no arguments and returns an instance ofTopology. The following is such an example:fromwotemu.enumsimportNetworkConditionsfromwotemu.topology.modelsimport(BuiltinApps,Network,Node,NodeApp,NodeResources,Topology)_SERVER_GIST="https://gist.github.com/agmangas/94cc5c3d9d5dcb473cff774b3522bbb6/raw"deftopology():network_3g=Network(name="3g",conditions=NetworkConditions.REGULAR_3G)node_server=Node(name="server",app=NodeApp(path=_SERVER_GIST,http=True),networks=[network_3g],scale=1)host_server="{}.{}".format(node_server.name,network_3g.name)app_reader=NodeApp(path=BuiltinApps.READER,params={"servient_host":host_server,"thing_id":"urn:wotemu:quickstart:thing"})node_reader=Node(name="reader",app=app_reader,networks=[network_3g],resources=NodeResources(mem_limit="150M"),scale=4)topology=Topology(nodes=[node_server,node_reader])returntopologyThere are two types of nodes here:Thereaderuses theREADERbuilt-inapplication, which takes a WoTPy Servient index URL (servient_host) and Thing ID (thing_id) as arguments and periodically reads all properties exposed by the Thing; this particular instance ofREADERis connected to theservernode. All replicas ofreaderare constrained to 150MB of memory.Theserveruses acustom application defined in a remote HTTP URLthat exposes a Thing with two properties.Both nodes are connected in a network that uses theREGULAR_3Gnetwork conditions. The four replicas ofreaderwill periodically read both properties from the single replica ofserveron a channel that displays the typical latency and bandwidth of a 3G connection.ApplicationsAnapplication(i.e. the code run by aNode) is a Python file that exposes anasynchronousappfunction that takes at least three positional arguments:VariableTypeDescriptionwotwotpy.wot.wot.WoTWoTPy WoT entrypoint decorated and pre-configured by WoTemu.confwotemu.config.EnvConfigEnvironment configuration that is currently active.loopasyncio.AbstractEventLoopLoop that is running the application.Thepathparameter of aNodeAppinstance should point to anapplication. There are three distinct options when setting the value ofpath:Using a WoTemu built-in application (e.g.BuiltinApps.READER).Using a remote HTTP URL.Using a local file path.Loading applications from the filesystem of a custom Docker image based onagmangas/wotemuis arguably themost versatile option. To that end, you may use the optionalimageparameter in theNodeclass (set toagmangas/wotemu:latestby default).Please note that although WoTemu does not impose any restrictions on what is actually executed in the application function, your code should follow theasynchronous I/O programming modelto avoid blocking the main thread (there are some WoTemu background processes running in the loop that is passed as argument).Deploy the stackA Compose file describing the emulation experiment can be created automatically from a topology file using thewotemu composeCLI command:wotemu compose --path ./examples/quickstart.pyThis stack may then be deployed to the Swarm cluster in the usual fashion:docker stack deploy -c ./examples/quickstart.yml quickstartBuild the final reportMetrics such as network packets, interactions or system usage data points will be periodically collected while the stack is active. The emulation stack can be stopped when the user considers that enough time has passed to gather a significant amount of data for the experiment:wotemu stop --compose-file ./examples/quickstart.yml --stack quickstartIt is necessary to stop the stack withwotemu stopinstead ofdocker stack rmto capture a final snapshot of the stack state and keep the Redis store online.An HTML report containing useful insights into the behaviour of the emulation stack can be then generated with the following command.wotemu report --out /report/ --stack quickstart