Groups

You can work in groups of two on this assignment.

Pair Programming

It is strongly recommended that you use formal “pair programming”, where one person (the driver) types/creates and the other (the navigator) observes/assists. Moreover, you should alternate roles so each person takes on each role for a roughly equal amount of time. Remember that a spokesperson will be designated at checkout time, so both group members need to be comfortable presenting the work.

Repositories

Before configuring a repository, decide if you will be working in a group or not. If you will be working in a group, decide who will create the GitHub group and who will join it.

Follow the same basic process used in studios and previous assignments to create/join a group, download the resulting repository (with GitHub Desktop), and import it using the Particle Desktop IDE.

The GitHub Link is: https://classroom.github.com/g/8lCbNDbx

Files in your repository:

The repository currently contains a few files:

• README.md contains some questions you need to complete when you’re done with the assignment
• Garage Hardware files
  • GarageController/src/GarageController.ino Copy/paste the updated/completed work from the previous assignment.
  • GarageController/lib/GarageHardware/src/GarageHardwareProxy.cpp Copy/paste the updated/completed work from the previous assignment.
  • You should not add any extra functions in this file, but only edit the contents of the existing functions, leaving the function signature unchanged.
  • GarageController/lib/GarageHardware/src/GarageHardware.h: This contains the declarations for the Hardware API used by the real hardware. These represent a contract between the hardware team and you. DO NOT MODIFY THEM.
  • GarageController/lib/GarageHardware/src/GarageHardwareReal.cpp: This contains the definitions for the Hardware API for real hardware. DO NOT MODIFY THEM.
  • GarageController/lib/GarageHardware/HardwareCheckoutSteps.md: This contains the directions you need to follow to switch between the hardware checkout with the mini-garage and using your proxy hardware.
• documentation/contents.md: This contains a description of the files that should be included in the documentation directory when you’re done.
• The project does not yet include a ui directory. See Suggested Workflow Part 3 for details on how to create it.

Your (Sixth) Assignment

DBI wants you to turn your website UI into a phone application to increase ease of access for their customers. They’ve asked you to complete the first prototype of the “native app”, which includes:

• DBI has decided that the App should use the Cordova framework, which will allow them to put native apps for both iOS and Android in their respective app stores. (See Suggested Workflow Part 3 to set up the project)
• You still don’t need to worry about including user account functionality
• You also don’t need to be concerned with the remote control functionality from Assignment 5
• You will need to include the advanced light features that were required for Assignment 5
• All pages should be easy to use on common sizes of mobile devices:
  • Be sure to use your browser’s tools for responsive designs and a size that corresponds to iPhone 8 / Galaxy S8 sizes or smaller)
  • Users should never have to scroll!
  • All controls that require touching (buttons, scroll bars for controls, text fields, etc.) must be big enough to accommodate a wide range of hands. Review other apps and note the typical sizes of interactive elements.
• The app should support two “pages” of content. In order to keep the interface simple, these pages should be shown separately:
  • Basic Controls
    • Open/Close Door
    • Light On/Off
    • display state of Door & Light
  • Advanced Features
    • ability to enable/disable and set value of AutoClose time for the Door
      • make sure to provide the user with some form of clear indication of whether AutoClose is enabled or disabled
      • input should still be restricted to certain values and validated to check that it is of the appropriate/expected type
    • ability to set value of AutoOff time for Light
    • ability to set light max brightness of the Light
  • Users must be able to easily navigate back and forth between the screens

Cumulative Implementation Requirements

• You must use the Cordova framework for your UI and be able to test your work as it is being “served” from the PhoneGap Desktop App.
• You must meet all assignment requirements for Assignments 1-4, in addition to the Advanced Light features from Assignment 5

Past Requirements:

• Ensure that the AutoClose functionality is implemented via Timers on the Photon, not through JavaScript
• The state machine on the Photon should check sensor values for the initial state rather than making any assumptions about the condition of the door upon startup
• All streams used for communication should be private streams (rather than public)
• All HTML, JavaScript, CSS, C code, and other assets should be your work. No use of outside libraries other than Particle’s JavaScript library
• HTML should continue to follow the “single page application” approach. All HTML should be in a single file, but elements should be hidden/shown to keep the visible user interface as simple as possible
  • Additionally, JavaScript, CSS, and HTML should all be in separate files
• User Interfaces should restrict any inputs to appropriate types and ranges (an “alert()” can be used to indicate an error)
• You must use Particle’s JavaScript API (Not Particle’s Cloud API, which uses URLs and GET/POST/PUT methods)
• Simulated hardware should:
  • Use only the Hardware API from Assignment 3 for all hardware interaction. (No calls to pinMode(), analogRead(), analogWrite(), digitalRead(), digitalWrite() except in the stubs of the designated functions!)
  • The same inputs and outputs that were specified in Assignment 3
• Unnecessarily polling information from a remote system could use excessive data when this work is converted to a mobile app, so it is not allowed.
  • Don’t use a JavaScript timer to repeatedly call functions on the Photon
  • Don’t repeatedly/excessively publish things from the Photon or from the JavaScript
• Do not use delays or anything else that would block execution on the Photon or in your JavaScript files

Suggested Workflow

1. Complete any/all remaining requirements left over from previous assignments that will be needed.
2. Run your existing HTML through a validator and fix any significant errors
   • One common error that can cause problems in Cordova is an element that isn’t properly closed
3. You must create the ui folder using PhoneGap Desktop:
   1. Open the PhoneGap Desktop App
   2. Click on + to add a new project
   3. Select Create new PhoneGap project...
   4. Select the Blank template and select Next
   5. Configure the project
   6. The Local Path should be the path to your repo.
   7. The Name should be ui
   8. The ID is optional and you can pick any value you’d like (but it should be a reverse internet domain name format)
   9. You may want to refer to Studio 12 to identify locations for files.
   10. You may want to edit the config.xml file to change the App’s name.
   11. Merge your HTML, JavaScript, and CSS in the appropriate places (www/index.html and www/js/, www/css/).
   12. Review the use of events and files in Studio 12 and update any code as needed.
4. Test your work using PhoneGap. Open the project in PhoneGap Desktop, then click on the URL at the bottom of the PhoneGap Desktop pane. This will open your app in the browser on your PC. Test the basic functionality.
5. Test the responsiveness of your website on different mobile device sizes and fix any layout issues one at a time.

Hints

• Review Studio 12
• Validate your code
• Be sure to open the app by clicking the URL at the bottom of the PhoneGap window, not by directly opening the HTML file. If the HTML file is opened directly in the browser, it won’t have the proper directory structure to access files in sub-directories (like those in www/js/).
• The developer tools in most browsers allow you to select a device size. Use this when updating sizes to simplify testing. Be sure to use iPhone 8 or Galaxy S8 sizes or smaller.
• Add a console.log() message to the top and bottom JavaScript file. If this message doesn’t print when loading the page it may that there’s a syntax error in your JavaScript (like a missing bracket or mismatched parentheses, etc.)
• The PhoneGap desktop app can be used to display console.log() messages from your mobile device - it’s the square icon on the left panel (just above the question mark). This can vastly simplify debugging.

Extra Credit

• +20% for using a CSS library that makes the app look like a native App (Common ones are: Ionic Framework, Onsen UI, and Framework7). Using one of these three libraries or another that you get pre-approved is acceptable (Overrides the “no external libraries” prohibition)
  • PhoneGap includes Framework7 templates. You can start by selecting the +, picking Create new PhoneGap project..., and selecting the Framework7 template.
  • Extra credit UI work should be in a secondary directory named uiec. You you also need to include the non-extra credit UI (so do it first!)
• +10% build a native app for iOS or Android
  • This will require using the Cordova command-line interface (CLI) to add iOS and/or Android platform support. See “Create the App”.
  • Follow the iOS Platform Guide or the Android Platform Guide (or the Windows/Blackberry/etc. guide)

Artifacts that are Due

Tentative Rubric

• Run from PhoneGap Desktop (55%)
  • intuitive navigation between screens (5 points)
  • state of Door is displayed on Basic Controls Screen (5 points)
  • state of Light is displayed on Basic Controls Screen (5 points)
  • user does not need to scroll on Basic Controls Screen (5 points)
  • user does not need to scroll on Advanced Features Screen (5 points)
  • all buttons are appropriately sized (5 points)
  • all controls are easy/intuitive to interact with (5 points)
  • AutoClose for the Door can be easily enabled and disabled (5 points)
  • AutoClose time for the Door can be set from the app (5 points)
  • AutoOff time for the Light can be set from the app (5 points)
  • all fonts/images are readable and organized nicely on the screen (5 points)
• functionality of requirements specified in previous assignments (20 points)
• functionality with mini garage (15 points)
• code quality and readability and comments (5 points)
• completed README.md (5 points)

Submission & Checkout

As outlined in the course policies, you must commit work to GitHub and demo it by class time on the due date for full credit.

You need to be prepared to demo and explain your work during your checkout as well as answer the questions in the README.md. (The final checklist may help verify that you are ready to demo)

Checkout and review will be done on a first-come-first-serve basis. If you aren’t done before class, you risk not being able to check out during class time. Work demoed after class time is considered late and will either not count as a grade or will consume late day coupons.