# ECE564project: Perygee Hub Companion App

App architecture and UI wireframes can be found on our [Figma](https://www.figma.com/file/lRm7zGEXkX3TQMgSwK6V8P/Perygee-Application-ECE564?node-id=0%3A1).

An overview of the writeups for app architecture, features, apis, etc can be found [here](https://docs.google.com/document/d/10R-Px_YxAACcKHnQKZvaR9Pyn6CfoXPsKg051YsbpFM/edit?usp=sharing).

A presentation on the App's purpose, functionality, and primary features can be found [here](https://docs.google.com/presentation/d/1tysyLxoBlR1xTHJHvBKbhqsr2-MQ3mVAJyLcOpGRGjs/edit?usp=sharing).

### Developers
Abhijay Suhag (as866)
Frank Tang (ft39)
Varun Kosgi (vsk10)

### Timeline

Start Date: March 23, 2021
Submission Date: April 22, 2021
Hours Spent: 100+ (~30-40 hours each)

### Introduction
Perygee is an Internet of Things (IoT) Security platform aiming to secure enterprise users' most critical connected infrastructure devices. By providing Perygee Hubs that facilitate communication between enterprise networks and the Perygee Cloud, Perygee offers real-time monitoring, detection, and prevention of the world's most dangerous cybersecurity threats.

### Functionality
The Perygee Hub Companion App was designed to assist in the setup and monitoring of Perygee Hubs and their associated devices, which are meant to secure IoT devices in real-time and provide crucial analytics on network behavior.

#### Implemented Features
* Hub Setup
* Scan a QR Code to register and configure a Perygee Hub
* Parses text data from QR code to gather new Hub's relevant parameters
* Call a GraphQL add mutation to update company's Hasura backend database with new Hub information, including user's current location (representing Hub location)
* Hub Directory
* View and edit all Hubs and Devices on a Network
* Calls a GraphQL query to fetch all Hubs from the server
* Populates Table View to allow User to scroll through and tap for more information on each Hub.
* Uses universal search bar to narrow down Hubs based on parameters
* Swipes on a cell to edit and delete Hub from directory (via GraphQL calls)
* Views Hub info/devices and edit Hub image, location, name, and manufacturer
* Device Directory
* User can tap to see a Hub's associated devices from the database (separate table in GraphQL, accessed with conditional query)
* Associated devices can also be tapped to see more info and edit devices' images, locations, names, manufacturers, and priorities.
* Hub Location Visualization
* Monitor Hubs at different geographical locations
* Hubs dynamically appear on Map View based on parsed latitude and longitude from server
* Click into each Hub directly from Mapview to either view information about the Hub or edit Hub's parameters (dynamic segue)
* Clustering allows for a clean view of groups of hubs from a distance
* Change the detail and look of the map on the fly through the segmented controller on the navigation bar
* Analytics Dashboard
* Aggregate network insights into customizable widgets
* View aggregate hub info, including count, packet info, and availability
* Drag and drop widgets into different slots on dashboard
* Long press on a widget to get the option to remove it from the Dashboard
* Swap same size widgets
* Add widgets from a Widget Library by swiping in from the left

### Primary Roles

#### Abhijay
* Dashboard and Widget Library
* Custom widgets for viewing data in various ways using Charts framework, complete with collision handling, swaping, deleting, animations
* Separate view controllers for active and inactive widgets
* Timers for periodic data pulling from GraphQL or from a set of mock data
* Added haptic feedback to notify user of deletion and addition success and fail
* Map View
* Custom annotation views for single hubs and for clustered hubs
* Custom callout for single hub annotations that display picture, location, and buttons for seguing to read-only/edit detail views
* Dynamic map type switching via segmented controller
* Added haptic feedback to notify user that an annotation was successfully clicked, and that a button in the annotation was successfully pressed
* QR Scanning
* Researched into framework, modified existing QR code to start and stop camera sessions and retrieve meta data
* Created a custom scanner overlay with a mask, indicator box, highlighted region, and instruciton label
* Alert functions for repeated QR code scans
* Directory TableView
* Setup and overall design - curved imageviews, curved cells
* Created and implemented collapsible headers
* Detail View Controllers
* Added image selection with both camera and photo album
* Storyboard
* Setup initial project Storyboard with TabBarViewController and main VCs/segues

#### Frank
* Perygee Hub and Perygee Device directory controllers
* Hub and Device detail view controllers that show detailed information about each hub/device stored on Perygee Hasura Server
* Live editing capabilities from these pages of hubs/devices directly to server
* Developed the basic structure of a TableView in a UIView to showcase the hub/device list and details
* Testing for bugs and racing conditions when viewing and editing pages
* Data Model development
* Assisted development with JSON codability and GraphQL compatibility with Varun
* QR Scanning
* Created the QR string parser/format for making hubs
* Storyboard
* Created the original hub and device detail VCs and linked many of the segues to the detail pages (e.g. mapView to Detail)

#### Varun
* GraphQL Server integration
* Apollo framework to authenticate and post queries/mutation to Perygee Server
* Defined parameters in database and coded appropriate parsing from calls
* Editing of Hubs & Devices on server from app
* Data Model development
* Parameter development with JSON codability and GraphQL compatibility
* Parsing of DataModel into Table Views
* Directory TableView Controller
* Search functionality for Hubs
* Cell population, deletion, and active server refreshing
* Map View Controller
* Developed initial population of annotations from hub latitudes and longitudes from server
* QR Scan Controller
* Addition of new Hub to database upon QR Scan

### Frameworks Used
* Apollo - GraphQL Integration (See auto-generated **GraphQLAPI.swift** for auto-generated methods)
* Had to run introspection query on company database to find all possible calls (had to program authentication manually)
* Then ran .sh script provided by framework, in addition to the queries/mutations defined in get_hub.graphql, to auto generate GraphQL method calls in **GraphQLAPI.swift**
* Called methods within appilcation to perform qeuries or mutations
* Charts - Dashboard View
* Learned api for multiple modes of data presentation such as LineChartView, BarChartView, PieChartView
* Customization as well as data initialization and periodic updating
* AV Foundation - QR Scan
* Researched metadata parsing and video layers
* MapKit - Hub Map View
* Researched into clustering, custom annotation views, numerous delegate functions

### Running the Application
**Location Permission Note:** Upon running the app, the app will ask for location permission. For the QR code scanning and hub instantiation to work, location permission needs to be granted, otherwise an alert/error will pop up.

* **Dashboard/Analytics Page** - This page has graphs and statistics available to admins about the hubs and devices in their network.
* **Widgets** - Multiple dashboard widgets that show different network analytics. For the sake of the project, several of the widgets showcase mock data, but the hub and device totals pull data from the hasura server and change dynamically
* **Movement** - By pressing and holding down on a widget, the widget will begin to wiggle, showing a delete button in the top-right hand corner of the widget. The user can then move this widget around on the dashboard to a new dashboard location. If the user tried to move the widget into the cell of a similarly-sized widget, the moving widget will move static widget out of the cell.
**Note:** An easy way to see this is to press and hold the hub/device totals widget in the top-right corner and slide it over the availability widget in the top-left corner.
* **Widget Library** - The dashboard also has several other widgets in a widget library that users can add/remove into the main dashboard page if there is space. To see this, press and hold on a widget and delete it from the dashboard page. By swiping right from the left side of the application, a widget library will pop up with all the different widgets that can be used in the dashboard. By tapping on a widget, the widget will be added in the closest available slot in the dashboard.
**Note:** An easy way to see this is to delete one of the medium-sized widget (a widget that takes up an entire row e.g. unauthorized usage widget.) By going into the app library, tapping on another medium widget will populate the dashboard page with it.

* **Directory Page** - This page has a listing of all the hubs in the network, seguing into the details of the hub, the device list of a hub, and the details of a device
* **Tableview** - All the controllers in the Directory Page chain use a tableview of sorts to display data. For the directory and deviceList VCs, these tableviews display hubs and devices respectively that can be selected to segue into the details of said hub or device. In the hubDetail and deviceDetail pages, the tableview is used to list the details about a hub or device
* **Server Fetching** - The main directory page has a refresh button in the top-right that will do a full server fetch from the Perygee cloud to populate the hub directory. The same server fetch can be done by pulling down on the directory. This makes it so that a user can keep up-to-date information about their network.
**Note:** An easy way to test this is by having two devices and scanning in a new hub with the QR scanner on one of the phones. By being on the directory page on the other phone, we can click refresh or pull down to refresh and see that the new hub will pop up on our directory, showing that the app is fetching data from the Perygee Cloud
* **Swipe Action** - On the main directory page, the hub cells have a swipe action handler that allows users to do two things: delete a hub or go directly to editing a hub. By swiping right to left, the user can access these buttons.
* **Deleting** - Swiping all the way from the right to the left will delete the hub from the directory and the Perygee cloud (it is not recommended to delete too many hubs, as this will cause them to be permanently deleted from the Perygee cloud until reinstantiated). The same functionality can be done by pressing the "Delete" button when it shows up from swiping on a cell.
* **Editing** - By pressing on the "Edit" button in the swipe menu, a user can go directly to the hub detail page in edit mode. This allows for faster access into editing the hubs.
* **Search Bar** - The directory page also has a search bar to filter through all the different hubs. This search is based on an auto-generated description made from the hub's details.
* **Collapsible Sections** - The directory page also has collapsible sections. This can be done by pressing the small triangle button on the section header in order to minimize all the hubs in that section

* **Hub Detail Page** - This page holds all the details about a hub, such as its name, IP address, MAC address, etc. This is to provide more details about the hubs and allows a user to segue into the devices that hub protects
* **Live Hub Editing** - On the hub detail page, a user can directly edit the hub on the app, which will then save to the Perygee cloud using a GraphQL mutation. This is done by being in edit mode, which can be achieved by using the edit button from the directory or the edit button in the top-right corner. By being in edit mode, certain fields are enabled for editing -- the name, location, picture and manufacturer of a hub.
Other fields are kept immutable because we considered them as fixed and should not be able to be edited. A user knows when a field is mutable by the thin black box that appears around the field's right side description. The picture can be changed by clicking on the image of the hub in editing mode, and it will allow the user to either take a photo or use a photo from gallery. These text fields can be edited, and by pressing "Save Changes" in the top right corner, a query to the cloud will be made and the changes saved. Upon pressing the button, a timed "Saving..." alert will appear (this is to prevent racing conditions found because of staging a query to the Hasura server).
* **Viewing Device List** - Users can also access the device list that the hub protects by pressing the "Devices" row to segue into the deviceList VC.
* **Device List Page** - This page acts like the directory view, except it lists the devices that a hub protects. Devices would normally be discovered by its hub automatically -- to simulate this, the devices are prepopulated and queried using its linked hub ID.
* **Swipe Action** - Users can swipe to open up the "Edit" button to segue into the device details in editing mode automatically. Unlike the hubs, there is not delete button to delete devices from the hub. We chose to do this in particular for the project because we did not want users to delete a device from the DB permanently, as the only way to add back a hub is through the DB. This is because the device discovery from Perygee was not added to the app, which is how device would normally be added.
* **Viewing Device Details** - Users can access the details of a device by pressing on a device in the device list. This will segue into the details about the device (normally in viewing mode unless the user presses the swipe edit button)
* **Device Detail Page** - This page holds all the details about a device, such as the name, location, manufacturer, priority, etc. It is very similar to the hub detail page, as they both function to list details about a hub or device repsectively.
* **Live Device Editing** - Similar to the hub editing, devices can be live-edited by being in editing mode, which is triggered from the device list swipe edit button or the edit button in the top-right. Fields like the name, priority, location, picture, and manufacturer can be changed (indicated by the thing black box that outlines these fields when in editing mode). Pressing save changes in the top right will trigger a similar GraphQL mutation to change the device details on the Perygee Cloud.
* **Map View Page** - This page has a map that shows the location of all the hubs geographically. Provides a spatial perspective to a network admin of where all their hubs are located.
* **Clustering** - Hub annotations are grouped and clustered together when too close to each other based on the zoom of the user in the map. An annotation that holds the count of the hubs in that cluster shows the general location of this hub. Upon zooming in closer, this cluster breaks into smaller chunks, until each individual hub is visible to the user.
* **Map Viewing Options** - The user has the ability to see the map in three different views: standard, satellite, and hybrid. These viewing options can be changed via the segmented control at the top of the map.
* **View and Edit Segues to Hubs** - By pressing on the annotation of a hub, a user will see the hub's picture and two icon buttons in the annotation -- an eye (for viewing) and pen & paper (for editing). By pressing on either of these buttons, the user will segue into the hub detail page of the selected hub from the annotation in either viewing or edit mode.
* **QR Scanning Page** - This page provides a QR code scanner that is used to instantiate hubs into the Perygee cloud.
* **QR Code Scanning/Hub Instantiation** - Provides an area where a QR code should be placed for scanning. Upon scanning the code, a new hub detail page will be presented modally, indicating that the new hub has been successfully instantiated. When scanning a poorly formatted QR code or the QR code of an existing hub, the app will pop up with an alert to tell the user the error

### Conclusion
Our Perygee companion app is robust and offers many features to network admins for use with the Perygee platform. Despite the core of the app being a simple hub and device directory, by adding supplementary frameworks like the map and QR code scanning, we create a complex and effective app. While there is still work to be done, the app showcases that it has the ability to be well-integrated in the Perygee business model and can be used right now as a demoing tool for fund raising and attracting clients.