CarMedia Technical Documentation Updated 15/01/2011 SVN Revision n° 466

Summary 1. Introduction ...... 3 2. Get the source code ...... 3 2.1. Data Structure ...... 3 3. Source code documentation ...... 4 4. Compile the source code ...... 4 4.1. Mandatory ...... 4 4.2. Compile on GNU/ ...... 4 4.2.1. Get the dev libraries ...... 4 4.2.2. Compile ...... 4 4.3. Compile on Windows ...... 5 4.3.1. Mandatory ...... 5 4.3.2. Compile ...... 5 5. Design ...... 5 5.1. Car -> Arduino -> CarMedia ...... 5 5.2. Events ...... 5 5.3. Sensors ...... 6 5.3.1. Classes ...... 6 5.3.2. Communication with the car ...... 7 5.4. Plugins ...... 7 5.4.1. Create a plugin ...... 8 6. Bugs ...... 9

1. Introduction CarMedia is a software application designed to be embedded in a car become the dashboard and/or multimedia center. The application core can retrieve and display real time values from the censors of the car (fuel, speed, number of turns/second, etc...). It is also possible with the API displayed in this document to add others plugins. CarMedia is developed in C++ with Nokia's Qt framework (http://qt.nokia.com/). QtCore, QtGui and QtNetwork plugins are used. For the multimedia part, we use the Phonon framework (http://fr.wikipedia.org/wiki/Phonon_(KDE)), which is cross-platform written for KDE who relies on Qt. CarMedia is designed to be cross-platform, we use it on Windows & GNU/Linux.

Note: This documentation is intended to the SVN revision that you can find on the first page.

2. Gets the source code Given that no stable version has been released actually, you have to retrieve the source code with the SVN at this URL: https://labeip.epitech.net/svn/2011/carmedia/.

On GNU/Linux, you can download the data with this command line:

svn checkout https://labeip.epitech.net/svn/2011/carmedia/trunk carmedia

On Windows you can use a SVN client like TortoiseSVN (http://fr.wikipedia.org/wiki/Comparaison_des_clients_pour_Subversion).

2.1. Data Structure Structure of the main folder: • arduino/ => Source code that the Arduino run. • carmedia/ => Source code of the sofware. ◦ core/ => Folder with source code of the application core. ▪ images/ => Folder with the pictures used by the application. ▪ Locales/ => Folder with language files of the application. ▪ src/ => C++ source code of the application. ▪ core.pro => project file. Used to compil the application. ▪ core.qrc => File used to link images and binary. ◦ doc/ => Folder with documentation. ◦ plugins/ => Folder with source codes of the plugins. ◦ carmedia.dox => Configuration file for Doxygen. ◦ carmedia.pro => Qmake project file. Calls core/core.pro and plugins/*/*.pro. 3. Source code documentation The most important classes of CarMedia are documented with Doxygen (http://www.stack.nl/~dimitri/doxygen/). Doxygen is a documentation generator, it parses the source code, extract the comments generates documentation in HTML, LaTeX, PDF, etc... We will produce that documentation at each release. It is advised to create it once you have downloaded the data on the SVN.

4. Compile the source code

4.1. Mandatory To create a CarMedia binary you need to have: • A C++ compilator • The Qt framework >= 4.6

4.2. Compiling on GNU/Linux

4.2.1. Get the Qt dev libraries Each GNU/Linux distribution comes with a package manager. On Fedora:

yum install gcc-c++ qt4-devel

On Debian:

apt-get install qt4-dev-tools

4.2.2. Compiling The Qt framework is cross platforms, The Qt program generates a platform-specific project file. On GNU/Linux it will be a Makefile. Run the commands below into the carmedia/ folder.

Qmake # Generates the Makefile.

make # Run the compilation.

./carmedia # Run the application binary.

4.3. Compiling on Windows

4.3.1. Mandatory The simplest way to create a CarMedia binary on Windows is to use . Download the Qt SDK (Software Development Kit) at the url: http://qt.nokia.com/downloads/sdk- windows-cpp. Then install it with the defaults options.

4.3.2. Compiling To create a CarMedia binary, run Qt Creator and open the file carmedia/carmedia.pro. It will load the project (the application core and plugins). Choose « Compiler » on the Start Menu then « Runs » (or CTRL+R).

5. Architecture

5.1. Car -> Arduino -> CarMedia To retrieve the values of the sensors in the car, we use a programmable hardware piece called Arduino (http://www.arduino.cc). The source code run by the Arduino is located in the folder arduino/. In this documentation, we only focus on the core of CarMedia, how to add plugins and how to get values form the censors.

5.2. Events The CarMedia application works by events. It uses the Qt signalx/slots and especially an object called EventBus. The event bus is designed to communicate the informations between objects unreferenced to each other. An object subscribes for an event, and then when it occurs, the object is automatically notified when the event happens. Below the object EventBus:

class EventBus

{

public:

EventBus();

~EventBus();

private:

EventBus(const EventBus&);

EventBus& operator=(const EventBus&);

public:

void addHandler(QEvent::Type type, QObject* pHandler);

void removeHandler(QEvent::Type type, QObject* pHandler);

void emitEvent(Event* pEvent);

void emitEventRightNow(Event* pEvent);

private:

static QMap > msHandlers;

static QReadWriteLock msHandlersLock;

};

The addHandler() and removeHandler() methods are called for subscribe and unsubscribe to an events. Both methods take as parameters an event type and an object. Event types are described in carmedia/core/src/events/eventtypes.h. The object must inherit QObject class and is notified of the event by the method event(). There are many examples in the plugins and especially in plugins/videoplayerplugin.

The emitEvent() method allow to emit an event in the application. The event passed as parameter is sent to all handlers. It is sent by the Qt event system, thus in the Qt main scope. Th emitEventRightNow() method works like emitEvent() but the events are not sent in the Qt main scope. They are immediately sent to theirs handlers

5.3. Sensors CarMedia allows to display the values from differents censors of the car. At this time we support two modes and one norm. It means that we are able to generate random values or get the censor values with the network. Both ways the CarMedia application will receive the same data format.

In a near future it will be possible to add others modes and norms with the plugins.

5.3.1. Classes Below the classes used by the sensors. • IDevice => Device Interface. ◦ DefaultDevice => Creates a Thread. ▪ SerialPortDevice => To handle the devices on serial port. ▪ NetworkDevice => To handle the networked devices. • ISensors => Interface to stack the censors values. ◦ DefaultSensors => Implements Isensors, with the list of cesnsors. • IProtocol => To handle the evolutions of the communication protocol with the Arduino. ◦ CarmediaProtocolV0001 => First version of protocol. ◦ CarmediaProtocolV0002 => Second version of protocol.

Here is a schema about the classes :

IDevice IProtocol ISensor

Parses that data Get the data from Verifies the values the device and send and send the values An event is created at each it to protocol to the object who change of values stock them.

5.3.2. Communication with the car In the 2.0 version of the communication protocol between the Arduino and CarMedia, There is no text exchange, only binary data. We choose this because the text protocol needs to much power from the Arduino. The strings concatenation, converting integer to string, consuming a lot of cycles. The binary data exchange is a real benefit for the Arduino.

L'Arduino emit thoses octets : 1 octet with the value 'c'. 1 octet with the value 'r'. 1 octet with the value 'm'. 1 octet who describes the censor type. 4 octets for the value from the censor (unsigned int).

The octet who describes the censor type can take the values below : 1 : Fuel level. 2 : Car speed. 3 : Doors (opened/closed). 4 : Lights (on/off).

5.4. Plugins To be loaded, a plugin must be located into the folder plugins/ of CarMedia. At the boot, all applications located in the folder plugins/ are loaded and will be unloaded when the application exits. To use them, the user has to go into « Application » and touch the plugins he wants. 5.4.1. Create a plugin To create a plugin, you need to implement the interface Iplugin below :

class IPlugin

{

public:

virtual ~IPlugin() {};

virtual QString name() const = 0;

virtual QIcon icon() const = 0;

virtual QWidget* appWidget() = 0;

virtual bool hasAnApp() const = 0;

virtual void startApp() = 0;

virtual void stopApp() = 0;

virtual bool hasAProtocol() const = 0;

virtual IProtocol* protocol() = 0;

virtual QWidget* settingsWidget() = 0;

};

The name() and icon() methods are informations for the user: it is the name and the icon of the application. A plugin for CarMedia must implement the appWidget(), hasAnApp(), startApp() and stopApp() methods. AppWidget() must always return a valid widget (if hasAnApp() returns true). The startApp() and stopApp() methods are used to inform the core if the plugin is running or not. The hasProtocol() method returns true if the plugin has a protocol. The protocol() method returns a pointer on an object that implements IProtocol or NULL if there is no protocol. The purpose of being able to add a new protocol with the plugins is to be able to support different models of cars. A plugin can be an application, a protocol or both.

To create your own plugin, we advise you to take the plugins/dummyplugin source code as a start.

6. Bugs Closed Tickets: • #1 Segfault aléatoire de la libVLC • #2 Slider du mediaplayer de CarMedia