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
- username:
- Regular
- username:
smartdispenser
- password:
developer
- username:
- 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.
- Download NodeJS
- Download MongoDB
- Download MongoDB Compass
- Download MongoDB Shell
- 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:
C:\Program Files\nodejs\
C:\Users\{USERNAME}\AppData\Local\Programs\mongosh\
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.
- Open
Zadig
as an Administrator. - Go to
Options
, checkList All Devices
. - 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 wasFFFF 0035 00
(the ProductID is35
). You should check yours from the Device Properties. - On the Driver section, select
WinUSB (v6.X.XXXX.XXXXX)
. - When you are sure that this is the device, the last step is to click
Replace Driver
. - 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.
- Start MongoDB Shell.
- command:
mongosh
- command:
- Create new database named smartdispenser.
- command:
use smartdispenser
- command:
- Check if the database was created successfully. You would see smartdispenser in the list.
- command:
show dbs
- command:
- Use admin database to create new user.
- command:
use admin
- command:
- Create Super Admin user.
- command:
db.createUser({user: "admin", pwd: "developer", roles: ["root", "userAdminAnyDatabase", "dbAdminAnyDatabase", "readWriteAnyDatabase"]})
- command:
- 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"}]})
- command:
- Check if users are successfully created. You would see two users in the list.
- command:
db.system.users.find()
- command:
- Exit MongoDB Shell.
- command:
exit
- command:
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.
- Start MongoDB Shell.
- command:
mongosh
- command:
- Use admin database.
- command:
use admin
- command:
- Shutdown the server.
- command:
db.shutdownServer()
- command:
- Exit from MongoDB Shell.
- command:
exit
- command:
- Start MongoDB service.
- command:
net start MongoDB
- command:
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.
- Download
Smart Dispenser v2.0-Alpha1.zip
from theProduction
folder in Google Drive. - 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
....
- Go to the project directory (using File Explorer) and open file
.env
using text editor. - Modify the
PORT
,USB_VENDOR_ID
, andUSB_PRODUCT_ID
value according to your need. TheUSB_XXX
is the device descriptor of the RFID Reader. You can find the VendorID and ProductID in the device properties. - Open Windows PowerShell as Administrator.
- Go to project directory.
- command:
cd "C:\Smart Dispenser"
- command:
- Install all dependencies.
- command:
npm install --only=prod
- command:
- Run application for the first time.
- command:
node index.js
- command:
- Stop the NodeJS application by pressing
CTRL + C
. If this is not working, you can close Windows PowerShell and open it again. - Start the Application Service.
- command:
net start smartdispenser
.
- command:
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.
- Open Windows PowerShell as Administrator.
- Stop current service.
- command:
net stop smartdispenser.exe
- command:
- Go to project directory.
- command:
cd "C:\Smart Dispenser"
- command:
- Uninstall the service.
- command:
npm run uninstall
- command:
- Make sure that the
daemon
folder inside the project directory has been deleted. If not, you can runnpm run uninstall
once again or just deleting it manually. - After the service has been successfully uninstalled, you can install it again.
- command:
node index.js
- command:
- Stop the server by pressing
CTRL + C
or just closing the Windows PowerShell and open a new one. - Start the service.
- command:
net start smartdispenser.exe
- command:
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.
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.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.
PIN_RELAY
is used by the Relay.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.
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.PIN_PROXIMITY
is used by the Proximity Sensor.PIN_ETHER_XXX
is used by the Ethernet Module. Please note that you need to change theMODE
toTCPClient::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.
PIN_RELAY
as Output.PIN_BUZZER
as Output.PIN_LED
as Output.PIN_BUTTON_STOP
as Input.PIN_WATERFLOW
as Input (Interrupt).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.
MODE
is the connection carrier type. There are two possible mode which isTCPClient::WIFI
andTCPClient::ETHERNET
.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.IP_XXX
andDNS_XXX
are used by WiFi and Ethernet module to connect to the network server using Static Configuration.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.URL
is the server address. You can modify it according to your server setting. The valid format isws://{hostname}:{port}/device
.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:
Admin
can access all the field including modifying device setting, modifying employee list, and modifying users.Manager
can modify employee list but can't modify device setting and user list.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:
/app
is used to manage employee list, user list, and modifying device setting./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 theWeb Application
./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.
Adding
,Updating
, andDeleting
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).Adding
,Updating
, andDeleting
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 alsoReset
andSave
the updated employee. When the Reset button is clicked, the employee field will return to it's original value. ToDelete
and employee, you can Right click-ing it and then choose Delete. In order to add a new employee, you can click theAdd 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.
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 theFlow Constant
. Otherwise, you need to increase theFlow 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.