KNoT Network of Things - Gateway

This is the gateway software module for the KNoT platform. It is based on buildroot 2014.11 version for RaspberryPi hardware.

Copyright (C) 1999-2005 by Erik Andersen andersen@codepoet.org
Copyright (C) 2006-2014 by the Buildroot developers buildroot@uclibc.org
Copyright (C) 2014 by the Buildroot developers buildroot@buildroot.org
Copyright (C) 2016 by the C.E.S.A.R KNoT developers knot-devel@cesar.org.br

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

System requirements

Buildroot is designed to run on Linux systems. If you are using a Mac, there is an experimental Vagrant box configured to build the KNoT Gateway (see below).

While Buildroot itself will build most host packages it needs for the compilation, certain standard Linux utilities are expected to be already installed on the host system. Below you will find an overview of the mandatory and optional packages (note that package names may vary between distributions).

1. Mandatory packages

Build tools:

which sed make (version 3.81 or any later) binutils build-essential (only for Debian based systems) gcc (version 2.95 or any later) g++ (version 2.95 or any later) bash patch gzip bzip2 perl (version 5.8.7 or any later) tar cpio python (version 2.6 or any later) unzip rsync libtoolize aclocal pkg-config autoconf-archive libdbus-1-dev

Source fetching tools:

wget

2. Optional packages

Configuration interface dependencies:

For these libraries, you need to install both runtime and development data, which in many distributions are packaged separately. The development packages typically have a -dev or -devel suffix.

ncurses5 to use the menuconfig interface qt4 to use the xconfig interface glib2, gtk2 and glade2 to use the gconfig interface

Source fetching tools:

In the official tree, most of the package sources are retrieved using wget from ftp, http or https locations. A few packages are only available through a version control system. Moreover, Buildroot is capable of downloading sources via other tools, like rsync or scp (refer to Chapter 19, Download infrastructure for more details). If you enable packages using any of these methods, you will need to install the corresponding tool on the host system:

bazaar cvs git mercurial rsync scp subversion

Java-related packages, if the Java Classpath needs to be built for the target system:

The javac compiler The jar tool

Documentation generation tools:

asciidoc, version 8.6.3 or higher w3m python with the argparse module (automatically present in 2.7+ and 3.2+) dblatex (required for the pdf manual only)

Graph generation tools:

graphviz to use graph-depends and -graph-depends python-matplotlib to use graph-build

Use a Vagrant box (experimental)

This repository provides a Vagrant box running Ubuntu with all the packages needed to build the KNoT Gateway. Before running it, install Vagrant and VirtualBox.

Then, install a Vagrant plugin to resize disks in VirtualBox:

$ vagrant plugin install vagrant-disksize

To create the box, run:

$ vagrant up

It will ask for adminstrator credentials, required to map this folder inside the box using NFS.

To enter the box, run:

$ vagrant ssh

There are two folders in the home folder:

• buildroot: maps the repository root inside the box. It is accessing the host file system using NFS.
• output: where the build output will be located. If the host OS is a Mac OS X or Windows, the build must be made out-of-tree (see instructions in the next section), because of limitations of their file systems.

How to Buid it

The knot_gateway_defconfig configuration is a minimal configuration with all that is required to bring the KNoT platform on RaspberryPi. Note: you will need to have access to the network, since Buildroot will download the packages' sources.

You should base your work on this defconfig:

1. run make <knot_board_defconfig> Currently supported KNoT defconfigs:
   • knot_raspberrypi3_defconfig
2. run make menuconfig
3. select the extra packages you wish to compile
4. run make (This may take a while; consider getting yourself a coffee ;-) )
5. wait while it compiles
6. Use your shiny new root filesystem.

Offline build

In order to do an offline-build (not connected to the net), fetch all selected source by issuing a

$ make source

before you disconnect. If your build-host is never connected, then you have to copy buildroot and your toplevel .config to a machine that has an internet-connection and issue make source there, then copy the content of your dl/ dir to the build-host.

Building out-of-tree

Buildroot supports building out of tree with a syntax similar to the Linux kernel. To use it, add O= to the make command line, E.G.:

$ make O=/tmp/build

And all the output files (including .config) will be located under /tmp/build.

More finegrained configuration

You can specify a config-file for uClibc:

$ make UCLIBC_CONFIG_FILE=/my/uClibc.config

And you can specify a config-file for busybox:

$ make BUSYBOX_CONFIG_FILE=/my/busybox.config

To use a non-standard host-compiler (if you do not have 'gcc'), make sure that the compiler is in your PATH and that the library paths are setup properly, if your compiler is built dynamically:

$ make HOSTCC=gcc-4.3.orig HOSTCXX=gcc-4.3-mine

Depending on your configuration, there are some targets you can use to use menuconfig of certain packages. This includes:

$ make HOSTCC=gcc-4.3 linux-menuconfig
$ make HOSTCC=gcc-4.3 uclibc-menuconfig
$ make HOSTCC=gcc-4.3 busybox-menuconfig

Please feed suggestions, bug reports, insults, and bribes back to the knot mailing list: knot-devel@cesar.org.br

Result of the build

After building, you should obtain this tree:

output/images/
+-- rootfs.ext2
+-- rpi-firmware
|   +-- bootcode.bin
|   +-- config.txt
|   +-- fixup_cd.dat
|   +-- fixup.dat
|   +-- start_cd.elf
|   +-- start.elf
+-- zImage

The rootfs.ext2 file contains (as the name suggests) the root file system for your linux setup. The rpi-firmware directory contains the RaspberryPi bootloader and all the files that it needs. The zImage is the Linux kernel image.

Preparing and writing the SDcard

The RaspberryPi bootloader needs to be in a FAT32 partition. So, the SDCard must have first partition in FAT32 and marked bootable.
The bootloader and required files needs aproximatedly 10MB.
The root file system size depends on the applications, libraries, etc that you included in your build.

We created two scripts that automates the process of preparing and writing those files on SDCard.
The fisrt one is create_boot_disk.sh that will partition the sdcard and format the volumes according to its file systems (FAT32 and ext4).
The second is the update_boot_disk.sh that will write the files to each volume (boot and rootfs). These scripts are located in path board/raspberrypi/, relative from the knot-gateway-buildroot folder.

If you have new SDCard, you will need to create the partition first:

$ ./board/raspberrypi/create_boot_disk.sh /dev/sdX

where sdX is the device corresponding to your SDCard in your system, such as sdb or sdc (or also mmcblkX).

Note: create_boot_disk.sh will repartition and formating your entire disk. This means that all INFORMATION on it will be LOST. Please use it with care!

If your SDCard was previously used with this system and you just need to update the files resulted from a fresh build, you can use:

$ ./board/raspberrypi/update_boot_disk.sh /dev/sdX

where sdX is the device corresponding to your SDCard in your system, such as sdb or sdc (or also mmcblkX).

Note: update_boot_disk.sh will ERASE the first 3 partitions of the disk. This means that all INFORMATION on it will be LOST. Please use it with care!

Let's see how to access your KNoT gateway

To access the KNoT gateway of your Network open your browser and type knot.local:8080 in your URL bar.

Managing the RabbitMQ Server

If you need to debug the RabbitMQ message broker or just collect data about many aspects of the system, you can use the management plugin.

In order to enable it, access the gateway terminal and run this command (logged in as 'rabbitmq' user):

$ rabbitmq-plugins enable rabbitmq_management

Now, create a new user and set its permissions to allow remote connections:

$ rabbitmqctl add_user <username> <password>
$ rabbitmqctl set_user_tags <username> administrator
$ rabbitmqctl set_permissions -p / <username> ".*" ".*" ".*"

The management UI can be accessed at http://knot.local:15672/, just use the created user and enjoy it.

Possible troubleshootings

I've typed knot.local:8080 on the URL bar but my browser returned that it can't find the page

In the KNoT gateway it is installed a service that allows to the find it with a logical address (knot.local) without let you know the physical address (an address like 192.168.x.y), but sometimes it could happen that this service is blocked by either the router firewall or the computer firewall.

To solve that problem you have to:

A - Go to a linux machine on same local network and execute the followed command on terminal $ arp-scan -l | grep b8:27:eb

B - Go to the KNoT gateway then put a screen and a keyboard, login as user root and password root, type the followed command hostname -i (it's important that hostname is write lowercase).

This command will return the IP address the router have assigned to the KNot gateway; now that you know the IP address, go to the browser and type the IP address instead of knot.local. For example, imagine it returned 192.168.1.4, go to the browser and on the URL bar type: 192.168.1.4:8080

Contact

KNoT mailing list: knot-devel@cesar.org.br

-And finally, enjoy your brand new KNoT Gateway platform!