Linx Platform Toolsuite for Mobile Devices

15 050 Examensarbete 15 hp Juni 2015

LinX Platform Toolsuite for Mobile Devices

Jakob Andersson Dennis Myrgren John Rahme Abstract LinX Platform Toolsuite for Mobile Devices

Jakob Andersson, John Rahme, Dennis Myrgren

Teknisk- naturvetenskaplig fakultet UTH-enheten The project has shown that it is possible to create applications for Besöksadress: different mobile operating systems and Ångströmlaboratoriet Lägerhyddsvägen 1 linking the devices to the signal Hus 4, Plan 0 handler Data Engine. Using Qt as a framework and development environment Postadress: allows doing this with only one code Box 536 751 21 Uppsala base, which can be made to work on different platforms. This creates great Telefon: opportunity to save time and to reach a 018 – 471 30 03 wider audience. The creation of a

Telefax: demonstrator application, a tutorial and 018 – 471 30 00 a template for new projects has been the main goals for this project. These will Hemsida: serve as examples and guides for http://www.teknat.uu.se/student applications to come on how to deploy to mobile devices and connect to Data Engine using Wi-Fi. Though support for Windows Phone was not achieved, due to both development-wise difficulties and choices made during the project's course, the project was considered a success.

Handledare: Daniel Nisses-Gagnér Ämnesgranskare: Daniel Carlsson Examinator: Martin Sjödin ISSN: 1401-5757, UPTEC F15 050 Populärvetenskaplig sammanfattning

Det här projektet har utförts på uppdrag av företaget maximatecc. maximatecc utvecklar och levererar avancerade styrsystem för mobila maskiner verkande i tuﬀa miljöer, till exempel skogsavverkningsmaskiner eller skördetröskor. maximatecc har en mjukvaruplattform, LinX Software Suite, som agerar mellanhand mellan styrsystemets användargränssnitt och datalager.

I dagens samhälle har appar blivit stor del av vår vardag och de används numera till mängder av saker på alla olika slags mobila enheter. Ett intresse som maximatecc har märkt från sina kunder är att de efterfrågar möjligheten att koppla sina mobila enheter till de styrsystem de har i sina fordon. Det är här detta projekt kommer in i bilden. Projektets syfte har varit att undersöka möjligheterna att göra denna koppling mellan LinX och mobila enheter och ta fram en verktygskedja och guide för hur en applikation byggs och kopplas till styrsystemet. De mobila operativsystemen som har undersökts är Android, iOS och Windows Phone och ett av målen har varit att skapa en demonstrator som kan köra på vart och ett av dessa operativsystem. Huruvida den speciﬁka hårdvaran i de mobila enheterna, till exempel ljussensorn eller accelerometern, kan användas för att påvisa nyttan med att koppla sin mobil till ett fordon har även varit en del av projektets syfte.

Programmeringen i projektet har utförts i mjukvaruplattformen Qt:s miljö Qt Creator. Qt löser problemet som länge har funnits då man utvecklat mot ﬂera operativsystem sam- tidigt, att olika system använder sig av olika programmeringsspråk. I Qt Creator skrivs en enda gemensam kodbas som sedan kan kompileras mot valfritt opertivsystem som stöds. Detta är en smidig funktion som spar mycket tid och arbetskraft för utvecklaren.

3 Table of contents

1 Introduction 6 1.1 Background - maximatecc ...... 6 1.2 The need behind this project ...... 6 1.3 The idea of the project ...... 6

2 Objective 7

3 Theory 8 3.1 Qt: QML, JavaScript and C++ ...... 8 3.1.1 QtQuick and QML ...... 8 3.2 Other programs and utilities ...... 9 3.2.1 Github ...... 9 3.2.2 Templates ...... 9 3.3 Data Engine ...... 9 3.4 Dependencies ...... 10 3.4.1 Sapcore ...... 10 3.5 The LinX Software Suite ...... 10

4 Method and development 11 4.1 Creating templates ...... 11 4.1.1 Our templates ...... 11 4.2 The Tutorial ...... 11 4.2.1 Reasoning and purpose ...... 11 4.2.2 Method ...... 11 4.3 Creating a demo application ...... 11 4.3.1 The starting point ...... 11 4.3.2 Working on our own application ...... 12

5 Results 13 5.1 Libraries ...... 13 5.2 A plain template ...... 13 5.3 A basic template ...... 13 5.4 The Tutorial ...... 15 5.5 The Demonstrator Application ...... 15

6 Discussion 17 6.1 Operating system evaluation ...... 17 6.2 Github ...... 17 6.3 Qt as an IDE ...... 17 6.4 The demonstrator application ...... 17 6.5 The templates ...... 18 6.6 The future of this project ...... 18

7 Conclusions 19 7.1 Selection of operating systems ...... 19 7.2 Final conclusion ...... 19

8 References 20

4 9 Appendix 21 9.1 Abbreviations ...... 21 9.2 The tutorial ...... 21

5 1 Introduction

1.1 Background - maximatecc This project was executed at the request of maximatecc, speciﬁcally at their software development oﬃce in Uppsala. maximatecc is a company specializing in operator-interface solutions for critical environments, e.g. construction sites. They work globally to make machines smart, safe and productive through technology, engineering expertise and opera- tional excellence. One of the largest parts of this business is the designing and production of the operator-interface solutions that are used in the logging sector, the seagoing ship sector and many others. [1]

1.2 The need behind this project In recent times the use of smart phones and other smart devices such as tablets have become increasingly common. Not only have they become more frequently used as a per- sonal but also as a professional tool. For maximatecc this has revealed itself in the fact that some of their customers are asking for the option to use their smart devices as a com- pliment to the operator-interface solutions that they are already using. As an example one could envision an application that lets a construction site manager see an overview of which vehicles and machines that are running.

This is probably not something that applies only to maximatecc but to many companies in many diﬀerent trades. Since the use of smartphones and similar devices has become increasingly popular in recent years, and are already used by so many people across the world, this kind of adaptation will become increasingly more common in the future.

1.3 The idea of the project The basic idea behind this project is that it should not be complicated to create a graphical application fulﬁlling the new need. The customers of maximatecc already program their own applications for the operator-interface computers and we want to ﬁnd a way to easily implement those applications, or similar versions of them, on smart devices. We will focus on devices based on the iOS, Windows Phone and Android operating systems since those are the most commonly used.

6 2 Objective

At the beginning this project had a broad and somewhat undeﬁned objective. We simply were to explore the possibilities of making applications for mobile devices that can connect to and communicate with the Data Engine module, see Theory 3.3. This aim has since the start evolved to include more speciﬁc points of interest which are as follows:

• We were to formulate a toolsuite tutorial for the process of developing an application and connecting it to LinX Data Engine™ for the intended use with the following platforms:

– Android – iOS – Windows Phone

The tutorial covers most of what we’ve done ourselves during the project and its purpose is to readily explain the steps needed to get going with cross-platform application development in Qt.

• To easily show what an application of this kind can be used for we were to create a basic demonstrator application that will graphically show a working connection to LinX Data Engine™ for each respective platform.

• We were to explore what environments were best equipped for the development of this kind of application. We were also going to try to ﬁnd what diﬀers depending on what OS the developer is working from and what target OS the application is meant for.

7 3 Theory

To better understand this project some knowledge is needed of the tools that were used. This section explains what programming languages, IDE’s, Integrated Development En- vironment, and other utilities we have used and why we have used them.

3.1 Qt: QML, JavaScript and C++ Qt, pronounced as cute or cue-tee, is a cross-platform application development framework designed to speciﬁcally make cross-platform development easy. The idea is that the developer can use the same code base for diﬀerent target platforms, thus reducing development time and cost.

The development itself is performed in the Qt Creator application supplied with the Qt software package. The version used in this project is the newest as of April 2015, version 3.3.2, and an example of how the software and QML looks is shown in Figure 1. The Qt Creator uses the standard C++ language, with extensions specially designed for Qt, and Qt’s own language QML.[2]

Figure 1: The Qt software when writing in QML.

3.1.1 QtQuick and QML

Qt provides the QtQuick framework and it is that which is used to create the applications and templates in this project. Qt Quick itself includes the declarative scripting language QML.

QML is referred to as the Qt Meta Language, or the Qt Modeling Language, and is a language based on JavaScript which it uses to provide its logic. QML specializes in interface-centric applications and is often used to make mobile applications. This is because of the ease in making ﬂuid animations and objects that uses touch input.[3]

8 3.2 Other programs and utilities 3.2.1 Github

Github is a web-based code repository oﬀering version control and other managing tools for developers. Github lets the users share their work with others, letting them work on it too. The site provides social functions, such as followers and the possibility to see the work of other users. For Windows there is also a desktop application that makes working with Github very smooth. In this project Github was used to share code and allow simultaneous work on the same application. [4]

3.2.2 Templates

A template, in the meaning of the word relevant to this project, is a pre-constructed application base. When creating a new application, the user is prompted with the options of either starting on a blank slate or using a template. A template can be anything from just a few lines of code to an already working program. The user may also be prompted to choose between diﬀerent choices that will impact the program later on.

3.3 Data Engine What in this report is called Data Engine is a program in the LinX Core, provided by maximatecc, that is used for transmitting information over a Wi-Fi network. Data Engine sets up a server, which applications on LinX Platforms and other devices can connect to. The server that Data Engine runs can be set up on either a LinX device or on a computer. The applications on diﬀerent devices can use the Data Engine server to share information between each other as described in Figure 2. The ﬁgure also shows a LinX device as the host of the Data Engine server.

Figure 2: A graphic representation of the connection to a Data Engine server.

9 3.4 Dependencies When importing and using libraries in Qt, there is a need to specify what library to use on what platform since libraries are platform specific. This means that for every platform that utilizes the library, there needs to be a separate library file compiled for that platform. Library paths in Qt are set in the .pro file and to specify what library to use on what platform, the code snippets in Table 1 are required, see section 5.1.

3.4.1 Sapcore

To use Data Engine for communication between devices all projects need to import a library called Sapcore where the basic functions for connection are located. Sapcore is a library build in Qt by maximatecc. In the templates and demo application, library ﬁles for the following platforms are supported:

• Windows (Windows 8 and Windows Phone not supported)

• OS X

• Linux

• Android

• iOS

3.5 The LinX Software Suite LinX Software Suite is an open software platform with tools for easy development of the systems that the customers of maximatecc needs. Among many other tools it contains the LinX Core which is the location of the Data Engine which in turn is used to a great extent in this project. [1]

10 4 Method and development

During this project we have not had any strict allocation of assignments between us within the group. Instead we have tried to work together with whatever was the current task so that everyone in the project could have the same chance to learn about the things we were working on.

4.1 Creating templates Templates are created as .xml files, basically a type of text file, and in those files everything that should be included in the template, such as different kinds of files or code snippets, must be defined. The files that are specified to follow with the program should also exist in the same directory as the template.

4.1.1 Our templates

To create our templates we used a standard template as the base to make use of its structure. The source and header ﬁles for the connection to and communication with Data Engine was added to the templates .xml ﬁle and to its directory. We added an option to include an external library, in this case Sapcore, which is used to establish contact with Data Engine, with a standardized search path. The user also has the option to change the search path.

4.2 The Tutorial 4.2.1 Reasoning and purpose

We created the tutorial to be a guide on how to start developing applications for the three OS:s primarily discussed in this report. It is composed from our experiences from working with Qt. The tutorial is supposed to contain information about how to set up the development environment, how to include images and external libraries and how to deploy the application to diﬀerent devices.

4.2.2 Method

The tutorial was written by first using Google Documents, which allows several users to edit the same document at the same time, followed by a transfer of the finished text to Libre Office Writer. In the Writer we put it in maximatecc’s standard document layout and added all images, re-structured the lay-out and made sure it was completed before converting the finished tutorial into a PDF file.

4.3 Creating a demo application Our reasons to create a demo application was both to show maximatecc what a mobile device can handle and also to let ourselves learn more about Qt, QML etcetera. What we learned from this we would later have use for in the work with the tutorial.

4.3.1 The starting point

The demo application was created by using our own template as a base. This made it easy for us to start the development of the application since a part of the required work already was completed in the template.

11 4.3.2 Working on our own application

We built all of the graphical components using QML and the reason for this is that it is easier and more effective to build graphic components with QML than it is with C++. Instead of having a set plan from the beginning the application grew when we had a new idea or when we found something interesting that we wanted to try out. Because of this there are some differences in the design in the different sections of the application. For an example some of the buttons are drawn by the program and some are imported images.

The images we used in the demo application was from an earlier example application provided by maximatecc. Some of the inspiration for the development of the demo application came from this example but it was mostly in the way of graphical design. There was still the need to connect the device’s diﬀerent sensors to Data Engine and to decide what to use those sensor readings for.

How the signals were sent to and received from Data Engine was programmed in the project’s C++ header and source ﬁles, allowing the signals to also be used in the QML part of the application. By using built-in objects and commands we created a compass, a light sensor, an accelerometer and a proximity sensor, each of them linked to a speciﬁc signal value. The graphical objects were then assigned which of these signal values to display.

One thing we had problems with at a time was that the file system used with QML programming, the QtQuick Resource system, did not allow for file sizes over a certain size and this prevented the program from compiling at all. A workaround that we found was to split the files into several resources.

12 5 Results

5.1 Libraries The library, Sapcore, that was used in the application and template was successfully conﬁgured for all operating systems except Windows RT and Windows Phone. Sapcore has plug-ins that are not supported in Windows RT and Windows Phone, which caused a problem. These plug-ins were Winsock2.h and Ws2_32. A solution to this problem was not found and this resulted in the fact that we could not have any compatibility between Windows Phone and Data Engine. In Table 1 it is shown what commands are needed to import libraries for the diﬀerent operating systems.

Table 1: A table showing how to implement libraries for diﬀerent platforms in Qt.

5.2 A plain template The plain template is based on the QtQuick 2.0 template provided in Qt Creator. There are no additional classes or graphics in the plain template aside from what already exists the QtQuick 2.0 template. The only diﬀerence is that it contains all the libraries that are required to connect a device to Data Engine. The supported operating systems are Windows, OS X, iOS and Android.

The only way the plain template wizard diﬀers from the QtQuick 2.0 wizard is that the user is asked to provide the folder where the libraries for Data Engine are located.

5.3 A basic template The basic template contains the same things as the plain but also holds a few pre- conﬁgured classes and graphics to give an example on how a graphic application could look. It gives the user a wider starting point to set-up a connection with Data Engine. The template consists of three pages. One for connecting, one for receiving data and one for sending data.

In addition to giving the user an example of how to use Data Engine the template also shows a way of making the application layout dynamic for diﬀerent screen sizes. In Figure 3 we see that all the objects have their sizes conﬁgured relative to the width and height of the screen.

13 Figure 3: A code example of making a dynamic button that ﬁts all screen sizes.

How the three pages and the menu looks are shown in Figure 4. We have tried to make the look simplistic and the use of few colours is to not distract the user from what is shown. The default state of the menu is hidden to the left of the main view and when the “Menu” button is clicked it will appear with three buttons as shown in Figure 4d.

(a) The connect view (b) The receive view

Figure 4: An example of what the Basic Mobile Application template looks like.

14 5.4 The Tutorial Our work with the tutorial resulted in a 18 pages long document guiding the reader into the world of Qt cross platform application development and how to adjust an application for use of the maximatecc LinX Data Engine™. The tutorial is found as an attachment to this report.

The tutorial is structured in a way such that it starts with how to set up the required development environment and then moves on to covering each operating systems speciﬁc requirements system by system. Following the set-up comes a section on how to deploy applications to physical devices. After each OS has been covered follows a short guide on how to include external libraries and images to a project. The tutorial uses narrating ﬁgures with the text to make it more user friendly.

5.5 The Demonstrator Application The final version of the demo application was finished in the middle of May and it’s code is too large to show here. It consists of over a hundred different files, both code files and images, and over 3000 lines of code. In Figure 5, on the next page, several views of the finished application is shown.

The demo application consist of a start view, a connect view, a send view, a receive view and a crane view. The start view, Figure 5a, shows a welcome text and a small video feed showing the device’s camera output. When the bar to the left of the application is clicked a side menu, Figure 5b, will slide. The side menu contains buttons for each view which will direct the user to the chosen view when clicked.

In the connect view, Figure 5c, there are two text ﬁelds taking the input required to connect to Data Engine. There is also three buttons: the “Standard” button that enters a pre-set IP and port address, the “Connect” button used to connect and the “Subscribe” button which, if the application is connected to Data Engine, will let the application receive signals from and send signals to Data Engine.

The send view, Figure 5d, consist of several diﬀerent components, a compass, a water bar, three buttons and three text outputs. The compass and water bar are connected to the device’s own compass sensor and light sensor. The “+10” and “-10” buttons will change an outgoing signal when clicked and the button that reads “Receive” will toggle the application to a receiver mode, allowing the application to display incoming signals on the receive view. The text outputs displays the raw data from the device’s sensors.

The receive view has two diﬀerent views, one that shows the raw data from the incoming signals, as in Figure 5e, and one that uses the same signals to display a compass and a water bar, Figure 5f. The button reading “High end mode” changes the look of the water bar to a simpler design. Finally we have the crane view, Figure 5g, which holds a simulated crane. The crane design was taken from maximatecc’s own demo application and it is controlled using accelerometer signals. If the receiver mode is activated it will be controlled by the sending device’s signals, otherwise the crane will be controlled using the device’s own accelerometer.

15 (a) The start view (b) The menu view

(e) The receive view in text mode (f) The receive view in graphic mode

(g) The crane view

Figure 5: The diﬀerent views of the demo application

16 6 Discussion

Since this project was conducted in a relatively short time frame we have had to make decisions on what to include in the project, what goals to set and more. When deciding on what to include we’ve had to set some interesting or exciting ideas aside to only do what we thought was more practical and some of those excluded ideas will be discussed in this section. What will also be discussed is why we made the decisions we did and if we could have done this project, or parts of it, in any other way.

6.1 Operating system evaluation From the beginning the idea of this project was to explore ways to create applications for the three mobile operating systems Android, iOS and Windows Phone but during the project’s course the goals changed due to some complications with Windows Phone development. These complications led us to, in the end, put the Windows Phone development on a hold. The problem with Windows Phone originated in maximatecc’s source code for the connection to Data Engine, which did not include support for a plug-in that Windows Phone needs. Since the project had a relatively short time frame there was not enough time to find a solution to this problem. The fact that Windows Phone as an OS soon is going out of shop also made us reluctant of committing the required time and effort. Already later this year Windows 10 will be released and all Windows devices will use this new OS albeit with slightly different versions. So even if we did manage to work it out with Windows Phone our work would have become obsolete in just a few months time. Instead of putting down time on the Windows Phone we now hope the work we have done that works on Windows 8.1 Desktop will also be viable on Windows 10. [5]

6.2 Github The code-service Github has been a constant help to us during the project and this is exactly why we chose to work with it as the means to share our work. It is easy to create new repositories and to share them with your co-workers. It is also easy, if everyone documents their work properly, to follow every addition or edit to the project. Github makes sure that the users is always up to date when working on their projects, it makes the life of any programmer much easier!

6.3 Qt as an IDE Using Qt to develop applications was mostly a pleasant experience. Qt as an IDE is relatively easy to get started with it and there is a lot of good examples and tutorials on learning how to properly write code for Qt. We mostly wrote our code using QML which we found very user friendly and easy to get used to. On top of being a pretty good IDE Qt also shines when it comes to development for devices running on diﬀerent operating systems. If everything is set up correctly it is enough to write one code that can be compiled to the OS of the user’s choice and Qt will do the rest. The ease of not having to write a diﬀerent code for each OS saves a lot of time for the programmer and may in some cases be essential for a project to succeed.

6.4 The demonstrator application What might have been the largest and most time-consuming part of this project is the development of the demonstrator application. The reason that we made the demo appli-

17 cation is so that we could show both maximatecc and ourselves what was possible to do using a mobile device. Through working with the application we increased our knowledge of Qt and application development which also later in the project helped us with creating the tutorial. Something worth noting is since we had a ’learn by doing’-approach when developing the application it is written diﬀerently throughout its code. For an example, in the beginning we programmed the buttons using QML’s built in feature “Button” but since these buttons have a default look that we did not want we later chose to build the buttons by ourselves using the standard Rectangle type and some added functionality. [6]

Something that we quickly understood when deploying to devices with diﬀerent screen sizes and resolutions was that we had to design all graphics dynamically. This would ensure that the application’s interface looks good on all kinds of devices. Something else we discovered was that all the Sensor types in Qt does not work on all kinds of devices, Qt only has support for a certain number of devices for each Sensor type. We chose not to address this problem because of the limited time that was left in the project. [7]

A problem we did have time to ﬁx was that the application crashed whenever the user tried to connect to a non-valid IP-address. To work around this we created a function that checks that the numbers only take up to 32 bits of storage which is the limit for an IPv4 address. When the “Connect” button is clicked the function will ﬁrst check that the IP address is valid and only if so allow a connection to be made. [8]

It may be of worth to note that the images in the demonstrator application are imported from an example application supplied by maximatecc and we have two reason to why this was done. The ﬁrst was that we wanted our demo application to have a maximatecc-like look which it automatically got when we used their graphics. The second reason was that we did not have enough time in the project to create all the graphics on our own. The application is also not going to be used for anything more than as a demo for maximatecc and hence it is ﬁtting that it has their graphics.

6.5 The templates An important part of the project is the work we’ve done with the templates. Why we made templates at all was to show and give maximatecc a working base to develop applications that uses a connection to the Data Engine server. The template can be deployed to a mobile device without any alteration and was made so that it would show how a few signals could be sent and also received and displayed on the mobile device. This is a good place to start when building a mobile application in Qt and the template shows how easy it is to get going. The template may also work as a base for maximatecc to continue working on and maybe even to supply their own customers with.

6.6 The future of this project In the future this project could lead to many different applications in the hands of both maximatecc and their customers. Hopefully they will see the advantages of being able to communicate with the LinX Systems through a mobile device and continue to develop the software suite in that direction. Who knows what they will create and what other possibilities it may lead to in the end. Whatever happens we hope that it will be used in a way that integrates the different sensors and abilities a mobile device offers to improve work place of people across the world.

18 7 Conclusions

7.1 Selection of operating systems From the results of the project we can come to several conclusions. One of them is that some operating systems are better suited for cross platform application development than others. Because development for iOS devices requires Xcode which in turn requires OS X to run the user is required to use a Mac somewhere down the line of developing.

Another thing we conclude is that developing for Windows Phone devices in most cases will not be worth the effort or funds required. You will need to both work on a Windows 8.1 Pro system and get the rather expensive software Microsoft Visual Studio. Also, within not one year’s time, Windows will be releasing a new OS, Windows 10. The new OS will be distributed as different versions across all kinds of devices and platforms and effectively make Windows Phone useless. Because of that developing for Windows Phone might be a waste of time since anyone doing that soon will be forced to swap over to Windows 10 development instead. [5]

Concerning the third OS we tried developing for, Android, it is not operating system- bound like development for Windows Phone or iOS. This means that working with An- droid is the easiest to achieve for the user, not requiring anything but free software and a free choice of OS for the environment’s system.

Because of the reasons mentioned above we recommend using OS X as your environment’s OS. This will give the user the widest alternatives for choice of development target. If your system is not running OS X and getting an Apple system is out of the question this can be achieved through running OS X in a virtual machine on any desktop. While the same is also true if you would want to run Windows development on a non-windows system it is not the best solution.

7.2 Final conclusion The project has been successful in showing that a connection can be made between two mobile devices through Data Engine. It has also been successful at showing how to create and deploy applications for diﬀerent mobile operating systems through the work with templates and the demo application. The goals that we set up in the beginning has all been fulﬁlled but one, the Windows Phone connection, but we still think that the project has been successful.

19 8 References

[1] maximatecc (company) as of May 2015. Information from http://www.maximatecc.com/ and Daniel Nisses-Gagnér, employee of maximatecc.

[2] Qt and Qt Creator 3.3.2 as of May 2015. Information and software downloaded from http://www.qt.io/ and information from http://en.wikipedia.org/wiki/Qt_(software).

[3] Qt Modeling Language, May 5th 2015, http://en.wikipedia.org/wiki/QML.

[4] Github, May 12th 2015, http://en.wikipedia.org/wiki/GitHub and https://github.com/.

[5] Microsoft News Center, May 20th 2015, http://news.microsoft.com/2014/09/30/microsoft- unveils-the-future-of-windows/.

[6] Button and Rectangle, Qt Types, May 26th 2015, http://doc.qt.io/qt-5/qml-qtquick- controls-button.html and http://doc.qt.io/qt-5/qml-qtquick-rectangle.html.

[7] Sensor, Qt Type, May 26th 2015, http://doc.qt.io/qt-5/qtsensors-index.html.

[8] The IPv4 protocol, May 29th 2015, http://en.wikipedia.org/wiki/IPv4.

20 9 Appendix

9.1 Abbreviations APK Android Application Package - the ﬁle format used to distribute application software onto the Android OS

IDE Integrated Development Environment - a software application providing facilities for software development

NDK Native Development Kit

OS Operating System

QML Qt Modeling Language - a JavaScript based language used by Qt Quick in Qt programming

Qt A cross-platform application framework

SDK Software Development Kit

9.2 The tutorial One of the results of this project was a tutorial on how to get started with application development in Qt focused on developing applications connecting to the maximatecc LinX Data Engine. The tutorial, in its entirety, is found below.

21 LinX Mobile Application Toolsuite Revision: 4 A tutorial: How to get started Date: 2015-06-03

LinX Mobile Application Toolsuite

A tutorial: How to get started

www.maximatecc.com Contents Revision history...... 2 1.Introduction...... 3 1.1.The IDE: Qt 5.4...... 3 2.Installing the required software...... 4 2.1. Android development...... 4 2.1.1.Requirements...... 4 2.1.2.Setup...... 4 2.1.3.Building and deploying...... 8 2.2. iOS development...... 10 2.2.1.Requirements...... 10 2.2.2.Setup...... 10 2.2.3.Building and deploying...... 11 2.3. Windows development...... 13 2.3.1.Requirements...... 13 2.3.2.Setup...... 13 2.3.3.Building and deploying...... 14 3.Importing Data Engine support and other libraries...... 15 4.Adding images...... 16 5.Converting an existing project...... 17 6.FAQ...... 18

Revision history

Rev Date Author Comments Dennis Myrgren, John 1 2015-05-20 The first version of the tutorial. Rahme, Jakob Andersson Dennis Myrgren, John 2 2015-05-21 Fixed miscellaneous small errors. Rahme, Jakob Andersson Dennis Myrgren, John 3 2015-05-26 Added links where needed. Rahme, Jakob Andersson Dennis Myrgren, John Section 5: converting an existing project added. 4 2015-06-03 Rahme, Jakob Andersson Apart from that only minor tweaks. 1. Introduction

This is a tutorial on how to create and develop mobile applications with the purpose of connecting them to maximatecc’s LinX module Data Engine. The tutorial is composed of text with graphic representations helping to explain some steps. It is recommended that all relevant parts of the tutorial is read before beginning to configure your computer system. The major part of the tutorial will be on setting up your system for application development. If you are already set up you can skip down to 'Importing libraries' where we explain specifically how to connect the correct libraries to your project to get the connection to the Data Engine.

1.1. The IDE: Qt 5.4 This tutorial will be using Qt 5.4 as its Integrated Developing Environment. It is the IDE that was used in the project where this tutorial was made and it also is supported in maximatecc’s software suite. Qt also allows for easy cross-development of applications for different mobile operating systems which is very handy for the purpose of this tutorial. The firmware can be downloaded from Qt Downloads (May 2015).

www.maximatecc.com 2. Installing the required software

Depending on what system is used for developing and on what kind of device the applications are meant to run on the installation process varies. In this tutorial we will go through the steps to set up a developing environment for Android, Windows Phone and iOS devices. The processes are similar and in many places overlap so if the intention is to develop for more than one operative system make sure to follow all of the relevant guides.

2.1. Android development

2.1.1. Requirements Before setting up to start developing and building applications for Android you will need Qt 5.4. Earlier versions may or may not work but it is recommended to use the latest stable version of Qt.

2.1.2. Setup The first part of the setup is to install the Android Development kits. The ones that are needed are listed below as they were May 2015. Install the software in a location that is easy to find later on. There is also a guide on how to get started with Android development provided by Qt, it can be found here.

The following should be installed:

▪ Android JDK ,1.8.0_45, Java SE Development Kit 8 (May 2015) ▪ Android SDK, install API 22, Google USB Driver and the other default tools, Android SDK Tools (May 2015) ▪ Android NDK, r10e, Android NDK Tools (May 2015), requires a search path without blank spaces ▪ Apache Ant, 1.9.4, Apache Ant Download

Figure 1: The needed tools and kits from the Android SDK (part one). www.maximatecc.com Figure 2: The needed tools and kits from the Android SDK (part two).

When these are installed it is time to install Qt Creator. If it already is installed you will instead need to update its packages. Open ‘Change/Uninstall Programs’ from the Control Panel and find Qt in the list. Right-click on Qt, choose ‘Uninstall’ but instead of uninstalling choose the option ‘Package Manager’. In figure 3, below, it is shown what packages should be chosen for Android development.

Depending on your Qt version you may need to register a repository to be able to add packages. If you don’t have any prepared repositories one of Qt’s online repositories, e.g. Qt Windows x86 Online Repository, will do.

www.maximatecc.com Figure 3: The necessary Qt packages for Android development.

The most common kit, as of May 2015, when developing for Android is armeabi-v7a but the others might be needed to develop applications for older devices or devices not running on ARM.

When all of the above is installed it is time to configure Qt. Open Qt Creator and go to Tools -> Options. In the options window choose Android in the panel on the left. Here you are going to let Qt know where the JDK, SDK, NDK and Ant folders are located on your system as done in Figure 4. When that is done you are ready to start developing your application!

Figure 4: Where the pathways to the SDK, JDK, NDK and Apache ant are entered. www.maximatecc.com Figure 5: As figure 4 but with the pathways entered.

To deploy to a device some special USB drivers are required. These drivers are included in the SDK and is called Google USB Driver and they are probably already downloaded if you chose the defaults in the SDK. When an Android device is connected to the computer, open the Device Manager from the Control Panel. Right click the Android device in the list, choose ‘Install drivers’ and find the location of the Google USB Drivers as in Figure 6.

Figure 6: Where the Android device drivers are updated.

Some application settings need an Android Manifest-file (.xml) and to create and configure one of those in Qt go to Projects -> Build -> Build Android APK -> Create Templates, see figure 7. In this file the APK file may be edited, application name can be set, icons may be inserted etc.

www.maximatecc.com Figure 7: Where you can create and edit a template for an Android application.

2.1.3. Building and deploying Deploying to a local Android device requires only a few steps.

▪ Connect the device to the computer

▪ Choose the correct device it when building and running from Qt

▪ Make sure that the USB debugging in the Developer options on your Android device is enabled

▪ When you start building you will need to confirm that the computer may launch an application to the device

www.maximatecc.com Figure 8: Deploying locally to an Android device.

An example of deployment to a Nexus 7 tablet is shown in Figure 8. To deploy the application for a wider but still restricted audience you can e-mail or share the application's .apk file directly to your target recipients. The .apk file is located in the directory Android-build->bin in your build folder and is by default named QtApp- debug.apk (or QtApp-release.apk depending on what was built).

Figure 9: The location of the .apk file.

www.maximatecc.com 2.2. iOS development

2.2.1. Requirements To develop for iOS you will need the following:

▪ Xcode (preferably the latest version) ▪ A system running OS X ▪ An Apple Developer's license (for deployment, not development) ▪ Qt 5.4 or later

2.2.2. Setup When setting up for iOS development start by downloading and installing Xcode from App Store. You will also need to install Qt on your system. Download the latest version and install it with the packages shown in Figure 10 below.

Figure 10: Qt packages needed for iOS development.

If installed correctly you should now be able to create a project in Qt with the iPhone kits as in Figure 11.

Figure 11: The kits that should be available. www.maximatecc.com 2.2.3. Building and deploying When you have got your Apple Developer's license you are ready to deploy to iOS. Start by opening Xcode and configuring it in the following way: go to Xcode → Preferences → Accounts → make sure that Xcode is connected to the account which has a Developer's license.

When a Qt project is ready for deployment, build it for the preferred iOS (e.g. iphoneos-clang). This will create a .xproj file in your build folder and this is the file that will be opened in Xcode. When in Xcode you may also set icons for the project under the project's 'General' tab. Choose 'Use Asset Catalog' for the option 'App Icon Source' and you will get a folder under 'Resources' → 'Images' where the icons can be put.

Figure 12: The application's bundle identifier.

When it is opened in Xcode go to its 'General tab' and find the Bundle identifier for the project, see figure 12. Sign in to the Apple Developer's center and go to the member's center (Apple Member's Center as of May 2015) in which you will find 'Certificates, identifiers and profiles'. Hit 'identifiers' and in the new view add a new identifier with the Bundle ID from the Xcode project as in figure 13.

Figure 13: Creating an identifier in the Apple Developer's center.

The next step is in the 'Provisioning profiles', go there and press 'Create new' and you will move on to the next view, see figure 14. After choosing the correct project you will be asked what provisioning profile that is needed and depending on how the application is going to be distributed you can either choose 'Development' or 'App Store', see figure 15. www.maximatecc.com Figure 14: Creating a Provisioning profile in the Apple Developer's center.

Figure 15: Choosing the Provisioning profile type.

Deploying the application now needs only two more steps: go to iTunes Connect with your registered Bundle ID and add the application there. When the ID is added to iTunes Connect the project can be submitted from Xcode. With Xcode open go to www.maximatecc.com 'Product' → 'Archive' and hit 'Submit'. Remember to choose the correct iOS device when submitting, see figure 16.

Figure 16: Choosing the correct iOS device when deploying.

An important note is that for a seamless distribution to a closed audience the Enterprise Developer's license, which inherently has this function, is recommended.

2.3. Windows development

2.3.1. Requirements ▪ Windows OS, preferably 8.1 or later

▪ Microsoft Visual Studios 2013 or later

▪ Microsoft Developer's account

2.3.2. Setup When setting up for Windows development it is recommended to install Microsoft Visual Studios 2013 before installing Qt, choosing the necessary components in the process. If Qt Creator is already installed then go to the Package manager is found in the Uninstall wizard. What kits are needed for development on Windows Phone and Windows RT are seen in figure 17.

Figure 17: Qt packages needed for Windows application development.

www.maximatecc.com 2.3.3. Building and deploying You may want to transfer your project from Qt to Microsoft Visual Studio for continued development or to add dependencies unique for Visual Studio. It is also required if the application is to be simulated.

In Qt, right click the .pro file for your project. Select ‘Open Command Prompt here’. In the command prompt, write ‘cd’ followed by the Windows build’s search path. After this write down the search path for the appropriate qmake.exe file, in the example in figure 19 this is done for Windows Phone arm, and then “-tp vc” , the .pro files search path and “”CONFIG+=windeployqt””.

Figure 18: An example of how to transfer "winTest" to Microsoft Visual Studio.

The Microsoft Visual Studio project file will now appear in the build folder of the Qt project as a VC++ file.

www.maximatecc.com 3. Importing Data Engine support and other libraries

Everything brought up so far in this tutorial has been about installing the necessary software for application development and your system should by now be ready for that. The objective of the tutorial, however, is to get started with developing applications connecting to the maximatecc LinX Data Engine. To do that the sapcore library needs to be imported to the application's project and how to add libraries will be explained in this section.

For the application to able to communicate with the Data Engine it needs to import the correct libraries. The libraries are a part of the Core program provided by maximatecc and can be found under Core → sapcore. Finding and importing the right library can be a bit tricky because depending on what destination OS the application has it will need different libraries. This means that before importing a library to your project you must build the library itself for the relevant OS.

It should also be noted that the search path to a library will be different on Windows systems compared to Linux systems and therefore you should use specific commands in the .pro file that includes only the paths for the OS that you are building for. Figure 19 holds an example of how the calls for the different libraries can be written in a project's .pro file. For the example it was decided to keep the libraries compiled for different operating systems in the same directory and hence they had to be named differently. The example is working for Android, iOS and Windows desktop.

Figure 19: Code extract from .pro file showing how to make calls for different OS's.

www.maximatecc.com 4. Adding images

Depending on what you have worked with earlier you may already be familiar with this process but if you are not, this could help you. To add an image to the Qt project you first need to put the image file in the project directory. Then you need to create a new ‘Qt Resource File’ in the project, name it as you see fit. Right click the resource file and choose ‘Add Existing File’ and then find the image or images that you want to add.

Qt supports several image types without the need of importing additional modules but an exception is vector graphics. For .svg files the addition ‘QT += svg’ in the .pro file is required and the inclusion ‘#include ’ might be needed in your headers and/or source files.

A note on the usage of the Qt resource system is that the files included in a single resource cannot be above a certain size limit that depends on your current system. If the files takes up too much memory the C++ compiler will crash.

www.maximatecc.com 5. Converting an existing project

If the case is that you want to convert an existing project to run on mobile devices instead of starting from scratch this tutorial covers that too. When you have decided what systems to try to develop for, install those packages for Qt to get started. See section 2 for details.

When the correct software is installed these are some of the actions needed for the project to run on mobile devices. Not all may be required for every project and in some cases there are probably even more adjustments needed

• Make sure that all of the imported files, images, audio etc., are handled correctly. They may need to be moved to Qt Resource files.

• Make sure that all the libraries your application uses are built for the new OS. See section 3 for details and an example.

• Make sure that all search paths are correct, they vary depending on what OS you are developing from.

• Depending on what kind of application is to be converted some additional Qt libraries may need to be imported.

• If the application has been used on a device with different hardware options and connections these code parts handling this may need to be configured or removed. For an example an application may be converted from use on a device controlled by buttons to an Android device controlled by a touch screen. The Android device does probably not have support for the buttons and the code will then not compile until configured.

• If the application is supposed to be deployed to different sized devices, for an example both an Android phone and an Android tablet, we strongly recommend that the graphic in the application uses a dynamic layout. This makes sure that the application looks good and work correctly on many devices.

As mentioned earlier these are just some of the changes that may need to be done and if you are working with a big project there are probably more.

www.maximatecc.com 6. FAQ How do I play audio files on iOS? To play audio files in general the QML type MediaPlayer can be used. There can be some unforeseen difficulties though in getting the audio files onto the iPhone device. To solve this problem the following code snippet needs to be added in the .pro file, where “Audio” is the folder with audio files that needs to be added.

ios { message(Compiling for iOS) data.files = Audio QMAKE_BUNDLE_DATA += data }

To then use the files in the application you need to have the absolute path to the file. For example in your main.cpp file the following code could be added:

QString workingDir = "file://"+QDir::currentPath(); engine.rootContext()->setContextProperty("baseDir", workingDir);

In the QML MediaPlayer you would then set the source to the following:

source = baseDir+"/Audio/YourAudioFile.mp3"

The audio files should now play without issues.

How do I add icons to iOS without using Xcode? The recommended way to add icons to iOS is to use Xcode, it is the easiest way. But if needed you can modify the Info.plist file yourself. The Info.plist file contains information about, for an example, the icons, the start up image and the screen orientation. All of this can also be edited in Xcode. Qt provides a very good guide on how to modify the Info.plist file directly in Qt on this link (May 2015): http://doc.qt.io/qt-5/platform-notes-ios.hmtl

Potential fix for Android compile problem During the research to create this tutorial a problem with compiling to Android troubled us for some time. The fix we used was found on Stack Overflow: http://stackoverflow.com/questions/4314085/android-compile-error-no-jvm- initialized