Packages can be downloaded as iop-locnet
from the IoP package repositories.
The IoP repository is located at repo.iop.cash
which you can configure
to your package manager. E.g. on Ubuntu add something like below into your
/etc/apt/sources.list.d
deb [arch=amd64] http://repo.iop.cash/ 16.04 main
and accept the repository keys with the following commands
gpg --keyserver keys.gnupg.net --recv-keys 0CC9EB6DA69C84F4
gpg -a --export A69C84F4 | sudo apt-key add -
You can find more details about how to configure the repository at this document.
After you successfully installed or unpacked the binary distribution,
you should start binary iop-locnetd
. There are a lot of optional arguments,
but also some mandatory options that you must specify.
You can use the command line directly to do so, e.g. assuming GPS location of Budapest,
application can be run with a minimal configuration of
iop-locnetd --nodeid YourNodeIdHere --latitude 48.2081743 --longitude 16.3738189
To persist configuration, you may save the same options into config file
~/.iop-locnet/locnet.conf
with content
--nodeid YourNodeIdHere
--latitude 48.2081743
--longitude 16.3738189
and run the executable without any command line options.
You can also have your config file at a custom path and use option
--configfile
to specify its location on the command line.
To help filling in these details automatically, we provide a small python script
generate-iop-locnet-config.py
with the binaries. It will generate a unique node id
and query a rough approximation of your GPS location based on your IP address.
It will print generated options to the console, so you can copy-paste them
to your command line or redirect them to your config file as
generate-iop-locnet-config.py > ~/.iop-locnet/iop-locnet.cfg
Note that the application will create its database and log files under ~/.iop-locnet
by default.
If application startup is successful, it will open three sockets and serve requests on them.
By default port 16980 is used for node to node communication to build and maintain the network,
16981 for clients to discover the network and 16982 for local services to register or get the neighbourhood.
Please check available options using
iop-locnetd --help
Currently the following options are useful for configuring your instance:
--clientport ARG TCP port to serve client (i.e. end user) queries. Optional,
default value: 16981
--configfile ARG Path to config file to load options from. Optional, default
value: ~/.iop-locnet/iop-locnet.cfg
--dbpath ARG Path to db file. Optional, default value:
~/.iop-locnet/locnet.sqlite
--host ARG Externally accessible IP address (ipv4 or v6) to be
advertised for other nodes or clients. Required for seeds
only, autodetected otherwise.
--latitude ARG GPS latitude of this server as real number from range
(-90,90)
--localport ARG TCP port to serve other IoP services running on this node.
Optional, default value: 16982
--logpath ARG Path to log file. Optional, default value:
~/.iop-locnet/debug.log
--longitude ARG GPS longitude of this server as real number from range
(-180,180)
--nodeid ARG Public node id, should be an SHA256 hash of the public key of
this node
--nodeport ARG TCP port to serve node to node communication. Optional,
default value: 16980
--seednode ARG Host name of seed node to be used instead of default seeds.
You can repeat this option to define multiple custom seed nodes.
For conventional usage, the preferred way of installing the software is using packages or installers created specifically for your operating system. We suggest compiling your own version for development or packaging for a new platform.
Though we mostly used different Ubuntu versions during development, we use only standard C++11 features and platform-independent libraries. Consequently, our sources should compile and work also on Windows or Mac OS with minimal efforts.
The project has multiple dependencies. Some of them are shipped with the sources, others has to be installed independently.
Some (mostly header-only) dependencies already included in directory extlib
:
asio
1.10.8 standalone mode without Boost. Used for networking, download here. Note that this library is a candidate to be included in the C++ standard.easylogging++
9.95.3, used for logging in the whole source, download hereezOptionParser
0.2.2 (with minimal changes to compile on Windows, see file history), used for handling options from command line and config files, download herecatch2
2.0.1, used only for testing, download here
Generated sources already included in directory generated
:
- ProtoBuf classes used for messaging, generated from the protocol definitions found here. Provided script generated/regenerate.sh also needs a protobuf compiler.
External dependencies to be manually installed on your system:
- A C++11 compiler. Developed with
g++-5
andg++-6
, but sources are platform independent, should work with any standard compiler (maybe minimal changes to CMake project files are needed). cmake
used to generated Makefiles. 3.x preferred, but 2.8 still should be enough.protobuf3
used for messaging between nodes and clients. Included sources are generated with 3.0, but using 2.x should not be hard after minimal changes (e.g. marking fields optional in the protocol definition). Unless present in your package manager, you have to download and compile cpp version manually from this page, currently the latest version is ProtoBuf 3.3spatialite
used to persist node data with locations, any recent version is expected to work. Available as an Ubuntu package or download and compile manually
First, you have to install all external dependencies.
If you are on Ubuntu 17.04 you are lucky and just have to do:
apt-get install -y g++ cmake protobuf-compiler libprotobuf-dev libspatialite-dev
Otherwise, for others Ubuntu distributions from 14.04, you will have to compile a protobuf compiler by yourself:
apt-get install -y curl g++ cmake automake autoconf libprotobuf-dev libspatialite-dev
curl -OL https://github.com/google/protobuf/releases/download/v3.5.0/protobuf-cpp-3.5.0.tar.gz
tar zxvf protobuf-cpp-3.5.0.tar.gz
cd protobuf-3.5.0
./configure
make
make install
ldconfig
Once this done, go inside the folder where you cloned or uncompressed this project in order to start to type the build commands.
Optionally, you can regenerate the C++ sources from the protocol definitions in order to make sure these files are compatible with your protobuf version:
cd generated && ./regenerate.sh && cd ..
Finally, you can just run build.sh
or perform the same steps as the script as follows:
First you have to generate build files with CMake, specifying the directory
containing our main CMakeLists.txt
file. We suggest running the build in a dedicated directory,
the provided script uses directory build
. Thus from the project root you can run
mkdir build
cd build
cmake ..
CMake should have successfully generated a Makefile
, so you can just execute
make
Assuming the stars aligned luckily for your environment and you followed the suggested directory structure, you find the executable file src/iop-locnetd
created under your build
directory.
If you also want to install the software to your system directories, you have to run
make install
So you were not so lucky and had problems, most probably compile errors. What to do?
If you encounter errors complaining about no file found for imported headers like
#include <some/header.h>
then you missed to deploy the shown dependent library.
Make sure that all dependent libraries are properly installed and try again.
Most often you may encounter compile errors about some ProtoBuf definitions, usually in files
located in directory generated
. Whenever you see a ProtoBuf-related error,
the reason may be that your ProtoBuf library version is slightly different
from what we used to generate the files. To get rid of the problem,
you have to regenerate these files for your version.
To do this, go back to the sources of the location-based network. In directory generated
, simply run:
./regenerate.sh
then try again compiling our source code.
You should already have a version of the Visual Studio C++ compiler installed, we do not detail this here.
Please make sure that you have the directory of the 64bit binaries set on your PATH
(usually <VisualStudioDirectory>\VC\bin\amd64
), not the 32bit version of the compiler or the linker.
You also have to install the Windows SDK,
find binaries and instructions here.
Recent Visual Studio versions have a bundled Git, so you can easily clone the repository either from the IDE or from the command line as
git clone https://github.com/Internet-of-People/iop-location-based-network.git
We couldn't easily achieve Windows compilation with CMake, so we're using a custom build system called Maiken.
Sources or some binaries are available here.
After compiling or downloading binaries, you have to set up its configuration.
You have to create file settings.yaml
in directory <UserDir>/maiken
set up with the proper
directory paths to the Visual Studio and Windows SDK binaries.
E.g. my host has the following directory paths and settings:
inc:
C:/Program\ Files\ (x86)/Windows\ Kits/10/Include/10.0.14393.0/ucrt/
C:/Program\ Files\ (x86)/Windows\ Kits/10/Include/10.0.14393.0/um
C:/Program\ Files\ (x86)/Windows\ Kits/10/Include/10.0.14393.0/shared
C:/Program\ Files\ (x86)/Microsoft\ Visual\ Studio\ 14.0/VC/include
path:
C:/Program\ Files\ (x86)/Windows\ Kits/10/Lib/10.0.14393.0/um/x64
C:/Program\ Files\ (x86)/Windows\ Kits/10/Lib/10.0.14393.0/ucrt/x64
C:/Program\ Files\ (x86)/Microsoft\ Visual\ Studio\ 14.0/VC/lib/amd64
env:
- name: PATH
mode: prepend
value: C:/Program\ Files\ (x86)/Microsoft\ Visual\ Studio\ 14.0/VC/bin/amd64
file:
- type: cpp:cxx:cc:c
compiler: cl
archiver: lib
linker: link
Having the settings set up, all you have to do is to open a console in the directory of our cloned sources and start the build
mkn.exe
Binaries will be created in directory bin\build
. Note that DLLs still have to be copied
from directory win\lib
to near the generated executable.
There are probably a lot of ways to do this, we preferred using the checkinstall
package
as an easy and minimalistic tool. As a summary, checkinstall
simply runs make install
in a sandbox and deploys every file into a generated Linux package instead of your filesystem.
You just have to specify a few options to describe a few details of the generated package
like format (deb, rpm, etc), name, package dependencies or developer email and you're done.
Directory package/locnet
contains a few shell scripts that generate packages
for a few Ubuntu versions. Based on these scripts it should be very easy to generate
a package for your favourite Linux distribution.
Note that we used libprotobuf-dev 3.0 which is available in package repository
only of the latest Ubuntu 16.10, not earlier. To support older releases,
we had to manually create custom libprotobuf-dev 3.0 packages.
For that purpose you can find some shell scripts also using checkinstall
in directory package/libprotobuf3
.