wachidsusilo / smartdispenser Goto Github PK

Below is the default credentials for the database and the application. The admin credential for the application is automatically generated if it doesn't exist.

• Admin
  • username: admin
  • password: developer
• Regular
  • username: smartdispenser
  • password: developer

• username: admin
• password: developer

Download all files below and install them on your windows machine. You may want to choose .msi file as it provide easy installation step.

1. Download NodeJS
2. Download MongoDB
3. Download MongoDB Compass
4. Download MongoDB Shell
5. Download Zadig

After software installation complete, you may need to add the paths below into your system path. To do so, open Windows Search and type Environment in the search field. Choose Edit the system Environment Variables from the search result. The System Properties window will appear, click Environment Variables in the bottom right corner of the window. Inside Environtment Variables window, select variable Path and click Edit. When the Edit environtment variables window appears, click new to add the following path:

1. C:\Program Files\nodejs\
2. C:\Users\{USERNAME}\AppData\Local\Programs\mongosh\
3. C:\Program Files\MongoDB\Server\5.0\bin\

You may need to restart your machine before your terminal recognize the new system path. The next step is to install LIBUSB driver using Zadig. You need to be careful here as installing driver into the wrong device may result an unexpected result. You should make sure that you are selecting the RFID Reader and not another device.

1. Open Zadig as an Administrator.
2. Go to Options, check List All Devices.
3. Select your RFID Reader. The device may be listed as USB Standard Keyboard (Interface 0). You need to make it sure by looking into the USB ID (it's the same as ProductID), in my case the USB ID was FFFF 0035 00 (the ProductID is 35). You should check yours from the Device Properties.
4. On the Driver section, select WinUSB (v6.X.XXXX.XXXXX).
5. When you are sure that this is the device, the last step is to click Replace Driver.
6. After the driver is successfully installed, yo can't use the device as you regularly did. This is important for the sake of the server to be able to access the device. Otherwise, the server will tell you that the device is not supported by the Operating System.

To setup MongoDB Security, you need to open Windows PowerShell and run the following command.

1. Start MongoDB Shell.
   • command: mongosh
2. Create new database named smartdispenser.
   • command: use smartdispenser
3. Check if the database was created successfully. You would see smartdispenser in the list.
   • command: show dbs
4. Use admin database to create new user.
   • command: use admin
5. Create Super Admin user.
   • command: db.createUser({user: "admin", pwd: "developer", roles: ["root", "userAdminAnyDatabase", "dbAdminAnyDatabase", "readWriteAnyDatabase"]})
6. Create a user which will be used by the server to connect to the database.
   • command: db.createUser({user: "smartdispenser", pwd: "developer", roles: [{role: "readWrite", db: "smartdispenser"}]})
7. Check if users are successfully created. You would see two users in the list.
   • command: db.system.users.find()
8. Exit MongoDB Shell.
   • command: exit

After the shell command successfully executed, you need to go to C:\Program Files\MongoDB\Server\5.0\bin (MongoDB installation directory) and open mongod.cfg file using text editor. Add the following configuration command after #security: line.

security:
  authorization: enabled

You may need to restart MongoDB Service to enable authorization feature. To do so, open Windows Task Manager by pressing CTRL + SHIFT + ESC and select Services tab. Find process with name MongoDB, right click it and select restart. You can also restart the service using terminal by running the following commands.

1. Start MongoDB Shell.
   • command: mongosh
2. Use admin database.
   • command: use admin
3. Shutdown the server.
   • command: db.shutdownServer()
4. Exit from MongoDB Shell.
   • command: exit
5. Start MongoDB service.
   • command: net start MongoDB

The insctructions below will guide you to install the NodeJS application as a windows service. The service will run as daemon and will automatically restart it self when the application crashed. The service will automatically started after system boot, so you don't need to start it manually.

1. Download Smart Dispenser v2.0-Alpha1.zip from the Production folder in Google Drive.
2. Copy the file to C:\ drive, and then extract it. The project structure should looks like this:

C:\
  | Smart Dispenser
      | build
      | database
      | oauth
      | routes
      | utilities
  ....

2. Go to the project directory (using File Explorer) and open file .env using text editor.
3. Modify the PORT, USB_VENDOR_ID, and USB_PRODUCT_ID value according to your need. The USB_XXX is the device descriptor of the RFID Reader. You can find the VendorID and ProductID in the device properties.
4. Open Windows PowerShell as Administrator.
5. Go to project directory.
   • command: cd "C:\Smart Dispenser"
6. Install all dependencies.
   • command: npm install --only=prod
7. Run application for the first time.
   • command: node index.js
8. Stop the NodeJS application by pressing CTRL + C. If this is not working, you can close Windows PowerShell and open it again.
9. Start the Application Service.
   • command: net start smartdispenser.

Important! The PORT, USB_VENDOR_ID, USB_PRODUCT_ID and all of it's kind inside .env file are treated as Environtment Variable. These variables are created only the first time when the service created. Whenever you are modifying these variables, you need to reinstall the service. To do so, follow the steps below.

1. Open Windows PowerShell as Administrator.
2. Stop current service.
   • command: net stop smartdispenser.exe
3. Go to project directory.
   • command: cd "C:\Smart Dispenser"
4. Uninstall the service.
   • command: npm run uninstall
5. Make sure that the daemon folder inside the project directory has been deleted. If not, you can run npm run uninstall once again or just deleting it manually.
6. After the service has been successfully uninstalled, you can install it again.
   • command: node index.js
7. Stop the server by pressing CTRL + C or just closing the Windows PowerShell and open a new one.
8. Start the service.
   • command: net start smartdispenser.exe

The following instructions will guide you to setup the ESP32 microcontroller using Arduino IDE.

The pins used in the microcontroller are as shown below. You can change it according to your PCB Schema.

1. PIN_BUTTON_STOP is used by the Stop Button. When the button is pressed, current registered user will be invalidated and the Relay will stop responding to the Proximity sensor.
2. PIN_LED is used by the WS2812B LED. There is only one LED is used. The meaning of the first LED colors are described as the following:
   • RED means the device is offline or cannot connect to the server.
   • YELLOW means the device is online (connected to the server) but there is no user is registered (it is on idle or ready state). The Relay will not respond to Proximity state, unless Temporary Open is set.
   • GREEN means there is a user registered and the device is ready to go. The Relay will respon to Proximity state, and will override Temporary Open setting. It's mean that if the users use their card, their quota will be used instead of the Temporary Open quota.
   • BLUE means the Relay is ON.
3. PIN_RELAY is used by the Relay.
4. PIN_BUZZER is used by the Buzzer. The beep sound of the buzzer is vary according to the device state. The meaning of the buzzer beeps are described as the following:
   • Beep Once means the user quota has been reached.
   • Beep Twice means the user has pressed the Stop Button and it's data has been invalidated.
5. PIN_WATERFLOW is used by the Water Flow Sensor. The water flow sensor needs to be calibrated. The calibration constant (flowConstant) can be set through the web application as an Admin or an Operator. The flowConstant is assigned as double with the default value of 10. Please note that the water output will increase as the flowConstant decrease. It means that the flowConstant of 5 will be outputting more water than the flowConstant of 6.
6. PIN_PROXIMITY is used by the Proximity Sensor.
7. PIN_ETHER_XXX is used by the Ethernet Module. Please note that you need to change the MODE to TCPClient::ETHERNET to be able to use Ethernet as the connection carrier.

Input can be configured as Pulled Up which mean the default state when not pressed is HIGH. Output can be configured as Active Low which should be used if the device is Active Low as well. For example, most of relay modules are Active Low, so it's important to configure PIN_RELAY as Active LOW. This setting can be modified through void setup() by modifying the begin(bool) parameter. relay.begin(true) means the PIN_RELAY is set to Active Low and buttonStop.begin(true) means the PIN_BUTTON_STOP is set to be Pulled Up. The IO pins are described as the following.

1. PIN_RELAY as Output.
2. PIN_BUZZER as Output.
3. PIN_LED as Output.
4. PIN_BUTTON_STOP as Input.
5. PIN_WATERFLOW as Input (Interrupt).
6. PIN_PROXIMITY as Input.

The variables used by the microcontroller are described as the following. Please note that these variables are constant and cannot be modified at runtime.

1. MODE is the connection carrier type. There are two possible mode which is TCPClient::WIFI and TCPClient::ETHERNET.
2. MAC_ADDRESS is the MAC address of the Ethernet Module. You can set the address arbitrarily as long as it's not being used by other device in the same network.
3. IP_XXX and DNS_XXX are used by WiFi and Ethernet module to connect to the network server using Static Configuration.
4. WIFI_XXX is the WiFi credentials. You can modify it according to your ssid and password. If the WiFi is open, you can set the password as an empty string.
5. URL is the server address. You can modify it according to your server setting. The valid format is ws://{hostname}:{port}/device.
6. KEY_XXX is the key of the variable saved in the device database. This value should not be modified.

The server application was build on top of NodeJS Express framework. There is only one server running at a time and is handling all of the incoming request, i.e. authentication, managing database, and responsible for the communication between Web Application and Microcontroller. The key feature is described as the following.

The server is secured by OAuth 2.0 credentials. The web application must use accessToken in order to be able to communicate with the server (except for public area). You can request accessToken using POST request by providing username, password, clientId, and clientSecret to \oauth\token. You can also retrieve accessToken by providing refreshToken to the same address. The refresh token is always sent along with the accessToken.

The default user is admin and will be created automatically when the server start. You can add or modify user through Web Application. There is three different roles of user, which is:

1. Admin can access all the field including modifying device setting, modifying employee list, and modifying users.
2. Manager can modify employee list but can't modify device setting and user list.
3. Operator can modify device setting and read employee list (only read, modifying employee list is not allowed). Operator can't access user list.

The communication between client and server are using WebSocket. There is no single REST API defined in this server. All of the transactions are cached on both server and client, and will be destroyed after the client has been signed out. There are three different Web Socket servers available, which is:

1. /app is used to manage employee list, user list, and modifying device setting.
2. /data is a public area, which means any client can access it without providing credentials. This socket is only used by the server to send currently registered employee (i.e. when an employee tap a card) to the Web Application.
3. /device is used by the Microcontroller to communicate with the server.

Upon connecting to the Web Socket server, the client must provide ticket as part of the url query (only if you are trying to connect to \app), otherwise the connection will immediately be closed by the server. You can retrieve a ticket by doing POST request to \oauth\ticket. Please note that the ticket can only be used once and only valid for one minute. The request must be composed with the following schema.

{
    type: "reg" | "action",
    data: {
        command: "add" | "get" | "update" | "delete",
        content: object
    }
}

There are four pages in the web application, including Home, Login, Dashboard, and History. Each of them are described in the following section.

Home is a public area, any client can access it. The main purpose of the home page are to display current active employee (i.e. any employee which is tapping the card).

Login page is used to authorize a user using username and password. Whenever an unauthenticated user trying to access another page (except Home), they will be redirected into this page.

Dashboard page is used for managing employee list, user list, and device setting. The visual and/or functional elements are different between users, depending on their role. An Admin can access all of the available options, whereas a Manager or an Operator can only access part of the available options. The functionality of this page are as described below.

1. Adding, Updating, and Deleting users. This feature is only available for Admin. You can access this functionality inside the Setting section of the page (by clicking the Setting icon).
2. Adding, Updating, and Deleting employees. This feature is only available for Admin and Manager. You can update an employee by selecting it in the list. By doing so, you can also Reset and Save the updated employee. When the Reset button is clicked, the employee field will return to it's original value. To Delete and employee, you can Right click-ing it and then choose Delete. In order to add a new employee, you can click the Add Employee button. Right after you click it, a Modal will appear, you need to fill all of the necessary field to continue. You may notice that after Adding or Updating an employee, a colored marker showing up in the right corner of the field. The meaning of each marker colors are described as of the following.
   • RED means there is error in the field (e.g. there is an empty field). Whenenever this happens, the Save button is grayed out and you can't save the updated value.
   • ORANGE means the value has been modified but is not saved yet.
   • GREEN means a newly added employee. An employee is considered as new if it was created less than a day ago.
3. Modifying Device Setting. This feature is only available for Admin and Operator. You can access it by click-ing the setting icon. All of the available options for Device Setting are described below.
   • Status tells whether the device is currently connected to the server. If so, the indicator will show online, otherwise it will show offline.
   • Pump tells whether the Relay is currently active. If so, the indicator will show ON, otherwise it will show OFF.
   • Flow Constant is the calibration constant of the water flow sensor.
   • Auto Invalidation Timeout is used to determine how long an employee (i.e. who is tapping their card) is held active. You can still press the Stop Button to immediately invalidate the currently active employee. Please note that when an employee triggering (approaching) the Proximity sensor, the timeout will be cancelled, and will be set again after the employee is away from the sensor (or when it's quota has been reached).
   • Temporary Open tells the microcontroller to temporarily open it's functionality for the given quota. It means that anyone can get a water without tapping their card. Please note that if an employee tapping their card, their quota will be used instead of the Temporary Open quota. This feature is very useful to be used as calibration tools. For example, you can set the Temporary Open value to 100 ml, then you can take water using a measuring cup. If the water that comes out is less than 100 ml, then you need to reduce the Flow Constant. Otherwise, you need to increase the Flow Constant until the water that comes out is around 100 ml.

History page gives you information about how much water is used by the employee each day. You can save it as .json or .xlsx format. If you want to go to the Dashboard page, you can click the dashboard icon. You can always go back to the Home page by click-ing the application icon on the top-left corner.