Development Environment

You only need to follow these instructions if you wish to modify the mobile apps. I've provided the source code that you can modify and improve as you wish, and then deploy it to your own phone or tablet without needing a paid developer account to the mobile app stores.

To be able to build and deploy the app, you need to have the appropriate development environment setup. This page outlines how to setup this environment from scratch, assuming that none of the requirements have been previously installed.

Where possible I accept the default values. This may result in options that we don't need being installed, but I prefer to have a "standard" environment setup where possible.

To setup the environment to modify the sketch, please see the Arduino section of the install page.


The following instructions were tested on Mac OS X 10.11 El CapitanWindows 10.

Ionic Platform

The app is created using version 1 of the Ionic Framework. Ionic allows for the creation of "hybrid" applications that can be run on multiple platforms from a single code base of HTML 5, CSS and Javascript. Ionic leverages Cordova to support this code reuse across platforms, and the NodeJS javascript runtime environment.

To install Ionic, I followed the steps as outlined on the Ionic Getting Started page (and added a step for xml2js). I've listed the steps out below, but if you run into problems, follow the advice of that page.

Instal Node.js

At the time of writing, Node.js v4.x.x is supported by Ionic, whereas the newer v5.x.x is not. As such we will install the version 4 LTS (Long Term Support) edition of Node.js.

Visit the NodeJS homepage, and download the latest version 4 LTS edition that is appropriate for your platform. For this example it was v4.2.6 LTS

  1. Run the installer that was downloaded
    1. Click "Continue" on the "Introduction" screen
    2. Click "Continue" on the "License" screen
    3. Click "Agree" to accept the license agreement
    4. The standard install is ok, so just click "Install" on the "Installation Type" screen
    5. Enter the "Username" and "Password" of an administrator on the computer, and then click "Install Software"
    6. Click "Close" at the "Summary" screen
  1. Run the installer that was downloaded
    1. Click "Next" on the setup wizard welcome page
    2. Click "I accept the terms in the License Agreement" checkbox
    3. Click "Next"
    4. Accept the default install location and click "Next"
    5. Accept the defaults in the "Custom Setup", and click "Next"
    6. Click "Install"
    7. Click "Yes" to allow this the "User Account Control" "Do you want to allow this app to install software on your PC?" dialog
    8. Click "Finish"

Node.js should now be installed.

Instal Cordova

To install Cordova, we use npm via the command line. npm was installed as part of the Node.js installation.

Information on Cordova can be found on it's website.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run sudo npm install -g cordova
  3. Enter your administrator password when prompted
  1. Start "Command Prompt" hitting "Windows" + "R" keys, then typing cmd
  2. Run npm install -g cordova

Cordova should now be installed.

Install Ionic

To install Ionic, we use npm via the command line. npm was installed as part of the Node.js installation.

Information on Cordova can be found on it's website.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run sudo npm install -g ionic
  3. Enter your administrator password when prompted
  4. Run ionic
  5. You will be prompted to say that "xcodebuild" command requires the command line developer tools. Click "Install" to install these tools
  6. Click "Agree" to the license agreement
  1. Start "Command Prompt" hitting "Windows" + "R" keys, then typing cmd
  2. Run npm install -g ionic

Ionic should now be installed.

Install XML2JS

To install xml2js, we use npm via the command line. npm was installed as part of the Node.js installation.

xml2js is used to allow a build script within the BlueCube project to modify the config.xml file.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run sudo npm install -g xml2js
  3. Enter your administrator password when prompted
  1. Start "Command Prompt" hitting "Windows" + "R" keys, then typing cmd
  2. Run npm install -g xml2js

xml2js should now be installed.

iOS Support

iOS support requires a Mac. While there are some workaround, I only provide instructions for use with a Mac.

To be able to build and deploy iOS applications, you need to install additional components. If you don't plan on building the iOS version of BlueCube, you can skip this section. I've installed the items mentioned on the Cordova iOS Platform Guide. If you encounter any problems please refer to this link.

Install Xcode

Xcode is Apple's Integrated Development Environment (IDE) for iOS Development.

  1. Visit the XCode page within the Mac App Store
  2. Click on "Get"
  3. Click on "Install App"
  4. If prompted, enter your AppleID and password, then click "Sign In"
  5. If two factor authentication is on, select the device to verify your identity and click "Continue"
    1. Enter the verification code

Xcode will now download into your "Applications" folder. Please note that depending on your connection speed this may take a little while.

  1. Once Downloaded, launch Xcode via "Applications" "Xcode"
  2. Agree to the "Xcode and iOS SDK License Agreement"
  3. Enter your administrator "Username" and "Password" then click "OK"

Xcode is now installed

Install iOS-Sim

iOS-Sim allows you to work with the iOS Emulator from the Cordova / Ionic command line tools.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run sudo npm install -g ios-sim
  3. Enter your administrator password when prompted

iOS-Sim is now installed

Install iOS-Deploy

iOS-Deploy allows you to work with the iOS devices from the Cordova / Ionic command line tools.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run sudo npm install -g ios-deploy --unsafe-perm=true --allow-root
  3. Enter your administrator password when prompted

iOS-Deploy is now installed

Android Support

To be able to build and deploy Android applications, you need to install additional components. If you don't plan on building the Android version of BlueCube, you can skip this section. I've installed the items mentioned on the Cordova Android Platform Guide. If you encounter any problems please refer to this link.

Java Development Kit

Android applications are written in the Java programming language, and as such require the Java Development Kit (JDK) installed (please note that this is different then the typically installed Java Runtime Environment (JRE)).

  1. Visit the Java Development Kit website
  2. Accept the license agreement
  3. Download the Mac OS X x64 installer
  4. Run the downloaded installer
    1. Click "Continue" on the "Introduction" screen
    2. Click "Install" on the "Installation Type" screen
    3. Enter the "Username" and "Password" of an administrator on the computer, and then click "Install Software"
    4. Click "Close" on the "Summary" screen
  1. Visit the Java Development Kit website
  2. Accept the licence agreement
  3. Download the appropriate installer (Windows x86 or Windows x64)
  4. Run the downloaded installer
    1. Click "Yes" to allow this the "User Account Control" "Do you want to allow this app to install software on your PC?" dialog
    2. Click "Next" to start the install wizard
    3. The default install options are fine, so click "Next"
    4. The default install location is fine, so click "Next"
    5. Click "Close"

The Java Development Kit is now installed, however we need to add an environment variable to it's location. To do that:-

  1. Click on the "Start" menu
  2. Type "Environment"
  3. Click on "Edit the system environment variables"
  4. Click on "Environment Variables..." on the "Advanced" tab of the "System Properties" window that opened
  5. Click "New..."
    1. Variable Name: JAVA_HOME
    2. Variable Value: C:\Program Files\Java\jdk1.7.079
      1. It's best to click "Browse Directory..." and find where the JDK was installed, as the location maybe different then the one I have specified
  6. Click "OK" to set the new variable
  7. Click "OK" to close the "Environment Variables"
  8. Click "OK" to close "System Properties"

Android Studio

Android Studio is Google's Integrated Development Environment (IDE) for Android development.

  1. Download Android Studio from here
  2. Accept Licence Agreement and Download
  3. Open the downloaded disk image
  4. Drag Android Studio into the "Applications" folder
  5. Run "Android Studio" from the "Applications" folder
  6. When prompted, click "Open" to allow Android Studio to run as it was downloaded from the internet
  7. On the "Complete Installation" screen, select "I do not have a previous version of Studio or I do not want to import my settings"
  8. Click "Next" on the welcome screen
  9. Ensure "Standard" is selected on the "Install Type" screen and click "Next"
  10. Verify the selected settings and click "Finish", taking note of the "Destination Folder"

The installer will now download additional items that are required. This may take a while.

  1. Click "Finish" when the install is complete. If the "HAXM" installation fails, don't worry about it. "HAXM" is used for speeding up the emulator, but we don't use the emulator for this app

Android Studio is now running

  1. Quit Android Studio

We need to add the location of the Android tools to the PATH environment variable so that Cordova / Ionic can use them. To do this:-

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run pico -w ~/.bash_profile
  3. Add export PATH=${PATH}:/Users/<user>/Library/Android/sdk/platform-tools:/Users/<user>/Library/Android/sdk/tools to the file
    1. If you didn't change the install path, then the above will just need you to replace <user> with your short user name (the value before the $ sign in terminal). If you changed the install location, use the location that was specified in "Destination Folder" during step 10, replacing the text upto platform-tools and tools
  4. Hit Ctrl+O then enter key to save the file
  5. Hit Ctrl+X to exit
  6. Run source ~/.bash_profile
  1. Download Android Studio from here
  2. Accept Licence Agreement and Download
  3. Run the downloaded installer
  4. Click "Yes" to allow this the "User Account Control" "Do you want to allow this app to install software on your PC?" dialog
  5. Click "Next" on the "Welcome" screen
  6. The default components are fine, so click "Next"
  7. Click "I Agree" to the licence agreement
  8. The default install locations are ok, so click "Next" (take note of the Android SDK Installation Location)
  9. The default emulator setup settings are ok, so click "Next"
  10. The default start menu folder is ok, so click "Install", and wait for it to finish
  11. Click "Next" once the installation is complete
  12. ----Uptick "Start Android Studio" and then click "Finish"
  13. XXXStart the app, and don't import
  14. XXXAllow access for Android Studio if asked by the windows firewall

We need to add the location of the Android tools to the PATH environment variable so that Cordova / Ionic can use them. To do this:-

  1. Click on the "Start" menu
  2. Type "Path"
  3. Click on "Edit the system environment variables"
  4. Click on "Environment Variables..." on the "Advanced" tab of the "System Properties" window that opened
  5. Click "New..."
    1. Variable Name: ANDROID_HOME
    2. Variable Value: C:\Android\sdk
      1. It's best to click "Browse Directory..." and find where the Android SDK was installed. using the location that was specified in "Android SDK Installation Location" during step 8
  6. Select "PATH" and click "Edit..."
  7. Add ;%ANDROID_HOME%\platform-tools;%ANDROID_HOME%\tools to the end of what is already there
  8. Click "OK" to set the PATH variable
  9. Click "OK" to close the "Environment Variables"
  10. Click "OK" to close "System Properties"

Android SDK

The Android SDK contains the required components to develop Android applications against particular API's (Android versions).

  1. Start "Terminal" from "Applications" "Utilities"
  2. Run android
    1. When the "Android SDK Manager" loads, it will check for any updates, and most likely find some. This is ok. We will install these updates in addition to the items we require
  3. Expand "Android 5.1.1 (API 22)"
  4. Click the check box next to "SDK Platform" under "Android 5.1.1 (API 22)"
  5. Click "Install # Packages" to install that package and any updates that are available
  6. Select a package on the left, then click "Accept License" on the right &
  7. Click "Install"
  1. Start "Command Prompt" hitting "Windows" + "R" keys, then typing cmd
  2. Run android
    1. When the "Android SDK Manager" loads, it will check for any updates, and most likely find some. This is ok. We will install these updates in addition to the items we require
  3. Expand "Android 5.1.1 (API 22)"
  4. Click the check box next to "SDK Platform" under "Android 5.1.1 (API 22)"
  5. Click "Install # Packages" to install any updates that are available
  6. Select a package on the left, then click "Accept License" on the right
  7. Click "Install"

Build & Deploy

Change Project ID

The project has a given ID of "ninja.secretcode.BlueCube". This ID needs to be unique for each developer that builds the apps. This change needs to be completed every time you download a new version of BlueCube (you can reuse the ID you choose for each subsequent version). To edit it:-

  1. Browse to "BlueCube" "IonicApp"
  2. Edit config.xml in the text editor of your choise
  3. On the second line where it says id=ninja.secretcode.BlueCube change it so that it is unique to you. Normally the name ID is in reverse DNS format, so if you own "fredsautos.com", the ID would be id=com.fredsautos.BlueCube. Otherwise just add a random number to the end of "BlueCube", without any spaces or punctuation. If in doubt, add the machines MAC address at the end. On OS X run ifconfig en0 ether | grep ether | awk '{ print $2 }' | sed s/\://g
  4. Save the file and quit the text editor
  5. Start Terminal "Applications" "Utilities" "Terminal"
  6. Change to the BlueCube folder by cd and dragging the "IonicApp" ("BlueCube" "IonicApp") folder onto the terminal window, then hitting "Enter". For example, I have the BlueCube folder on my desktop, and my username is adam. In this case the command was cd /Users/adam/Desktop/BlueCube/IonicApp
  7. Remove the previously configured platforms
    1. ionic platform rm ios
    2. ionic platform rm android
  8. Re-add the iOS platform if you wish to build the iOS app
    1. ionic platform add ios@3.9
  9. Re-add the Android platform if you wish to build the Android app
    1. ionic platform add android@4.1
  1. Browse to "BlueCube" "IonicApp"
  2. Edit config.xml in the text editor of your choise
  3. On the second line where it says id=com.example.BlueCube change it so that it is unique to you. Normally the name ID is in reverse DNS format, so if you own "fredsautos.com", the ID would be id=com.fredsautos.BlueCube. Otherwise just add a random number to the end of "BlueCube", without any spaces or punctuation. If in doubt, add the machines MAC address at the end. Run getmac, from the command prompt and pick the "Physical Address", removing the hyphens
  4. Save the file and quit the text editor
  5. Start Command Prompt "Windows Key + R" and run "cmd.exe"
  6. Change to the BlueCube folder by cd and dragging the "IonicApp" ("BlueCube" "IonicApp") folder onto the command prompt, then hitting "Enter". For example, I have the BlueCube folder on my desktop, and my username is adam. In this case the command was cd "C:\Users\adam\Desktop\BlueCube\IonicApp"
  7. Remove the previously configured platforms
    1. ionic platform rm ios
    2. ionic platform rm android
  8. Re-add the Android platform
    1. ionic platform add android@4.1

Build

Every time you modify the BlueCube's code, you need to instruct ionic to build it. This prepares all of the items in a platform specific way. You build the code from the command line.

  1. Start "Terminal" from "Applications" "Utilities"
  2. Change to the to "BlueCube" "IonicApp" folder by running cd /path/to/BlueCube/IonicApp (you can drag the IonicApp folder from Finder into the Terminal window to automatically provide the complete path)
  3. ionic build (to build both iOS and Android apps), or
  4. ionic build ios (if building iOS app), or
  5. ionic build android (if building Android app)
  1. Start "Command Prompt" hitting "Windows" + "R" keys, then typing cmd
  2. Change to the to "BlueCube" "IonicApp" folder by running cd "C:\Users\Adam\BlueCube\IonicApp" (you can drag the IonicApp folder from Explorer into the command window to automatically provide the complete path)
  3. ionic build
    • You may be asked by the windows firewall to allow access for Java. It is up to you if you wish to allow this access.

Deploy to Mobile Device

Ensure that before deploying to a mobile device, that the latest version of the code has been build, as outlined in the instructions above.

iOS

  1. Connect your iOS mobile device to your Mac with a lightning cable, and unlock the device
  2. If requested, Trust the computer on your mobile device (this should only occur the first time you connect the mobile device)
  3. Open the Xcode project by browsing to "BlueCube" "IonicApp" "platforms" "ios" and double clicking on "BlueCube.xcodeproj"
  4. Xcode will launch, and the project will load (which can take a while the first time - progress is shown in the toolbar at the top of the Xcode window)
  5. Ensure that in the top toolbar, that BlueCube and your mobile device are selected. If not, click on this and pick your phone from the list of available options
  6. Click Build (the black arrow icon). The first time you do this you may need to do the following tasks:-
    • If prompted, enable "Developer Mode" and provide your password when requested
    • You may get an error saying 'Failed to code sign "BlueCube"', and are provided an option to "Fix issue". If this occurs, click the "Fix issue" button
      1. When asked, click "Add" to add your Apple ID
      2. Enter your Apple ID and Password, then click "Sign In"
      3. If two factor authentication is enabled, select the phone to send the code to, and click "Continue", then enter the provided code and click "Verify"
      4. You will now see the Accounts tab of the preferences window, and your AppleID will be listed. Close this window.
      5. If you have multiple teams associated with your AppleID, select the one you want to use and click "Choose"
    • If you have your AppleID developer account setup on a different mac for use with Xcode, you will need to export the developer profile (via Preferences -> Accounts -> Cog icon), then click Import Developer Profile, otherwise let Xcode download the signing certificates that are required
    • Finally Always Allow codesign to sign the code
    • After the code is uploaded to your mobile device, Xcode may give you a 'Could not launch "BlueCube"' error, mentioned that the process launched failed because of security. It this happens, on your mobile device:-
      1. Launch "Settings"
      2. Select "General"
      3. Select "Device Management"
      4. Select the option that represents your Apple ID
      5. Tap "Trust 'Apple ID'"
      6. Tap "Trust"
      7. Rebuild the app in Xcode
  7. Test the app on your mobile device
  8. Stop the app via the stop icon on the top toolbar in Xcode

At this stage you can quit the Xcode, and use the app like a normal app.

Android

To be able to deploy the app to your Android device, we need to enable USB Debugging. To do that:-

  1. Launch the "Settings" application on your Android device
  2. Select "About phone" or "About tablet" from the bottom of the list of settings
  3. Scroll to the bottom of the information, and find "Build number"
  4. Tap "Build number" seven times
  5. "You are now a developer" will be shown when this has been successful
  6. Tap the back button to return to the settings menu
  7. Select "Developer Options" menu which has now been added to the settings menu
  8. Enable "USB debugging"

Your mobile device is now ready to have the app deployed to. To deploy the app:-

  1. Connect your mobile device to the computer via USB, and unlock it
  2. If prompted, select "Always allow from this computer" and touch "OK" on your device
  3. Launch Android Studio
  4. Select "Import project (Eclipse ADT, Gradle, etc.)"
  5. Select "BlueCube" "IonicApp" "platforms" "android" folder
  6. Click "OK", and wait for the app to load (which can take a while the first time - you can see progress in the bottom status bar after the initial stage has completed)
  7. Click Build (Green arrow in middle of top toolbar)
  8. Select "Choose a running device", and select your mobile device
  9. Click "OK"
  10. The application will launch, and you can see logs within Android Studio. Test the app as appropriate

At this stage you can quit Android Studio, and use the app like a normal app.

Other Tools

In addition to the above requirements, I find that there are some optional tools that make development easier. These tools are listed below:-

  • Notepad++ is a free text editor
  • Git is a free version control system tool. I've used Git during the development of BlueCube
  • SourceTree is a free graphical front end to Git from Atlassian

Video Tutorials

Development Environment Setup