---
header-includes:
- \usepackage{natbib}
- \usepackage{longtable,booktabs}
- \usepackage{amsmath,amssymb}
- \usepackage{lmodern}
- \usepackage{minted}
- \usepackage{parskip}
- \usepackage{url}
- \title{MANUAL USUARI}
- \assignatura{PROJECTE TECHLAB - Grup E}
- \numpract{MANUAL USUARI}
- \autor{Artur Blaya, Andreu Villaró \& Llorenç Garcia}
- \usepackage{fvextra}
- \DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,commandchars=\\\{\}}
---

###### tags: `IS`

# Terminal físic
## Components

{height=200px}

{height=200px}

## Primera instal·lació
### Cablejat
Primer de tot hem de connectar adequadament tots els cables al terminal. De manera que aquest quedi correctament alimentat i pugui funcionar com és degut.

#### Cable alimentació
A la part inferior de la placa, trobem una placa de desenvolupament anomenada ESP32, amb un connector micro-USB. Connectem el cable en aquest i l'altre extrem del cable a un port USB amb corrent (per exemple el carregador del mòbil).

{height=200px}

#### Màquina a controlar
Al lateral dret de la placa trobem un connector verd de 3 pins. Aquests pins estan connectats a un relé, un dispositiu que actua com un interruptor. Llavors haurem de connectar un dels cables (només un) d'alimentació de la màquina a controlar als dos pins de la dreta

{height=200px}

### Configurar paràmetres
Cada terminal té uns paràmetres concrets els quals s’han de configurar en temps de compilació. Aquests paràmetres inclouen els detalls de la connexió wifi, el broker MQTT i l’identificador de màquina.

Per modificar aquests paràmetres hem d'obrir el fitxer de “parameter.h”, el qual per defecte té el següent aspecte:

#ifndef PARAMETERS_H
#define PARAMETERS_H
 
#include <Arduino.h>
 
#define WiFi_Name "Fibracat_19653"
#define WiFi_Password "404630b333"
 
#define MQTT_Broker "test.mosquitto.org"
#define MQTT_User "rw"
#define MQTT_Password "readwrite"
#define MQTT_Client "Terminal"
#define MQTT_Port 1884
 
#define Terminal_ID "63ab0c155a8b724741a0a9e8"
 
#endif // PARAMETERS_H

Els paràmetres que hem de definir de manera obligatòria són:

* WiFi_Name → SSID del wifi (amb connexió a internet)
* WiFi_Password → Contrasenya del wifi
* Terminal_ID → Identificador del terminal

La resta de paràmetres només s'ha de modificar en configuracions avançades, en la gran majoria de casos s’han de mantenir per defecte.

### Comprovació funcionament correcte
Per comprovar que el terminal està preparat per funcionar correctament, el terminal tindrà les següents característiques:

* Led color vermell
* Missatge pantalla:
* ID Waiting

{height=200px}

#### Possible problema 1
En cas d'haver-hi qualsevol mena de problema amb el wifi, el terminal tindrà
les següents característiques:

* Led color lila
* Missatge pantalla: Waiting wifi

Si dura més d'uns pocs minuts, contactar amb l'administrador del sistema.

{height=200px}

#### Possible problema 2
En cas d'haver-hi qualsevol mena de problema amb el MQTT, el terminal tindrà les següents característiques:

* Led color lila
* Missatge pantalla
* Waiting MQTT

Si dura més d'uns pocs minuts, contactar amb l'administrador del sistema.

{height=200px}

## Funcionament
Un cop tenim el sistema funcionant correctament, podem interactuar amb el terminal de diferents maneres.

### Comprovar reserva
Per comprovar si tenim una reserva associada a una targeta d'identificació, simplement haurem d'apropar la targeta al lector NFC. I en breus instants obtindrem una de les següents situacions:

* Hi ha una reserva disponible
* LED color verd
* Brunzidor fa 1 to de mig segon
* Missatge pantalla: Reserve active

* No hi ha cap reserva disponible
* LED color vermell
* Missatge pantalla: Reserve not found

{height=200px}

{height=200px}

### Standby reserva
Un cop tenim una reserva activa, podem activar o desactivar la màquina sense haver de cancel·lar la reserva completament. Aquest mode de funcionament es diu standby.

Per activar o desactivar aquest mode, ho farem apropant la targeta (associada a la reserva) al lector NFC. Si passem la targeta un cop, activem el mode standby i la màquina s'apaga. Si tornem a passar la targeta, sortim d'aquest mode i la màquina torna a funcionar amb normalitat.

{height=200px}

### Reserva acabada
Un cop la reserva arriba al seu final, aquesta actuarà de la següent manera:

* LED color vermell
* Brunzidor fa 2 tos de mig segon
* Missatge pantalla: Reserve ended

{height=200px}

### Mostrar codi
Quan no disposem d'una targeta física, tenim la possibilitat de mostrar un codi de 5 dígits a la pantalla per verificar que estem davant d'aquesta.

L'aspecte que tindria aquest és el següent:

{height=200px}

\clearpage

# Interfície web
## Pàgina d'inici
En l’extrem superior dret es veu un apartat de login on l’usuari pot iniciar sessió amb el seu compte de google. L’usuari, haurà d’iniciar sessió amb el seu compte de la epsem ja que serà el que estava registrat amb els permisos prèviament. Un cop l’usuari faci el login ja podrà fer les reserves segons el seu nivell de permís.

En la part central veiem l’apartat titulat com a “Màquines disponibles”. En aquest apartat l’usuari pot veure llistades totes les màquines en les que té el permís suficient per a reservar.

{height=200px}

## Reserva de màquines
Un cop el login fet, si l’usuari vol reservar una màquina ha de prémer sobre la màquina. Seguidament haurà de seleccionar una data fent ús d'un calendari, i a continuació seleccioanr una hora.

{height=200px}

Si s'intenta accedir a una màquina sense estar logejat, sortirà l'opció de logejar-se.

Cal tenir clar que quan reservem una màquina de les que estan disponibles, en realitat estem reservant un terminal. Per aquest motiu, és possible que ens apareixen 2 "màquines" amb el mateix nom, en la secció de màquines disponibles.

Un cop es fa una reserva, es mostra les dades de la reserva.

{height=200px}

## Històric de reserves
Aquest apartat està dividit en 3 subapartats, per les reserves passades, actuals, i futures.
Quan s'intenta accedir a un dels tres històrics, sense estar logejat, sortirà l'opció de logejar-se.

{height=200px}

### Reserves Actuals
En el subapartat de reserves actuals veurem la llista de les reserves que estan delimitades entre abans i després del moment actual. Aquí tindrem l'opció de veure la informació de les reserves i també d’activar la reserva des de la pàgina web, per si l’usuari no disposa de la targeta quan està en el laboratori.

Per a activar la reserva l’usuari premerà en activar reserva i en aquell moment en la pantalla led de la SP es mostrarà un codi. En l’aplicatiu apareixerà un input on l’usuari haurà d’entrar el codi i llavors si l’usuari entra el codi correctament, s’iniciarà la reserva. D’aquesta manera podrem assegurar que l’usuari realment està en el laboratori quan activa la reserva, ja que si no, no podria llegir el codi.

Recordem que si l’usuari disposa de la targeta pot passar-la per lector RFID i la reserva s'activa automàticament.

{height=200px}

### Reserves Passades
El subapartat de reserves passades mostra un històric de les nostres reserves passades amb totes les dades de la reserva.

{height=200px}

### Reserves futures
El subapartat de reserves futures mostra una llista de les reserves que encara no han començat i hi haurà la opció de cancelar la reserva. Apareixerà un botó amb el text cancel·lar reserva, si es prem es demana confirmació i es borra la reserva deixant la màquina lliure per a que un altre usuari pugui reservar la màquina en aquell interval de temps.

{height=200px}

## Barra Lateral
A l'extrem superior esquerra hi ha un botó format per 3 línies horitzontal que al ser premut, obra un menú lateral, on es troben enllaços per realitzar determinades accions.

{height=200px}

## Gestió d'errors
Tots els errors de la pàgina web es mostren de la mateixa manera. Quan hi ha algun error, es mostra una finestra on s'indica el motiu de l'error. Aquesta finestra es pot tancar amb la creueta que surt a la banda superior dreta.

{height=200px}

\clearpage

# Inserció de dades en la BD: Pàgina d'admin
Per tal de donar accés al client a la base de dades oferim una secció de la web que consisteix en fer operacions d'administrador. Aquesta secció es tracta d'una pàgina la qual només serà accessible per als usuaris admin ( amb un nivell de permís de 10 o superior).

Des d'aquesta secció els usuaris podran fer operacions relacionades amb afegir borrar i editar instàncies de la base de dades. A continuació s'explicarà en detall quines opcions té el client en aquesta secció i com ha d'afegir la informació per a assegurar un correcte funcionament de l'aplicatiu.

## Usuaris

 {
       email:{
           type: String,
           unique: true
       },
       username: String,
       rfid: String,
       permission: Number
   }

Com veiem en el codi, consta d’un camp de email que actua com a identificador, d’un camp de username, d’un camp de rfid que ha de coincidir amb el valor del rfid de la targeta upc de l’usuari, i permission que pot prendre valors del 0 al 10.
Un usuari podrà reservar una terminal si el seu nivell de permís es igual o superior a aquesta.
Un usuari de nivell 10 és un admin pel que pot realitzar operacions privilegiades. (és pot afegir nivells si és necessari)

Per a la gestió dels usuaris hi ha dues operacions disponibles:


- Borrar usuari:
S'ha d'introduïr el correu del mateix i l'usuari s'elimnara de la base de dades.
- Actualitzar usuari:
S'ha d'especificar el correu de l'usari que es vol modificar i el nou valor del RFID, el seu del grau de permís o els dos. Si es deixa un camp en blanc aquest no es modifica.

No hi ha cap funció per a afegir usuaris ja que aquest es crearà automàticament quan algu realitzi un login de google.

## Màquines
Les instàncies de màquines són els tipus de màquines que es troben en el laboratori. Si per exemple hi ha dos oscil·loscopis iguals només és necessari crear una instància d'oscil·loscopi i aquesta mateixa instància es pot associar a diferents terminals de forma que es podran reservar per separat.

   {
       name: {
           type: String,
           unique: true
       },
       description: String
   },

Identificador únic és el name i el camp de description és una petita descripció que es mostrarà als usuaris quan entrin a reservar la màquina.

Per a la gestió de màquines:

{height=200px}

- Afegir màquina:
Demana els camps del nom i descripció. L'unica restricció es no afegir dues màquines amb el mateix nom. (recordem que si hi ha varies màquines iguals només s'ha de crear una instància de màquina i aquesta s'asocia a diferents terminals)
- Delete màquina:
Esborra la maquina amb el nom especificat

## Terminals
Les terminals són la instància que fa referència a les plaques electròniques físiques que se’ns han facilitat. La estructura és la següent:

  {
       machine_name: String, //name of the associated machine
 
       permission: Number
   },

L'identificador únic de les terminals és el _id que MongoDB afegeix automàticament.
Cada terminal està associada a una màquina. Aquesta associació es fa mitjançant el camp de machine_name, ja que el nom és l'identificador de les màquines. A més les terminals tenen el camp de permission que fa referència al nivell necessari dels usuaris per a poder reservar la terminal. Un usuari podrà reservar una terminal només si el seu nivell de permís és igual o superior al de la terminal.

{height=200px}

- Afegir terminal:
Es crearà una terminal nova asociada a la màquina i amb el permis specificats. La màquina ha d'estar afegida previament abans d'associar una terminal.

- Elimina terminal:
S'entra el id de la terminal que es vol esborrar i aquesta s'esborra. El id s'obté de l'aplicatiu, en la pàgina principal es mostren totes les màquines (que estan asociades a una terminal) i quan entres en els detalls es mostra el terminal_id.

- Bind terminal:
Asocia la terminal especificada a una nova màquina. La asociassió anterioir queda destruida.

- Canviar permís terminal:
Modifica el permís necessari per a reservar la terminal. Les reserves efectuades abans de canviar el permís no es veuran afectades.

Per fer més fàcil la experiencia dels usuaris alhora de reservar l'aplicació mostra que els usuaris estan reservant màquines, tot i que realment estan realitzant reserves de les terminals. Però d'aquesta forma per a ells resulta més intuitiu. No obstant el client ha de tenir clar que les reserves es realitzen sobre les terminals.