# Poynt PST3 Emulator Setup

# MacOS Instructions

To help you speed up the development and testing processes, we have created a developer edition of PoyntOS that you can execute on an Android emulator. Certain functionalities, such as collecting customer input from a second screen and card payment handling, will not be available. However, the emulator is designed to provide you with enough tools to start building and testing your applications.

With this emulator, you will have access to dynamic and high-performing features, including the following:

  • Catalog-driven POS App
  • Transaction Data
  • Customer Data
  • Terminal Application

Whenever possible, we strongly recommend getting the complete Developer Kit through your developer portal, which will allow you to test your components thoroughly and enjoy many other development features.

Additionally, activating the PoyntOS virtual device on a device emulator is very similar to activating a physical Poynt Smart Terminal, which will facilitate the process. Let's get started!

TIP

Depending on your device, you can select the setup instructions for macOS or Windows.

# Prerequisites

  • Mac OSX 10.14+
  • 8GB RAM and 8GB disk space
  • Android SDK with API level 29 (Android 10)
  • Android SDK Command-line Tools
  • Java JDK
  • Python (for installation scripts)

Note

Please keep in mind that this emulator does not support macOS M1.

# Accessing the terminal

To begin the installation process for the Poynt C emulator in macOS, you must open a terminal window by searching and selecting the Terminal.app on your computer.

terminal app

The following steps will require you to execute a series of commands in the Terminal. Make sure to verify the tools you have already installed or follow the instructions to install the new ones.

# Setting up Android SDK

All Poynt emulators are Android-based; for this reason, they require Android SDK to run correctly.

Note

If you are an Android software developer and have already installed Android SDK, you may skip this step. If you haven’t, or you are unsure, please follow the instructions below.

  1. Download and install the latest version of Android SDK using Android Studio's official documentation (opens new window).

  2. Take note of the installation path for Android SDK. The environment variable for this tool will require further configuration.

    • On macOS devices, the path will look similar to this: ~/Library/Android/sdk.
  3. Verify the installation path by listing the folders and files under it. You can complete the verification by executing the ls -la ~/Library/Android/sdk command on the terminal. The outcome should look similar to the image below.

androidsdk

WARNING!

Do not continue if the path does not exist or appears empty unless you are sure you will be using a different Android SDK path.

# Setting up Java

Note

If you have already installed JDK, you may skip this step. If you haven’t, or you are unsure, please follow the instructions below.

Apple does not natively support Java. However, there are several unofficial JDKs out there. In this case, we will be using OpenJDK v8 as an example.

  1. Follow the link to download AdoptOpenJDK v8. (opens new window)

  2. Install the downloaded OpenJDK8U-jdk_x64_mac_hotspot_8u312b07.pkg file.

  3. Take note of the installation path for JDK. For macOS devices, the path should look similar to this: /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home.

    Note: The path shown above starts from root, instead of /Users/<username>.

  4. Verify the installation path by executing the following command on the terminal: ls -la /Library/Java/JavaVirtualMachines/temurin-8.jdk/Contents/Home. The outcome should look similar to the image below.

jdk

WARNING!

There should be a series of folders and files under this path. Do not continue if the path does not exist or appears empty unless you are sure you will be using a different JDK path.

# Configuring the environment variables

The environment variables are in charge of storing information about the system for applications to run smoothly. In this case, they contain the paths to Android SDK, JDK, and the Poynt emulator information. If these paths are not properly configured, the Poynt emulator installation script will not execute correctly.

ANDROID_HOME contains the path to Android SDK and JAVA_HOME contains the path to JDK.

These two environment variables and other emulator-specific variables will need to be placed in the Terminal init script.

TIP

Newer macOS versions will be using “zsh” by default. Older versions may be using bash. You can usually tell which one you are using by looking at the terminal’s window bar.

zsh

For zsh, the init file is located at ~/.zshrc, and for bash, the the location is ~/.bashrc.

Below, we will be using .zsh as an example.

  1. Make sure the ~/.zshrc location exists by “touching” the file using the command touch ~/.zshrc

  2. Open the ~/.zshrcfile with Mac’s default text editor or any other text editor using the command open -e ~/.zshrc

  3. Add the following lines to the bottom of the file and follow the configuration steps outlined in the table below to set the variables.

export JAVA_HOME="/Library/Java/JavaVirtualMachines/temurin- 8.jdk/Contents/Home"
export PATH=$JAVA_HOME/bin:$PATH

export ANDROID_HOME=/Users/$USER/Library/Android/sdk
export PATH=$ANDROID_HOME/tools/bin:$ANDROID_HOME/platform-tools:$PATH

# Poynt C emulator
export EMULATOR_REPO_PATH=https://poynt-emulator.s3.us-west-1.amazonaws.com/custom-emulator/android10
export EMULATOR_SERIAL=P6EMUA<put-8-random-digits-here>	# put digits
export OUT_DIR=/Users/$USER # the Poynt emulator will be placed here
export EMULATOR_NAME=Poynt_PST3

Note

Please make sure that the environment variables $PATH and $USER are already configured.

Variable Name Configuration
JAVA_HOME Change it to the JDK installation path.
ANDROID_HOME Change it to the Android SDK installation path.
PATH These variables do not require changes. These lines add JAVA_HOME and ANDROID_HOME to your existing PATH so that all Java command line tools are available to you regardless of the path.
EMULATOR_REPO_PATH This variable does not require changes. This line tells the Poynt installation script the location to download the emulator image.
EMULATOR_SERIAL Replace "put-8-random-digits-here" with 8 random digits. This will be the terminal ID for your emulator.
OUT_DIR This variable does not require changes. This line tells the Poynt installation script which directory it should use to save the emulator image.
EMULATOR_NAME This variable does not require changes. This is the name of your emulator. You should only change it if you have more than one Poynt C emulator.
  1. Save the file and close the existing terminal window.

  2. Open a new terminal window to allow the values to take effect.

  3. Confirm that the environment variables are being used in your new terminal session by displaying their values using the following commands:

echo $JAVA_HOME
echo $ANDROID_HOME
echo $EMULATOR_REPO_PATH
echo $EMULATOR_SERIAL
echo $OUT_DIR
echo $EMULATOR_NAME

The output should be similar to the image below.

env vars

# Creating a Virtual Device

  1. Open the AVD Manager in Android Studio.
Virtual Device 1
  1. Click on Create device to set up a new device.
Virtual Device 2
  1. Select the device definition of your choice and click on New Hardware Profile.
Virtual Device 3
  1. Complete the Hardware Configuration to fit your requirements and click on Finish to exit the window. Once you go back to the Device Definition window, click on next to continue
Virtual Device 6
  1. Select and download the API level 29 for your System Image.
Virtual Device 4
  1. After the download is complete, you must click on Next and Finish to create the device.
Virtual Device 7

NOTE

Please remember to use the same name as the EMULATOR_NAME variable.

  1. Once you come back to the initial page, you should see the new virtual device. You can click on it to begin the launch process.
Virtual Device 8

NOTE

Please remember to keep the Virtual Device Manager tab open while you are installing and starting the emulator using the corresponding scripts

# Installing the Poynt emulator

For macOS or Linux, please follow the link to download the install-poynt-emulator.sh (opens new window) and execute it in the terminal from the directory of the file using sh install-poynt-emulator.sh.

This script should take a while to execute. When it completes, the output will look similar to the image below.

emulator

# Starting the Poynt emulator

If the command line install-poynt-emulator.sh was executed correctly, you can start the emulator by running the generated script start-poynt-emulator.sh from the path you specified in $OUT_DIR:

After executing the command, a welcome screen will be displayed and the Poynt emulator will become operational.

emulator start

Great job! You have successfully installed the Poynt C Emulator.

TIP

To learn more about the configuration process, please refer to the Activation section in the official documentation.

Last Updated: 7/29/2022, 12:49:22 PM