Using the Motorola Data Collection Solution with MSP

(1)

Using the Motorola Data Collection

Solution with MSP

(2)

(3)

Using the Motorola Data Collection Solution with MSP

72E-139416-03 Revision A December 2011

(4)

© 2011 by Motorola Solutions, Inc. All rights reserved.

No part of this publication may be reproduced or used in any form, or by any electrical or mechanical means, without permission in writing from Motorola Solutions. This includes electronic or mechanical means, such as photocopying, recording, or information storage and retrieval systems. The material in this manual is subject to change without notice.

While every reasonable precaution has been taken in the preparation of this document, neither Symbol Technologies, Inc., nor Motorola Solutions, Inc., assumes responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

The software is provided strictly on an “as is” basis. All software, including firmware, furnished to the user is on a licensed basis. Motorola Solutions grants to the user a transferable and non-exclusive license to use each software or firmware program delivered hereunder (licensed program). Except as noted below, such license may not be assigned, sublicensed, or otherwise transferred by the user without prior written consent of Motorola Solutions. No right to copy a licensed program in whole or in part is granted, except as permitted under copyright law. The user shall not modify, merge, or incorporate any form or portion of a licensed program with other program material, create a derivative work from a licensed program, or use a licensed program in a network without written permission from Motorola Solutions. The user agrees to maintain Motorola Solution’s copyright notice on the licensed programs delivered hereunder, and to include the same on any authorized copies it makes, in whole or in part. The user agrees not to decompile, disassemble, decode, or reverse engineer any licensed program delivered to the user or any portion thereof.

Motorola Solutions reserves the right to make changes to any software or product to improve reliability, function, or design.

Motorola Solutions does not assume any product liability arising out of, or in connection with, the application or use of any product, circuit, or application described herein.

No license is granted, either expressly or by implication, estoppel, or otherwise under any Motorola Solutions, Inc., intellectual property rights. An implied license only exists for equipment, circuits, and subsystems contained in Motorola Solutions products.

Motorola Solutions and the Stylized M Logo and Symbol and the Symbol logo are registered in the US Patent & Trademark Office. All other product or service names are the property of their respective owners.

Motorola Solutions, Inc One Motorola Plaza

Holtsville, New York 11742-1300

(5)

Chapter 2 – Understanding Data Collection ... 7

Overview ... 7 Collection Manager ... 7 Collection Strings ... 7 Collection Modules ... 7 Collection APIs ... 8 Collection Services ... 8 Explicit Naming ... 9 Mapped Naming ... 9 Collection APIs ... 10

SystemManager Collection APIs ...11

Unparameterized Collection APIs that Return Structured Data ...11

MotorolaTools Collection APIs ...13

Unparameterized Collection APIs that Return Scalar Data ...13

Parameterized Collection APIs that Return Scalar Data ...14

(6)

WwanStats Collection APIs ...29

GPSInfo Collection APIs...33

Unparameterized Collection APIs that Return Structured Data ...35

SmartBatteryInfo Collection APIs ...37

Collection Log Files ... 37

Collection Documents ... 37

Chapter 3 – Security Considerations ... 39

Overview ... 39

Sensitivity of Collected Data ... 39

Storage of Data on Device ... 40

Delivery of Data to Relay Server ... 40

Storage of Data on Relay Server... 40

Uploading of Data to the MSP Server ... 41

Storage of Data in the Collected Data Tables ... 41

Availability of Data via the MSP Console UI ... 41

Chapter 4 – Control Modules ... 43

Required Control Modules ... 43

MotorolaDC ...43 Purpose ...43 Installation ...43 Configuration ...43 Operation ...43 Device Attributes ...43 PC_MotorolaDC ...44 Purpose ...44 Installation ...44 Configuration ...44 Operation ...44 Device Attributes ...44 Android_MotorolaDC ...44 Purpose ...44 Installation ...45 Configuration ...45 Operation ...45 Device Attributes ...45

Chapter 5 – How the Motorola Data Collection Solution Works ... 47

Overview ... 48

High Level Architecture ... 48

Receiving and Processing Settings Jobs ... 49

Configuring Data to be Collected... 49

Collecting Data ... 49

Collection Sample Acquisition ...49

Handling Suspend and Resume ...49

Storing Collected Data ... 50

When Data Cannot be Collected ... 50

(7)

Chapter 6 – Using the Motorola Data Collection Solution ... 53

Overview ... 53

Prerequisites ... 53

Suitable MSP Agent Version ...53

Deployed Control Module ...53

Activated and Applicable Collection Request ...54

Correct Device Local Time ...54

Using Data Collection and Collected Data ... 54

(8)

(9)

About This Guide

MSP Documentation

This document provides information on the Motorola Data Collection Solution.

The library of available MSP documentation is extensive and widely available to MSP customers. Customers may obtain the latest version of all documents from:

http://support.symbol.com/support/product/softwaredownloads.do.

A Documentation library is available by accessing the MSP Console UI online Help.

Service Information

If you have a problem with your software, contact Motorola Enterprise Mobility support for your region. Contact information is available at: http://www.symbol.com/contactsupport.

When contacting Enterprise Mobility support, please have the following information available: Serial number of the software

Model number or product name Software type and version number Software license information

Motorola responds to calls by email, telephone or fax within the time limits set forth in support agreements.

If you purchased your Enterprise Mobility business product from a Motorola business partner, contact that business partner for support.

(10)

(11)

Chapter 1 – Introduction

Overview

This document describes the Motorola Data Collection Solution provided as an add-on to MSP . As an add-on, the components required to use the Motorola Data Collection Solution are not automatically installed with MSP. One or more Add-On Kit(s) must be separately imported into MSP in order to use its functionality.

Varieties of the Motorola Data Collection

Solution

The Motorola Data Collection Solution is separate from, but cooperates with and is dependent on the MSP Client Software running on a device. For more information on the MSP Client Software, refer to the MSP Client Software Guide.

The Motorola Data Collection Solution theoretically can be supported on any device for which a variety of the MSP Client Software is available. In practice, a variety of the Motorola Data Collection Solution may or may not be available to support every device that is supported by a variety of the MSP Client Software.

This document will describe all the varieties of the Motorola Data Collection Solution that are available and will be updated to reflect new varieties as they become available. Varieties of the Motorola Data Collection Solution are available for Windows Devices (Device Class “Mobile Device”), Windows PCs (Device Class “Windows PC”) and Android Devices (Device Class “Android Device”). For more information on Device Classes, refer to Understanding MSP – Understanding Device Classes and Proxies.

(12)

Acquiring the Motorola Data Collection

Solution

Obtaining Add-On Kits

The Motorola Remote Control Solution components are provided via Add-On Kits that are included with MSP and that are separately available for download from the following link:

http://support.symbol.com/support/product/softwaredownloads.do

Updated versions of the Add-On Kits containing updated components may also periodically be available for download from the same link.

Add-On Kit for Windows Devices

The Add-On-Kit for Windows Devices will be a .ZIP File with a name of the form: MotorolaDC_<version>_<date>.ZIP

where:

<version> indicates the version number of the software delivered in the Add-On Kit.

<date> indicates the release date of the Add-On Kit .ZIP File (represented in YYYYMMDD format).

The Add-On Kit .ZIP File contains the following contents:

The Motorola Data Collection Solution Control Module Package MotorolaDC.APF.

Add-On Kit for Windows PCs

The Add-On-Kit for Windows will be a .ZIP File with a name of the form: MotorolaDC_PC_<core version>_<zip version>_<date>.ZIP

where:

<core version> This is the version of the primary component of the Add-On. <zip version> This is a version number that is used to indicate that something

has changed in the Add-On other than the primary component. This needs to be reset when the Core Version changes. <date> indicates the release date of the Add-On Kit .ZIP File

(represented in YYYYMMDD format).

The Add-On Kit .ZIP File contains the following contents:

(13)

Add-On Kit for Android

*

Devices

The Add-On-Kit for Android Devices will be a .ZIP File with a name of the form: MotorolaDC_Android_<core version>_<zip version>_<date>.ZIP

where:

<core version> This is the version of the primary component of the Add-On. <zip version> This is a version number that is used to indicate that something

has changed in the Add-On other than the primary component. This needs to be reset when the Core Version changes. <date> indicates the release date of the Add-On Kit .ZIP File

(represented in YYYYMMDD format). The Add-On Kit .ZIP File contains the following contents:

The Motorola Data Collection Solution Control Module Package Android_MotorolaDC.APF The MotorolaDC release notes, MotorolaDC_Release_Notes.txt

New Collection Metrics in folder CollectionMetrics

Modified Collection Categories to include new collection metrics, in folder CollectionCategories

Note: If the Data Collection Category that is being imported is used in a Collection Request that is already activated, then the user is required to de-activate the Collection Request, before

proceeding with the Collection Category upload. Once uploaded, the Collection Request can be re-activated to enable data collection.

Add-On Kit Installation

For Users with direct access to Windows Console on the MSP Server, an Add-On Kit .ZIP File can be installed using the MSP Administration Program. See Add-On Kit Installation in

Administering MSP.

Licensing the Motorola Data Collection

Solution

The licensing required to use the Motorola Data Collection Solution for all supported devices is included in the per-device license required to manage a device with MSP. Data Collection can only be used with MSP Control Edition and the act of deploying a the Motorola Data Collection Solution to a device will cause that device to require a Control License if it previously required only a Stage or Provision license.

(14)

(15)

Chapter 2 – Understanding Data

Collection

Overview

This chapter discusses key concepts required to understand and use the Motorola Data

Collection Solution. Key concepts related to all Data Collection solutions are described in Using MSP - Using Data Collection.

Collection Manager

The MotorolaDC Control Module implements the Motorola Data Collection Solution on a device; within this Control Module the core functionality of Data Collection is implemented by the

Collection Manager. The Collection Manager coordinates the collection of data and utilizes a set of Collection Services to acquire Collection Samples for supported Collection Metrics.

Data Collection via the Motorola Data Collection Solution is configured via Collection Settings that are sent by the MSP Server. Collection Settings contain Collection Strings which define how each Collection Sample for each Collection Metric are to be acquired.

Collection Strings

Collection Strings are used to configure Data Collection performed via the Motorola Data Collection Solution. Collection Strings follow the syntax described in Using MSP - Using Data Collection. The semantics of Collection Strings are defined with the standard syntax by specifying Collection Module Names and Collection API Names, potentially qualified by Parameters and/or Field Names, as required for a given Collection API.

Collection Modules

Collection Strings within Collection Settings are used to configure the Collection Manager to acquire Collection Samples for sets of selected Collection Metrics at selected Collection Frequencies.

(16)

Within the Collection String for a specific Collection Metric, a Collection Module Name must be specified, as described in Using MSP - Using Data Collection. The Collection Module Name directly or indirectly selects a Collection Service that the Collection Manager will use to acquire Collection Samples for that Collection Metric.

Not all Collection Modules are supported on all Device Classes. The Collection Modules supported by the available Data Collection Solution Varieties are shown in Table 1 below.

Collection Module Name Windows Devices Device Class = “Mobile Device”? Windows PC Device Class = “Windows PC”? Android Device Device Class = “Android Device”?

SystemManager Yes Yes Yes MotorolaTools Yes Partial Partial RegistryData Yes Yes Partial WwanStats Yes No Partial GPSInfo Yes No Partial SmartBatteryInfo Yes No No

Table 1 – Collection Module Support by Data Collection Solution Variety

Where a Collection Module is shown as “Yes” for a given Device Class, all of the APIs defined for that Collection Module are supported by the Motorola Data Collection Solution for that Device Class. Where a Collection Module is shown as “No” for a given Device Class, none of the APIs defined for that Collection Module are supported by the Motorola Data Collection Solution for that Device Class. Where a Collection Module is shown as “Partial” for a given Device Class, some of the APIs defined for that Collection Module are supported by the Motorola Data Collection

Solution for that Device Class. Check the API table for that Collection Module to see which APIs are and are not supported for that Device Class.

Collection APIs

Within the Collection String for a specific Collection Metric, a Collection API Name must also be specified, as described in Using MSP - Using Data Collection. A Collection Module Name and a Collection API Name must be paired to determine the exact call that will be made into a

Collection Service to acquire Collection Samples for that Collection Metric.

Collection Services

For Windows Devices and Windows PC, Collection Services are DLLs that implement the ability to acquire Collection Samples for sets of Collection Metrics. Similarly, for Android Devices collection services are implemented as Android services to acquire collection samples. A number of Collection Services are included as part of the Control Module that implements the Motorola Data Collection Solution. New Collection Services also can be developed and plugged into the Motorola Data Collection Solution. All Collection Services used with the Motorola Data Collection Solution must conform to the Collection Service Model defined as part of the Motorola Data Collection Solution.

Within the Collection String for a Collection Metric, a Collection Module Name and a Collection API Name are paired to determine the Collection Service that will be used and the function within that Collection Service that will be called to acquire Collection Samples for that Collection Metric. There are two modes by which a Collection Module Name and Collection API Name pair can be used to identify a Collection Service; they are explicit naming and mapped naming.

(17)

Explicit Naming

A Collection Service can be specified by using a Collection Module Name that is the Explicit Name of the DLL (without the path or file extension) or Android Service name that implements the desired Collection Service in the device. In such a case, the Collection API Name must be the exact name of a function exposed by that Collection Service.

This mode is commonly used to access Collection Services that are specific to the Motorola Data Collection Solution. It can also be used to access Collections Services implemented by other services that are plugged-into the Motorola Data Collection Solution. Table 2 below lists the Collection Services that are built-into the Control Module for the Motorola Data Collection Solution.

Collection Service Description

SystemManager This Collection Service provides access to a variety of information about the Operating System of the device.

MotorolaTools This Collection Service provides access to a variety of information about the device.

RegistryData This Collection Service provides access to information from the Device Registry.

WwanStats This Collection Service provides access to a variety of information from the Wireless Wide Area Network (WWAN) subsystem on the device, if it has one.

GPSInfo This Collection Service provides access to a variety of information from the Global Positioning System (GPS) subsystem on the device, if it has one.

SmartBatteryInfo This Collection Service provides access to a variety of information from the Smart Battery System subsystem on the device, if it has one.

Table 2 – Built-in Collection Services

Mapped Naming

A Collection Service can also be specified by using a logical Collection Module Name paired with a Collection API Name. A mapping table maps the pair to a specific Collection Service Plug-In. In such a case, the Collection API Name must also be the exact name of a function exposed by that Collection Service Plugin.

For Windows Devices and Windows PC, this mapping information is contained within the Device Registry. In the case of Android devices, this information is stored in a flat file in the Android device.

This mode is commonly used to access Collection Metrics that are pre-defined in MSP. If the name of the Collection Service Plug-In that implements a given Collection Metric is not named identically to the Collection Module Name used in the Collection String pre-defined within MSP, this mode allows mapping to the correct Collection Service.

(18)

Table 3 below provides a list of the pairs of Collection Module Names and Collection API Names that are mapped to specific Collection Service Plug-Ins.

Collection Module Name Collection API Name(s) Collection Service Plugin

MotorolaTools GetRegistryValue GetRegistryValueDelta RegistryData MotorolaTools GetScanAttemptCount GetScanBeamOnTime GetScanCompleteCount ScannerInfo MotorolaTools GetWlanErrorDelta GetWlanRadioOnTime GetWlanReceiveByteDelta GetWlanReceivePacketDelta GetWlanRetryDelta GetWlanSignalQuality GetWlanTransmitByteDelta GetWlanTransmitPacketDelta WlanStats SystemManager - Applicable for Android devices only

ACLineStatus MotorolaTools

Table 3 – Collection Module Name / Collection API Name Mappings

Collection APIs

The Collection Manager acquires Collection Samples for a given Collection Metric using a Collection API implemented within a Collection Service Plug-In. Collection APIs can be subdivided into the following types based on the format of the Collection String required to call them:

Unparameterized Collection APIs that Return Scalar Data

These Collection APIs are called by their name and take no parameters. The value returned is numeric and suitable for use as the value of any MSP Data Collection Metric with a data type of FLOAT.

Unparameterized Collection APIs that Return Structured Data

These Collection APIs are called by their name and take no parameters. The value returned is a structure containing multiple fields. Individual fields of the structure returned may be numeric and suitable for use as the value of any MSP Data Collection Metric with a data type of FLOAT.

Parameterized Collection APIs that Return Scalar Data

These Collection APIs are called by their name and require that one or more parameter/value pairs be supplied to qualify their operation. The value returned is numeric and suitable for use as the value of any MSP Data Collection Metric with a data type of FLOAT.

The Collection APIs implemented by the Collection Service DLLs that are built-into the Control Module that implements the Motorola Data Collection Solution are described in the following sections, categorized by Collection Service.

(19)

SystemManager Collection APIs

The SystemManager Collection Service Plug-In is generally supported on any Windows CE or Windows Mobile device that supports the relevant standard Microsoft-defined Win32 APIs or Android Devices.

The SystemManager Collection Service contains Collection APIs as described in the following sections.

Unparameterized Collection APIs that Return Structured

Data

The SystemManager Collection Service contains an Unparameterized Collection API that returns Structured Data as listed in Table 4 below.

API Name Description

GetSystemInfo This Collection API returns Structured Data containing a variety of values related to the Operation System on the device.

Explanations of the Fields contained within the Structured Data returned by this Collection API are listed in Table 5 below.

Table 4 – SystemManager Unparameterized Collection APIs that Return Structured Data

The GetSystemInfo API in SystemManager Collection Service returns structured data. The fields that are available within the structured data are defined in Table 5 below.

Field Name Description

ACLineStatus This field returns a value of “1” if the device is currently connected to AC power (i.e. is charging) and a value of “0” if the device is currently running from battery power (i.e. is discharging)

Note: This is not applicable for Android devices. In Android devices, this metric is collected as a part of MotorolaTools

AvailablePhysicalMemory This field returns the total amount of Physical Memory (Program Memory) in bytes that is currently available for use (i.e. is not currently allocated to some program).

Note:

The definition of Physical Memory tends to be the same for all versions of Windows CE and Windows Mobile.

(20)

Field Name Description

AvailableStorageMemory This field returns the total amount of Storage Memory (a.k.a. File System Memory) in bytes that is currently available for use (i.e. is not currently allocated to hold files). Note that the definition of Storage Memory may be different between different versions of Windows CE and Windows Mobile.

Note:

In the case of Android devices, this includes the memory available in the SDCard and the phone memory.

MemoryLoad This field returns the percentage of Total Memory that is currently allocated (i.e. is currently in use and hence is not available for use).

TotalMemory This field returns the total amount of memory that is present in the device, and is generally the sum of the values of TotalPhysicalMemory and TotalStorageMemory.

TotalPhysicalMemory This field returns the total amount of Physical Memory (Program Memory) in bytes that is present in the device, whether it is currently available for use (i.e. is not currently allocated to some program) or is currently in use (i.e. is not available for use). Note that the definition of Physical Memory tends to be the same for all versions of Windows CE and Windows Mobile.

TotalStorageMemory This field returns the total amount of Storage Memory (File System Memory) in bytes that is present in the device, whether it is currently available for use (i.e. is not currently allocated to hold files) or is currently in use (i.e. is currently allocated to hold files). Note that the definition of Storage Memory may be different between different versions of Windows CE and Windows Mobile. In Android devices, this memory includes the memory in storage card and phone memory

(21)

MotorolaTools Collection APIs

The MotorolaTools Collection Service is generally supported on any Windows CE or Windows Mobile device that supports the relevant proprietary Motorola-defined and/or standard Microsoft-defined Win32 APIs. This is also supported on Android Devices.

The MotorolaTools Collection Service contains Collection APIs as described in the following sections.

Unparameterized Collection APIs that Return Scalar

Data

The MotorolaTools Collection Service contains Unparameterized Collection APIs as listed in Table 6 below.

API Name Description Windows

Devices

Windows PCs

Android Devices

GetBatteryLevel _{This Collection API returns the}

current battery level of the device as a percentage of the total capacity of the battery. The value returned can range from 0% to 100%.

If the device does not have a battery or the level of the battery cannot be determined, then no value will be returned.

Yes Yes Yes

GetWlanSignalQuality _{This Collection API returns the}

current WLAN signal quality on the device as a percentage of the best possible signal quality. The value returned can range from 0% to 100%.

If the device does not have WLAN support or it is not possible to track the operation of the WLAN on the device, then no value will be returned.

Yes No Yes

ACLineStatus This Collection API returns a value of “1” if the device is currently connected to AC power (i.e. is charging) and a value of “0” if the device is currently running from battery power (i.e. is discharging) Note: This metric is collected as a part of System Manager Plug-in in the case of Windows Devices and Windows PC

Yes Yes Yes

(22)

Parameterized Collection APIs that Return Scalar Data

The MotorolaTools Collection Service contains Parameterized Collection APIs that return Scalar Data as listed in Table 7 below.

API Name Description Windows

Devices

Windows PCs

GetAcChargeTime This Collection API returns the amount of elapsed time in seconds that the device has been connected to AC power (i.e. has been charging) since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported.

Yes Yes Yes

GetAcChargeCount This Collection API returns the number of times that the device has been connected to AC power (i.e. has been charging) since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported.

(23)

API Name Description Windows Devices Windows PCs Android Devices

GetBacklightOnCount This Collection API returns the number of times that the backlight on the device has been turned on since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a backlight or it is not possible to track the state of the backlight on the device, then no value will be returned.

Yes No No

GetBacklightOnTime This Collection API returns the amount of elapsed time in seconds that the backlight on the device has been on since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a backlight or it is not possible to track the state of the backlight on the device, then no value will be returned.

(24)

API Name Description Windows Devices Windows PCs Android Devices

GetBatteryLevelDelta This Collection API returns the change in the battery level of the device since the last time this Collection API was called for the same named Collection Group. The value returned can range from -100% to 100%.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a battery or the change in the level of the battery cannot be determined, then no value will be returned.

Yes Yes Yes

GetDeviceCpuTimeDelta This Collection API returns the change in the amount of CPU time in seconds that has been accrued since the last time this Collection API was called for the same named Collection Group. The value returned can range from 0 to the Collection Frequency of the Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the amount of accrued CPU time cannot be measured, then no value will be returned.

(25)

API Name Description Windows Devices Windows PCs Android Devices

GetDeviceOnTime This Collection API returns the amount of elapsed time in seconds that the device has been powered on since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported.

Yes Yes No

GetDisplayOnTime This Collection API returns the amount of elapsed time in seconds that the display on the device has been on since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a display or it is not possible to track the state of the display on the device, then no value will be returned.

(26)

API Name Description Windows Devices Windows PCs Android Devices

GetKeylightOnCount This Collection API returns the number of times that the keylight on the device has been turned on since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a keylight or it is not possible to track the state of the keylight on the device, then no value will be returned.

Yes No No

GetKeylightOnTime This Collection API returns the amount of elapsed time in seconds that the keylight on the device has been on since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a keylight or it is not possible to track the state of the keylight on the device, then no value will be returned.

(27)

API Name Description Windows Devices Windows PCs Android Devices

GetPowerCycleCount This Collection API returns the number of times that the device has been powered on since the last time this Collection API was called for the same named Collection Group.

(28)

GetProcessCpuTimeDelta This Collection API returns the amount of elapsed CPU time (in seconds) for all processes or for a selected process since the last time this Collection API was called for the same process and the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter.

To acquire the CPU time for all processes, no additional parameters should be provided.

To acquire the CPU time for a specific process, an additional parameter must be provided to supply the executable file name (with file extension but without path) for the process. For example,

“Process=30agent.exe” would request the CPU time for the MSP Agent process.

When the CPU time for a specified process is requested and that process is not

running, then no value will be returned.

(29)

API Name Description Windows Devices Windows PCs Android Devices

GetScanAttemptCount This Collection API returns the number of times that the Barcode scanner on the device has been activated (i.e. an attempt to scan a Barcode has been made) since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a Barcode scanner or it is not possible to track the activation of the Barcode scanner on the device, then no value will be returned.

If the device has more than one Barcode scanner, then no value will be returned.

(30)

GetScanBeamOnTime This Collection API returns the amount of elapsed time in seconds that the Barcode scanner on the device has been activate (i.e. that Barcode scanning was being attempted) since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a Barcode scanner or it is not possible to track the activation of the Barcode scanner on the device, then no value will be returned.

(31)

API Name Description Windows Devices Windows PCs Android Devices

GetScanCompleteCount This Collection API returns the number of times that the Barcode scanner on the device has resulted in the successful scanning of a Barcode since the last time this Collection API was called for the same named Collection Group. Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a Barcode scanner or it is not possible to track the success of Barcode scanning on the device, then no value will be returned.

Yes No No

GetWlanErrorDelta This Collection API returns the number of errors that have occurred during WLAN communications on the device since the last time this

Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have WLAN support or it is not possible to track the operation of the WLAN on the device, then no value will be returned.

(32)

API Name Description Windows Devices Windows PCs Android Devices

GetWlanRadioOnTime This Collection API returns the amount of elapsed time in seconds that the WLAN radio on the device has been powered on since the last time this Collection API was called for the same named Collection Group.

Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported. If the device does not have a WLAN radio or it is not possible to track the operation of the WLAN on the device, then no value will be returned. If the device has more than one WLAN radio, then no value will be returned.

Yes No Yes

GetWlanReceiveByteDelta This Collection API returns the number of bytes that have been received as part of WLAN communications on the device since the last time this Collection API was called for the same named Collection Group.

(33)

API Name Description Windows Devices Windows PCs Android Devices GetWlanReceivePacketDelt a

This Collection API returns the number of packets that have been received as part of WLAN communications on the device since the last time this Collection API was called for the same named Collection Group.

Yes No Yes

GetWlanRetryDelta This Collection API returns the number of retries that have occurred during WLAN communications on the device since the last time this

(34)

API Name Description Windows Devices Windows PCs Android Devices

GetWlanTransmitByteDelta This Collection API returns the number of bytes that have been transmitted as part of WLAN communications on the device since the last time this Collection API was called for the same named Collection Group.

Yes No Yes

GetWlanTransmitPacketDelt a

This Collection API returns the number of packets that have been transmitted as part of WLAN communications on the device since the last time this Collection API was called for the same named Collection Group.

Yes No Yes

(35)

RegistryData Collection APIs

The RegistryData Collection Service Plug-in is generally supported on any Windows CE or Windows Mobile device that supports the relevant standard Microsoft-defined Win32 Registry APIs.

In the case of Android devices, in the absence of registry, database is used to store attributes, which can be monitored and collected using the Registry Data Collection APIs.

These APIs are not supported on Enterprise Android Devices.

Parameterized Collection APIs that Return Scalar Data

The RegistryData Collection Service contains Parameterized Collection APIs that return Scalar Data as listed in Table 9 below.

API Name Description

GetRegistryValue This Collection API returns the value of a specified named REG_SZ or REG_DWORD value in a specified key within the Device Registry for windows devices.

For Android Devices, values stored in the Registry DB for the specified key name is returned

The required parameters for these Collection APIs are listed in Table 7 below.

If the specified named value does not exist in the specified key within the Device Registry or the value exists but is not of type REG_SZ or REG_DWORD, then no value will be returned.

If the specified named value exists in the specified key within the Device Registry and is of type REG_DWORD, then the DWORD numeric value will be returned.

If the specified named value exists in the specified key within the Device Registry and is of type REG_SZ, then the

(36)

API Name Description

GetRegistryValueDelta This Collection API returns the change in the value of a specified named REG_SZ or REG_DWORD value in a specified key within the Device Registry or registry database Since this Collection API is intended to acquire Collection Samples for Quantity Metrics, the name of the Collection Group must be passed as the first parameter. No other parameters are supported.

The additional required parameters for these Collection APIs are listed in Table 9 below.

If the specified named value does not exist in the specified key within the Device Registry/ Registry Database or the value exists but is not of type REG_SZ or REG_DWORD, then no value will be returned.

If the specified named value exists in the specified key within the Device Registry/Database and is of type REG_DWORD, then the DWORD numeric value will be converted to FLOAT and will be used to compute the delta from the prior sample. If the specified named value exists in the specified key within the Device Registry/Database and is of type REG_SZ, then the STRING value will be converted to FLOAT and will be used to compute the delta from the prior sample. If the STRING value cannot be successfully converted to a FLOAT (e.g. due to a non-numeric string value), then no value will be returned.

Note:

The change in the registry value will be returned in the first collection interval, after the start of the Motorola Data Collection Engine. The value will be returned in the first collection interval only if this registry value has been previously requested in the collection requests, during the earlier instance of running Motorola Data Collection

Table 8 – RegistryData Parameterized Collection APIs that Return Scalar Data

Parameter Name Description

KeyName This parameter identifies the full path to the desired Registry Key. For example, KeyName=

HKEY_LOCAL_MACHINE\Comm.

In the event that the specified Registry Key does not exist, then no value will be returned.

(37)

Parameter Name Description

In the case of Android Devices, the key name will be stored in the database.

ValueName This parameter identifies the name of the value to be extracted from the specified Key. For example,

ValueName=BootCount would get the number of times the device has rebooted.

In the event that no value of the specified name exists under the specified Registry Key or a value exists but is not of type REG_SZ or REG_DWORD, then no value will be returned.

Table 9 – GetRegistryValue and GetRegistryValueDelta Parameters

WwanStats Collection APIs

The WwanStats Collection Service is generally supported on Android devices and on any WWAN-equipped Windows Mobile Phone Edition device that supports the relevant standard Microsoft-defined Win32 RIL APIs

Data

The WwanStats Collection Service contains Unparameterized Collection APIs that return Scalar Data as listed in Table 10 below.

API Name Description Windows

Devices

WwanErrorRate This Collection API returns the bit error rate, in one hundreths of one percent, as of the time the call is made.

If the device does not have WWAN support or it is not possible to track the operation of the WWAN on the device, then no value will be returned.

Note that this is not supported in CDMA based Android Phones. In GSM based phones, this metric will be reported if the specific model supports this feature

(38)

API Name Description Windows Devices

WwanSignalQuality This Collection API returns the current WWAN signal quality on the device as a percentage of the best possible signal quality. The value returned can range from 0% to 100%.

Yes Yes

Table 10 – WwanStats Unparameterized Collection APIs that Return Scalar Data

Parameterized Collection APIs that Return Scalar Data

The WwanStats Collection Service contains Parameterized Collection APIs that return Scalar Data as listed in Table 11 below.

API Name Description Windows

Devices

WwanIncomingCallAttempts This Collection API returns the number of incoming call attempts that have been made since the last time this Collection API was called for the same named Collection Group.

(39)

API Name Description Windows Devices Android Devices WwanIncomingCallCompleti ons

This Collection API returns the number of incoming calls that have been successfully connected since the last time this

Yes Yes

WwanIncomingCallDuration This Collection API returns the amount of elapsed time in seconds that incoming calls have been in progress since the last time this Collection API was called for the same named Collection Group.

Yes Yes

WwanOnTime This Collection API returns the amount of elapsed time in seconds that the WWAN radio on the device has been powered on since the last time this Collection API was called for the same named Collection Group.

If the device does not have a WWAN radio or it is not possible to track the operation of the WWAN on the device, then no value will be returned.

If the device has more than one WLAN radio, then no value will be returned.

(40)

API Name Description Windows Devices

WwanOutgoingCallAttempts This Collection API returns the number of outgoing call attempts that have been made since the last time this Collection API was called for the same named Collection Group.

On some Android phones, support for trapping outgoing calls may not be available.

On such phones, this metric may report no information (i.e. values of zero).

Yes Yes

WwanOutgoingCallCompleti ons

This Collection API returns the number of outgoing calls that have been successfully connected since the last time this

(41)

API Name Description Windows Devices

WwanOutgoingCallDuration This Collection API returns the amount of elapsed time in seconds that outgoing calls have been in progress since the last time this Collection API was called for the same named Collection Group.

Yes No

Table 11 – WwanStats Parameterized Collection APIs that Return Scalar Data

GPSInfo Collection APIs

The GPSInfo Collection Service DLL is generally supported on any GPS-equipped Windows CE or Windows Mobile device that supports the relevant standard Microsoft-defined Win32 GPS APIs.

Data

The GPSInfo Collection Service contains Unparameterized Collection APIs that return Scalar Data as listed in Table 12 below.

API Name Description Windows

Devices

GetDeviceState This Collection API returns the state of the GPS Device.

Yes Yes

GetServiceState This Collection API returns the state of the GPS Service.

Yes No

(42)

Unparameterized Collection APIs that Return Scalar

Data

The GPSInfo Collection Service contains Unparameterized Collection APIs that return Scalar Data as listed in Table 13 below.

API Name Description Windows

Devices

GetDeviceStateOnTime This Collection API returns the time, in seconds, the GPS in Device has been active (i.e. is powered on). The GPS of Device could be powered on and off multiple times within a given time interval and the accumulated time spent active will be reported.

Yes Yes

GetServiceStateOnTime This Collection API returns the time, in seconds, the GPS Intermediate Service has been active (i.e. is operative). The GPS Service could be activated and deactivated within a given time interval and the accumulated time spent active will be reported.

Yes No

(43)

Unparameterized Collection APIs that Return Structured

Data

The GPSInfo Collection Service contains an Unparameterized Collection API that returns Structured Data as listed in Table 14 below.

API Name Description

GetGPSPosition This Collection API returns Structured Data containing a variety of values related to the GPS Position of the device Explanations of the Fields contained within the Structured Data returned by this Collection API are listed in Table 13 above.

Table 14 – GPSInfo Unparameterized Collection APIs that Return Structured Data

The GetGPSPosition API in GPSInfo Collection Service returns structured data. The fields that are available within the structured data are defined in Table 15 below.

Field Name Description Windows

Devices

GetAltitudeWRTEllipsoid This field returns the height, in meters, above the reference ellipsoid used to approximate the earth’s surface.

Yes No

GetAltitudeWRTSeaLevel This field returns the height, in meters, above Mean Sea Level (MSL).

Yes Yes

GetHeading This field returns the direction of travel, expressed as an angle of motion, in degrees, relative to Magnetic North.

Yes Yes

GetHorizontalDilutionOfPrecision This field returns the degree to which the horizontal position (latitude and longitude) is affected by horizontal dilution of position (HDOP). HDOP is caused by the location of the satellites providing the GPS fix. Lower numbers indicate a more accurate position. A value of 1.0 indicates the least dilution (highest accuracy); a value of 50.0 indicates the most dilution (lowest accuracy)

Yes No

GetGPSLocation This field returns the current position on the earth as a latitude and longitude pair, in decimal degrees.

Yes Yes

GetMagneticVariation This field returns the angular difference, in decimal degrees, between True North and Magnetic

(44)

Field Name Description Windows Devices

Android Devices North.

GetPositionalDilutionOfPrecision This field returns the degree to which the overall position is affected by positional dilution of position (PDOP). PDOP is caused by the location of the satellites providing the GPS fix. Lower numbers indicate a more accurate position. A value of 1.0 indicates the least dilution (highest accuracy); a value of 50.0 indicates the most dilution (lowest accuracy).

Yes Yes

GetSatellitesCount This field returns the number of satellites used to calculate the position.

Yes Yes

GetSatellitesInView This field returns the number of satellites in view of the GPS device.

Yes No

GetSpeed This field returns the speed of travel, in knots (nautical miles per hour).

Yes Yes

GetUTCTime This field returns the time of the sample as reported by the GPS device, in the fixed format: “MM/DD/YYYY HH:MM:SS”.

Yes Yes

GetVerticalDilutionOfPrecision This field returns the degree to which the vertical position (altitude) is affected by vertical dilution of position (VDOP). VDOP is caused by the location of the satellites providing the GPS fix. Lower numbers indicate a more accurate position. A value of 1.0 indicates the least dilution (highest accuracy); a value of 50.0 indicates the most dilution (lowest accuracy).

Yes No

(45)

SmartBatteryInfo Collection APIs

The SmartBatteryInfo Collection Service DLL is generally supported on any Windows CE or Windows Mobile device that supports the relevant proprietary Motorola-defined Smart Battery API. This is not applicable for Android devices.

Data

The SmartBatteryInfo Collection Service contains Unparameterized Collection APIs that return Scalar Data as listed in Table 16 below.

API Name Description

BatteryChargeCyclesChange This Collection API returns the change in the number of Battery Charge Cycles for the device.

BatteryChargeCycles This Collection API returns the number of Battery Charge Cycles for the device.

BatteryTemperatureChange This Collection API returns the change in the Battery Temperature of the device.

BatteryTemperature This Collection API returns the Battery Temperature of the device.

Table 16 – SmartBatteryInfo Unparameterized Collection APIs that Return Scalar Data

Collection Log Files

Collection Log Files are used to store Collection Samples on the device before they are

converted into the format in which they will be delivered to the MSP Server via the Relay Server. Each Collection Log File is stored in a text format that is internal to the Motorola Data Collection Solution and not published for external use.

There will be at most one Collection Log File created in a device at any one time for each Collection Group. Each Collection Log File is named based on the identifier of its associated Collection Group and is stored in the “Data” subfolder under the subfolder in the Device File System where the Control Module is installed. The Collection Log Files in the case of Consumer Android devices is stored in the external storage system (SD Card). For Enterprise Android Devices, log files are placed in the enterprise/motoroladc folder. Typical file names for Collection Log Files are “1.nv”, “2.nv”, and “3.nv”.

When the Collection Sample Time arrives for a particular Collection Group, Collection Samples are acquired in accordance to the Collection String defined for each Collection Metric requested by that Collection Group. All data samples that were successfully acquired will be appended to the end of the Collection Log File for that Collection Group.

Collection Documents

When the time comes to deliver data to MSP via a Relay Server, the data samples stored in each Collection Log File is converted into a corresponding Collection Document. Collection

Documents are stored in a compressed but unencrypted format that is defined by MSP and is described in Using MSP - Using Data Collection.

(46)

Once all the data for a Collection Group in the Collection Log File has been converted into a Collection Document, then that Collection Log File is deleted. Collection Log File for each Collection Group will then be created as needed when the next Collection Sample Time for that Collection Group arrives.

(47)

Chapter 3 – Security Considerations

Overview

This section considers the most common Security concerns that may be important to consider when using the Motorola Data Collection Solution.

Sensitivity of Collected Data

The Motorola Data Collection Solution is designed to collect information about the status, operation, and performance of devices. Since devices could be engaged in activities where proprietary or sensitive data is acquired or utilized by applications, it may be a natural concern whether any data being collected by the Motorola Data Collection Solution could be of a sensitive nature.

The set of pre-defined Collection Metrics in MSP is described in Using MSP - Using Data Collection. These pre-defined Collection Metrics are all focused on “physical” aspects of the device as opposed to “data” or “application” aspects of the device. Collected data can include information on batteries and charging, device performance, and resource usage (memory, CPU, peripheral activity, WLAN activity, etc.).

As can be seen, none of these pre-defined Collection Metrics deal directly with the content of any data collected by or used by applications, and hence would normally not be involved in the collection of sensitive information. The only possible exception might be device usage statistics which could reflect the performance of Device Users and could, under some circumstances, could be deemed to have Human Resources implications.

Since the Motorola Data Collection Solution is extensible, it is possible to extend it to collect other information from the device. If such extensions are used to collect sensitive or proprietary data, then the handling of that data will be identical to the handling of all other data. It may therefore be advisable to understand the end-to-end handling of all data collected using the Motorola Data Collection Solution, as discussed in the following sections, and to assess whether that handling could in any way compromise the security of that data. When in doubt, it may be prudent to avoid the collection via the Motorola Data Collection Solution of any data that is considered sensitive.

(48)

Storage of Data on Device

As discussed elsewhere in this document, all Collection Samples for all Collection Metrics collected by the Motorola Data Collection Solution on a device are stored in Collection Log Files in the file system of that device or in external storage for Consumer Android devices or in enterprise/motoroladc folder for Enterprise Android devices. Such files are stored unencrypted and will reside on the device until the MSP Agent determines that it is time to deliver it.

If any of the data being collected is considered sensitive in any way, as discussed in the prior section, then consideration should be given to whether the storage of that data unencrypted in Collection Log File could in any way compromise the security of that data. If the data comes from other locations in the device where it is stored unencrypted, then the storage of the additional storage of the data in unencrypted the Collection Log File should not materially affect the security of that data. However, the security of any data that is normally secured by encryption could be compromised if it is elected to be collected via the Motorola Data Collection Solution.

Delivery of Data to Relay Server

As discussed elsewhere in this document, when the MSP Agent decides it is time to deliver Collected Data, any Collection Log File containing Collection Samples are converted into compressed Collection Documents and stored in the file system of the device until they can be successfully delivered to the Relay Server.

Like Collection Log Files, Collection Documents are stored unencrypted. Consequently, if it is deemed that storage of sensitive data in Collection Log Files is a security risk, then storage of that data in Collection Documents likely represents the same risk. Unlike Collection Log Files, which are only stored on the device, Collection Documents are intended to be transferred off the device. Consequently, any risk of compromising the security of potentially sensitive data stored in Collection Documents may be of more concern.

The transfer of Collection Documents to the Relay Server is accomplished using the same protocol defined for all communications between the device and the Relay Server. If the protocol selected is FTP, then the unencrypted Collection Documents could be subject to interception and/or alteration during transfer. If the protocol selected is FTPS, then the Collection Documents would be protected against interception or alteration during transfer to the Relay Server.

Storage of Data on Relay Server

The three-tier architecture of MSP means that all communications between the MSP Server and any device happens via a Relay Server. In the case of Collected Data, Collection Documents are transferred from the device to the Relay Server and are stored on that Relay Server until they are asynchronously uploaded and deleted by the MSP Server. As such, if sensitive information is contained with an unencrypted Collection Document, it may be vulnerable while that Collection Document resides on that Relay Server.

Since the FTP protocol is Inherently Non-Secure, if the Relay Server is configured to allow the use of the FTP protocol, then a malicious entity could intercept login credentials by “sniffing” the network while an authorized entity is accessing the Relay Server using the FTP protocol. Once in possession of valid login credentials, the malicious entity would have the same access to the Collection Documents stored on that Relay Server as the authorized entity. By configuring a Relay Server to disallow the FTP protocol and only allow the FTPS protocol, such vulnerabilities can be eliminated.

(49)

If a Relay Server exposes any other protocols which might provide access to that portion of the file system in which Collection Documents are stored, then the security of the data in those Collection Documents might also be at risk. It would generally be advisable to disable or suitably secure any such protocols that might be used compromise the security of Collection Document if those Collection Documents may contain sensitive data.

It should be noted that some Relay Servers may offer the option to encrypt data stored in the file system. Such encryption may provide some security against manually accessing or tampering with the data. But file system encryption generally cannot protect against access to the data using exposed protocols such as FTP or FTPS since they must, by definition, provide access to the unencrypted data.

Uploading of Data to the MSP Server

Periodically, the MSP Server connects to each Relay Server and uploads and then deletes Collection Documents. This process is subject to the same over-the-air security considerations previously described for delivery of data to the Relay Server. Use of the FTPS protocols is advised whenever the data contained within Collection Documents is considered sensitive.

Storage of Data in the Collected Data Tables

When the MSP Server processes uploaded Collection Documents, it extracts Collection Samples and stores them into the Collected Data Tables of the MSP Database. No means to encrypt or otherwise protect Collected Data stored in the MSP Database is provided.

If the instance of SQL Server on which the MSP Database is hosted is remote from the MSP Server, all Collected Data will be transferred to the Collected Data Tables unencrypted using the SNI protocol and hence could be subject to interception and/or alteration. Further, once the data is in the MSP Database, it is subject to access by any entity that is in possession of the

credentials needed to access that database.

In addition, if the MSP Asset Reporting feature is turned on, then Collected Data will also be stored in a separate set of tables designed for ease of Asset Reporting using external applications (e.g. Crystal Reports). While the MSP Asset Reporting Tables can be highly valuable for providing access to Collected Data, they could also represent a serious security risk if any sensitive data is collected.

Availability of Data via the MSP Console UI

Once Collected Data is stored in the Collected Data Tables of the MSP Database, it is available for access to users of the MSP Console UI. The MSP Server treats all Collected Data

equivalently and has no provision for treating any Collected Data as more sensitive than any other Collected Data. Consequently, any sensitive data collected from a device using the Motorola Data Collection Solution will be available to any user authorized to view Collected Data for that device via the MSP Console UI.

(50)

(51)

Chapter 4 – Control Modules

Required Control Modules

MotorolaDC

Purpose

The MotorolaDC Control Module deploys the components necessary to implement the Motorola Data Collection Solution on supported Windows Devices (Device Class “Mobile Device”).

Installation

This Control Module is implemented by the Package MotorolaDC.APF. This Package should be deployed to a Windows Device if Motorola Data Collection functionality is required.

Configuration

This Control Module has no settings that are directly user-configurable.

The Data Collection functionality of this Control Module will be indirectly configured by MSP to collect data as a result of one or more Data Collection Requests.

Operation

Se

Using the Motorola Data Collection Solution with MSP