Table of contents

1 IDE Installation
1.1 Linux VM Environment
1.2 Eclipse Environment
1.3 Install your own developper installation
2 Dashboard Installation
2.1     Tablet
2.2   Application Installation
2.3     Application Configuration
3 Open the Box OSGi Framework Installation and Configuration
3.1    Framework Installation
3.2     Framework Configuration
3.3     Start OpenTheBox framework
4 Target Environment to be used during Orange tutorial meetings

1 IDE Installation

Developers are provided with a complete programming environment in a Linux VM (ubuntu 14.04), containing an Eclipse workspace and a Maven 3 local repository. In order to use them, follow these steps.

1.1 Linux VM Environment

Install Oracle VM VirtualBox 4.3.20 (download).
Download the 5 parts of the VM from this link http://openthebox.org/vm/.
Open the first part with WinRAR tool. It will gather all parts in one.
Double-click on OTB_Hack.vbox to start it.
Connect on the VM (login/password: otb/otb).
If there is a problem, check the network configuration: follow menu “Peripherals / Network / Network Settings”, choose “Network Access Mode: Access by bridge” and “Name : <the name of your Ethernet card>”. Type ifconfig in a terminal, you should see an Ethernet interface with IP address. This configuration needs be done only once.

1.2 Eclipse Environment

Start Eclipse on the VM. The workspace contains by default a project “ZigBee Tutorial” and the Application template described here.
To build an application, open a terminal, go in the project folder (e.g. cd ~/workspace/hackathon.template.app) and use the Maven commands (e.g. mvn clean install).

1.3 Install your own developper installation

Should the developer prefer to use his/her own development environment (highly inadvisable, we cannot guarantee that it works properly), it is recommended to use Eclipse Luna (Open the Box has not been tested on any other IDE) and Maven 3. Open the Box projects having Maven dependencies towards Orange libraries that are not public, it is essential to use a local repository that can be %% found here. This section est given for information only, or to install Open the Box on a non prepared environment.

2 Dashboard Installation

The Open the Box Dashboard is an application to be used on an Android tablet (apk).

2.1 Tablet

The Android version must be at least 4.2.2.
The screen must have a minimum size of 7 inches (10 inches for a better user experience).
The tablet must be connected on wifi with the routeur (identifier is written on a label on the provided TPLink, password openthebox).

2.2 Application Installation

Download the last release of the « Dashboard » package. You can easily transfer this apk onto the tablet by mail or by USB copy.
Carry out the installation of the apk.

2.3 Application Configuration

Once the application is started, click on the Settings menu (icon upper right).

With mode “Auto HAB discovery”, the dashboard should find by itself the HAB on the network if it is unique, but for this Hackathon, as there are several sub-networks on a single Livebox, you have to select the option “Manual HAB discovery” and enter the following values:

HAB ip address : 10.0.10.1n
HAB port : 8081

For the address of the AppStore, enter:

http://ohomeint.orange-labs.fr:9000/OpenTheBox/oas_for_otb?clientId=<hab_serial_number>

where <hab_serial_number> is the value of the field DeviceInfo.SerialNumber in configuration file usine.txt of the HAB (cf. § 3.2). This value is given on the label on the Raspberry Pi. For instance:

http://ohomeint.orange-labs.fr:9000/OpenTheBox/oas_for_otb?clientId=hackathon-hab-n

The login/password should not be modified (otb1/otb1).

3 Open the Box OSGi Framework Installation and Configuration

To be noted: This section describes how to install Open The Box framework on your own Raspberry Pi. If you are invited in Orange hackathon meeting, the section has to be skipped. Please see 4 Target Environment to be used during Orange tutorial meetings for more details.

Prerequisite: You have to install the Raspbian distribution on your Raspberry Pi. This distribution can be freely download from https://www.raspberrypi.org/downloads/. This distribution natively includes Oracle Java 8 JVM. Please follow this tutorial to know how to install the distribution.

The OTB framework has been successfully tested with JVM 8 SE Embedded Compact 1 from Oracle. This JVM is available here: http://www.oracle.com/technetwork/java/embedded/embedded-se/downloads/index.html#javase8

3.1 Framework Installation

The OpenTheBox framework is available as a APT package for Raspberry Pi target. This package is hosted on the OpenTheBox APT repository.
Please, open a SSH connection through a terminal. Default login is pi and default password is raspberry.

3.1.1 Configure APT management tool

Create otb.list file into the /etc/apt/sources.list.d.
Edit this file and add the next line:
deb http://openthebox.org/packages/ internal/
Then, execute the next command:
sudo apt-get update
This command updates the list of packages by requesting APT repositories.

3.1.2 Install the OpenTheBox package

Execute the next command:
sudo apt-get install otb.framework
The otb.framework package requests the sdevice and the libjansson4 package. APT requests an agreement to install both of these packages. Confirm your agreement by entering ‘Y’.
Then apt-get tool reports that the sdevice and the otb.framework packages aren’t signed. Enter ‘y’ again to install them.
Finally, the Open The Box framework is installed into the /usr/share/otb-framework folder.

3.2 Framework Configuration

This section describes the Open The Box configuration files such as the Modus TR69 client configuration file or the management plateform configuration file.

When you reach this point, you have to contact Open The Box team and request a valid serial number for your Raspberry Pi. We will help you to complete the configuration and test your installation.

For your information, you can have look to the next sub-sections. They describe all configurations files.

3.2.1 Modus client TR069 configuration file

The file data/usine.txt is used to configure the Modus client that allows for communication with the ACS.
The following table gives the important parameters of this file:

Parameter	Value	Description
`DeviceInfo.SerialNumber`	<*unique* value>, e.g. hackathon-hab-n	Identifier used by the ACS. See label on the Raspberry Pi.
`DeviceInfo.Description`	Raspberry
`ManagementServer.URL`	http://g-acsrd.orange-labs.fr:8080/edge/tr69	URL of the ACS
`ManagementServer.STUNEnable`	false	The STUN stack must be deactivated in this configuration

Important Note : the field DeviceInfo.SerialNumber must have a unique value in order to discriminate all HABs managed by the same ACS. It is composed only with alphanumeric characters. The default value hackathon-hab-n ends with a n that varies according to the work stations, typically from 1 to 5.

3.2.2 HABAM Configuration

The file data/config.cfg is used to configure the Open the Box HABAM module that allows for communication with the PFG:

Parameter	Value	Description
`ipAddress`	10.0.10.1n	IP Address of the Raspberry Pi
`PFG_address`	http://ohomeint.orange-labs.fr:9000	IP Address of the PFG
`PFG_login`	otb1	Login for connection with the PFG
`PFG_password`	otb1	Password for connection with the PFG

3.2.3 Knopflerfish Framework Configuration

Files props.xargs and otb_hackathon.xargs respectively contain the settings for the Knopflerfish framework and the ordered list of bundles to be installed and started. They are a priori not to be modified, or just marginally (for example to change the property -Forg.knopflerfish.log.out=true in props.xargs to display logs).

3.3 Start OpenTheBox framework

Go to /usr/share/otb-framework and execute the next command:
sudo ./startRsp_hackathon.sh

4 Target Environment to be used during Orange tutorial meetings

Provided Raspberry Pi targets have been prepared, necessary packages installed. Each target owns an IP address 10.0.10.1n (n ranging from 1 to the number of prepared work stations), depending on the Livebox configuration. This IP address is specified on the label sticked on the Raspberri Pi. Check that it is plugged in.

The target hosts the Open the Box OSGi framework. Access is performed from the VM by the command ssh pi@10.0.10.1n (password raspberry). It could also be done from the PC with a putty-like SSH console, port 22, login/password pi/raspberry.

cd /home/pi/hack/otb-framework-knopflerfish
Configuration is set. For information (see section 3 for details), it consists of files:
- data/usine.txt for Modus configuration (link with the ACS) ;
- data/config.cfg for PFG / AS configuration;
- props.xargs for settings of the OSGi Knopflerfish framework;
- otb_hackathon.xargs for the list and ordering of OSGi bundles to be started.
To start the framework: sudo ./startRsp_hackathon.sh (do not forget the sudo !)

Notes

[1] In order for the Open the Box platform to work properly, it has been necessary to fix some bugs on the Knopflerfish framework (especially for permission management). Corresponding patches have been submitted to the Knopflerfish project and will be inserted into next versions of maintenance of KF 4.x. While waiting for the publication of this corrective release, it is necessary to use the provided version, which contains these fixes, and not a release downloaded from their web site.
[2] To use permissions, the Knopflerfish framework must be configured so that they are activated (this is not the default case). This is performed by changing the configuration file props.xargs, following lines:

# Security
-Forg.osgi.framework.security=osgi
-Forg.knopflerfish.framework.service.permissionadmin=false

Installation Guide