This repository contains the Buendia app, which runs on tablets with Android 4.4.2 (KitKat) or higher. See the Buendia wiki for more details about the project and about the OpenMRS module that this app communicates with.
Copyright 2015 The Project Buendia Authors
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Follow the instructions below to get your system set up to do Buendia client development.
- If
java -versionreports a version lower than 1.7, install JDK 7:- Linux:
sudo apt-get install openjdk-7-jdk - Mac OS: Download from Oracle
- Linux:
- Note: JDK 8 works fine for client development, but to run the OpenMRS server you have to use JDK 7, not 8.
- Visit https://developer.android.com/sdk/installing/studio.html and follow the steps to install Android Studio.
- We have tested the application with Sony Xperia Z2 tablets in the field: they are waterproof, have a great screen, and come with KitKat. However, in 2019 these are no longer in production.
- Any Android tablet should do fine. We recommend a tablet with at least an 8-inch display; the app is designed for 1200 x 1920 resolution.
- The app will also run on an Android phone. The user interface can be scaled down to be usable on a phone (though a bit unwieldy).
- You can also use an emulator instead of a real device (see below).
- You can skip this step if you're using an emulator (see below).
- On the device, enable Developer options by opening the Settings app, selecting Software options, and tapping the Build number 7 times.
- In the Settings app under Developer options, turn on USB debugging.
- Connect a USB cable from your computer to your device. Click OK when asked if you want to allow USB debugging.
- Now you need to set up your computer:
- If you're developing on Mac OS X, it just works. You're done.
- If you're developing on Windows, you need to install a USB driver for adb. For an installation guide and links to OEM drivers, see this OEM USB Drivers document.
- If you're developing on Ubuntu Linux, you need to add a
udevrules file that contains a USB configuration for each type of device you want to use for development. In the rules file, each device manufacturer is identified by a unique vendor ID, as specified by theATTR{idVendor}property. For a list of vendor IDs, see USB Vendor IDs. To set up device detection on Ubuntu Linux.-
Log in as root and create this file: /etc/udev/rules.d/51-android.rules.
-
Use this format to add each vendor to the file:
SUBSYSTEM=="usb", ATTR{idVendor}=="054c", MODE="0666", GROUP="plugdev". In this example, the vendor ID 054c is for Sony. The MODE assignment specifies read/write permissions, and GROUP defines which Unix group owns the device node. -
Now execute:
chmod a+r /etc/udev/rules.d/51-android.rules. -
NOTE: 2019-06-07 I did not set up these udev rules on my Ubuntu 16.04 machine, and it worked anyway
-
-
Get the Buendia client source code:
git clone --recursive [email protected]:projectbuendia/client.git git submodule update --init -
Launch Android Studio and click Open an existing Android Studio project.
-
Navigate to the root directory of your
clientrepo, select thebuild.gradlefile there and click Open. -
Wait a few minutes while Android Studio builds the project for the first time.
- During the first build, it's normal to get errors about missing parts of the SDK (e.g. "Error: failed to find target android-21", "Error: failed to find Build Tools revision 19.1.0"). In each case, just click the suggested resolution to install the necessary SDK component (e.g. "Install missing platform(s) and sync project", "Install Build Tools 19.1.0 and sync project") until the build finishes without errors.
You are now ready to develop the Buendia client in Android Studio.
Connect a USB cable from your computer to your device.
On Android Studio, click the Run button (green triangle in the toolbar at the top). For Module select app and click OK.
You should see your device appear in the "Select Deployment Target" window. Select it and click OK.
Wait a few minutes for the app to build (you can see progress in the status bar at the bottom). When it's done, Android Studio will automatically install it on the tablet and start it.
By default, the app is configured to use a server address pointing at a server on the Internet that contains dummy data. Feel free to add and edit users and patients.
The client-side tests include both unit tests and functional tests, all located under the project's androidTest folder. These tests run best on a real tablet attached to your computer. (When run on an Android emulator, some tests work and some don't.)
You can run just the tests in a single file, or run all the tests under a given folder (such as the androidTest/java folder for all the tests in the entire project). In the Project pane, right-click a file or folder, choose Create Run Configuration, and then choose Android Tests (the one with the icon containing the little green Android robot). It's necessary to set the Specific instrumentation runner to AndroidJUnitRunner. Then you can Run or Debug this run configuration to run the tests.
You can always manually change the OpenMRS server, username, and password on the Settings page in the app. It's tedious to keep doing this every time the app is uninstalled and reinstalled, though. To change the default settings, which are built into the app, edit these lines in app/build.gradle:
def serverDefault = serverDev
def openmrsUserDefault = 'buendia'
def openmrsPasswordDefault = 'buendia'
By default, the client is built with its Server set to dev.projectbuendia.org, which is an instance of the OpenMRS server with dummy data that we use for development. For release builds, we set this to simply server, which is the hostname of the Edison server in real deployments. (When you set the Server to, say, blarg, the OpenMRS base URL is automatically set to http://blarg:9000/openmrs. If you need to use a different port or path, you can edit the URL directly in the Advanced page in Settings.)
If you want to run the client with an OpenMRS server that you have built locally, you have three options:
- Deploy OpenMRS with your locally built server module on an Internet-accessible website; run the client on a real tablet with Internet access and set its OpenMRS base URL to point at that website
- Run OpenMRS on your own computer; assign your computer an IP address that's reachable from the tablet; run the client on a real tablet and set its OpenMRS base URL to point at your computer
- Run OpenMRS on your own computer; run the client in an Android emulator on your computer
An Android emulator runs significantly slower than a real tablet, but in terms of setup it's usually the quickest way to get a locally built client running with a locally built OpenMRS server. Using a local client and local server also enables you to do development while completely offline.
To set up an emulator with some settings that are known to work:
- In Android Studio, open Tools > Android > AVD Manager
- Click Create Virtual Device
- Click New Hardware Profile and select:
- Device Type: Phone/Tablet
- Screensize: 10.1 inches
- Resolution: 1200 x 1920 px
- Memory: RAM: 2 GB
- Input: no hardware buttons, no keyboard
- Navigation Style: None
- Supported device states: Portrait only
- Cameras: both front and back
- Sensors: all sensors (Accelerometer, Gyroscope, GPS, Proximity)
- Default Skin: No Skin
- Click OK and with your new hardware profile selected, click Next
- For System Image, choose the KitKat image with API level 19 and Target Android 4.4.2 and click OK
- Click Show Advanced Settings and select:
- Startup size and orientation:
- Scale: Auto
- Orientation: Portrait
- Camera:
- Front: None
- Back: None
- Network:
- Speed: Full
- Latency: None
- Emulated Performance:
- Host GPU: on
- Store a snapshot for faster startup: off
- Memory and Storage:
- RAM: 2 GB
- VM heap: 256 MB
- Internal Storage: 1 GB
- SD card: Studio-managed, 1 GB
- Custom skin definition: No Skin
- Keyboard:
- Enable keyboard input: turn this off for a realistic simulation (on-screen soft keyboard); turn this on for the convenience of typing with your real keyboard instead of clicking the tablet keyboard
- Startup size and orientation:
- Click Finish
The emulated tablet will not have access to the Internet, but it will see your computer at IP address 10.0.2.2, so you'll need to run an OpenMRS server on your computer and then set the client's OpenMRS base URL to http://10.0.2.2:9000/openmrs. If you edit app/build.gradle and change
def openmrsRootUrlDefault = openmrsRootUrlDev;
to
def openmrsRootUrlDefault = openmrsRootUrlLocalhost;
the client will have its server URL set to http://10.0.2.2:9000/openmrs by default.
In the field, the Buendia project uses Sony Xperia Z2 Tablets. The user interface, has thus been written assuming a tablet interface, and in particular, assuming the specific resolution and DPI of the Sony Xperia Z2.
You can determine the specific resolution / DPI of the Sony Xperia Z2 Tablet by plugging it into a computer and running the following commands (make sure you have adb set up and USB debugging turned on):
$ adb shell wm size
Physical size: 1920x1200
$ adb shell wm density
Physical density: 240
If you've got an Android phone, but not an Android tablet, it's still possible to develop the Buendia app, but it will be much easier if you fake the screen resolution of the tablet on your phone. You can do this by plugging your Android device into a computer, and running:
$ adb shell wm size 1920x1200
$ adb shell wm density 240
$ adb reboot
Note:
- You may need to use a size of
1200x1920instead of1920x1200; it depends on the default orientation of your phone screen. - It's important to reboot because most apps assume that the density (in particular) doesn't change over the life of the application.
- These settings persist through reboots.
Once you're finished developing, you probably want to be able to use your phone as normal again 😄
I suggest the following commands:
$ adb shell wm size reset
$ adb shell wm density reset
$ adb reboot
- Works on a release-build Nexus 5 running Lollipop; your mileage may vary.
If you're using Android Studio, you don't need to worry about installing SDK packages; Android Studio will take care of it for you (see Android Studio project setup above). You only need to install the packages yourself if you want to build the client from the command line.
The set of Android SDK packages needed to build the client is:
- Android SDK Platform 5.0.1 (API level 21)
- Android SDK Build-tools, revision 19.1
- Android Support Library, revision 23
- Android Support Repository, revision 17
The graphical Android SDK Manager at $ANDROID_HOME/tools/android will let you select and install these packages interactively; or you can install them all with the command:
$ANDROID_HOME/tools/android update sdk --no-ui --all --filter android-21,build-tools-19.1.0,extra-android-support,extras-android-m2repository,platform-tools
ANDROID_HOME is usually /opt/android-sdk-linux on a Linux machine and ~/Library/Android/sdk on a Mac.
To build the client from the command line, go to the root of your client repo and run ./gradlew clean assembleDebug. The resulting apk will be at app/build/outputs/apk/app-debug.apk.
sudo apt-get install openjdk-8-jdk unzip git
mkdir -p ~/.android && touch ~/.android/repositories.cfg
mkdir android && cd android
wget https://dl.google.com/android/repository/sdk-tools-linux-4333796.zip
unzip sdk-tools-linux-4333796.zip
export PATH=$HOME/android/tools:$HOME/android/tools/bin:$PATH
export ANDROID_HOME=$HOME/android
yes | sdkmanager --licenses
sdkmanager "platforms;android-21" "build-tools;19.1.0" "extras;android;m2repository" "platform-tools"
cd ../client/
git submodule update --init client-libs
./gradlew assembleDebug
ls app/build/outputs/apk/debug/
# ./gradlew -PversionNumber=0.10.0 clean assembleDebug
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent