LOMI School android application Guide

LOMI® School consists of 13 apps as following:

1. Launcher

 A home screen app, from where other apps are launched.

2. Lock Screen

 This app appears when the device wakes up.

 The device will be unlocked by touching the LOMI School icon in the middle.

3. Library

 A collection of videos and books for children to enjoy.

 Video will play in place, while a separate book viewer will open to read a book.

4. Book Viewer

 Book viewer app, which reads aloud most of books. The app will also read each word when one
is touched.

5. Main App

 Main learning app with tailored curriculum.

6. Blackboard

7. Drawing

8. Drum

9. Marimba

10. Writing Board

11. Sea World

12. Voice Engine (for English only)

13. Gallery

 Additional tools/toys as rewards

Most of the apps above share code from LOMI school logger
14. LOMI School Logger

 Not a stand-alone app, but the code is shared among other apps

Book Viewer and Main App are made upon cocos2d-x engine, while others are native Android apps
written in Java

#Build Environment#

Android studio and Android NDK is necessary to build the APKs.

Be sure to use the specified versions mentioned below, to avoid errors.

Android studio will also ask to install the relevant SDKs and build tools that are missing - please install
them along the way.

1. Download Android Studio

 https://developer.android.com/studio/archive
 Install Android Studio

2. Download Android NDK (r14b, except for voice-engine which uses r16b)

 https://developer.android.com/ndk/downloads/older_releases.html
 https://dl.google.com/android/repository/android-ndk-r14b-darwin-x86_64.zip
 https://dl.google.com/android/repository/android-ndk-r16b-darwin-x86_64.zip
 unzip the NDK, and set the NDK path in the relavent projects (mainapp, seaworld, bookviewer)

# Copy Resources/Engine Files #

Download the relevant resources/3rd party files from the release assets (v1.3)

 to build "mainapp", place the resources/3rd party files in the following folders
 cocos2d ROOT/mainapp/cocos2d
 common resources (mainapp_resources)

ROOT/mainapp/Resources

 language specific resources (pick only one)

 mainapp_en_us (for English)

ROOT/mainapp/Resources/localized/en-us

 mainapp_sw_tz (for Swahili)

ROOT/mainapp/Resources/localized/sw-tz

 to build "seaworld", place the cocos files in the following folder

 cocos2d

ROOT/seaworld/cocos2d
  to build "bookviewer", place the cocos files in the following folder
 cocos2d

ROOT/bookviewer/cocos2d

 to build "library", pick (only) one of the language specific resource files in the following folder
 library_en_us (for English)

ROOT/library/localized/en-us

 library_sw_tz (for Swahili)

ROOT/library/localized/sw-tz

# Build the APKs #

Build with Android Studio

 don't forget to set the NDK folder

 set the appropriate 'Build Variant'
 mainapp : generalDebug
 launcher, library, bookviewer : swahiliDebug or englishUSDebug (or englishDebug)
 others : debug
 build variant of LOMIlogger will be set automatically (release)
 from the top menu, choose Build > Build APK

The resulting APK will be generated in app/build/outputs/apk/[appname]-[language]-debug.apk

# Install & Run the APKs #

Install all the APKs, then start the LOMI Launcher to explorer.

 Please make sure there is enough storage on the device.

 Most of the APKs will not show up in the android (default) launcher.

# Trademarks

LOMI School, name and logo, and LOMI are trademarks of LOMI, Inc. The Apache License 2.0 under
which LOMI School software is released does not grant any license or right to use the trademarks. Please
see [Guidelines for Trademarks](http://LOMIschool.com/legal-LOMI/) to learn more about the terms.

LOMI and LOMI are trademarks of LOMI, Inc., registered in the U.S. and other countries.

# Questions?

### Copyright 2021 LOMI plc

Licensed under the Apache License 2.0 and the Creative Commons Attribution International 4.0 License
(the “Licenses”); you may not use these files except in compliance with the Licenses.

## Installation steps for all the apps

Last updated: May 6, 2021

1. Install Android Studio 3.3.2 or later.

2. Download Android NDK 14.

3. Replace _cocos2d_ folder present in the _mainapp_, _bookviewer_ and _seaworld_ projects with the
one present in the downloaded _assets_ folder.

5. Replace the _Resources_ folder in the _assets_ with the one present in _mainapp_ project. Ensure
that only one locale specific folder is present in the _localize_ folder i.e., keep either en-us_ folder and
the related files.

6. Open the application that you are trying to build in Android Studio. Select the build option under Build
menu.

7. The build process may prompt you to install various dependencies related to the Android SDK and
Build Tool. Make sure to install them.

8. If the application prompts you to update the _Gradle_ version used in the project, <ins>do not</ins>
update it.

9. Install the applications from Android Studio using the _Run app_ option from the _Run menu_ or
using the APK generated in _app/build/outputs/apk_ folder.

#### Note:

1. If any of the applications throw APK signing error then either comment the signing configuration from
the app's gradle file or create your own _keystore_ file following the steps mentioned
[here](https://developer.android.com/studio/publish/app-signing#generate-key).

2. _LOMI SchoolLogger_ module is shared among the projects.

3. Set the build variant to __debug__ for all project apps except for the _mainapp_ which is described in
the fourth FAQ below.

4. There is no need to install _cocos_ application separately for these projects.

## FAQs

1. There is a cross mark on the app cofiguration button. How do I fix that?

 If there is a cross mark, the default/main activity of the application is not set for the project.
Either go to _app/build/outputs/apk_ folder and install the APK which is generated right after
the build process or set the start activity in the app configuration settings of the project.
2. How do I enable the _Build variant_ option in the _Build_ menu?

 The _Build variant_ option is enabled only when the module-level gradle file is opened.

3. The application throws _keystore_ file not found error. How do I fix this?

 A _keystore_ file is used to digitally sign an Android application, hence, it is not provided with
the project. You must create your own _keystore_ file using the [Android
keytool](https://developer.android.com/studio/publish/app-signing) that comes with the
Android Studio in order to sign the APK.

4. How do I fix the mainapp application when it gives a runtime error related to the package name _?

 The runtime error related to the __ package is caused by an incorrect build variant setting for
the application. Refer to the table below for the build variant settings.
 |<center>App name</center>| <center>Build variant<center>|

> |--------|--------------|

> |LOMISchool|generalDebug-armeabi|

> |LOMIlogger|release|

> |libcocos2dx|debug|

> models|debug|

5. How do I fix NDK not found error?

> 1. Unzip the NDK folder.

> 2. Rename the unzipped folder to "ndk-bundle" and place it in the Android SDK root directory.

> 3. Ensure the _ndk-bundle_ folder contains the children files and folders.

# Localization steps for LOMISchool Applications

Last updated: May 13, 2021

## Overview
LOMI School consists of several apps that work together to have kids learn basic literacy and numeracy
skills.

Currently LOMI School supports English which can be extended to support more.

However, it is worth noting that simply translating the contents will not be enough.

It will require substantial effort and content modification to adapt to different language systems and
cultures.

That being said, here is a guide for localization.

## Launcher

1. The Launcher application is used for launching applications in LOMI School world.

2. It also sets the default language (locale) that other apps will be using, defined as "default Language" in
"configuration.xml" of each build variant.

en-US for English (/launcher/app/src/englishUS/res/values/configuration.xml)

To add language build variant, modify /launcher/app/build.gradle and create a matching folder under
/launcher/app/src/

For example, "hi-IN" for Hindi.

(And with all the apps, use "hi-IN" in place of "sw-TZ", "hi-in" for "sw-tz", and "hi" for "sw" respectively)

3. The strings used in the Launcher app is defined in

launcher/app/src/main/res/values/strings.xml (english, which is default) or

launcher/app/src/main/res/values-sw/strings.xml (swahili, overriden by Android according to the

language setting)

Change the value for each element in strings.xml file or add a new strings.xml file in the additional
language folder
___

## Main App

1. The Main App is the primary learning application in LOMI School with a tailored curriculum. This
application consists of content for literacy and numeracy training.

2. Each section of the application consists of section-specific audios, videos, and images. These assets
can be localized as follows:

1. Modify Language Manager (/mainapp/Classes/Managers/LanguageManager.[cpp,hpp]) to support

new language locale

2. Put the locale-specific content in the /mainapp/Resources/localized/[locale-code] folder.

- Files in the locale-specific folder (/mainapp/Resource/localized/[locale-code]) will supersede the

file with the same name in the general resource folder (/mainapp/Resources)

- "curriculumdata.tsv" must exist in the locale-specific folder to be recognized by the app

3. The PocketSphinx library is used for speech recognition.

___

## Bookviewer

The Bookviewer app reads storybooks aloud.

The Bookviewer refers to the resources in the main app folder (/mainapp/Resources/bookviewer and
/mainapp/Resources/localized/[locale]/games/books)

Thus, localization is not needed for this application as long as the Main App is set up accordingly.

## Library

1. The Library application consists of a collection of storybooks and videos.

1. The list of the books with the metadata is stored in

[library/localized/[locale]/assets/[locale]/library_book_data.tsv]
 2. The list of the videos with the metadata is stored in
[library/localized/[locale]/assets/[locale]/library_video_data.tsv]

3. The thumbnail images of the storybooks and the vidoes are located at
[library/localized/[locale]/assets/[locale]]

4. The videos are located at [library/localized/[locale]/res/raw]

* The Bookviewer app will be launched when a book is selected

2. The strings used in the Library app are defined in library/app/src/main/res/values[-

language]/strings.xml. Change the value for each element in strings.xml file or add a new strings.xml file
in the additional language folder

___

## Writing Board

The Writing Board application uses images containing alphabets and words. Users trace the images to
learn to write. To localize this application, the images containing alphabets and words must be replaced
with locale-specific images as follows:

1. Create a new folder in [/writingboard/app/src/main/assets/image] with locale-specific language:

For example, create a folder named _"hi-in"_ for the Hindi language.

2. Create locale-specific images similar to the images available

LOMISchool/tree/master/writingboard/app/src/main/assets/image/en-us) folder and place them in the

newly created locale-specific folder.

___

## Drawing

Drawing is an app where a child can draw on a digital paper using crayons.
The strings used in the Drawing app (mainly the names of colors) are defined in
launcher/app/src/main/res/values[-language]/strings.xml

Change the value for each element in strings.xml file or add a new strings.xml file in the additional
language folder

___

## Lock Screen

The Lock Screen app appears when the device wakes up. The device will be unlocked by touching the
LOMISchool icon.

The strings used in the Lock Screen app are defined in launcher/app/src/main/res/values[-
language]/strings.xml

Change the value for each element in strings.xml file or add a new strings.xml file in the additional
language folder

___

## Drum - Not required

Drum is an app where a child can tap on the screen to hear a drum sound. Localization is not needed for
this application.

___

## Blackboard - Not required

Blackboard is an app where the child can draw or write on a blackboard using a chalk. Localization is not
needed for this application.

___

## Marimba - Not required

Marimba is an app where the child can tap on the screen to hear a marimba sound. Localization is not
needed for this application.

___

## Seaworld - Not required

Seaworld is an app where various fish appear on the screen. Localization is not needed for this
application.
___

## LOMISchoolLogger - Not required

LOMISchoolLogger is not a stand-alone app, but the code shared among all the applications to log
details and handle shared data. Localization is not needed for this application.

___

## Voice Engine (for English only) - Does not support localization

Voice Engine is used by "Word Note" activity in the Main App. This app does not support localization.