Open the Box tutorials

Open the Box Workshop

Table of Contents:

1 Introduction
1.1 Architecture and required devices
1.2 Deployment choice of the Open the Box infrastructure
2 Installation
3 Tutorials
3.1 Developing an Open the Box application
3.2 Device Management
4 Application Template
5 Related Open-source Projects
6 Acronyms

Main goal: Help the developer to understand and handle the « Open the Box  software development workshop », as it will be provided for, e.g. a  creativity session, like a Hackathon or a FAB LAB event. A development laptop, a HAB (e.g. a Raspberry Pi), some USB dongles (for EnOcean, ZigBee, etc.), and the corresponding set of devices will be used in the workshop.

The Java developer will then take advantage of the Open the Box infrastructure in order to make a Smart Home application based on already integrated/available devices. S/He will finally deploy her/his applications on a Rapsberry Pi.

Prerequisites: The developer should have skills in Java/OSGi (knowing the OSGi compendium would be even better), as well as classic development tools like Eclipse and Maven. S/He may also know, for example, the ZigBee, or the SimpleBee concepts.

How-to use this guide: This page is the home page of a set of documentation files. It provides an overview of the guide, an acronyms list, and links to associated Open Source projects. Each referred page starts by a link to this home page in order to ease browsing this web site.

1 Introduction

This section briefly presents the technical organisation of an Open the Box Workshop. A workshop consists of “business” users (i.e. users that imagine services related to their business expertise/knowledge) using the Open the Box infrastructure in order to rapidly prototype the services they just imagined. A workshop can take several hours.

To start with, the Open the Box preamble section outlines Open the Box infrastructure main concepts, and technical choices.

1.1 Architecture and required devices

An Open the Box workshop usually involves 5 development workspaces that are linked to an Open the Box infrastructure.

A workspace regroups:

  • a development laptop (i.e a PC containing the Open the Box development environment based on Eclipse) ;
  • a Home Automation Box, in short HAB, (i.e. a Raspberry Pi) supporting at least one wireless connectivity via USB dongles (one per connectivity technology) ;
  • a set of devices related to the HAB connectivities.

The Open the Box infrastructure involves:

  • a HABs Management Platform (HMP, aka PFG in french) for administrating the applications deployed on the HABs via an Auto Configuration Server (ACS) ;
  • an Application Store (AS) displaying to the user, on a web site (GUI), a list of ’applications that can be deployed on the HAB via the HMP/PFG.

1.2 Deployment choice of the Open the Box infrastructure

The Open the Box infrastructure is designed to manage a set of HABs (owned by the customers).  The AS, and the HMP/PFG are designed to be shared amongst several HABs. As a consequence, the AS and the HMP/PFG are expected to be on a WAN (e.g. a telecom operator WAN), and each HAB itself is expected to be on a LAN (i.e. a customer home).

Several deployment choices are made in order to ease the Open the Box workshop:

  • All the Open the Box infrastructure, as well as the development workspaces will be on the same unique LAN provided by a WiFi router.
  • The development workspaces, and in particular the development laptops, will also be on this LAN.
  • The WiFi router will, in general, be connected to the Internet.
  • The AS, the HMP/PFG, and the ACS will be unique, and available on-line.

All the configuration details are available in the Installation section.

2 Installation


  • A PC laptop with Windows 7, or Linux. MacOS is expected to be supported soon…
  • An Android tablet with version >= 4.2.2.
  • A Raspberry Pi.

Software to be installed on the PC

Software to be installed on the Raspberry Pi

  • Install the Raspbian distribution for Raspberry Pi. This distribution is available here:
  • Install and configure OpenTheBox Debian APT package for Raspberry Pi

The Installation guide section indicates how to install and configure the development workspace.

3 Tutorials

3.1 Developing an Open the Box application

The Open the Box Application Developper Guide details what an Open the Box application is, how to develop and use one, as well as, how to test and deploy it. The developer is deeply encouraged to read it, in particular because it contains a sample Open the Box application.

3.2 Device Management

The Open the Box Connectivity Guide presents the connectivities (Zigbee, EnOcean, Philips Hue, etc.) supported by the Open the Box infrastructure (thanks to the base drivers it embeds), and how to integrate them in the applications.

4 Application Template

This page describes an Open the Box application template. It can be used as a basis when starting the development of a new Open the Box application. The page itself proposes a general presentation of the template, and a zip file containing the template application itself (as a Maven project), the Java code, and the related configuration files.

5 Related Open-source Projects

[EnOcean] EnOcean Base driver, open source project under Eclipse license, currently being transferred to the Eclipse SmartHome project.

[Modus] BroadBand Forum TR-069 Client, open source project under Apache license.

[SimpleBee] SimpleBee Base driver, open source project under Apache license.

[SimpleBee4Arduino] SimpleBee on Arduino, open source project under Apache license.

6 Acronyms

Acronym Definition
ACS Auto-Configuration Server: server that remotely manages gateway-like devices (e.g. Livebox) via the Broadband Forum TR-069 standard protocol (BBF TR-069). It also enables the deployment of software on the gateways’ TR-069 clients via a second protocol named BBF TR-157.
AS Application Store: service platform providing a web interface that lists the applications available for the customers.
Base Driver OSGi bundle offering a programming interface enabling the communication with a given type of devices, e.g. ZigBee devices, SimpleBee devices.
Dashboard A graphical interface hosted on the Android tablet providing a way to locally manage the Open the Box applications, and devices, ’and to access the AS.
HAB Home Automation Box: an embedded software platform deployed on a Smart Home box (over the top), or on a Home gateway (triple play). A HAB is managed via an ACS, and supports application, installation, and execution.
HABAM HAB Application Management: a software interface providing programmatic ways to interact with the Open the Box applications, the OSGi framework embedded in the HAB (for rights management), Modus TR-069 client, the HMP/PFG, and the dashboard.
Modus Java/OSGi open source TR069 client. It is integrated in the Open the Box platform (i.e. in the HAB). It directly interacts with the ACS (Modus TR069).
HMP/PFG HABs Management Platform, or “Plate-forme de gestion” in french: the Open the Box software service platform managing all the HABs, and their deployed applications. The AS uses the HMP/PFG in order to manage the available applications, and to deploy them.