Tracking App Administrator and User Guide

Tracking App connects to NCTU MapTalk by default. For general users, please refer to the section 1 of each part. If you want to link the Tracking App to your own MapTalk, please follow the section 2 of each part.

Part 1. Tracking App Installation

System Requirements Android OS version 8.0 and above MapTalk

The first section of this part illustrates the installation for the users. The second section describes the installation for the administrators.

Section 1. User Installation

This section consists of two steps. Please follow the steps in order.

Step 1. On your smartphone, click the link or scan the QR code below to download the Tracking App APK (Android application package) file.

https://github.com/IoTtalk/IoTtalkAndroidApp/raw/master/quick_install/IoTtalkApp-1080310.apk

Step 2. After successfully downloading the APK file, click it to install

1

Tracking App.Click the Tracking App APK file on your smartphone, and then the smartphone displays the installation prompt (Figure 1 (a)). Please click the “INSTALL” button (Figure 1 (1)) to start the installation. Wait for the progress (Figure 1 (b)) until the installation is complete (Figure 1 (c)). Next, please see the Tracking App operation in section 1 of Part 2.

1

(a) Installation prompt (b) Installation in progress (c) Installation doneFigure 1. IoTtalk App installation screenshots

Section 2. Administrator Installation

This section consists of four steps. Please follow the steps in order.

Step 1. Click on the link below to download the IoTtalk App source codehttps://github.com/IoTtalk/IoTtalkAndroidApp

Step 2. Modify IoTtalkAndroidApp/app/src/main/java/tw/org/cic /tracking_mobile/TrackingConfig.java

1. Set the IoTtalk server address. Tracking App connects to the IoTtalk server.

Scenario 1：secure connection (https)static final String trackingHost = "https://IOTTALK_SERVER_DOMAIN_NAME";

Example：2

static final String trackingHost = "https://map.iottalk.tw";

Scenario 2：no secure connection (http)static final String trackingHost = "http://IOTTALK_SERVER_IP:IOTTALK_SERVER_PORT";

Example：static final String trackingHost = "http://140.113.111.111:9999";

2. Set the Map address. Tracking App connect to Map. Scenario 1：secure connection (https)

static final String mapURL = "https://YOUR_MAP_DOMAIN_NAME/map/";

Example：static final String mapURL = "https://map.iottalk.tw/map/";

Scenario 2：no secure connection (http)static final String mapURL = "http://YOUR_MAP_IP:YOUR_MAP_SERVER_PORT";

Example：static final String mapURL = "http://140.113.111.111:8866";

Step 3. Package the IoTtalk App source code to an APK (Android application package) file by using the software such as Android Studio or Eclipse and provide the APK file for general users to download.

Take Android Studio software for example： Import IoTtalk App source code

File Open IoTtalk App source code OK Package to the APK file

Build Build APK(s) Get the APK file with the following path

IoTtalkAndroidApp/app/build/outputs/apk/debug/app-debug.apk

Step 4. Send the APK file to your smartphone and click it to install Tracking App

Click the Tracking App APK file on your smartphone, and then the smartphone displays the installation prompt (Figure 1 (a)). Please click the “INSTALL” button (Figure 1 (1)) to start the installation. Wait for the

3

progress (Figure 1 (b)) until the installation is complete (Figure 1 (c)). Next, please see the Tracking App operation in section 2 of Part 2.

Part 2. Tracking App Operation

The first section of this part illustrates the operating procedures for the users. The second section describes the operation for the administrators.

Section 1. User Operation

This section consists of five steps. In Step 1~3, please follow the steps in order. In Step 4~5, you can decide the execution order by yourself.

Step 1. Open the Tracking App page

After the installation is done, click the IoTtalk App icon (Figure 2 (a)) on the smartphone’s desktop, and then the smartphone displays the IoTtalk App index page (Figure 2 (b)). Please click the “TRACKING” button (Figure 2 (1)) to open the Tracking App page (Figure 2 (c)).

1

5

3

4

6

2

7

(a) IoTtalk App icon (b) IoTtalk App Index page (c) Tracking App page

Figure 2. Screenshots of using IoTtalk App

Step 2. Set up on the Tracking App page

1. Set your Tracking name

4

The Name (Figure 2 (2)) field implements the user’s specific name shown on the Map (e.g. Cindy). Please fill your name in the editing area (Figure 2 (3)).

2. Set the Tracking timeThe Time (Figure 2 (4)) field implements the duration of using the Tracking service. Please select the duration that you want to be tracked in the drop-down list (Figure 2 (5)), ranging from 10 to 60 minutes or unlimited.

Step 3. Start up the Tracking service

1. Click on the “Start” button (Figure 2 (6)) to start the Tracking service. Before starting the Tracking service, the system first checks the following item. Network

Since the Tracking service needs to open the Map GUI and upload the device location, if there is no network connection, the network access request dialog box (Figure 3 (a)) will pop up. After the dialog box pops up, please click the “OPEN NETWORK” button (Figure 3 (1)) to enter the network setting page and open the available network.

App Location Access PermissionThe main function of the Tracking service is used to get the user’s location. Therefore, if you are using this service for the first time, you will be asked to provide location access (Figure 3 (b)) for the Tracking App. Please click “ALLOW” button (Figure 3 (2)) to ensure that the Tracking service can be successfully executed. After clicking the “ALLOW” button (Figure 3 (2)), the location access permission dialog box is no longer displayed.

Device LocationThe Tracking service keeps getting the user’s location. Therefore, if the user doesn’t open the device location, the system will display a turn on location request dialog box (Figure 3 (c)). Please click the “OK” button (Figure 3 (3)) to open the device location. Let the Tracking service get the user’s location.

5

1

1

32

(a) Network access request (b)Location access request (c)Turn on location request

Figure 3. Screenshots of Tracking permission request dialog box

2. After passing the inspection, the Tracking service starts running. After that, the system changes the word “Start” on the button (Figure 2 (6)) to “Stop” and sends an Android system notification (Figure 4) to inform the user that the Tracking App is running in the background. In addition, if the user selects the Tracking duration in the Time field (Figure 2 (4)), the system additionally sends a Tracking remaining time notification (Figure 5). Next, the Tracking service automatically open the Map GUI through the browser.

Figure 4. Android system notification

Figure 5. Tracking remaining time notification

6

Step 4. View the “HumanTracking” App on the Map GUI1. When the Tracking service starts running, the Map device continue

receiving the user’s location (Figure 12). After the Map GUI is automatically opened by the browser, Map will locate the cyber object which represents the user’s location in the center of the map (Figure 6 (1)). In addition, the cyber object displays the user’s ID in the center. If the user clicks on the cyber object, a dialog box will pop up (Figure 6 (2)).

1

5

34

6

2

7

9

8

1011

12

13

(a) Dialog box (b) History trajectory (c) Offline displayFigure 6. HumanTracking cyber objects screenshot

2. The contents of the dialog box can be divided into the following three items：(1) Name (Figure 6 (3))

This field displays the name of the user. It is the same as name the entered in Step 2.

(2) Update Time (Figure 6 (4))This field displays the latest update time for the cyber object.

(3) History (Figure 6 (5))When the user clicks the “History” button, a history time selection dialog box ( Figure 7) pops up. After choosing an option, the user can track the trajectory of the user (Figure 6 (6)) and the color of the trajectory is the same as the ID in the object (Figure 6 (7)).

7

Figure 7. History time selection dialog box

3. If you have trouble finding your location in the map, you can click the location button (Figure 6 (8)), which shows the map with your cyber object in the center.

4. Moreover, if you want to view the location of the other users, you can click the “App” button (Figure 6 (9)) on the menu bar and find the application named “HumanTracking” (Figure 6 (10)) in the drop-down list. After clicking the “HumanTracking” button, you can see the names of all users. Next, click “Show All” (Figure 6 (11)) or personal user name (Figure 6 (12)) to watch the locations of other users (Figure 6 (13)).

5. Note that if the user’s location has not been updated for more than one hour, which indicates the user is offline, then the user’s cyber object shows with an additional black edge (Figure 6 (13)).

6. In addition, if you want to reopen Map after closing it, you can click the “open Map” button (Figure 2 (7)). If you click the “open Map” button while tracking, your cyber object will be placed in the center of the map (Figure 6 (1)). Otherwise, your cyber object will not be placed in the center.

Step 5. Close the Tracking service

1. When the Tracking service starts running, the word “Start” on the button (Figure 2 (6)) will be changed to “Stop”. The user can stop the Tracking service at any time by clicking the “Stop” button. After the Tracking service is stopped, the word “Stop” on the button will be changed to “Start”. If the user wants to start the Tracking service again, he/she can click the “Start” button (Figure 2 (6)).

2. if the user selects the Tracking duration in Step 2, the Tracking service will automatically stop at the end of the time and send a Tracking end notification (Figure 8) to inform the user that the Tracking service has

8

terminated. If the user want to start the Track service again, he/she can click the Tracking end notification to open the Tracking App page (Figure 2 (c)).

Figure 8. Tracking end notification

9

Section 2. Administrator Operation

This section consists of seven steps. In Step 1~4, please follow the steps in order. In Step 5~7, you can decide the execution order by yourself.

Step 1. Open the Tracking App page

After the installation is done, click the IoTtalk App icon (Figure 2 (a)) on the smartphone’s desktop, and then the smartphone displays the IoTtalk App index page (Figure 2 (b)). Please click the “TRACKING” button (Figure 2 (1)) to open the Tracking App page (Figure 2 (c)). At this moment, Tracking App automatically registers the device to MapTalk.

Step 2. Connect Tracking App to MapTalk

1. If you are using this service for the first time, please follow the instructions in the MapTalk administrator and user guide Part 2 Section 2 Step 1~2 to add a movable application named “HumanTracking”. You have to select the “Movable” option in the Location field and the “No Letter” option in the Layout field.

2. Go to IoTtalk Homepage Project Select a project (Figure 9 (a)) add project (Figure 9 (b)) to create a project

a

b

Figure 9. IoTtalk project window

10

3. Click Model (Figure 10 (a)) Tracking (Figure 10 (b)) to display the registered Tracking device ( Figure 11 (a))

a

ba

b

Figure 10. Device model selection Figure 11. Device model connection

4. The device feature (DF) of the Tracking device is “IDGeoData-I” ( Figure11 (b)). There are five DF-parameters in the DF. The DF-parameters from left to right represent latitude (Figure 12 (a)) 、 longitude (Figure 12 (b))、name (Figure 12 (c))、ID (Figure 12 (d)) and timestamp (Figure 12 (e)). The name field is consistent with the input in Step 3, and the ID field is assigned by the system to distinguish it from different users. Moreover, the types of five DF-parameters are float, float, string, float, string.

d eca b

g

f

h

Figure 12. Device model connection (cont.)

5. Next, please follow the instructions in the MapTalk administrator and user guide Part 2 Section 2 Step 4 to display the Map device and

11

connect the IDF (input device feature; Figure 12 (f)) “IDGeoData-I” to the ODF (output device feature; Figure 12 (h)) “HumanTracking” through the join circle (Figure 12 (g)) is shown in Figure 12. In this way, all users can deliver the ID tag tracking data to the map through the join circle.

Step 3. Go back to the Tracking App page

1. Set your Tracking nameThe Name (Figure 2 (2)) field implements the user’s specific name shown on the Map (e.g. Cindy). Please fill your name in the editing area (Figure 2 (3)).

2. Set the Tracking timeThe Time (Figure 2 (4)) field implements the duration of using the Tracking service. Please select the duration that you want to be tracked in the drop-down list (Figure 2 (5)), ranging from 10 to 60 minutes or unlimited.

Step 4. Start up the Tracking service

1. Click on the “Start” button (Figure 2 (6)) to start the Tracking service. Before starting the Tracking service, the system first checks the following item. Network

Since the Tracking service needs to open the Map GUI and upload the device location, if there is no network connection, the network access request dialog box (Figure 3 (a)) will pop up. After the dialog box pops up, please click the “OPEN NETWORK” button (Figure 3 (1)) to enter the network setting page and open the available network.

App Location Access PermissionThe main function of the Tracking service is used to get the user’s location. Therefore, if you are using this service for the first time, you will be asked to provide location access (Figure 3 (b)) for the Tracking App. Please click “ALLOW” button (Figure 3 (2)) to ensure that the Tracking service can be successfully executed. After clicking the “ALLOW” button (Figure 3 (2)), the location access permission dialog box is no longer displayed.

Device Location

12

The Tracking service keeps getting the user’s location. Therefore, if the user doesn’t open the device location, the system will display a turn on location request dialog box (Figure 3 (c)). Please click the “OK” button (Figure 3 (3)) to open the device location. Let the Tracking service get the user’s location.

2. After passing the inspection, the Tracking service starts running. After that, the system changes the word “Start” on the button (Figure 2 (6)) to “Stop” and sends an Android system notification (Figure 4) to inform the user that the Tracking App is running in the background. In addition, if the user selects the Tracking duration in the Time field (Figure 2 (4)), the system additionally sends a Tracking remaining time notification (Figure 5). Next, the Tracking service automatically open the Map GUI through the browser.

Step 5. View the “HumanTracking” App on the Map GUI

1. When the Tracking service starts running, the Map device continue to receive the user’s location (Figure 12). After the Map GUI is automatically opened by the browser, Map will locate the cyber object which represents the user’s location in the center of the map (Figure 6 (1)). In addition, the cyber object displays the user’s ID in the center. If the user clicks on the cyber object, a dialog box will pop up (Figure 6 (2)).

2. The contents of the dialog box can be divided into the following three items：(1) Name (Figure 6 (3))

This field displays the name of the user. It is the same as name the entered in Step 3.

(2) Update Time (Figure 6 (4))This field displays the latest update time for the cyber object.

(3) History (Figure 6 (5))When the user clicks the “History” button, a history time selection dialog box ( Figure 7) pops up. After choosing an option, the user can track the trajectory of the user (Figure 6 (6)) and the color of the trajectory is the same as the ID in the object (Figure 6 (7)).

13

3. If you have trouble finding your location in the map, you can click the location button (Figure 6 (8)), which shows the map with your cyber object in the center.

4. Moreover, if you want to view the location of the other users, you can click the “App” button (Figure 6 (9)) on the menu bar and find the application named “HumanTracking” (Figure 6 (10)) in the drop-down list. After clicking the “HumanTracking” button, you can see the names of all users. Next, click “Show All” (Figure 6 (11)) or personal user name (Figure 6 (12)) to watch the locations of other users (Figure 6 (13)).

5. Note that if the user’s location has not been updated for more than one hour, which indicates the user is offline, then the user’s cyber object shows with an additional black edge (Figure 6 (13)).

6. In addition, if you want to reopen Map after closing it, you can click the “open Map” button (Figure 2 (7)). If you click the “open Map” button while tracking, your cyber object will be placed in the center of the map (Figure 6 (1)). Otherwise, your cyber object will not be placed in the center.

Step 6. Close the Tracking service

1. When the Tracking service starts running, the word “Start” on the button (Figure 2 (6)) will be changed to “Stop”. The user can stop the Tracking service at any time by clicking the “Stop” button. After the Tracking service is stopped, the word “Stop” on the button will be changed to “Start”. If the user wants to start the Tracking service again, he/she can click the “Start” button (Figure 2 (6)).

2. If the user selects the Tracking duration in Step 3, the Tracking service will automatically stop at the end of the time and send a Tracking end notification (Figure 8) to inform the user that the Tracking service has been terminated. If the user want to start the Track service again, he/she can click the Tracking end notification to open the Tracking App page (Figure 2 (c)).

14

Step 7. Gain insight into the Tracking App operation

Figure 13 illustrates the architecture of the Tracking App. Next, the Tracking App operation is explained based on the figure：

GraphicRenderer

6User Event Handler 2

Tracking Control 4

Static File

DataControl

3

5

Notification Handler

Timer

11

13

User 1

MsgHandler7

9

PermissionHandler 10

Push Register

MapTalk Server

Location Handler

12

814

Figure 13. The functional blocks of the Tracking device

1. Clicking the “TRACKING” button (Figure 2 (1)) will load the Tracking App page and automatically register the device to MapTalk.

When the user (Figure 13 (1)) clicks the “TRACKING” button (Figure 2 (1)) in the IoTtalk App index page (Figure 2 (b)), the User Event Handler (Figure 13 (2)) catches the event. The User Event Handler is used to catch the events that a user clicks to trigger. Therefore, the User Event Handler passes the open Tracking App page (Figure 2 (c)) request to the Data Control (Figure 13 (3)), at the same time, delivers the registration request to the Tracking Control (Figure13 (4)).

The Data Control is responsible for communicating with the Static File (Figure 13 (5)). The Static file is an XML file that stores the Tracking App data. As a result, the Data Control retrieves the required data from the Static file, such as the user name, Tracking time, Tracking status and sends the above data to the Graphic Renderer (Figure 13 (6)). The Graphic Renderer shows the GUI that the user sees. Therefore, the Graphic Renderer will generate the entire Tracking App page and display it to the user. The message path of the whole process is (1) (2) (3) (5) (3) (6) (1).

15

The Tracking Control is used to manage the Tracking service. Therefore, after the Tracking Control realizes that it is a registration request, it will check if the device is already registered. If not, the Tracking Control dispatches the registration request to the MsgHandler (Figure 13 (7)). The MsgHandler is responsible for interacting with the MapTalk server (Figure 13 (9)). Therefore, the MsgHandler dispatches the registration request to the Register task (Figure 13 (8)). Eventually, the Register task connects to the MapTalk server. The message path of the whole process is (1) (2) (4) (7) (8) (9).

2. Clicking the “Start” button (Figure 2 (6)) will start the Tracking serviceWhen the user clicks the “Start” button (Figure 2 (6)) in the

Tracking App page, the User Event Handler will pass the start tracking service request to the Data Control and the Permission Handler (Figure13 (10)). The Data Control saves the user input name and the duration selected by the user to the Static File. In this way, the user doesn’t need to input the user data again the next time they enter the Tracking App page next time. The message path of the whole process is (1) (2) (3) (5).

The Permission Handler handles the permissions required by the Tracking service. It checks the network connection, App location access permission and device location. If something is not ready, it will invoke the Graphic Renderer to generate the dialog box (Figure 3) to get the user’s agreement. The message path of the whole process is (1) (2) (10) (6) (1).

After the user clicks the agree button, it triggers the User Event Handler, which calls the Permission Handler. The Permission Handler sends the start Tracking service request to the Tracking Control after checking the required permissions. The message path of the whole process is (1) (2) (10) (4).

After receiving the start Tracking service request, the Tracking Control changes the Tracking status to “on” and passes the Tracking status to the Data Control, Graphic Renderer, Notification Handler (Figure 13 (11)) and the Location Handler (Figure 13 (12)). If the duration in the Time field (Figure 2 (4)) is selected by the user, the Tracking Control additionally sends the request to the Timer (Figure 13 (13)).

16

When the Data Control receives the change of the Tracking status, the Data Control saves the Tracking data in the Static File through the message path (4) (3) (5). In addition, the Graphic Renderer replaces the word “Start” on the button (Figure 2 (6)) with “Stop” and automatically opens the Map GUI through the browser ((4) (6) (1)).

The Notification Handler is responsible for sending the smartphone notifications. When the Notification Handler receives the starting message from the Tracking service, it sends an Android system notification within 5 seconds, and instructs the Graphic Renderer to render the related GUI (Figure 4). The Android system notification is used to remind the user that the App is running in the background ((4) (11) (6) (1)).

The Timer is a countdown timer for calculating the remaining time of the Tracking service. When the Timer starts, it instructs the Notification Handler to send a Tracking remaining time notification. The Notification Handler dispatches the Graphic Renderer to render the corresponding GUI (Figure 5), which enables the user to know the Tracking remaining time whenever necessary ((4) (13) (11) (6) (1)).

The Location Handler is responsible for getting the user’s current location. As the Tracking service operates, the Location Handler continues detecting the user’s location and sends the latitude and longitude data to the MsgHandler. The MsgHandler packs the data into the specific format and dispatches the Push task (Figure 13 (14)), which uploads the data to the MapTalk server ((4) (12) (7) (14) (9)).

3. Clicking the “open Map” button (Figure 2 (7)) will open the Map GUI After the user clicks the “open Map” button (Figure 2 (7)), the User Event Handler sends the open Map request to the Graphic Renderer. The Graphic Renderer checks the Tracking status and determines whether indicates the user’s location in the map (Figure 6 (1)) or not and then opens the Map GUI ((1) (2) (6) (1)).

17

4. Clicking the “Stop” button (Figure 2 (6)) will manually stop the Tracking service.

When the user clicks the “Stop” button (Figure 2 (6)), the User Event Handler sends the stop Tracking service request to the Tracking Control. The Tracking Control changes the Tracking status from “on” to “off” and passes the status to the Data Control, Graphic Renderer, Notification Handler and Location Handler. If the user selects the duration in the Time field (Figure 2 (4)), the Tracking Control also sends the request to the Timer.

After receiving the stop Tracking service request, the Data Control saves the Tracking status in the Static File ((4) (3) (5)) and the Graphic Renderer replaces the word “Stop” on the button (Figure 2 (6)) with “Start” ((4) (6) (1)). Moreover, the Notification Handler cancels the Android system notification and instructs the Graphic Renderer to remove the related GUI ((4) (11) (6) (1)).

When the Timer receives the stop request, it shutdowns the countdown functionality and invokes the Notification Handler to cancel the Tracking remaining time notification. The Notification Handler instructs the Graphic Renderer to remove the related GUI ((4) (13) (11) (6) (1)).

As the last step of terminating the Tracking service, the Location Handler stops detecting the user’s current location ((4) (12)).

5. Automatically stop the Tracking service when time’s up When time’s up, the Timer sends the terminating message to the Notification Handler and the Tracking Control for automatically stopping the service.

Receiving the stop message, the Notification Handler cancels the Tracking remaining time notification and sends the Tracking end notification to the Graphic Renderer. The Graphic Renderer then renders the related GUI (Figure 8) to notify the user ((13) (11) (6) (1)). The Tracking Control updates the status to “off” and send the message to the Data Control, Graphic Renderer, Notification Handler and Location Handler. After receiving the stop message, the components mentioned above conducts the corresponding process.

18

The Data Control saves the latest data to the Static File ((4) (3) (5)); the Graphic Renderer replaces the word on the button (Figure2 (6)) with “Start” ((4) (6) (1)).

The Notification Handler cancels the Android system notification; the Graphic Renderer remove the related GUI ((4) (11) (6) (1)).

As the last step, the Location Handler immediately terminates detecting the user’s location ((4) (12)).

19