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
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 3 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 4 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 5 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 7 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 8 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 9 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 10 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 11 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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).
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 12 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 13 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 14 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
9. A new blank application is created.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 15 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 16 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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()
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 18 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 19 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 21 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 22 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 23 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
o Make outgoing call
o Answer incoming call
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 24 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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:
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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)
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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"
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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)
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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"/>
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 33 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
o MagicSmoke
o MusicVisualization
o LatinIME
o OpenWnn
o PinyinIME
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 34 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 35 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 36 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 38 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
D/GpioService( 801): Pin event received, value = false
D/GpioService( 801): Gpio pins initialized
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Pin event received, value = true
D/GpioService( 801): Pin event received, value = false
D/GpioService( 801): Toggling GPIO pin
D/GpioService( 801): Pin event received, value = true
D/GpioService( 801): Pin event received, value = false
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 39 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
6.3.1 Connect the module
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:
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 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:
--------- beginning of /dev/log/main
--------- beginning of /dev/log/system
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 40 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 41 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
6.4.2 Build and run the SpiService app
To build the SpiService 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 the app, in the command line enter the following
command:
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:
--------- beginning of /dev/log/main
--------- beginning of /dev/log/system
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.
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 42 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
6.5.2 Build and run the UartService app
To build the UartService 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 the app, in the command line enter the following
command:
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
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 43 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
7 SECURITY
(Under preparation)
APPZONE FOR ANDROID DEVELOPER GUIDE 80496ST10724A 44 of 45
© 2016 Telit Communications PLC and its corporate affiliates. All
rights reserved. Reproduction forbidden without Telit’s prior
written authorization.
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.3.1 Connect the module
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