Setting up Raspberry Pi for Mobile App Development.md

Cat5Scouting_on_RPi_HTML

<h1 id="setting-up-a-raspberry-pi-for-mobile-app-development">Setting up a Raspberry Pi for Mobile App Development</h1>

<p><em>Written by:</em> <a href="mailto:[email protected]">David Castro</a>, <a href="http://team3489.org">Team 3489</a> <br>
<em>Last updated:</em> 2016-12-17</p>

<p>This document provides the steps for setting up a Raspberry Pi to use for mobile app development. It is written specifically for using a Raspberry Pi 3/Model B, and for working on the code for <a href="http://www.cat5scouting.mobi">the Cat5Scouting app</a>. However, it may be useful even if you’re using a different version of the Pi, or want to work on a different app.</p>



<h2 id="overview">Overview</h2>

<p>The process of setting up your Raspberry Pi, GitHub account, and Adobe PhoneGap Build account usually takes about two and a half hours. The following are the major steps covered in this document for going from zero to pushing an updated app to a Android tablet or phone:</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVTEdKLUhPenVpc1U" alt="" title=""></p>



<h2 id="what-you-need">What You Need</h2>

<ul>
<li><p><a href="https://www.adafruit.com/products/3055">A Raspberry Pi 3 - Model B - ARMv8 with 1G RAM</a></p>

<ul><li><p>The Pi must have NOOBS installed on it. Installing NOOBS involves both copying files onto the microSD card and choosing the Raspbian operating system when booting up the Pi for the first time. </p></li>
<li><p>Installation will require a keyboard, wired mouse, and HDMI-compatible monitor to be plugged into the Raspberry Pi. Subsequent to that installation, you will have the option to choose between continuing to use the keyboard, mouse, and monitor, or switching to using VNC to remotely connect to the Pi from a network-connected laptop or desktop computer. </p></li>
<li><p>Further instructions on installing NOOBS are provided overed in the later section, <a href="#FirstSteps">First Steps</a>.</p></li></ul></li>
<li><p>A power cord for the Pi (<a href="http://a.co/975cXEK">micro-USB style</a>)</p></li>
<li>An <a href="http://a.co/8GxsVQw">8GB or larger microSD card</a></li>
<li><p>For a laptop-connected configuration:</p>

<ul><li>A laptop with a connection to the Internet. Note that these instructions are written for a Windows 10 machine, and may be different if you are using a different version of Windows or a non-Windows operating system. If you would like to help by writing a copy of this document for another operating system or system version, please <a href="https://form.jotform.com/63274691259162">let me know</a>!</li>
<li>A short <a href="http://a.co/cQ1GuBC">Ethernet cable</a></li></ul></li>
<li><p>For a self-standing configuration:</p>

<ul><li>Either a Wi-Fi network you can connect to, or an Ethernet connection to a network router</li>
<li>A wired keyboard (note: wireless will not work)</li>
<li>A wired mouse (note: wireless will not work)</li>
<li>An LCD monitor</li>
<li>An <a href="http://a.co/cTmnsg9">HDMI cable</a> with a full-sized HDMI end for the Raspberry Pi end, and the other end with a connector that matches the LCD monitor’s inputs</li></ul></li>
</ul>



<h2 id="first-steps">First Steps</h2>

<p>The following external web pages provide steps for getting up and running with your Raspberry Pi. Open the linked pages in a new browser tab and follow the steps, and return here after you complete each.</p>



<h3 id="physically-setting-up-the-pi">Physically Setting Up the Pi</h3>

<p><a href="https://www.raspberrypi.org/help/videos/#getting-started-with-raspberry-pi">Getting Started With Your Raspberry Pi</a> - shows you how to hook up all the parts-and-pieces to your Raspberry Pi, such as a power source, a video display, and USB peripherals. </p>

<p>Note that instructions are provided later in this document for working with a Raspberry Pi that is connected to a desktop or laptop, which does not require having a dedicated video display, keyboard, or mouse.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVV3dwS1RSV1l6Vzg" alt="" title=""> <br>
This step should take approximately 20 minutes.</p>



<h3 id="installing-an-operating-system">Installing an Operating System</h3>

<p><a href="https://www.raspberrypi.org/help/videos/#noobs-setup">NOOBS Setup</a> - Assuming you’re using a NOOBS microSD card (all Team 3489 students will be), skip to 3:00 in this video and follow the instructions. If you’re using a blank microSD card, follow the instructions from the beginning. If you’d prefer following written instructions, <a href="https://www.raspberrypi.org/documentation/installation/noobs.md">here are text-based steps</a>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVOEtaaE90eXhrT3M" alt="" title=""> <br>
This step should take approximately 30 minutes.</p>



<h2 id="setting-up-for-app-development">Setting up for App Development</h2>

<p>There are two sets of steps in this document for setting up to work on the mobile app’s source code. <a href="#setting-up-for-app-development-when-you-have-a-monitor-mouse-and-keyboard">The first</a> is for when you have a monitor, mouse, and keyboard to hook up to the Raspberry Pi. <a href="#setting-up-for-app-development-using-vnc">The second</a> is when you have a desktop or laptop computer on a home network that you can hook your Raspberry Pi up to. </p>



<h3 id="setting-up-for-app-development-when-you-have-a-monitor-mouse-and-keyboard">Setting up for App Development When You Have a Monitor, Mouse, and Keyboard</h3>

<p><strong>Note:</strong> If you plan to use a laptop or desktop to connect to the Pi, skip this section and go straight to <a href="#setting-up-for-app-development-using-vnc">Setting up for App Development Using VNC</a>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVOEtaaE90eXhrT3M" alt="" title=""> <br>
The following steps should take approximately 30 minutes.</p>

<p><strong>To connect to your Pi using a keyboard, mouse, and monitor:</strong></p>

<ol>
<li><p>Connect a video display, corded mouse, corded keyboard, and power supply to the Raspberry Pi.</p>

<p>Do one of the following:</p>

<ul><li><p>When the Pi finishes starting up, switch to the <strong>Wifi Networks</strong> tab of the dialog box that appears and provide WiFi credentials to get online.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVMUo1Q2dxeXFicXc" alt="" title=""></p></li>
<li><p>Connect an Ethernet cable to the Pi.</p></li></ul></li>
<li><p>Switch to the <strong>Install</strong> tab of the dialog box, choose <strong>Raspbian</strong>, and click <strong>Install</strong>. <br>
<img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVSEpHNEpBSC1NRGc" alt="" title=""></p></li>
<li><p>Wait for a few minutes while the operating system installs.</p>

<p>The desktop will load after the operating system installs.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVd0REZnMwMU1feVE" alt="" title=""></p></li>
</ol>



<h3 id="setting-up-for-app-development-using-vnc">Setting up for App Development Using VNC</h3>

<p><strong>Note:</strong> If you already followed the steps in the preceding <em>Setting up for App Development</em> section, skip this section and go straight to <a href="creating-your-own-code-repository">Creating Your Own Code Repository</a>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVOEtaaE90eXhrT3M" alt="" title=""> <br>
The following steps should take approximately 30 minutes.</p>

<p>When you don’t have peripherals to connect to your Raspberry Pi, you can connect to the device using an existing network-connected desktop or laptop computer. </p>

<p><strong>To connect to your Raspberry Pi using VNC:</strong></p>

<ol>
<li><p>Connect your Ethernet cable between your desktop or laptop and the Raspberry Pi.</p></li>
<li><p>Follow some of the instructions from <a href="https://diyhacking.com/connect-raspberry-pi-to-laptop-display/">this page</a>. </p>

<p><strong><em>TODO: Expand the preceding step.</em></strong></p></li>
<li><p>Download the <a href="https://github.com/adafruit/Adafruit-Pi-Finder/releases/tag/3.0.0">Adafruit Pi Finder software installer</a> for your operating system. The links to the downloads are at the bottom of the page.</p></li>
<li><p>Extract the content of the Pi Finder software to a location on your machine.</p></li>
<li><p>Run the Pi Finder executable. Allow it to search your network to find your attached Pi. Note that this process can take several minutes if you have a complex or slow network.</p></li>
<li><p>Download <a href="http://www.putty.org/">PuTTY</a> on your laptop or desktop computer. <br>
Note: PuTTY doesn’t require an installation. Clicking the EXE file will run it.</p></li>
<li><p>Run PuTTY and connect to the Pi using the IP address that the Pi Finder indicated the Pi is using.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVdThqWnVCbjZNX2s" alt="" title=""></p></li>
<li><p>In the command window that opens, at the login as prompt, type <code>pi</code> and press ENTER key on the keyboard.</p></li>
<li><p>At the <strong>[email protected]’s password</strong> prompt, type <code>raspberry</code> and press ENTER on your keyboard. (Note that the prompt will have different numbers that correspond to your IP address.)</p></li>
<li><p>At the <strong>pi@raspberrypi</strong> prompt, type <code>vncserver</code> and press ENTER on your keyboard.</p></li>
<li><p>Download and install VNC Viewer on your laptop or desktop computer.</p></li>
<li><p>Run VNC Viewer, enter the IP address from Pi Finder in the bar at the top, followed by <code>:1</code>, and press ENTER on your keyboard.</p></li>
<li><p>On the <strong>Authentication</strong> screen, enter <code>pi</code> in the <strong>Username</strong> field and <code>raspberry</code> in the <strong>Password</strong> field and click <strong>OK</strong>.</p>

<p>A GUI screen appears, which lets you interact with the Pi as though you had a keyboard, mouse, and monitor attached to it.</p></li>
</ol>



<h2 id="creating-your-own-code-repository">Creating Your Own Code Repository</h2>

<p>In this section, you’ll create your own free GitHub account and then create a GitHub repository based on the main app repository. This will start you off with all of the files necessary to compile an Android executable (APK) file. </p>

<p><strong>To create your own GitHub repo:</strong></p>

<ol>
<li><p>Point your browser to <a href="https://github.com/">https://github.com/</a>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVTThyQUpWbi1Cbzg" alt="" title=""></p></li>
<li><p>Enter a username, your email address, and a password, and then click <strong>Sign up for GitHub</strong>.</p></li>
<li><p>If you plan to keep your repository open (so that other people can see what you’re doing as you’re doing it), then leave the account set to the free option. If you plan to go closed-source while working on the app (viewing the app as your “secret sauce”), then change the account type to the $7/month option.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVYzBZWTRBSVMwbEE" alt="" title=""></p>

<p>The following steps assume that you chose the free option.</p></li>
<li><p>Click <strong>Continue</strong>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVZkh4dFBDWUZpSEE" alt="" title=""></p></li>
<li><p>Answer the questions on the <strong>Tailor your experience</strong> page and click <strong>Submit</strong>.</p></li>
<li><p>Check your email inbox for an email from GitHub asking you to confirm your email address. You won’t be able to continue until you’ve clicked the link in the email.</p></li>
<li><p>Back in your browser, click in the <strong>Search GitHub</strong> field at the top of the page, type <em>Cat5Scouting</em>, and press ENTER on the keyboard.</p></li>
<li><p>Find and click the link for <em>CarolinaKinetic/Cat5Scouting</em> (this is the official repository for the app).</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVUlBEam5OVjk2Rkk" alt="" title=""></p></li>
<li><p>To ensure that you’ll receive notifications when updates are posted to the official repository, click the <strong>Star</strong> button in the upper left corner of the screen. </p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVb2RXOTU4NXFPbVE" alt="" title=""></p></li>
<li><p>To create a repository that automatically copies in the files from the official repository, click <strong>Fork</strong>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVakZlTkJ3aTBsaGM" alt="" title=""></p></li>
<li><p>Copy the URL in your browser and paste it into a text file for use in the next section. </p>

<p>To open a text editor on your Pi:</p>

<ul><li>Click the Raspberry icon in the upper left corner of the screen.</li>
<li>Click <strong>Accessories</strong>.</li>
<li>Click <strong>Text Editor</strong>.</li></ul></li>
</ol>

<p>You now have a repository with all of the files from the official repository. You’ll use this repository to copy the files to your Pi in the next section. When you update files, you’ll copy them back into your GitHub repository.</p>



<h2 id="cloning-source-files">Cloning Source Files</h2>

<p>To start making edits and additions to the Android app, you need to copy source files from the existing project to your Raspberry Pi. This copying is called “cloning” a project. </p>

<p><strong>To clone source code to your Raspberry Pi local storage:</strong></p>

<ol>
<li><p>Click the <img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVSnBubE1BQ29uNmM" alt="" title=""> icon in the task bar at the top of the screen to open the console.</p></li>
<li><p>Before we go any further, let’s update our repositories. This ensures that we have the latest information when we install applications on the Pi. It will also update some existing libraries (programs) on the device.</p></li>
<li><p>To update the repositories, type the following in the console, and then press the ENTER key on the keyboard:  <br>
<code>sudo apt-get update</code></p>

<p>Note that it may take a couple of minutes for all of the updating to finish.</p></li>
<li><p>Type the following in the console, and then press the ENTER key on the keyboard:  <br>
<code>cd Documents</code></p>

<p><strong>Note:</strong> The case (upper case or lower case) matters with Linux. Make sure you capitalize “Documents.”</p></li>
<li><p>Next, you’ll download your own copy of the app code. Copy the URL that you pasted into a text editor in the previous section. It should look something like <code>https://github.com/&lt;your username&gt;/Cat5Scouting.git</code>, but with <em>&lt;your username&gt;</em> replaced with the username you used when creating your account. </p></li>
<li><p>In the console:</p>

<ol><li><p>Type the following <em>without</em> pressing ENTER on the keyboard: <code>git clone</code></p></li>
<li><p>Paste the copied URL from the browser. </p>

<p>The full console command should look something like: <br>
<code>git clone https://github.com/CoolAppDeveloper/Cat5Scouting.git</code></p></li>
<li><p>Press the ENTER key on the keyboard.</p></li></ol>

<p>Following output similar to the following appears as the files are downloaded.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVMDQ4clB3LVVKX2M" alt="" title=""></p></li>
<li><p>Close the console window.</p></li>
</ol>

<p>You now have all of the app’s files on your Pi. Next, you’ll make a small modification to the app code.</p>



<h2 id="updating-the-source-code">Updating the Source Code</h2>

<p>Now that you have all of the source code for the application loaded on your Pi, it’s time to have some fun by making an edit to the app.</p>

<p>The version of the Raspbian operating system that comes with NOOBS includes a code editor called Geany Programmer’s Editor. We will use this editor to modify the source code.</p>

<p><strong>To update the app’s source code:</strong></p>

<ol>
<li><p>In the Pi GUI, click the Raspberry button in the upper left corner, then click <strong>Programming</strong>, and then click <strong>Geany Programmer’s Editor</strong>.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVU3h5cEhTa2MzeVU" alt="" title=""></p></li>
<li><p>Click the <strong>File</strong> menu, and then <strong>Open</strong>.</p></li>
<li><p>On the left side of the <strong>Open File</strong> screen, click <strong>Pi</strong>.</p></li>
<li><p>On the right side of the <strong>Open File</strong> screen, double-click <strong>Documents</strong>, then <strong>Cat5Scouting</strong>, then <strong>cat5scouting</strong>, then <strong>www</strong>, and finally <strong>js</strong>.</p></li>
<li><p>Double-click <strong>controllers.js</strong> to open the file.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVdHFKdzNJR2RfN3c" alt="" title=""></p>

<p>Feel free to look through the code, but don’t worry if not much of it makes sense, yet. While every attempt was made to add comments to the code as it was developed, it still needs some work in that area.</p>

<p>In the following steps, we’ll update the code so that the text file that is created when exporting Pit scouting data will include your team’s number at the beginning. So, for example, if you are team 123 (Team - Cosmos), you’d change the filename from <code>Cat5Scouting.Pit.txt</code> to <code>123.Cat5Scouting.Pit.txt</code>.</p></li>
<li><p>Scroll down to around line 823, and look for the line of code that looks like this:</p>

<p><code>var pitFilename = "Cat5Scouting.Pit." + $scope.getDateString() + ".txt";</code></p></li>
<li><p>Change the code by adding your team number and a period between the quotation mark and the word <em>Cat5Scouting.Pit.</em></p>

<p>It should look something like this: <br>
<code>var pitFilename = "123.Cat5Scouting.Pit." + $scope.getDateString() + ".txt";</code></p></li>
<li><p>Save the updated file.</p></li>
</ol>



<h2 id="committing-code-to-your-github-repository">Committing Code to Your GitHub Repository</h2>

<p>Now that you’ve updated your source code, you need to upload the changes to your GitHub repository. When working with the Git version control system, this is referred to as <em>committing</em> your code.</p>

<p>You will be using Git commands in the following steps, but there is not a lot of explanation of what each command does. Teaching Git is a big task, and is better handled in a document of its own. If you’d like to get a jump-start, check out the interactive tutorial available <a href="https://try.github.io/levels/1/challenges/1">here</a>.</p>

<p><strong>To commit code to your repository:</strong></p>

<ol>
<li><p>To open the console, click the <img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVSnBubE1BQ29uNmM" alt="" title=""> icon in the task bar at the top of the screen.</p></li>
<li><p>Enter the following and then press ENTER on the keyboard: <br>
<code>cd /home/pi/Documents/Cat5Scouting</code></p></li>
<li><p>Enter the following, replacing <code>[email protected]</code> with your email address, and then press ENTER on the keyboard: <br>
<code>git config --global user.email "[email protected]"</code></p></li>
<li><p>Enter the following, replacing <code>Your Name</code> with your name, and then press ENTER on the keyboard: <br>
<code>git config --global user.name "Your Name"</code></p></li>
<li><p>Enter the following and then press ENTER on the keyboard: <br>
<code>git add .</code></p>

<p>This adds the updated file to a set of files that will be uploaded to the GitHub repository in a later step.</p></li>
<li><p>Enter the following and then press ENTER on the keyboard: <br>
<code>git commit -m 'Updated filename for Pit data export'</code></p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVajJGamgxNUN1Tms" alt="" title=""></p>

<p>This bundles all of the files that will be uploaded (in this case, just a single file) into a <em>git commit</em> and provides a description of what was changed.</p></li>
<li><p>Enter the following and then press ENTER on the keyboard: <br>
<code>git push</code></p>

<p>This copies the updated file(s) to the GitHub repository.</p></li>
<li><p>When prompted, enter your GitHub username and password.</p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVQVpMdU04dm5rOUk" alt="" title=""></p>

<p>(Some of the output from the git push process has been removed from this image for brevity.)</p></li>
<li><p>Close the console window.</p></li>
<li><p>Open a browser and point it to your GitHub repository (<code>https://github.com/&lt;your account name&gt;/Cat5Scouting</code>)</p></li>
<li><p>Look for the commit message you used earlier to confirm that the file was uploaded. </p>

<p><img src="https://drive.google.com/uc?id=0B1_Yw5JimVKVMDhoRDdGQmVlQzA" alt="" title=""></p>

<p>You can also navigate to the specific file you changed and see that the date/timestamp has changed to a few minutes ago.</p></li>
</ol>



<h2 id="compiling-your-code-locally">Compiling Your Code Locally</h2>

<p>If you will be using your Pi to edit code when you do not have Internet access, then you will need to install Ionic on your Pi to compile the app on the device. Keep in mind that compiling the code will be extremely slow on your Pi, and so this should be a last resort rather than the first choice for compiling.</p>

<p><strong>To install Ionic on your Pi:</strong></p>

<ol>
<li><p>On your Pi, open a command line window.</p></li>
<li><p>Navigate to the directory that contains your source code. If you’ve chosen the default locations provided in this document, this will be </p>

<pre><code>/home/pi/Documents/Cat5Scouting/cat5scouting
</code></pre></li>
<li><p>Enter the following and then press ENTER on the keyboard:</p>

<pre><code>sudo apt-get install nodejs npm
</code></pre>

<p>This installs the NodeJS library and tools on your Pi. Next, you’ll install Cordova, which is a library that Ionic uses to interact with features of the tablet that you install the app on.</p></li>
<li><p>The default version of NodeJS that was installed won’t work for the app, so you’ll need to perform a couple of additional steps to get that updated to the latest stable version. Enter the following lines and press ENTER after each one and let it complete before entering the subsequent line.</p>

<pre><code>sudo npm cache clean -f
sudo npm install -g n
sudo n stable
</code></pre></li>
<li><p>Enter the following and then press ENTER on the keyboard:</p>

<pre><code>sudo npm install -g cordova
</code></pre>

<p>Next, you’ll install Ionic, which is the framework that you’ll work with to update the Cat5Scouting mobile app.</p></li>
<li><p>Enter the following and then press ENTER on the keyboard:</p>

<pre><code>sudo npm install -g [email protected]
</code></pre>

<p>The <code>@1.1</code> portion of the command above sets the Ionic installed to an earlier version that is known to work with the code base as of December, 2016. If you decide to add functionality not supported by the 1.1 version of Ionic, you can update to the latest version of the libraries by typing <code>ionic lib update</code> and answering yes when prompted to replace files with an updated version of Ionic.</p></li>
<li><p>You  need to change the permissions on your working directory for the next command to work. To do this, enter the following (including the period at the end) and then press ENTER on the keyboard:</p>

<pre><code>sudo chmod -R a+rwx .
</code></pre>

<p><strong>More stuff</strong></p>

<pre><code>wget http://dl.google.com/android/android-sdk_r24.2-linux.tgz
tar -xvf android-sdk_r24.2-linux.tgz
cd android-sdk-linux/tools
./android update sdk --no-ui
export ANDROID_HOME=$HOME/android-sdk-linux
export PATH=$PATH:$ANDROID_HOME/tools
</code></pre></li>
<li><p>Next, you’ll add supporting libraries for Android development. To do this, enter the following and then press ENTER on the keyboard:</p>

<pre><code>sudo ionic platform add android
</code></pre></li>
<li><p>Now that you have installed Cordova and Ionic and added Android support to your project, you can build your updated source code. To do this, enter the following and then press ENTER on the keyboard:</p>

<pre><code>ionic build android
</code></pre></li>
</ol>

<h2 id="compiling-your-code-remotely">Compiling Your Code Remotely</h2>

<p>Because of the processor and memory limitations of a Raspberry Pi, it makes more sense to use a free service from Adobe to compile code into an APK file rather than compiling directly on the Pi.</p>

<p>In the following steps, you’ll create an account on Adobe Phonegap Build, and then will compile an APK based on the code in your GitHub repository.</p>

<p><strong>To compile the Cat5Scouting app source code:</strong></p>

<ol>
<li><p>Point your browser to <a href="https://build.phonegap.com/">https://build.phonegap.com/</a></p></li>
<li><p>Click the <strong>Sign Up</strong> link in the upper left corner of the screen.</p></li>
<li></li>
</ol>



<h2 id="pushing-code-to-your-tablet">Pushing Code to Your Tablet</h2>