Skip to end of metadata
Go to start of metadata

This is an easy step-by-step guide to setup the environment for development of mUzima fingerprint module on Mac OS. Please feel free to update as necessary (smile). Let us get started with the setup.

Step 1: Install Java 7

  1. Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download Java Platform (JDK)
  2. Follow the detail instructions from http://www.java.com/en/download/help/mac_install.xml and install Java on your Mac
  3. Configure JAVA_HOME variable. One way to configure,
    •  Open terminal and run the following commands

      $ touch .bash_profile //for creating a bash profile file
      $ open -a TextEdit.app .bash_profile //to open the bash profile file created
    • It opens the .bash_profile in text editor

    • Write the following configuration in it

      export JAVA_HOME=$(/usr/libexec/java_home)
    • To apply these changes to the current terminal, run

      $ source .bash_profile
  4. Test whether Java is installed properly. To test,

    • Open terminal and run the following command

      $ java -version
    • It should print something similar to this

      java version "1.7.0_79"
      Java(TM) SE Runtime Environment (build 1.7.0_79-b15)
      Java HotSpot(TM) 64-Bit Server VM (build 24.79-b02, mixed mode)

Step 2: Install Apache Maven 3.3.3 or latest

  1. Go to http://maven.apache.org/download.cgi and download apache-maven-3.3.3-bin.tar.gz
  2. Extract the archive apache-maven-3.3.3-bin.tar.gz to /usr/local/apache-maven or any directory you wish to install Maven 3.3.3
  3. The subdirectory apache-maven-3.3.3 will be created from the archive
  4. Configure M2_HOME variable. One way to configure,
    •  Open the bash profile file that we already created while installing Java and add the following configurations to it

      export M2_HOME=/usr/local/apache-maven/apache-maven-3.3.3
      export PATH=${M2_HOME}/bin:$PATH
    • Apply changes to the current terminal as described above while installing Java
  5. Test whether maven is correctly installed. To test,
    •  Open terminal and run the following command

      $ mvn -version
    • It should print something similar to this

      Apache Maven 3.3.3 (7994120775791599e205a5524ec3e0dfe41d4a06; 2015-04-22T07:57:37-04:00)
      Maven home: /usr/local/apache-maven/apache-maven-3.3.3
      Java version: 1.7.0_79, vendor: Oracle Corporation
      Java home: /Library/Java/JavaVirtualMachines/jdk1.7.0_79.jdk/Contents/Home/jre
      Default locale: en_US, platform encoding: UTF-8
      OS name: "mac os x", version: "10.10.3", arch: "x86_64", family: "mac"

Step 3: Install MySQL

  1. Go to https://dev.mysql.com/downloads/mysql/ and download MySQL Community Server DMG Archive for your respective OS version
  2. Double click on the .dmg file to start installation
  3. Follow the installation steps from https://dev.mysql.com/doc/refman/5.1/en/osx-installation-prefpane.html
  4. Setup a MySQL root user password. To setup,
    • Go to System Preferences Pane and click on MySQL
    • Start the MySQL Server instance
    • Open the terminal and navigate to /usr/local/mysql/bin or the location that contains MySQL binaries and run 

       $ ./mysqladmin -u root password 'YourPassword'

Step 4: Install Android 8,17 and 18

  1. Go to http://developer.android.com/sdk/installing/index.html and select Stand-alone SDK Tools
  2. Download the SDK and unzip the file- android-sdk_r24.2-macosx.zip
  3. The directory named android-sdk_r24.2-macosx is created by default
  4. Move it to /usr/local/ or any directory you wish to install android SDK
  5. Add the SDK packages 8, 17, and 18. To add,
    •  Open the terminal and navigate to the tools/ directory in the location where the Android SDK was installed and run 

       $ android sdk
    • This will open the Android SDK Manager
    • By default several packages are selected. Leave them selected and select the desired packages i.e. API 8, 17 and 18. (The project is developed using Android 18 but is tested out on three of these platforms.)
    • Click Install X packages at the bottom


    • In the next window, click on each package name on the left, accept the license agreement for each and click Install


    • The download progress is shown at the bottom of the SDK Manager window
    • Do not exit the SDK Manager or it will cancel the download
  6. Configure ANDROID_HOME variable. One way to configure,
    •  Open the bash profile file that we already created while installing Java and add the following configurations to it

      export ANDROID_HOME=/usr/local/android-sdk_r24.2-macosx
      export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools
    • Apply the changes to the current terminal as described above while installing Java and Maven
  7. Test whether Android sdk is correctly installed. To test,
    • Open terminal and run the following command

      $ adb
    • It should print something similar to this

       Android Debug Bridge version 1.0.32
       
      
       -a - directs adb to listen on all interfaces for a connection
       -d - directs command to the only connected USB device
       returns an error if more than one USB device is present.
       -e - directs command to the only running emulator.
       returns an error if more than one emulator is running.
       -s <specific device> - directs command to the device or emulator with the given
       serial number or qualifier. Overrides ANDROID_SERIAL
       environment variable.
       -p <product name or path> - simple product name like 'sooner', or
       a relative/absolute path to a product
       out directory like 'out/target/product/sooner'.
       If -p is not specified, the ANDROID_PRODUCT_OUT
       environment variable is used, which must
       be an absolute path.
       -H - Name of adb server host (default: localhost)
       -P - Port of adb server (default: 5037)
       devices [-l] - list all connected devices
       ('-l' will also list device qualifiers)
       connect <host>[:<port>] - connect to a device via TCP/IP
       Port 5555 is used by default if no port number is specified.
       disconnect [<host>[:<port>]] - disconnect from a TCP/IP device.
       Port 5555 is used by default if no port number is specified.
       Using this command with no additional arguments
       will disconnect from all connected TCP/IP devices.
       
      
       device commands:
       adb push [-p] <local> <remote>
       - copy file/dir to device
       ('-p' to display the transfer progress)
       adb pull [-p] [-a] <remote> [<local>]
       - copy file/dir from device
       ('-p' to display the transfer progress)
       ('-a' means copy timestamp and mode)
       adb sync [ <directory> ] - copy host->device only if changed
       (-l means list but don't copy)
       (see 'adb help all')
       adb shell - run remote shell interactively
       adb shell <command> - run remote shell command
       adb emu <command> - run emulator console command
       adb logcat [ <filter-spec> ] - View device log
       adb forward --list - list all forward socket connections.
       the format is a list of lines with the following format:
       <serial> " " <local> " " <remote> "\n"
       adb forward <local> <remote> - forward socket connections
       forward specs are one of: 
       tcp:<port>
       localabstract:<unix domain socket name>
       localreserved:<unix domain socket name>
       localfilesystem:<unix domain socket name>
       dev:<character device name>
       jdwp:<process pid> (remote only)
       adb forward --no-rebind <local> <remote>
       - same as 'adb forward <local> <remote>' but fails
       if <local> is already forwarded
       adb forward --remove <local> - remove a specific forward socket connection
       adb forward --remove-all - remove all forward socket connections
       adb reverse --list - list all reverse socket connections from device
       adb reverse <remote> <local> - reverse socket connections
       reverse specs are one of:
       tcp:<port>
       localabstract:<unix domain socket name>
       localreserved:<unix domain socket name>
       localfilesystem:<unix domain socket name>
       adb reverse --norebind <remote> <local>
       - same as 'adb reverse <remote> <local>' but fails
       if <remote> is already reversed.
       adb reverse --remove <remote>
       - remove a specific reversed socket connection
       adb reverse --remove-all - remove all reversed socket connections from device
       adb jdwp - list PIDs of processes hosting a JDWP transport
       adb install [-lrtsd] <file>
       adb install-multiple [-lrtsdp] <file...>
       - push this package file to the device and install it
       (-l: forward lock application)
       (-r: replace existing application)
       (-t: allow test packages)
       (-s: install application on sdcard)
       (-d: allow version code downgrade)
       (-p: partial application install)
       adb uninstall [-k] <package> - remove this app package from the device
       ('-k' means keep the data and cache directories)
       adb bugreport - return all information from the device
       that should be included in a bug report.
       
      
       adb backup [-f <file>] [-apk|-noapk] [-obb|-noobb] [-shared|-noshared] [-all] [-system|-nosystem] [<packages...>]
       - write an archive of the device's data to <file>.
       If no -f option is supplied then the data is written
       to "backup.ab" in the current directory.
       (-apk|-noapk enable/disable backup of the .apks themselves
       in the archive; the default is noapk.)
       (-obb|-noobb enable/disable backup of any installed apk expansion
       (aka .obb) files associated with each application; the default
       is noobb.)
       (-shared|-noshared enable/disable backup of the device's
       shared storage / SD card contents; the default is noshared.)
       (-all means to back up all installed applications)
       (-system|-nosystem toggles whether -all automatically includes
       system applications; the default is to include system apps)
       (<packages...> is the list of applications to be backed up. If
       the -all or -shared flags are passed, then the package
       list is optional. Applications explicitly given on the
       command line will be included even if -nosystem would
       ordinarily cause them to be omitted.)
       
      
       adb restore <file> - restore device contents from the <file> backup archive
       
      
       adb disable-verity - disable dm-verity checking on USERDEBUG builds
       adb keygen <file> - generate adb public/private key. The private key is stored in <file>,
       and the public key is stored in <file>.pub. Any existing files
       are overwritten.
       adb help - show this help message
       adb version - show version num
       
      
       scripting:
       adb wait-for-device - block until device is online
       adb start-server - ensure that there is a server running
       adb kill-server - kill the server if it is running
       adb get-state - prints: offline | bootloader | device
       adb get-serialno - prints: <serial-number>
       adb get-devpath - prints: <device-path>
       adb status-window - continuously print device status for a specified device
       adb remount - remounts the /system and /vendor (if present) partitions on the device read-write
       adb reboot [bootloader|recovery] - reboots the device, optionally into the bootloader or recovery program
       adb reboot-bootloader - reboots the device into the bootloader
       adb root - restarts the adbd daemon with root permissions
       adb usb - restarts the adbd daemon listening on USB
       adb tcpip <port> - restarts the adbd daemon listening on TCP on the specified port
       networking:
       adb ppp <tty> [parameters] - Run PPP over USB.
       Note: you should not automatically start a PPP connection.
       <tty> refers to the tty for PPP stream. Eg. dev:/dev/omap_csmi_tty1
       [parameters] - Eg. defaultroute debug dump local notty usepeerdns
       
      
       adb sync notes: adb sync [ <directory> ]
       <localdir> can be interpreted in several ways:
       
      
       - If <directory> is not specified, /system, /vendor (if present), and /data partitions will be updated.
       
      
       - If it is "system", "vendor" or "data", only the corresponding partition
       is updated.
       
      
       environmental variables:
       ADB_TRACE - Print debug information. A comma separated list of the following values
       1 or all, adb, sockets, packets, rwx, usb, sync, sysdeps, transport, jdwp
       ANDROID_SERIAL - The serial number to connect to. -s takes priority over this if given.
       ANDROID_LOG_TAGS - When used with the logcat option, only these debug tags are printed.

Step 5: Install OpenMRS Standalone

Download the latest OpenMRS Standalone and follow the installation instructions from https://wiki.openmrs.org/display/docs/OpenMRS+Standalone

Step 6: Install Genymotion

  1. Go to https://www.genymotion.com/#!/download and download genymotion after creating your genymotion account when prompted
  2. Go to https://www.virtualbox.org/wiki/Downloads and download the VirtualBox platform package for your OS
  3. Install VirtualBox. To install,
    • Double-click on the downloaded VirtualBox-4.3.28-100309-OSX.dmg file
    • In the new window, double-click on the VirtualBox.pkg to install
    • Reboot after installation
  4. Install Genymotion. To install,
    • Double-click on the downloaded genymotion-2.4.0.dmg file
    • In the new window, drag and drop Genymotion and Genymotion Shell to the Applications directory

Step 7: Obtain a GitHub ID

Sign up for a GitHub account to work on the projects

Step 8: Install GitHub for Mac OS

  1. Go to https://mac.github.com/ and download GitHub for Mac
  2. To install, unzip the downloaded file and move the GitHub application to Applications or desired directory

Step 9: Get the mUzima projects’ repositories

  1. Go to https://github.com/muzima after you log in with your GitHub ID
  2. Search for the following repositories under muzima and click to open them
    • muzima-android 
    • openmrs-module-fingerprint
    • openmrs-module-muzima
    • openmrs-module-muzimaconsultation
    • openmrs-module-muzimaforms 
    • openmrs-module-muzimaregistration
  3. Fork a copy of them to your account. To fork,
    • Click on the Fork button on the top-right of the page


  4. Clone these repositories from your account into your machine to have a sinkable local copy. One way to clone,
    • Launch the GitHub Application that we have already installed in Applications directory
    • Find and click on the “+” button on the top left corner of the window


    • Click on clone to find the repositories that you have forked and clone them at desired directory

Step 10: Build projects

  1. To generate the .omod files (openmrs modules) we need to build the projects that we have cloned. One way to build,
    • Open terminal and navigate to the project location and run the following command

      $ mvn clean install
  2. You can locate the generated .omod/.apk in the target folder. For instance
    • /muzima-android/target/muzima-android-1.0-SNAPSHOT.apk
    • /openmrs-module-fingerprint/omod/target/muzimafingerPrint-1.0-SNAPSHOT.omod

Step 11: Download the required modules for muzima

  1. Go to https://modules.openmrs.org/#/search
  2. Search and download the following omods
    • Latest xforms
    • Latest Rest Web Services

Step 12: Install modules into OpenMRS Standalone

  1. Lauch the openmrs standalone and log in
  2. Click on Administration tab


  3. Find and click on Manage Modules under Modules section


  4. Click on Add or upgrade module button and add all the modules to install them into OpenMRS along with the downloaded omods (xforms and rest web services)

Step 13: Update Java settings

  1. Go to System Preferences and launch Java Control Panel
  2. Click on the Advanced tab and make the following changes
    • Debugging: Check all the three i.e. Enable tracing, Enable logging and Show applet lifecycle exceptions
    • Java Console: Choose Show console
    • JNLP File/MIME Association: Choose Always allow
    • Secure Execution Environment: Check Allow user to accept JNLP security requests


  3. Click on the Security tab and make following changes

    • Find the Exception Site List section and click on Edit site list


    • In the new window, click on the Add button at the bottom right
    • Add your site, i.e., http://localhost:8081/ or similar


    • This allows the browser to run the applet

Step 14: Install the fingerprint SDK

  1. Go to http://download.neurotechnology.com/Neurotec_Biometric_5_1_SDK_Trial_2015-06-09.zip and download the fingerprint SDK
  2. Unzip the file into desired directory and subdirectory Neurotec_Biometric_5_1_SDK_Trial is created by default
  3. To install the fingerprint SDK, locate the NeurotecBiometricTrial.pkg inside the Neurotec_Biometric_5_1_SDK_Trial directory and double-click on it
  4. Open terminal and navigate to /Neurotec_Biometric_5_1_SDK_Trial/Bin/MacOSX_universal/Activation location
    • Run the following command

      $ sudo ./run_pgd.sh start  //make sure it is started before you use the application
  5. Enter the system password when prompted
  6. If installed 
    • It should print something like this
       

      run_pgd.sh: starting pgd...
      run_pgd.sh: pgd run log (/Library/Logs/pgd.log):
      ----------------------------------------
      2015-05-28 13:17:46 Starting PG (revision: 124780, mode: single, trial)		
      2015-05-28 13:17:46 Darwin IN-REGI-4572 14.3.0 Darwin Kernel Version 14.3.0: Mon Mar 23 11:59:05 PDT 2015; root:xnu-2782.20.48~5/RELEASE_X86_64 x86_64		
      2015-05-28 13:17:46 PG started (pid: 5840).
      ----------------------------------------

Step 15: Launch the fingerprint module

  1. Open and log into openmrs standalone
  2. Click on Administration tab
  3. Locate and click on Manage fingerPrint under Muzima fingerPrint section


  4. This will launch the fingerPrint module
  5. Make sure plug-ins are not blocked and you always allow them to run the applet

TROUBLESHOOTING

1. If you want to stop the Neurotec_Biometric_5_1_SDK_Trial license activation 

  •  Open terminal, navigate to /Neurotec_Biometric_5_1_SDK_Trial/Bin/MacOSX_universal/Activation location and run the following command

    $ sudo ./run_pgd.sh stop

2. If build failed

Failed to execute goal on project muzimafingerPrint-fingerprint: Could not resolve dependencies for project org.openmrs.module:muzimafingerPrint-fingerprint:jar:1.0-SNAPSHOT: The following artifacts could not be resolved: com.neurotec:neurotec-core:jar:5.1.0.0, com.neurotec:neurotec-gui:jar:5.1.0.0: Could not find artifact com.neurotec:neurotec-core:jar:5.1.0.0 in openmrs-repo (http://mavenrepo.openmrs.org/nexus/content/repositories/public) -> [Help 1]
  • For instance consider com.neurotec:neurotec-core:jar:5.1.0.0
    • com.neurotec --> groupId
    • neurotec-core --> artifactId
    • 5.1.0 --> version
    • jar --> packaging
  • Install the jar files locally in your machine. One way to install,
    • Go to the jar folder in the terminal and run the following command or similar

      mvn install:install-file -Dfile=neurotec-core.jar -DgroupId=com.neurotec -DartifactId=neurotec-core -Dversion=5.1.0.0 -Dpackaging=jar

3. If you want to end a running java applet

  • Go to System Preferences and launch Java Control Panel
  • Click on General tab
  • Locate the Temporary internet files section and click on view button below it


  • Select the applet you want to remove and click on “X” symbol to remove it


4. If error is about neurotec component licenses not obtained 

  • Start the Neurotec_Biometric_5_1_SDK_Trial license activation. To start,
    • Open terminal, navigate to /Neurotec_Biometric_5_1_SDK_Trial/Bin/MacOSX_universal/Activation location and run the following command

      $ sudo ./run_pgd.sh start