appzone for android developer guide

AppZone for Android Developer GuideAPPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 1 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All rights reserved. Reproduction forbidden without Telit’s prior written authorization.
APPLICABILITY TABLE
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 2 of 45
SPECIFICATIONS SUBJECT TO CHANGE WITHOUT NOTICE
LEGAL NOTICE
These Guidelines are general guidelines pertaining to the installation and use of Telit’s Integrated Application
Development Environment (“IDE”). Telit and its agents, licensors and affiliated companies make no
representation as to the suitability of these Guidelines for your particular needs and Telit disclaims any and all
warranties, expressed or implied, relating to the contents of this document. Furthermore, this document shall not
be construed as providing any representation or warranty with respect to any Telit Product whether referenced
herein or not.
It is possible that this document may contain references to, or information about Telit products, services and
programs, that are not available in your region. Such references or information shall not be construed to mean
that Telit intends to make available such products, services and programs in your area.
HIGH RISK USES
The IDE is not intended for the design of software for use in hazardous environments or environments requiring
fail-safe controls, including the operation of nuclear facilities, aircraft navigation or aircraft communication
systems, air traffic control, life support, or weapons systems ("High Risk Activities"). Without derogation, Telit, its
licensors and its supplier(s) specifically disclaim any expressed or implied warranties with respect to the use of
the IDE for development of software for such High Risk Activities and specifically disclaim all liability with respect
to such use.
The names Telit, deviceWISE, deviceWISE by Telit, secureWISE, secureWISE by Telit, Telit IoT MODULES,
Telit IoT PORTAL, Telit IoT PLATFORM, Telit IoT PLATFORMS, Telit IoT CONNECTIVITY, Telit IoT SERVICES
and their associated logos are trademarks of Telit Communications PLC, its subsidiaries or affiliates in the United
States and/or other countries. Other company or product names are the trademarks of their respective owners.
All trademark rights are reserved.
THIRD PARTY RIGHTS
The IDE may contain or may be provided in conjunction with third party software (the “third party software”),
including some or all of those detailed in the NOTICES file provided to you during installation of the IDE. You
acknowledge that not all third party software detailed in the NOTICES file are necessarily used or provided in the
particular version of the IDE you install and use. Refer to the IDE’s EULA and the NOTICES file for licensing
information pertaining to the third party software.
CONTENTS
1.4 Text conventions 6
1.5 Related documents 6
2.1 Supported Android APIs 7
3 Development process 8
3.3 Start a new project 10
3.4 Build and run your app 15
3.4.1 Configure Run and Debug configurations 16
3.5 Debug your app 16
3.5.1 Example for debug Using Android Studio 16
3.6 Generate release versions for all APKs 19
3.7 Create and flash the customapps partition 20
3.7.1 Requirements 20
3.7.2 Install tools 20
3.7.3 Create a UBI Image with a SquashFS file system 20
3.8 Install an APK using Android Debug Bridge 21
4 Reference APKs 22
5.1.3 Network access 25
5.1.4 Call management 26
5.1.5 Data connectivity 26
5.2 E-call support 30
5.2.1 ECallServer 30
5.3 GNSS 30
5.3.2 LocationManager 31
5.4 Audio 31
6.1 Integrate the hardware library 34
6.1.1 Import the DIO library 34
6.1.2 Change the path to the DIO library 35
6.2 GPIO hardware access 36
6.2.1 Hardware mapping 36
6.2.4 Build and Run the GpioSample app 37
6.3 I2C hardware access 38
6.3.1 Connecting the module 39
6.3.2 Build and run the I2cService app 39
6.4 SPI hardware access 40
6.4.1 Adapting the app to your slave device 40
6.4.2 Build and run the SpiService app 41
7 Security 43
8 FOTA 44
1 INTRODUCTION
This guide describes how to install and use AppZone for Android.
1.1 Scope
This document explains how to install and use the AppZone for Android development environment. The programming language used to write an Android app is Java. This guide provides examples for writing a simple Java app and using the Android APIs. It assumes prior knowledge of Java.
This guide does not explain how to write Java or how to use the Android APIs, such as GPS. For a complete description of the Android APIs, see the technical resource section on developer.android.com.
This guide is accompanied by several reference applications, which are installed with the SDK. These applications demonstrate the main functions of the framework, and provide a starting point for developing applications. These applications were developed on an LE920A4 module.
For information on how to install and set up the development environment, see the AppZone for Android Getting Started Guide.
1.2 Audience
This guide is intended for software developers who want to develop applications for the Telit module.
It assumes that you are familiar with Java and Android programming.
1.3 Contact information, support
For general contact, technical support services, technical questions and report documentation errors contact Telit Technical Support at:
[email protected]
[email protected]
[email protected]
http://www.telit.com/support
For detailed information about where you can buy the Telit modules or for recommendations on accessories and components visit:
http://www.telit.com
Our aim is to make this guide as helpful as possible. Keep us informed of your comments and suggestions for improvements.
Telit appreciates feedback from the users of our information.
1.4 Text conventions
Caution or Warning – Alerts the user to important points about integrating the module, if these points are not followed, the module and end user equipment may fail or malfunction.
Tip or Information – Provides advice and suggestions that may be useful when integrating the module.
All dates are in ISO 8601 format, i.e. YYYY-MM-DD.
1.5 Related documents
[2] LE920A4 Hardware User Guide
2 APPZONE FOR ANDROID OVERVIEW
AppZone for Android is an open source Application Development Environment that makes IoT application development fun and easy.
AppZone for Android uses the power of the Android framework and tools. This means that you enjoy a contemporary, stable, widely used and debugged application framework. The framework includes standard API’s, which provide access to a rich set of capabilities, covering the entire spectrum required for IoT development. In addition, the framework was extended to cover areas that the Android framework does not handle, such as eCall and hardware access. The framework is based on the AOSP project, and built on top of a Linux Kernel. Android Studio is used as the IDE, enabling a standard and advanced development environment.
The Android framework was reduced and tuned for Telit’s IoT modules, enabling development for all verticals, such as industrial, automotive, and security. Your application can monitor sensors, connect to short range radios, collect GPS location, handle audio, process the data, and then send it over the cellular network to the Telit cloud securely.
This document describes the AppZone for Android framework – how it was modified, reduced, and sometimes extended; and how to use it.
2.1 Supported Android APIs
AppZone for Android is based on KitKat 4.4.4, with API level 19.
AppZone for Android is adapted for IoT and M2M devices, therefore, it does not support all Android APIs. Most of the APIs that are not supported by AppZone Android are related to human interface and graphical user interface.
For a complete list of items that have been removed from the framework, see Removed functionality.
3 DEVELOPMENT PROCESS
This section describes the AppZone for Android framework and how to develop and debug an app.
3.1 Framework
The AppZone for Android framework is built on Android KitKat 4.4.4, but differs from the original Android release in several ways. Most differences are because Android was designed for devices that interact with humans, while the Telit modules do not. Therefore:
The Android framework was greatly reduced – most GUI related components were removed. A complete list is in chapter 6
All apps must be pre-installed – applications reside in a dedicated customer partition, which is read-only and digitally signed. This method is used for increased security, and is the suitable method for non-GUI devices. Because the apps are pre-installed and therefore are not downloaded from Google Play, the Google app signing mechanism is not required.
No activity in the manifest – activity is the foreground section of the application, but because there is no GUI, it is not part of the application.
The framework is provided in a rooted way that enables working with no limitations.
The following figure provides an overview of the framework:
Linux Kernel
Audio driver
N A T I V E
SQLite
System apps
phone dio.jar
The framework consists of the following major components:
Linux kernel – AppZone for Android is built on top of an LTS Linux Kernel with required Android adaptations, such as enabling wakelocks, binder and ASHMEM.
HAL – hardware abstraction layer (HAL) to abstract the device drivers. It interfaces directly with the Linux kernel and has drivers for hardware components such as GNSS, Radio (RIL), audio.
Libraries – Android’s native libraries. Enables the device to handle different types of data. These
libraries are written in c or c++ language and are specific for a particular hardware.
Android Runtime – Consists of Dalvik Virtual machine and Core Java libraries:
o Dalvik VM – is the JVM used in android devices to run apps and is optimized for low
processing power and low memory environments. Unlike the JVM, the Dalvik Virtual
Machine doesn’t run .class files, instead it runs .dex files. The .dex files are built from
.class file at the time of compilation and provides higher efficiency in low resource
environments. The Dalvik VM allows multiple instance of Virtual machine to be created
simultaneously providing security, isolation, memory management and threading support.
o Core libraries – Provide most of the functionalities defined in the Java SE libraries.
Application framework – programs that manage the basic functions of phone such as resource
management, voice call management, and location manager. This layer gives the developers
access to the lower levels of the platform.
Applications – Use services provided by the application framework.
3.2 Development lifecycle overview
The following diagram describes the development lifecycle:
The entire development process is done using Android Studio. When you finish developing, you can generate a release version of all apps.
Start a new project in Android Studio
Develop and debug in Android Studio
Generate release versions for all apks
Create customapps image
Flash customapps image
3.3 Start a new project
You develop Android applications in Android Studio. The generated apks can then be installed on a device, and can be debugged using standard tools.
Generated apks must not contain activities, and must contain at least one service that the app will launch.
To create new project:
1. Open Android Studio and select Start a new Android Studio project.
Or from the menu, select File > New > Project.
The Create New Project window opens.
2. Enter the following information for your new project, and then click Next:
a. In the Application name field, type a name for your application.
b. In the Company Domain field, type the name of your company domain, which provides a qualifier that will be appended to the package name.
The Target Android Devices window opens.
3. Specify the target, and then click Next:
a. Select Phone and Tablet.
b. In the Minimum SDK, select API 19: Android 4.4 (KitKat).
4. Android Studio installs the components that you selected. When the installation ends, click Next to continue.
The Add an Activity to Mobile window opens.
5. Select Add No Activity, and then click Finish.
Android Studio downloads the required components and opens your new project in Android Studio.
6. To open the Project view, on the left panel click Project and then select app.
7. To create new Service component, right click app, and then select New > Service > Service.
The Configure Component window opens.
8. Configure the component, and then click Finish:
a. In the Class Name field, type a name for your class.
b. Select Exported to enable step-by-step debugged of your application.
c. Select Enabled to enable your application to start.
9. A new blank application is created.
3.4 Build and run your app
You can use LE920A4 to run, debug, and test your apps. You can install your app on the device directly from Android Studio. You can also install it from the command line using ADB for enhanced debugging capabilities. For more information see, Install an APK using Android Debug Bridge.
Before you build and run your app, make sure that the module is connected to your computer using a USB cable.
To build and run your app:
1. Click Run 'app'.
Android Studio builds your app with Gradle. The Select Deployment Target window opens.
2. Select a deployment target, and then click OK.
You can customize the default behavior, such as selecting an automatic deployment target, by changing the Configure Run and Debug configurations.
3.4.1 Configure Run and Debug configurations
When you run, debug, or test your code, Android Studio uses a run/debug configuration to determine how
to perform the operation. In most cases, the default configuration is sufficient and you can click Run ( )
or Debug ( ) to launch your app. However, you can modify and create new configurations, and modify the default templates to suit your development process.
Run/debug configurations specify details such as app installation, launch, and test options. You can define a configuration for one-time use, or save it for future use. After you save it, you can select the configuration from the Select Run/Debug Configuration drop-down list within the toolbar. Android Studio saves configurations as part of the project.
To create or edit a run/debug configuration:
From the menu, select Run > Edit Configurations.
3.5 Debug your app
After you build your app, you can debug it using all standard capabilities:
You can debug your app using one of these methods:
adb – The adb debugging capability is turned on in firmware by default. This fact enables application developer to use ADB’s capabilities to develop and debug applications.
For information on how to debug using adb, see Android Debug Bridge.
The app service must be marked as exported to enable step-by-step debugging.
Android Studio – Android Studio includes a debugger that allows you to debug apps running on the connected module.
For information on how to debug using Android Studio, see Debug your app using Android Studio.
3.5.1 Example for debug Using Android Studio
This section provides an example for debugging the HelloWorldSample app.
Android applications can be debugged on Android Studio using adb. To debug your app on a Telit module, perform the following steps:
1. Make sure, that the service in your project is marked as exported and enabled.
See Start a new project.
2. In your project's main service, locate the onStartCommand function.
3. At the beginning of the onStartCommand function, insert the following line:
android.os.Debug.waitForDebugger()
5. Click Debug ( ).
If this is the first time that you are debugging your app, the Device Chooser window opens.
6. Launch application service by entering the following command:
am startservice -n com.example.telit.myapplication/.TelitService
3.6 Generate release versions for all APKs
After you have completed developing all your apps, we recommend that you compile the APKs in release mode before generating the final image.
When you compile the app in release mode (rather than the debug mode in which you developed the app) a more compact app is generated, without debug information that is required during the development process. More details about this can be found in https://developer.android.com/studio/publish/preparing.html#publishing-configure
To compiling the app in release mode:
1. In the left panel, select Android.
2. From the menu, select Build > Edit Build Type. The Project Structure window opens.
3. Select the following information, and then click OK:
In the left pane under Modules, select app.
In the central pane, select release.
4. From the menu, select Run Build > Build APK. The release version is built and saved in the following path: \app\build\outputs\apk.
3.7 Create and flash the customapps partition
This section explains how to prepare your partition, customapps, for flashing. You prepare the partition after development is over, and you must prepare and flash the final image.
To develop applications on Android, it is important to understand the high level flash memory layout. The flash memory is divided between the framework partitions and the customer application partition. The customer application partition, customapps, is a read-only partition that uses the SquashFS file system.
3.7.1 Requirements
Ubuntu 12.04 LTS and above (can be executed using a virtual machine).
Ubuntu 14.04 LTS x86_64 is recommended (has been used for examples in this section).
Root access (to install required packages)
3.7.2 Install tools
Open the terminal on Ubuntu and install the following tools (if root access is not allowed ask your system administrator to install them for you):
sudo apt-get install android-tools-adb android-tools-fastboot android-tools-fsutils mtd-
utils
3.7.3 Create a UBI Image with a SquashFS file system
1. Create a temporary folder:
mkdir customapps
3. Run the following command outside of the customapps folder:
mksquashfs customapps/ customapps.sqsh
4. Use a text editor to create file outside of the customapps folder with the name of ubi.conf.
5. Enter the following text in the ubi.conf file that you created:
[customapps_volume]
mode=ubi
image=customapps.sqsh
vol_id=0
vol_name=customapps
vol_size=180MiB
6. Run the following command to create a ubi image for flashing:
ubinize -vv -o customapps.img -m 2048 -p 128KiB -s 2048 ubi.conf
7. To flash the image:
a. Put the device in bootloader mode.
b. Run the following command to flash:
fastboot flash customapps customapps.img
8. Reboot the device.
3.8 Install an APK using Android Debug Bridge
For enhanced debugging, you can install an apk onto an Android device by connecting the device to a computer with a USB cable, and then connecting to the device using ADB (Android Debug Bridge).
1. Connect the device to the development environment using a USB cable.
2. In Android Studio, open the terminal.
3. Enter the following command:
adb devices
The following example shows the output of the list of devices attached:
$ adb devices
LE920A4 device
4. To install the application, navigate to the folder containing the APK and install APK using adb by entering the following commands:
$ cd /AndroidStudioProjects/MyApplication/app/build/outputs/apk
$ adb install my_application.apk
5. If the device list is empty, or a given device is not listed, kill the ADB server by executing the following command:
adb kill-server
6. Execute adb devices again to restart the server, re-detect devices, and then try again.
4 REFERENCE APKS
The AppZone for Android SDK contains several reference applications that are installed with the SDK. These applications demonstrate the main functions of the framework, and provide a starting point for developing applications. These applications were developed on an LE920A4 module.
Each APK is accompanied by a text file that provides details on the apk.
By default, the reference apks are installed in the following location:
<Installation folder>\IoT_AppZone_IDE\tools\AndroidSamples.
The following reference applications are provided:
AudioSample – Demonstrates how the audio player works. This application provides the ability to play a file by specifying the path to it via intent parameters. It also enables to play music from an application without specifying the path to the file.
CloudSample – Demonstrates Telit Cloud functionality. The app shows how to access and process data.
ECallSample – Demonstrates eCall functionality. The app responds to a notice from the ecall button, generates an msd, selects the appropriate PSAP number from the eCall numbers database, and then sends the intent to the phone application.
GpioSample – Demonstrates GPIO functionality. The app shows how to access and process data.
GPSSample – Demonstrates how to work with the GPS and display the coordinates of the device by sending a special intent.
HelloWorldSample – Demonstrates how to work with BroadcastReceivers and start simple Services.
I2cService – Demonstrates DIO I2C library functionality. The app reads the internal Audio Codec revision number register, and then writes the byte 0x3C in the Audio Codec left volume control register and reads it out again.
SmsSample – Demonstrates how to change the configuration sms storage, send and receive sms, and get a stored sms from list and mapping.
SpiService – Demonstrates DIO SPI library functionality. The app writes eight bytes, and then reads eight bytes from a slave device that is attached to the SO208 connector.
TelephonySample – Demonstrates part of the telephony functionality, such as:
o Check network registration
o Check data registration
o Get operator name
o Display RAT type
o Display IMEI
o Display data state
o Display device software version
o Get current time in msec and format into human-readable form
o Display Cid and Lac
o Check service state
o Make outgoing call
o Answer incoming call
5 APIS
The AppZone for Android framework is based on KitKat 4.4.4, API level 19. The Android API’s are described in developer.android.com/reference/packages.html .
This chapter describes the different API packages supported, and indicates the differences from the original Android package, where applicable. Each section is accompanied with reference applications that demonstrate the main capabilities.
5.1 Telephony
Telephony .is a central part of the AppZone for Android framework. The major functions are described and pointers to the relevant Android online documentation is provided. The AppZone for Android SDK contains several applications that provide examples of how to use these capabilities.
The Telephony functionality includes:
E-call support
A full description of the Android telephony package can be found at: developer.android.com/reference/android/telephony/package-summary.html.
5.1.1 Sample apps
This section refers to the following sample applications, which are part of the SDK:
TelephonySample – demonstrates the main telephony functions, except SMS and eCall
SmsSample – demonstrates SMS functionality
ECallSample – demonstrates eCall functionality
5.1.2 Telephony boot process
During system boot, the framework tries to camp on the available cellular networks. In the LE920A4 module, LTE is preferred over other Radio Access Technologies (RAT). During the camping process on the network, the network provides information to the module, such as MNC, MCC, and the provider identity. The framework checks with the module that the SIM and IMEI are identified. In parallel, data registration is performed – at the end of this process, the module is aware of the available data technology (such as GPRS, HSPA, LTE) and a data session is started based on the appropriate APN.
The camping process is automatic and does not require any development. The app can poll to keep track of the status. Knowing the status enables the application to decide whether it can start a new data session, send an SMS, or perform other actions that require an active data session.
While the system is running, the telephony manager continuously monitors vital parameters (such as signal strength) and makes this information available to the application level.
5.1.3 Network access
The Network access category covers the cellular network capabilities. The TelephonySample reference application demonstrates most of the capabilities mentioned below, including network voice and data registration; network operator identification, RAT identification, and RSSI level value.
5.1.3.1 Tracking Network registration state
The following APIs are used to monitor the network registration and can also affect the process. The APIs are listed in the chronological order in which they are likely to be used.
Query the cellular registration status:
getState()
CellIdentityGsm.html
CellIdentityWcdma.html
CellIdentityLte.html
Check if registered:
getNetworkType()
CellSignalStrength.html
Enable the manual selection:
5.1.4 Call management
5.1.4.1 Query Call configuration
Query if voice calls are supported (ensure the device is not data only):
isVoiceCapable()
5.1.4.2 Broadcast and Activity intents
In Android, phone operations have no direct API’s; instead, these operations are handled by broadcast and activity intents. Broadcast intents are sent by the telephony service to notify about ongoing call operations (e.g. call status), and can be used to track the call state. Activity intents are sent from applications, in order to trigger phone operations (e.g. initiating a voice call).
AppZone for Android works similarly: Broadcast intents haven’t been modified. Intents are sent from applications, however they have been modified, as described in this section. The intents were enhanced to support eCall.
Dial (MO call)
To initiate an MO voice call, send the following modified intent to the system Phone.apk:
com.android.phone.ACTION_CALL --es number "%NUMBER%"
Answer (MT call)
To track mobile terminated voice call, create a BroadcastReceiver class:
android.intent.action.NEW_OUTGOING_CALL
android.intent.action.PHONE_STATE
Within this class, check if the call state is changed to CALL_STATE_RINGING and then access the
com.android.phone.ACTION_HANGUP modified intent.
To disconnect any active call, send the following modified intent:
com.android.phone.ACTION_HANGUP
5.1.5.1 Query on data connection state
Get the current cellular data state (CONNECTED, DISCONNECTED etc.)
getDataState()
5.1.5.2 Query on data traffic state
Get the current data traffic exchange status if any (Uplink /Downlink)
5.1.6 SMS
SMS capability consists of the SMS method configuration, MO and MT delivered SMS services.
To send or receive an SMS, the SMSManager API is used.
The built-in SMS application that uses intents to trigger activities is not supported.
5.1.6.1 Register to SMS manager
To get the Android SMS services, the client application must register with the SMSManager class:
Register SMS manager class
sendTextMessage()
sendDataMessage()
sendMultipartTextMessage()
Within this class, use the following SMS Android APIs.
Create an SMS message from the raw PDU received from intent on Track on receiving SMS
createFromPdu()
Return the origin address of the SMS from SMS message created above
getDisplayOriginatingAddress()
Get the received message body of the SMS from SMS message created above
getDisplayMessageBody()
Get the index of SMS in the SIM card if it stored in the SIM
getIndexOnIcc()
Read the SMS status
getStatusOnIcc()
Read the SMS status on SIM (READ, UNREAD, SENT, UNSENT) from the SMS that was created from the raw PDU received from intent on Track when receiving the SMS.
Get the service center address in order to send MO SMS
5.1.7 SIM manipulation
There are several possible functionality for applications regard to SIM/USIM cards. The functionality may include: SIM card information, execution of the SIM blocking/unblocking passwords for different situations and processes and access SIM commands to retrieve information or update the SIM card files.
5.1.7.1 SIM Card identification
Get the IMSI number
Query if the card is ICC (new generation SIM card)
hasIccCard()
getSimState()
To issue PIN manipulation commands from the application layer, application programmers can send intents that will trigger the phone .apk layer.
The intents to invoke the SIM manipulate operations are listed below.
Verify SIM PIN
com.android.phone.ACTION_VERIFY_PIN1 --es pin "password"
Insert the SIM password in order to block or unblock the SIM for user
Verify SIM PIN2
com.android.phone.ACTION_VERIFY_PIN2 --es pin2 "password"
Insert the Fixed Dial Number (FDN) password code in order to block or unblock the Fixed Dial number calls for user
Change SIM PIN
"new_password"
Change SIM PIN2
new_pin2 "new_password"
Change the Fixed Dial Number (FDN) password code that blocks/unblocks the Fixed Dial number calls for user
Enable/disable SIM PIN
Enablel/disable the SIM password that blocks/unblocks the SIM
Enable/disable SIM PIN2
pin2 "pin2_password"
Enable/disable the Fixed Dial Number (FDN) password code that blocks/unblocks the Fixed Dial number calls for user
Set PUK
"pin_password"
Insert the Pin Unlock Key (if the password is locked due to wrong PIN that was inserted 3 times), in that case also need new PIN for the SIM
Set PUK2
"pin2_password"
Insert the Pin Unlock Key for Fixed Dial Numbers (if the password of FDN is locked due to wrong value that was inserted 3 times), in that case also need a new FDN PIN2 for the SIM
Get SIM status
Operation result example
D/PhoneApp.IccCardReceiver( 566): Broadcast onReceive:
Get supported intents
5.1.8 Device radio capability
The mobile equipment has telephony capabilities that are transparent for application programmer. Nevertheless, there is API, which provides radio specific information.
Query the unique ID of the device
getDeviceId()
Determines the phone type of device (GSM, CDMA etc.)
getPhoneType()
Set the device service status (On, Emergency, Power off etc.)
setState(int)
5.2 E-call support
EU eCall and ERA/GLONASS eCall is supported, including the support of in-band modem (3GPP TS26.267), ecall Inactive mode support (3GPP TS24.008) and emergency call service request message (3GPP TS24.008).
E-call support is provided by a system application ECallServer.
5.2.1 ECallServer
The eCallServer application responds to an external hardware event (typically an airbag opening notification). Currently, the hardware event is the eCall button on the LE920A4 SDK board.
You can also send a broadcast intent, com.android.ecall.ACTION_ECALL (with no parameters), to trigger events by your manually.
Once an event is triggered and broadcast intents received, the ECallServer generates an MSD (Minimum Set of Data) and sends the eCall notification to the appropriate PSAP (according to location), and plays ringtone.
The following information is coded into MSD:
vehicle identifier (according to ISO 3779)
time stamp
other optional information
5.3 GNSS
GNSS location functionality is equal to the original functionality as described in developer.android.com/reference/android/location/LocationManager.html.
This section refers to the GPSSample app.
5.3.1 Specify app permissions
Applications that intend to use location services must request location permissions.
Android offers two location permissions: ACCESS_COARSE_LOCATION and ACCESS_FINE_LOCATION. The permission you choose determines the accuracy of the location returned by the API. If you specify ACCESS_COARSE_LOCATION, the API returns a location with an accuracy approximately equivalent to a city block.
In the GPSSample reference app, the app requires fine location detection, so that app can get as precise a location as possible from the available location providers. Request this permission with the uses- permission element in your app manifest, as shown in the following example:
<manifest xmlns:android=http://schemas.android.com/apk/res/android
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
5.3.2 LocationManager
This class provides access to the system location services. These services allow applications to obtain periodic updates of the device's geographical location.
You do not instantiate this class directly; instead, retrieve it through getSystemService(Context.LOCATION_SERVICE).
Request Location Updates
Before requesting location updates, your app must connect to location services and make a location request.
Depending on the form of the request, the location provider invokes the onLocationChanged() callback method and passes it a Location object, that contains the location in its extended data. The accuracy and frequency of the updates are affected by the location permissions you've requested and the options you set in the location request object.
Stop Location Updates
Start Service from command line
am startservice -n com.telit.samples.gps/.GPSService
5.4 Audio
This section refers to the AudioSample application in the samples directory.
Audio playback and record, in various formats, is supported. Audio functionality can be accessed using appropriate API, described at
developer.android.com/reference/android/media/package-summary.html, and supported audio formats list can be found at developer.android.com/guide/appendix/media-formats.html.
DRM, audio and video effects, video playback support were removed from MediaPlayer class.
For playing audio device, use the MediaPlayer class and the corresponding APIs.
5.5 Telit cloud
Telit provides a cloud solution called Telit IoT Portal that enables devices to send information to it, and then to view this information using methods, such as advanced filters and dashboards. For detailed information, capabilities, and usage of the Telit portal see help.devicewise.com.
The IoT portal connectivity is not part of the Android framework. Connecting to the IoT portal from an Android application is done by importing Java libraries provided by Telit. The APIs of these libraries are described in help.devicewise.com/display/M2MOpen/JAVA+-+Client+APIs.
You can download the Java libraries and examples from: dw- resources.s3.amazonaws.com/TR50_Clients/JAVA/dwtr50.0.1.0.tar.gz.
To add the Devicewise java library into your Android Studio application:
1. Download and unpack dwtr50.0.1.0.tar.gz.
2. Unpack it and copy dwtr50.jar into the app\libs folder in your project.
3. For TR50 via HTTP:
a. In your Android project, from the menu select New > New Module > Import Jar/AAR package
b. Browse to the apps\libs folder and then select dwtr50.jar.
A reference CloudSample app is provided and demonstrates reading the LE920A4 CPU temperature and sending it periodically to the cloud. The cloud credentials must be obtained and inserted into the code, as remarked in the apk.
5.6 Removed functionality
This section lists the functionality that was removed from AppZone for Android. Each item is a capability that may have been implemented using several APIs.
Components removed from the Android framework:
Removed all unnecessary graphical applications:
o AccountsAndSyncSettings
o Browser
o Calculator
o Calendar
o Camera
o CellBroadcastReceiver
o CertInstaller
o Contacts
o DeskClock
o Email
o Gallery
o Gallery3D
o HTMLViewer
o Launcher2
o Mms
o Music
o Nfc
o PackageInstaller
o Protips
o Provision
o QuickSearchBox
o Settings
o SmartCardService
o SoundRecorder
o SpeechRecorder
o Stk
o Tag
o VoiceDialer
o Basic
o LivePicker
o MagicSmoke
o MusicVisualization
o LatinIME
o OpenWnn
o PinyinIME
6 ACCESSING EXTERNAL HARDWARE
Typical IoT/M2M applications need to access hardware that is connected to the Telit module, such as GPIO, ADC, SPI, and UART. The standard Android framework provides high-level abstraction layers to use pre-defined hardware devices, such as the sensor framework, but does not provide low-level hardware control.
AppZone for Android provides the ability to access hardware using the OpenJDK Device IO module, an open source project adopted from Oracle Java ME. It provides a Java API to control low-level hardware.
You must integrate the dio.jar as an external library in your apk file you your app will not be able to access the hardware.
6.1 Integrate the hardware library
Telit provides a library, dio.jar, for the supported hardware access.
You must include the jar as a library in your Android Studio project.
In the sample projects, the library is already included.
6.1.1 Import the DIO library
To include a jar in an Android Studio project:
1. First make sure that you know the path to your dio.jar or copy it in a subfolder of your project, such as a folder under apps/ called libs/.
2. Open Android Studio.
3. In the Tools window, open the Project Tools window.
4. Locate the dio.jar file under app name > libs.
5. Right-click dio.jar, and then select Add as library. The Create Library window opens.
6. Select the module to which you want to add the library, and then click OK.
7. Rebuild the project.
You can import jdk.dio into any of your source files and use the DIO API.
6.1.2 Change the path to the DIO library
You can change the path to the dio.jar in the sample app project.
To change the path:
1. In the Project Tools pane, under Gradle Scripts click build.gradle (Module: app). The Gradle file opens.
2. Locate the path to the dio.jar file.
The path appears at the bottom of the file, after compile files in the dependencies section.
6.2 GPIO hardware access
6.2.1 Hardware mapping
The following table lists the mapping for the LE920A4 board between Telit GPIO names and the DIO (Digital Input Output) pin configuration numbers that are used to connect to external hardware.
Telit HW GPIO names DIO Pin Configuration Number
TGPIO_01 25
TGPIO_02 10
TGPIO_03 35
TGPIO_04 11
TGPIO_05 43
TGPIO_06 24
TGPIO_10 77
TGPIO_20 79
6.2.2 APIs
The Java ME API was not changed.
For the complete JAVA ME API documentation, including the DIO functionality in the apk, see: http://docs.oracle.com/javame/8.0/api/dio/api/index.html.
6.2.3 Connect the module
You can start your app as a service. This app prints the input of a changing Pin 79, which corresponds to TGPIO_20, and toggles the output of Pin 10, which corresponds to TGPIO_02.
The following figure shows an example of an LE920A4 board that is connected to a computer.
6.2.4 Build and Run the GpioSample app
This section describes how to use the GpioSample app. You can use this app as an example for using the DIO library in an app.
To build the GpioSample app:
1. From the menu, select Build > Build APK. Gradle builds the apk.
2. Run the app. See Build and run your app for more information.
3. To trigger your app, in the command line enter the following command:
adb shell am startservice -n com.example.gpioservice/.GpioService
You can filter the output using the following command:
adb logcat *:s GpioService.
The following example shows the output of the GpioSample app in the logcat window of Android Studio:
--------- beginning of /dev/log/main
--------- beginning of /dev/log/system
D/GpioService( 801): Going to init gpio pins
Input pin Output pin
D/GpioService( 801): Pin event received, value = false
D/GpioService( 801): Gpio pins initialized
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Pin event received, value = true
D/GpioService( 801): Pin event received, value = true
In the output:
Toggling GPIO pin – Indicates that the output pin is toggled.
You can measure either 0V or ~2V, alternating with each trace.
Pin event received – Indicates that the input pin value was modified.
6.3 I2C hardware access
This section describes how to use the I2cService sample app and the DIO I2C library in an app.
You can start the app as a service on an LE920-A4 module. The app reads the internal Audio Codec revision number register, and then writes the byte 0x3C in the Audio Codec left volume control register and reads it out again.
For illustration purposes, this example writes to the internal Audio Codec. However, most apps will access external devices, therefore, you must modify the I2CDeviceConfig config object:
In this example, the i2c-4 bus is used. Make sure that you modify the sample to use the I2C bus that is required for your external device.
Check the mapping section for the default Telit mapping. Set the I2cAddress to the address of the external slave device. You can find the slave address in the datasheet of that device.
You must specify whether the slave address has 7 or 10 bits.
The default clock frequency used by the DIO is 400kHz, which is the only frequency supported.
For the read and write operations, you can use the subaddress variable to set the register of the slave for read and write operations.
The i2c-4 bus on the LE920A4 module can be access through the S0207 connector. The following picture shows where to connect the I2C connector:
6.3.2 Build and run the I2cService app
This section describes how to use the I2cService sample app. You can use this app as an example for using the DIO library in an app.
To build the I2cService app:
3. To trigger the app, in the command line enter the following command:
adb shell am startservice -n com.example.i2cservice/.I2cService
The following example shows the output of the I2cService app in the logcat window of Android Studio:
D/I2cService( 779): Service firstly created...
D/I2cService( 779): Read register 0xff from device with address 0x18 -> 0x42
D/I2cService( 779): Read register 0x10 from device with address 0x18 -> 0x0
D/I2cService( 779): Wrote 1 byte to register 0x10 at device with address 0x18
D/I2cService( 779): Read register 0x10 from device with address 0x18 -> 0x3c
D/I2cService( 779): Closing I2C device 0x18
Register 0xff is the sub address of the Audio Codec revision number register, and 0x10 is the sub address of the Audio Codec left volume control register.
6.4 SPI hardware access
This section describes how to use the SpiService sample app and the DIO SPI library in an app.
You can start the SpiService sample app as a service on an LE920-A4 module. The app writes one byte, and then reads that byte from a slave device that is attached to the SO208 connector.
6.4.1 Adapt the app to your slave device
The SpiService sample app is provided for illustration purposes. Configuration and interaction with the slave device depends on the slave device that you want to use. You must adapt the app for opening the slave device that you connected.
Use the following guidelines to adapt the app to access your slace device:
Change the configuration in the openExternalSpiDevice() function.
To access device such as the following: /dev/spidevX.Y
o The busNumber is X
o The Slave Chip Select Address is Y.
For clockFrequence, wordLength, and bitOrdering you can use the defaults when working on the LE920-A4 module.
You must set the clockMode correctly, because it contains information about the Clock Polarity Bit (CPOL) and Clock Phase Bit (CPHA). See the datasheet of the slave device fir information on the CPOL and CPHA.
For information on the clockMode parameter mapping, see the DIO spibus API documentation.
Access the external SPI bus on the LE920-A4 through the S0208 connector.
6.4.2 Build and run the SpiService app
To build the SpiService app:
adb shell am startservice -n com.example.spiservice/.SpiService
You can filter on the output by entering the following command:
adb logcat *:s SpiService:*
The following example shows the output of the SpiService app in the logcat window of Android Studio:
D/SpiService( 1126): Running SpiService...
D/SpiService( 1126): Opening spi device on bus 1 with chip select 0
D/SpiService( 1126): Write byte Ox90 to spi slave
D/SpiService( 1126): Read byte from spi slave
D/SpiService( 1126): Successfully written and read back byte sequence to and from slave.
D/SpiService( 1126): Closing SPI device
6.5 UART hardware access
This section describes how to use the UartService sample app and how to use the DIO UART library in an app.
You can start the app as a service so that it acts as a terminal echoing any received character. you can connect to the module by opening the serial port using a terminal emulation program, such as Putty or Minicom, on the host computer.
The serial port settings used in the sample app are the following:
Port name: /dev/ttyHS0
baud rate: 115200
data bits: 8
6.5.1 Adapt the app
The LE920A4 has two UART ports that can be accessed via the mini-usb connector on the SDK board.
On the LE920A4, the UART ports can be accessed through /dev/ttyHS0 and /dev/ttyHSL0.
On Windows, you can see them as COMx and COMx+1 respectively.
On Linux, you can see them as /dev/ttyUSBx and /dev/ttyUSBx+1 respectively.
6.5.2 Build and run the UartService app
To build the UartService app:
adb shell am startservice -n com.example.uartservice/.UartService
You can filter on the output by entering the following command:
adb logcat *:s UartService:*
The following example shows the output of the UartService app in the logcat window of Android Studio:
01-02 00:02:26.419 828-828/com.example.uartservice D/UartService: Service created
01-02 00:02:26.479 828-828/com.example.uartservice D/UartService: Opening UART device
ttyHS0 with baud rate 115200
01-02 00:02:40.809 828-828/com.example.uartservice D/UartService: closing UART device
ttyHS0
7 SECURITY
(Under preparation)
8 FOTA
(Under preparation)
1 Introduction
1.1 Scope
1.2 Audience
2.1 Supported Android APIs
3.4 Build and run your app
3.4.1 Configure Run and Debug configurations
3.5 Debug your app
3.7.1 Requirements
3.7.3 Create a UBI Image with a SquashFS file system
3.8 Install an APK using Android Debug Bridge
4 Reference APKs
5.1.3.2 Cell signal quality
5.1.3.3 Network selection manipulation
5.1.5 Data connectivity
5.1.6 SMS
5.1.6.2 SMS Mobile Originated
5.1.6.3 SMS Mobile Terminated
6.1.2 Change the path to the DIO library
6.2 GPIO hardware access
6.3 I2C hardware access
6.4 SPI hardware access
6.4.2 Build and run the SpiService app
6.5 UART hardware access
6.5.1 Adapt the app
7 Security
8 FOTA

appzone for android developer guide

Documents