Smart Locks Control USER MANUAL. Team 5

Transcription

1 Smart Locks Control USER MANUAL Team 5 Vaibhav Vishal Mohammadreza Barazesh Hao-Yun Yang Zhe Wang Katarzyna Ruszowska Diego Brandao Alejandro Monroy Reyes University of Southern California CS 577 December, 2017 Smart Locks Control USER MANUAL Page 1

2 Revision Sheet Releas Date Revision Description Editor e No. Rev. 0 12/03 User Manual first draft Mohammadreza Barazesh /17 Rev. 1 12/03 Added section 4.0 instructions Alejandro Monroy /17 Rev.2 12/04 Adding section 1 Hao-Yun Yang /17 Adding section 2 Rev.3 12/04 /17 Review of correctness and minor modifications to finalize document for submission Katarzyna Ruszowska Smart Locks Control USER MANUAL Page 2

3 USER MANUAL TABLE OF CONTENTS 1.0 GENERAL INFORMATION 5-6 Page # 1.1 System Overview Organization of the Manual Acronyms and Abbreviations SYSTEM SUMMARY System Configuration Data Flows User Access Levels GETTING STARTED Setting up the hardware Setting up the server Installing the prerequisites Setting up the database Deploying the Docker Image Logging In Navigation Menu Exit System USING THE SYSTEM (ONLINE) Locks Add new slot Delete slot Update slot Assign random codes Hubs View Hub Status Logs View all logs Filter logs Users Add user Edit user Delete user My Profile Change user s password Smartthing View current configuration Special Instructions for Error Correction Caveats and Exceptions 28 Smart Locks Control USER MANUAL Page 3

4 Smart Locks Control USER MANUAL Page 4

5 1.0 GENERAL INFORMATION 1.0 GENERAL INFORMATION In this section, we will provide a brief system overview and explain the organization of the manual. Smart Locks Control USER MANUAL Page 5

6 1.1 System Overview This system is designed to help customers save time and money by allowing them to remotely manage their smart locks. In addition, this system provides a user hierarchy that enables customers to assign separate house managers for different houses who can help manage locks and house staff users associated with their assigned house. Furthermore, this system also allows the system administrator and house manager to create users with lower permission levels and assign temporary passwords to specific lock slots and users. Finally, this system improves security by providing a log system through which the system administrator and house managers can view and filter records of lock status changes. 1.2 Organization of the Manual The user manual consists of four major sections: General Information, System Summary, Getting Started, Using The System (Online). The General Information section explains the system and its purpose in general terms. The System Summary section provides a general overview of the system. The summary includes the uses of the system s hardware and software, system configuration, data flows, and user access levels. The Getting Started section explains how to install Smart Locks Control on the server, and how the user should set up the hardware before using the system. The Using The System (Online) section provides a detailed description of system functions with screenshots. 1.3 Acronyms and Abbreviations Samsung SmartThings: Samsung SmartThings is a product with its own server produced by Samsung to implement the Internet of Things communication with different kinds of devices. Smart Locks Control USER MANUAL Page 6

7 1.3.2 Hub In the Smart Locks Control system, we use SmartThings hubs produced by Samsung Administrator: The highest user level in Smart Locks Control. The administrator will probably be either the house owner himself/ herself or a person assigned by house owner House managers: The middle user level in Smart Locks Control. Those people assigned by the house owner or administrator to help with house management for different houses House staffs: The lowest user level in Smart Locks Control. Those people who do menial tasks to maintain the houses, such as cleaning or gardening Slots: Each lock allows for multiple access code to be associated with it, each of those code is stored in a specific slot. Smart Locks Control USER MANUAL Page 7

8 2.0 SYSTEM SUMMARY Smart Locks Control USER MANUAL Page 8

9 2.0 SYSTEM SUMMARY The System Summary section provides a brief overview of the Smart Locks Control system. The summary points out the requirements in terms of system hardware and software, system configuration, data flows, and user access levels. 2.1 System Configuration Smart Locks Control is a web-based management system for lock control. So far, this system supports use with Google Chrome and Firefox web browsers. Before installing Smart Locks Control on a server, the user must have a Samsung SmartThings account, and connect all locks to appropriate hubs and all hubs to the SmartThings account. For the software application part, the system requires connection to the Internet in order to retrieve data from the server. After preparation of the hardware and installation of the software on the server, Smart Locks Control is ready to fulfill the needs of its users from any web browser. 2.2 Data Flows Figure 1 shows the flow of data in Smart Locks Control system. When users open the website in a browser, they will see the login page first. After login, the web page will show a specific dashboard based on the permission level of the logged in user. Based on user s action, the system sends a request to the back-end. The back-end communicates with the database and Samsung SmartThings server, based on the user request. Finally, the Samsung SmartThings server sends the data to the hub if the user made any change to a lock, and the hub will update the lock with the change. Figure 1. Smart Locks Control USER MANUAL Page 9

10 2.3 User Access Levels This system separates users into three levels of access. For the highest level, we have a user called the administrator and created during initialization of the Smart Locks Control system. The current system supports exactly one system administrator for each local server. This user will have the ability to view/add/delete second and third level users, view/add/delete/modify/assign lock slots, and view all system logs for all locks. The middle level consists of users created by the administrator called house managers. Smart Locks Control allows the administrator to create multiple house manager accounts to help with management of third level users and locks. House managers have a lower permission level than the administrator; they can only create third level user accounts, view/add/delete/modify/assign lock slots of locks or hubs assigned to them, and view system logs of locks assigned to them or to the house staff users associated with them. The lowest level includes users called house staff, which the administrator or house managers can create. Smart Locks Control allows the administrator or house managers to assign locks to house staff users. The house staff users can only view all slots assigned to them and modify their own passwords. House staff can have lock slots assigned to them by the administrator or house managers of any building at which they work. Smart Locks Control USER MANUAL Page 10

11 3.0 GETTING STARTED Smart Locks Control USER MANUAL Page 11

12 3.0 GETTING STARTED This section provides a general walkthrough of the system from initiation through exit. The logical arrangement of the information shall enable the functional personnel to easily understand the sequence and flow of the system. 3.1 Setting up the hardware To set up the hardware you need to make sure you have the following items ready: Samsung SmartThings hubs Compatible locks LAN Internet access for the hubs Next, you need to make sure that all the locks are paired with their respective hubs. To do so, please refer to the instruction manual of each chosen lock. After pairing all the locks, you can now set up the device handler and the SmartApp. Follow these steps carefully: 1- Log in to your SmartThings IDE at (create a login if you don't have one AND don't forget to opt in for the developer account). To verify that you're logged in to the correct location, after logging in at the above link, click on "My Locations" and then click on the name of the location at which you want to install the SmartApp. Note: You may be asked to log in to your account again when you click on your location; if so, log in again. 2- Click on "My Device Handlers". 3- Click on "+New Device Handler" on the top right. 4- Click "From Code". 5- Paste the code (Ctrl + V) into the editor and click "Create". You can find the code for the device handler in the.\devicetypes\rboy\universal-zwave-lock-with-alarms.src project folder. 6- Click "Publish" and then "For me" on the top right. 7- Click on "My Devices" on top. 8- Click on your existing device (thermostat/lock etc which you want to change). 9- Scroll down and click on "Edit". 10- Under "Type *" select the new device handler you just created (it will show up at the bottom of the list). 11- Scroll to the bottom of the page and click "Update". 12- Open the SmartThings App on your phone and under "My Home" look for your new device. Smart Locks Control USER MANUAL Page 12

13 Next, you will need to install the provided SmartApp. To do so please follow the following steps: 1- After logging in to the SmartThings website, click on MySmartApps. 2- Click on + New SmartApp. 3- Click on From code tab. 4- Copy and paste the code. you can find the code for the SmartApp in the.\smartapps\vaibhavx\smart-locks-control.src folder. Finally, you will need to write down the Client ID and Client Secret parameter as you will need them in the next section. To do so: 1- Click on My Smart Apps. 2- Click on Smart Locks Control. 3- Click on App Settings. 4- Scroll down and click on OAuth You will find the Client ID and Client Secret here. 3.2 Setting up the server Installing the prerequisites For the system to work, it needs to be set up on a linux server alongside the following required softwares: MySQL Server Node.js NPM Docker You can install the mentioned applications using the apt package manager with the following commands : sudo apt-get update sudo apt-get install nodejs mysql-server mysql-client docker Setting up the database After carrying out the necessary installations, the system requires the creation of a mysql database. The database needs to be created using the default credentials unless they are overridden: Database name : smart_locks_control Root password: diversity05 You can override these credentials in the./webapp/server/db/config.json file Deploying the Docker Image Smart Locks Control USER MANUAL Page 13

14 Finally, the setup can be completed by deploying the docker image. To do so, first docker needs to be started which can be achieved by running the following command in the linux shell: sudo systemctl start docker Next, you need to log in to the docker repository and retrieve and deploy the latest version of the system. When asked for username and password, make sure to use the following credentials: Username: softwarediversity05 Password: diversity05 sudo docker login sudo docker pull softwarediversity05/smart-locks-control:latest sudo docker run -d -e -p 3000:3000 -p net=host softwarediversity05/smart-locks-control:latest After running these commands, the website should be running on ADDRESS>:3000. Next you will need to connect the website to the SmartThings platform. To do so, use the above address to log in to the website. Use the default administrator credentials ( provided separately ) to access the administrator dashboard. Click on the SmartThings button in the left sidebar. In the opened page, enter your Client ID and Client Secret. You may obtain them by following the instructions in section [3.1]. Next click on the Update Settings button. Finally, click on Log in to SmartThings button. You will then be redirected to the Samsung SmartThings website where you might need to login if necessary. After logging in, you will be shown a new page similar to the following picture. Smart Locks Control USER MANUAL Page 14

15 Choose any of the available options in the From: select field, and then click on the Authorize button. If authorization is successful, you will be brought back to the administrator dashboard. Now the system is completely configured and ready to be used. 3.3 Logging In After opening the website, the user will be greeted with a login page where they can enter their username and password to enter their personal dashboard in order to use the website. 3.4 Navigation Menu The navigation menu is located at the left side of the screen and allows the user to access the different parts of the system by simply clicking on the related button. We will discuss each of the options briefly here and in depth in section [4] Locks This page allows the users to access all the locks that they are assigned to, and to add or modify new slots if they are authorized to do so Hubs Smart Locks Control USER MANUAL Page 15

16 This page will allow users to view the status of the hubs and their associated locks. Information such as lock battery percentage and whether the locks are locked/unlocked can be retrieved by viewing this page Users This page contains a list of all the users. The administrator and managers can use this page to add new users to the system or edit/delete the existing ones Logs This page provides the administrator and the managers with logs of all the events related to the locks. This data can then be sorted and filtered by user, lock and date My Profile This page provides users the ability to view their basic information such as name and username and to change their passwords SmartThings This page will allow the Administrator to view or update the current configuration, and to link the system with a SmartThings account as part of the initial setup of the system. 3.5 Exit System After 30 minutes of inactivity the user will be signed out of the system for security reasons. However they can choose to do so manually if they desire by clicking on the sign out button at the top-right corner of the screen as shown in the picture below. Smart Locks Control USER MANUAL Page 16

17 4.0 USING THE SYSTEM Smart Locks Control USER MANUAL Page 17

18 4.0 USING THE SYSTEM This section provides a detailed description of the Smart Locks Control system from initiation through exit, explaining in detail the characteristics of the required input and system-produced output. 4.1 Locks This page contains a list of all the slots that have been set on the locks. The administrator and house managers can use this page to assign new slots to users Add new slot To add new slots and assign them to users of lower permission levels, the administrator or house managers need to perform the following steps: 1. Select Locks tab in the sidebar. 2. Select a Hub from the hubs list. 3. Click get slots button. 4. Click add new slot button. 5. Select a user to assign the slot, select the lock, select the slot number and enter a 4-digit code. 6. Click add slot button Delete slot To delete an assigned slot, the administrator or house managers need to perform the following steps: 1. Select Locks tab in the sidebar. 2. Select a Hub from the hubs list. 3. Click get slots button. 4. Select a slot or slots to delete. 5. Click delete slot button. Smart Locks Control USER MANUAL Page 18

19 4.1.3 Update slot To update an assigned slot, the administrator or house managers need to perform the following steps: 1. Select Locks tab in the sidebar. 2. Select a Hub from the hubs list. 3. Click get slots button. 4. Select a slot or slots to update. 5. Add 4-digit codes to the selected slots. 6. Click the update slots button Assign random codes To assign random codes to assigned slots, the administrator or house managers need to perform the following steps: 1. Select Locks tab in the sidebar. 2. Select a Hub from the hubs list. 3. Click get slots button. 4. Select a slot or slots to update. 5. Click random code button. 6. Click the update slots button. Smart Locks Control USER MANUAL Page 19

20 4.2 Hubs This page will allow user to view the status of the hubs and their associated locks. Information such as name, lock battery percentage and whether the locks are locked/unlocked can be retrieved by viewing this page View Hub Status To view the hub statuses, the administrator or house managers need to perform the following steps: 1. Select hubs tab in sidebar. 2. Select a hub in the drop down menu. 3. Click the get locks button. 4. Hub status will be showed. If the hub is offline a red label will appear. If the hub is online a green label will appear. 5. The user will be able to see all information related to locks associated with the hub. 4.3 Logs In this page, the administrator and house managers will be able to view a detailed log of all the events. They are also able to filter the logs by user, lock, and date and sort them if desired. Smart Locks Control USER MANUAL Page 20

21 4.3.1 View all logs To view all the logs, the administrator or house managers need to perform the following steps: 1. Select logs tab in sidebar. 2. In the new page shown below, click on Search. 3. The results will be shown Filter logs To filter the logs based on user, lock, or date, the administrator or house managers need to perform the following steps: 1. Select logs tab in sidebar. 2. Set the filters by selecting a lock, username, and/or a date. Note that all the filters are optional and you may use one or many at the same time. 3. Click on the search button. 4. You will be presented with the filtered results. Smart Locks Control USER MANUAL Page 21

22 4.4 Users The users tab contains all information related to users registered in the system. The administrator and house managers can use this page to manage users. The administrator is able to add new house managers and house staff, delete users, and update user information such as name, username, role, status, and password. The house managers may only to add, update, and delete house staff users Add user To add new users the administrator or house managers need to perform the following actions: 1. Select users tab in sidebar. 2. Click add new user button. 3. Fill all required fields. a. Name: Must be 6 characters minimum. b. Username: Must be 6 characters minimum. c. Role: Select from dropdown list. d. Password: Must be at least 6 characters and contain at least 1 lowercase letter, 1 uppercase letter and 1 number. e. Active user: Activate or deactivate user. 4. Click add user Smart Locks Control USER MANUAL Page 22

23 All fields are validated before adding a user. The new name, username, role and password must meet the requirements. 1. Every field is validated to ensure data consistency. 2. Add user button is disabled if data is not correct and complete Edit user To edit existing users the administrator or house managers need to perform the following actions: 6. Select users tab in sidebar. 7. Select a user by clicking the radio button. 8. Click update user button. 9. Update information to update. 10. Click update user button. Smart Locks Control USER MANUAL Page 23

24 4.4.3 Delete user To delete existing users the administrator or house managers need to perform the following actions: 1. Select users tab in sidebar. 2. Select a user by clicking the radio button. 3. Click update user button. 4. Click delete user button. 5. Confirm user deletion by clicking OK in the alert box. 4.5 My Profile This page provides the users the ability to view their basic information such as name and username, as well as to change their password. Smart Locks Control USER MANUAL Page 24

25 4.5.1 Change password Every user can change his own password by performing the following steps: 1. Select my profile tab in the sidebar. 2. Add a new password. 3. Confirm the new password. 4. Click update password button. Password should meet the following requirements: 1. Password must be at least 6 characters and must include at least one uppercase letter, one lowercase letter and one numeric digit. 2. If the requirements are not met the update password button will be disabled. Smart Locks Control USER MANUAL Page 25

26 4.6 SmartThings This page will allow the administrator to view/update the current configuration or link the system to a SmartThings account as part of the initial setup View current configuration What follow is the instructions to view the current configuration: 1. Select SmartThings tab in the sidebar. 2. In the opened page, you can see your current Client ID and Client Secret. 3. At the bottom of the page you will be able to see all the available locations that are linked to this account Update configuration To update the current configuration the next steps need to be performed: 1. From the navigation panel at the left side of the screen, click on the Smartthings tab. 2. Update Client ID field. 3. Update Client Secret field. 4. Click update settings button. Smart Locks Control USER MANUAL Page 26

27 4.6.3 Link to SmartThings account Please refer to section [3.2.3]. 4.7 Special Instructions for Error Correction The application itself handles error properly. When an action is performed correctly the user will receive a success alert on top of the page. On the other hand, if an action was not performed correctly the user will receive a warning indicating the error. 4.8 Caveats and Exceptions Due to the asynchronous nature of all the requests made to the SmartThings server there are some exceptions that need to be taken in consideration: 1. When adding or updating a new slot there is a probability of 1/5000 which is equal to.02% that the code that has been set is equal to the master code of the lock. In this case there will be an error while setting the code and it will not work properly. 2. If the information in the Samsung server is inconsistent or not up to date, the system may fail when setting codes. E.g. When the user tries to modify a slot in a lock that Samsung reports as active but the lock is not actually active the lock will not be set correctly. In this case the guest should contact the house manager or administrator to obtain a new code. Smart Locks Control USER MANUAL Page 27