gmlc-tdc / helics-ns3

ns-3 module for integrating with a HELICS co-simulation

helics-ns3

This version of the helics-ns3 module WILL NOT WORK with ns-3.36 or newer. Use ns-3.35 (or slightly older). It uses the WAF contrib build system, and ns-3 switched build systems from WAF to CMake for version 3.36, along with making other breaking changes to their code.

It is recommended to update to the latest versions of helics-ns3 and ns-3; older versions using WAF will not be supported/maintained.

helics-ns3 is an ns-3 module for coupling network simulations with other simulators using HELICS.

Older versions of HELICS and/or ns-3

For the last supported releases with older versions of HELICS and ns-3, look for the tags starting with HELICS-vand match the HELICS version with the build system (waf or cmake). Or look at the Releases page and find the most recent release for your version of HELICS and ns-3 build system.

For HELICS 3 and ns-3 using waf, HELICS-v3.x-cmake is the last tagged release.

For HELICS 2 and ns-3 using CMake, HELICS-v2.x-cmake is the last tagged release.

For HELICS 2 and ns-3 using waf, HELICS-v2.x-waf is the last tagged release.

For HELICS 1 (upgrade highly recommended), ns-3 using CMake is not supported; the final tag is HELICS-v1.3.x.

Prerequisites

Install version 3+ of HELICS; for building from source, be sure to set the CMake variable -DHELICS_BUILD_CXX_SHARED_LIB=ON and -DCMAKE_INSTALL_PREFIX=<path to install folder you have access to>.

Get a copy of ns-3.35 (slightly older may also work).

Git:

git clone -b ns-3.35 https://gitlab.com/nsnam/ns-3-dev.git

Installation

Clone a copy of this repository into a folder named helics in the ns-3 contrib directory. The module directory name must be helics, otherwise the ns-3 build system will be confused.

cd ns-3-dev/
git clone https://github.com/GMLC-TDC/helics-ns3 contrib/helics

Run ./waf configure with the --disable-werror option, and set the --with-helics option to the path of your HELICS installation. To enable examples or tests use --enable-examples or --enable-tests, respectively. If ZMQ is not found, --with-zmq can be used to specify where it is installed. Paths should be absolute.

After configuration is done, run ./waf build to compile ns-3 with the HELICS module.

./waf configure --with-helics=/usr/local --disable-werror --enable-examples --enable-tests
./waf build

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please see CONTRIBUTING for some additional notes on licensing of new components and modifications.

Release

The helics-ns3 repository is distributed under the terms of the GPL-v2 license as required by NS3 since this library derives some code from that code base.

Individual source files that do not require derivation from NS3 are licensed as BSD style. Any contributions to non-NS3 derived files ideally should be made with BSD markings in the source file. At some point in the future if legally allowed or the NS-3 derived components can be removed the repository will be relicensed.

SPDX-License-Identifier: GPL-v2

helics-ns3's Issues

LTE protocol doesn't assign IPs to user equipment

By design in the LTE protocol, user equipment (cell-phones, smart meters,...) are not assigned an IP. (See ns-3 documentation.) Looking through helics-helper.cc, it appears that the HelicsHelper::InstallStaticSource, HelicsHelper::InstallStaticSink and HelicsHelper::InstallFilter methods all assume an IPv4 address will be available. This will not be true for most of the nodes of interest in an LTE network.

Explore switching to HELICS shared c++ library

Look into switching from using helics-static to using the shared C++ HELICS library, helics-shared. This could potentially avoid requiring finding static library dependencies, without users needing to change any of their code -- along with being able to update to newer versions of HELICS without recompiling.

error: ‘class helics::MessageFederate’ has no member named ‘SendMessage’

Hi, everyone.
When I try to install helics-ns3 and input the command ./waf configure --with-helics=/usr/local --disable-werror --enable-examples --enable-tests, I encounter errors like
../contrib/helics/examples/fed-filter.cc:61:15: error: ‘class helics::MessageFederate’ has no member named ‘SendMessage’; did you mean ‘getMessage’? | mFed->SendMessage(idsource, name+"/"+dstEndpoint, message.data(), message.size()); | ^~~~~~~~~~~ | getMessage
I think that the errors are due to version issues and some function names are changed, but I can't deal with the issue above.
The versions of helics and ns-3 in my system are respectively 3.4.0 and 3.35.
Can you give me some hints to debug this problems?

Thank you in advance.

Add ns-3 module release for HELICS 1.3.x

Add a release (and tag?) the current state of the module as being for HELICS v1.3.x, and a note about which versions of ns-3 it is compatible with.

No written documentation building ns-3

As of this writing, there is no written documentation on how to build ns-3. The YouTube video tutorial video Jeff did does have an example command line that may or may not be correct. As might be expected, this makes building ns-3 difficult.

Make sure helics-ns3 used by ns-3 spack package matches HELICS version used

The spack ns-3-dev package will need the helics variant updated with constraints on the version of HELICS to ensure a compatible helics-ns3 module is used.

Boost Filesystem build error

On April 4th the nightly CI builds started failing -- it seems to be an issue with the Boost Filesystem library. Around that time it looks like there was a change to the Ubuntu images on Azure that made Boost 1.69 the default. Removing use of Boost Filesystem as part of GMLC-TDC/HELICS#605 should fix the error.

ns-3 filters not working

While simulating the ns-3 filter example (examples/ns3-filter.cc and examples/fed-filter.cc), the federate sends and receives the messages, without it passing through ns-3, even though the end point names in ns-3 match the end points in the federate. This example was tried with no modification from the user.
Versions:
ns-3 source: https://github.com/nsnam/ns-3-dev-git
helics-ns3: Branch: HELICS_2_0
HELICS-src: Tag/v2.0.0-rc1
The simulation was run using these commands -
In terminal 1: helics_broker --federates 2
In terminal 2: From ns-3 source, ./waf --run scratch/ns-3 filter
In terminal 3: From ns-3 source, ./waf --run scratch/fed-filter
The following warning was found in ns-3 log for endpoint 1 and 2 -

issues are not getting created

Helics Helper: helics_federate as a singleton

helics_federate seems like it is intended to be a singleton, but there are no checks in the SetupFederate helper methods to make sure that an existing federate hasn't already been created.

Why copy message between helics applications?

I have been reviewing HELICS as a potential enabler for some large scale ns-3 sims. Going through the sample applications I noticed that the HelicsApplication seemingly copies the message from the source application to the sink application (from the NS-3 perspective) while also sending the same message as a packet through the simulation. Did I misread the code? Is this intentional? If the simulation loses the packet (due to a lossy medium) does the Helics message map grow without bound?

in ubuntu for configure ns3 PyViz visualizer not enabled

Add support for building with CMake

ns-3 merged support for building with CMake on December 1st!

No more waf weirdness! Well, that's probably sticking around for a while, but supporting CMake could make some use cases much easier.

The minimum CMake version we should target is 3.10 to match the minimum version ns-3 allows. For a first pass, helics-ns3 should be able to build as a contrib module like it currently does with the ns-3 build system in charge of the actual build.

Eventually, helics-ns3 should be decoupled from building as a contrib module and should be able to work as a standalone project that uses find_package to locate an already compiled/installed copy of ns-3; this may require some changes to the upstream ns-3 build system to make sure it properly installs compiled ns-3 libraries/headers.

If this works, then package managers (e.g. spack) with ns-3 will work as a way to install ns-3 for building helics-ns3, and helics-ns3 could become a separate spack package that is easy to install and reuse. With the contrib module system this wasn't possible due to contrib modules not being able to build as part of spack compiling ns-3.

Repo Needs a license file

There is no license file in the repository, we need to add one, Not entirely sure if this needs to propagate from the NS-3 license or we can use the BSD 3 clause one we use in the other repositories.

helics-shared library not found

After installing HELICS, I have libhelicsSharedLib.so under the lib directory. However, the wscript search for helics-shared, which will cause a configuration error. Should I change helics-shared to helicsSharedLib in wscript? Or is there anything wrong with my HELICS installation? Thanks!

Search lib64 directory for helics library

Search the lib64 directory in addition to the lib directory for helics

How to use one node to send packets to different destinations

I am trying to create a network with multiple python programs simulating physical network connected devices that can send data to each other via ns3. Let's say, program 1 needs to send some data to program 2 and some other data to program 3. Does program 1 need to connect via HELICS to two different ns-3 nodes so that the data can be routed to the correct destination node? Is there any way to link program 1 to one ns-3 node to send data to two different destinations?

ns-3 build failure

Describe the bug
When building ns-3 with HELICS integration the build fails to build the helics-filter-application

To Reproduce
Attempt to build ns-3 with HELICS integration

Environment:

• Operating System: Mac OS X 10.12.6
• Language Extension: python 2.7.10
• Compiler: Apple LLVM version 8.0.0 (clang-800.0.42.1)
• HELICS version: 1.3.1 (09-23-18)
• ZMQ version: 4.2.5
• Boost version: 1.67.0

Additional context and information

configure command: ./waf configure --prefix=/Users/hard312/testbeds/HELICS_testbed --enable-examples --with-helics=/usr/local/ --boost-includes=/usr/local/include --boost-libs=/usr/local/lib --with-zmq=/usr/local/ --python=/usr/bin/python

configure output:Setting top to : /Users/hard312/source/HELICS-ns-3-dev-git
Setting out to : /Users/hard312/source/HELICS-ns-3-dev-git/build
Checking for 'clang' (C compiler) : /usr/bin/clang
Checking for cc version : 8.0.0
Checking for 'clang++' (C++ compiler) : /usr/bin/clang++
Checking for compilation flag -std=c++11 support : ok
Checking for program 'python' : /usr/bin/python
Checking for python version : (2, 7, 10, 'final', 0)
python-config : /usr/bin/python-config
Asking python-config for pyembed '--cflags --libs --ldflags' flags : yes
Testing pyembed configuration : yes
Asking python-config for pyext '--cflags --libs --ldflags' flags : yes
Testing pyext configuration : yes
Checking for compilation flag -Wno-array-bounds support : ok
Checking for pybindgen location : not found
Checking for python module 'pybindgen' : not found
pybindgen missing => no python bindings
Checking boost includes : 1_67
Checking boost libs : ok
Checking for boost linkage : ok
Checking for click location : not found
Checking for program 'pkg-config' : /usr/local/bin/pkg-config
Checking for 'gtk+-2.0' >= 2.12 : not found
Checking for 'libxml-2.0' >= 2.7 : yes
Checking for type uint128_t : not found
Checking for type __uint128_t : yes
Checking high precision implementation : 128-bit integer (default)
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for header sys/types.h : yes
Checking for header sys/stat.h : yes
Checking for header dirent.h : yes
Checking for header stdlib.h : yes
Checking for header signal.h : yes
Checking for header pthread.h : yes
Checking for header stdint.h : yes
Checking for header inttypes.h : yes
Checking for header sys/inttypes.h : not found
Checking for library rt : not found
Checking for header sys/ioctl.h : yes
Checking for header net/if.h : yes
Checking for header net/ethernet.h : yes
Checking for header linux/if_tun.h : not found
Checking for header netpacket/packet.h : not found
Checking for NSC location : not found
Checking for OpenFlow location : not found
Checking for 'sqlite3' : yes
Checking for header linux/if_tun.h : not found
Checking boost includes : 1_67
Checking boost libs : ok
Checking for boost linkage : ok
Checking for libzmq.so location : /usr/local/ (given)
Checking for HELICS location : /usr/local/ (given)
Checking for library zmq : yes
Checking for library helics-static : yes
['-O0', '-ggdb', '-g3', '-Wall', '-Werror', '-Wno-unused-local-typedefs', '-Wno-potentially-evaluated-expression', '-std=c++14']
Checking for program 'sudo' : /usr/bin/sudo
Checking for program 'valgrind' : /usr/local/bin/valgrind
Checking for 'gsl' : yes
python-config : not found
Checking for program 'doxygen' : not found
---- Summary of optional NS-3 features:
Build profile : debug
Build directory :
BRITE Integration : not enabled (BRITE not enabled (see option --with-brite))
DES Metrics event collection : not enabled (defaults to disabled)
Emulation FdNetDevice : not enabled (needs netpacket/packet.h)
Examples : enabled
File descriptor NetDevice : enabled
GNU Scientific Library (GSL) : enabled
Gcrypt library : not enabled (libgcrypt not found: you can use libgcrypt-config to find its location.)
GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)
HELICS Integration : enabled
MPI Support : not enabled (option --enable-mpi not selected)
NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick))
NS-3 OpenFlow Integration : not enabled (OpenFlow not enabled (see option --with-openflow))
Network Simulation Cradle : not enabled (NSC not found (see option --with-nsc))
PlanetLab FdNetDevice : not enabled (PlanetLab operating system not detected (see option --force-planetlab))
PyViz visualizer : not enabled (Python Bindings are needed but not enabled)
Python Bindings : not enabled (PyBindGen missing)
Real Time Simulator : not enabled (librt is not available)
SQlite stats data output : enabled
Tap Bridge : not enabled (<linux/if_tun.h> include not detected)
Tap FdNetDevice : not enabled (needs linux/if_tun.h)
Tests : not enabled (defaults to disabled)
Threading Primitives : enabled
Use sudo to set suid bit : not enabled (option --enable-sudo not selected)
XmlIo : enabled
ZMQ Integration : enabled
'configure' finished successfully (3.062s)

build error message: In file included from ../contrib/helics/model/helics-filter-application.cc:5:
./ns3/log.h:486:12: error: call to function 'operator<<' that is neither visible in the template definition nor found by argument-dependent lookup
m_os << param;
^
../contrib/helics/model/helics-filter-application.cc:71:47: note: in instantiation of function template specialization 'ns3::ParameterLogger::operator<<helics::Message' requested here
NS_LOG_FUNCTION (this << id.value() << time << *message);
^
./ns3/helics.h:15:15: note: 'operator<<' should be declared prior to the call site or in namespace 'helics'
std::ostream& operator << (std::ostream& stream, const helics::Message &message);
^
1 error generated.

Waf: Leaving directory `/Users/hard312/source/HELICS-ns-3-dev-git/build'
Build failed
-> task in 'ns3-helics' failed (exit status 1):
{task 4519280088: cxx helics-filter-application.cc -> helics-filter-application.cc.1.o}
['/usr/bin/clang++', '-O0', '-ggdb', '-g3', '-Wall', '-Werror', '-Wno-unused-local-typedefs', '-Wno-potentially-evaluated-expression', '-std=c++14', '-fPIC', '-I.', '-I..', '-I/usr/local/Cellar/gsl/2.5/include', '-I/usr/local/include', '-I/usr/local/include/helics', '-DNS3_BUILD_PROFILE_DEBUG', '-DNS3_ASSERT_ENABLE', '-DNS3_LOG_ENABLE', '-DHAVE_SYS_IOCTL_H=1', '-DHAVE_IF_NETS_H=1', '-DHAVE_NET_ETHERNET_H=1', '-DHAVE_GSL=1', '-DHAVE_SQLITE3=1', '-DNS3_HELICS', '-DHAVE_ZMQ', '../contrib/helics/model/helics-filter-application.cc', '-c', '-o', '/Users/hard312/source/HELICS-ns-3-dev-git/build/contrib/helics/model/helics-filter-application.cc.1.o']

SetupFederate helper function should initialize helics_federate as a singleton

The HELICS helper SetupFederate function currently creates a new federate each time it gets called. There should be a check to see if it has already been initialized before creating a new federate.

Change LoadFederateInfo function call to loadFederateInfo

After the json configuration changes get merged into develop, the function name will change from LoadFederateInfo to loadFederateInfo.

Generate Python Bindings

Generate Python bindings for the HELICS ns-3 module, so that it will work with PyViz.

For details on creating Python bindings for an ns-3 module: https://www.nsnam.org/wiki/Python_bindings#The_semi-automatic_way

Looking for examples

I found various cc and h files in the repository, but I'm not sure exactly how to build them, or what to do afterwards. Can you please point me to an example that runs under HELICS?

NS3 HELICS Build error

Describe the bug
Building NS3 with HELICS fails at helics-helper.cc

To Reproduce
Attempt to build ns-3 with HELICS integration

Env
OS: RHEL7
Compiler: GCC 4.9 and GCC 6.3
HELICS: 1.3.1
Boot: 1.63

Configure Command
CXXFLAGS="-W -Wall -g" ./waf configure -d debug --prefix=/home/USER/projects/cid/ns3-helics/ns3-helics-install-6_3 --enable-examples --with-helics=/home/USER/projects/cid/gld/helics-install --boost-includes=/include --boost-libs=/lib

Build Error
Waf: Entering directory `/home/USER/projects/cid/ns3-helics/ns3-helics/build'
[1981/2300] Compiling contrib/helics/helper/helics-helper.cc
In file included from ./ns3/packet.h:24:0,
from ./ns3/net-device.h:28,
from ./ns3/node.h:29,
from ./ns3/application.h:28,
from ./ns3/application-container.h:26,
from ../contrib/helics/helper/helics-helper.cc:4:
./ns3/buffer.h: In constructor 'ns3::Buffer::Iterator::Iterator(const ns3::Buffer*, bool)':
./ns3/buffer.h:828:55: warning: unused parameter 'dummy' [-Wunused-parameter]
Buffer::Iterator::Iterator (Buffer const*buffer, bool dummy)
^~~~~
In file included from /home/USER/projects/cid/gld/helics-install/include/helics/application_api/Federate.hpp:13:0,
from /home/USER/projects/cid/gld/helics-install/include/helics/application_api/MessageFederate.hpp:8,
from /home/USER/projects/cid/gld/helics-install/include/helics/application_api/CombinationFederate.hpp:8,
from /home/USER/projects/cid/gld/helics-install/include/helics/helics.hpp:14,
from ./ns3/helics.h:8,
from ../contrib/helics/helper/helics-helper.cc:9:
./ns3/log.h: At global scope:
/home/USER/projects/cid/gld/helics-install/include/helics/application_api/../flag-definitions.h:52:25: error: expected identifier before numeric constant
#define LOG_LEVEL_ERROR 0
^
./ns3/log.h:94:3: note: in expansion of macro 'LOG_LEVEL_ERROR'
LOG_LEVEL_ERROR = 0x00000001, //!< LOG_ERROR and above.
^~~~~~~~~~~~~~~
/home/USER/projects/cid/gld/helics-install/include/helics/application_api/../flag-definitions.h:52:25: error: expected '}' before numeric constant
#define LOG_LEVEL_ERROR 0
^
./ns3/log.h:94:3: note: in expansion of macro 'LOG_LEVEL_ERROR'
LOG_LEVEL_ERROR = 0x00000001, //!< LOG_ERROR and above.
^~~~~~~~~~~~~~~
/home/USER/projects/cid/gld/helics-install/include/helics/application_api/../flag-definitions.h:52:25: error: expected unqualified-id before numeric constant
#define LOG_LEVEL_ERROR 0
^
./ns3/log.h:94:3: note: in expansion of macro 'LOG_LEVEL_ERROR'
LOG_LEVEL_ERROR = 0x00000001, //!< LOG_ERROR and above.
^~~~~~~~~~~~~~~
In file included from ./ns3/core-module.h:49:0,
from ./ns3/helics-helper.h:6,
from ../contrib/helics/helper/helics-helper.cc:14:
./ns3/log.h:133:49: error: use of enum 'LogLevel' without previous declaration
void LogComponentEnable (char const *name, enum LogLevel level);
^~~~~~~~
./ns3/log.h:143:34: error: use of enum 'LogLevel' without previous declaration
void LogComponentEnableAll (enum LogLevel level);
^~~~~~~~
./ns3/log.h:155:50: error: use of enum 'LogLevel' without previous declaration
void LogComponentDisable (char const *name, enum LogLevel level);
^~~~~~~~
./ns3/log.h:162:35: error: use of enum 'LogLevel' without previous declaration
void LogComponentDisableAll (enum LogLevel level);
^~~~~~~~
./ns3/log.h:165:1: error: expected declaration before '}' token
} // namespace ns3
^

Waf: Leaving directory `/home/USER/projects/cid/ns3-helics/ns3-helics/build'
Build failed
-> task in 'ns3-helics' failed (exit status 1):
{task 140094289113424: cxx helics-helper.cc -> helics-helper.cc.1.o}
['/home/USER/app/bin/gcc-bin/g++', '-W', '-Wall', '-g', '-std=c++14', '-fPIC', '-pthread', '-I.', '-I..', '-I/home/USER/projects/cid/gld/helics-install/include', '-I/home/USER/projects/cid/gld/helics-install/include/helics', '-I/home/USER/app/boost_root/include', '-I/usr/local/include', '-DNS3_BUILD_PROFILE_DEBUG', '-DNS3_ASSERT_ENABLE', '-DNS3_LOG_ENABLE', '-DHAVE_SYS_IOCTL_H=1', '-DHAVE_IF_NETS_H=1', '-DHAVE_NET_ETHERNET_H=1', '-DHAVE_PACKET_H=1', '-DHAVE_IF_TUN_H=1', '-DHAVE_=1', '-DHAVE_SQLITE3=1', '-DNS3_HELICS', '-DHAVE_ZMQ', '../contrib/helics/helper/helics-helper.cc', '-c', '-o', '/home/USER/projects/cid/ns3-helics/ns3-helics/build/contrib/helics/helper/helics-helper.cc.1.o']

Example using helics module as a dependency

Add a module that uses the helics module as a dependency.

Update licenses & copyrights

Tracking issue: GMLC-TDC/HELICS#623

• LICENSE file
• DISCLAIMER/NOTICES file
• CONTRIBUTORS file
• Copyright/license notice at the top of all source files

Schedule ns-3 packets for incoming messages at time specified

Currently there seems to be a bug affecting the Static Source/Sink and Filter applications due to the callbacks for incoming messages from HELICS scheduling the ns-3 packets to be sent at the current ns-3 time instead of the time specified by HELICS for the message in the callback. The issue is that the callbacks are called before the HELICS request time function has given the granted time to ns-3 to advance its own simulation time.

The fix should be making the Send functions take the time given by the endpoint callback functions for messages, and schedule the ns-3 packet to be sent at time <incoming HELICS message time> - <ns3 simulation time>.