Backend

Backend Codebase Overview

The backend source code of the Robot Dashboard is located in the back-end-node-js/ directory, which serves as the root directory of the backend application.

The codebase is organized into several directories and files, each responsible for specific functionality, including API handling, MQTT communication, security, and real-time communication. This separation helps developers navigate the codebase, understand the responsibilities of individual modules, and identify relevant files for maintenance or further development.

The following sections provide an overview of the backend directory structure and the responsibilities of its main files and modules.

Configuration and Customization

The backend contains several configuration settings that allow developers to adapt the system to different requirements.

Some settings can be modified without affecting the underlying application logic, while others require changes across multiple files to maintain proper communication between the frontend, backend, and Robobot

This section outlines the available configuration options, their purposes, and the considerations developers should be aware of before making changes.

Environment Variables

The backend contains two .env files located in different directories, each serving a different purpose:

• Root directory (back-end-node-js/.env): Contains the environment variables used by the main backend application, including AdminPassword and SessionSecret. These variables are used for authentication and session management.

• Scripts directory (back-end-node-js/scripts/.env): Contains environment variables used specifically by scripts and test files within the scripts/ directory. These settings are separate from the main backend configuration.

Main Backend Environment Variables

The main backend .env file contains two environment variables:

• AdminPassword: Stores the bcrypt-hashed administrator password. This value should only be modified when changing the dashboard's login password. The new password must first be hashed using bcrypt before replacing the existing value.

• SessionSecret: Used to sign session cookies and protect their integrity. This value should generally remain unchanged, as modifying it may invalidate existing user sessions. It should only be changed when necessary, such as when rotating a compromised secret.

Both variables contain sensitive information and should not be publicly shared or included in version control.

When modifying environment variables, ensure that the correct .env file is updated, as changes to one file may not affect the other.

For instructions on modifying these settings, see Authentication and Session Configuration.

MQTT Configuration

The MQTT protocol is created in the "mqttConnection.js" file, and is the main file for communicating with the robot. To communicate different commands is used:

• mqttClient.subscribe
• mqttClient.unsubscribe
• mqttClient.publish
• mqttClient.on

mqttClient.subscribe

This is used to make the back-end begin to listen to a certain topic. The syntax of such message is:

mqttClient.subscribe("dtubot/drive/T0/gyroo");

• "dtubot" identifies the robot platform.
• "drive" represents telemetry topics used to receive data from the robot.
• "T0" is dependent on the number of Teensy Boards and is zero-indexed. It mentions which Teensy board it will listen to.
• "gyroo" represents the topic that is subscribed to.

mqttClient.unsubscribe

This is used to make the back-end stop listening to a topic. The syntax of such message is:

mqttClient.unsubscribe("dtubot/drive/T0/gyroo");

• "dtubot" identifies the robot platform.
• "drive" represents telemetry topics used to receive data from the robot.
• "T0" is dependent on the number of Teensy Boards and is zero-indexed. It mentions which Teensy board it will listen to.
• "gyroo" represents the topic that is subscribed to.

mqttClient.publish

This is to send a message to a specific topic, which the robot will receive. The syntax of such message is:

mqttClient.publish("dtubot/cmd/T0", "gyroc Start");

• "dtubot" identifies the robot platform.
• "cmd" represents telemetry topics used to send commands to the robot.
• "T0" is dependent on the number of Teensy Boards and is zero-indexed. It mentions which Teensy board it will listen to.
• "gyroc Start" is the command that is sent to the robot.

mqttClient.on

This function listens to certain MQTT messages from the protocol. The syntax of such message is:

mqttClient.on(title, payload)

The MQTT has different label titles i.e ("message" or "error") and payload is the content that follows that title. These determines what kind of output the MQTT protocol has sent.

If the label title is "message" it will contain a topic and a message.

If the label title is "error" it will contain an error message.

Service filles Configuration

The services/ directory contains files responsible for handling specific backend functionalities and communication between different components of the Robot Dashboard.

Each service is responsible for a particular task, helping separate the application's functionality and making the codebase easier to maintain.

Tab Service

The tabService.js file is responsible for managing MQTT subscriptions based on the active dashboard tab. It communicates with mqttConnection.js to start and stop subscriptions, ensuring that the backend only subscribes to the data required by the selected tab.

The file contains three main functions:

• tabChanged(previousTabTitle, newTabTitle): Handles switching between dashboard tabs by stopping subscriptions associated with the previously active tab and starting subscriptions required by the newly selected tab.
• onlyTabClosed(previousTabTitle): Handles closing the last open tab by stopping its associated MQTT subscriptions.
• tabChangedNoPrevious(newTabTitle): Handles opening a tab when no previous tab was active by starting the subscriptions required by the selected tab.

Each dashboard tab is associated with specific MQTT subscriptions, such as heartbeat data, IMU sensor readings, robot information, and distance sensor data.

When adding a new tab that requires MQTT data, the corresponding subscription handling should be added to the relevant functions in tabService.js.

Socket.IO Configuration

Sockets is the primary method of communication between the front-end and the back-end. There are two primary functions:

• socket.on (used in socket.js)
• io.emit (used in mqttConnection.js)

socket.on

"socket.on" listens for any commands that have been sent with a specific topic from the front end.

io.emit

"io.emit" sends commands to the front-end with a package.

Authentication and Session Configuration

This section explains how to modify the authentication settings used by the Robot Dashboard.

The \security/\ directory contains the script responsible for handling authentication. This script should remain unchanged.

Changing the Administrator Password

The administrator password is stored as a bcrypt hash in the .env file located in the backend root directory.

To change the administrator password, follow these steps:

Step 1: Generate a New Password Hash

1. Open back-end-node-js/scripts/generateHash.js.
2. Locate the variable userPassword and replace its current value with the desired new password.
3. Open a terminal and navigate to the scripts/ directory.
4. Run the following command to generate a new bcrypt hash:

   node generateHash.js

5. Copy the generated hash (the second output in the terminal).

Step 2: Update the Environment Variable

1. Open the .env file located in the backend root directory (back-end-node-js/.env).
2. Locate the AdminPassword variable.
3. Replace its existing value with the newly generated bcrypt hash.
4. Save the file and restart the backend application to apply the changes.
5. To restart the backend application, go to the robot's terminal and type sudo systemctl restart webapp.service

Step 3: Verify the New Password

1. Open back-end-node-js/scripts/testHash.js.
2. Update the test password to match the newly chosen administrator password.
3. Ensure that the test script compares the new password against the newly generated hash.
4. Run the test script from the scripts/ directory:

   node testHash.js

5. The script should return true if the password matches the hash, or false if they do not match.

Note: The administrator password must always be hashed using bcrypt before being stored in the .env file. Never store plaintext passwords in environment variables or commit passwords and hashes to version control.

Session Secret

The SessionSecret variable is used to sign session cookies. It should not be modified during normal configuration.

If the secret needs to be rotated, replace it with a new, securely generated random value. Changing the secret may invalidate existing sessions, requiring users to log in again.

If a new session needs to be generated, type from the root directory node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"