Hướng Dẫn Cài Đặt & Khởi Chạy Hệ Thống AquaSTEM

Hệ thống IoT + AI giám sát và tối ưu hóa môi trường nuôi trồng thủy sản (STEM Education). Khởi chạy đồng bộ và nhanh chóng sử dụng nền tảng container Docker.

1 Tổng Quan & Chuẩn Bị Cấu Hình

Tìm hiểu kiến thức nền tảng và kiểm tra yêu cầu phần cứng trước khi thiết lập hệ thống AquaSTEM.

1. Giới Thiệu Dự Án & Ứng Dụng Phương Trình Vi Phân (PTVP)

AquaSTEM sử dụng phương trình vi phân để tính toán và dự báo lượng Oxy hòa tan (DO - Dissolved Oxygen) trong nước theo thời gian thực.

Giải thích PTVP một cách trực quan (Dành cho học sinh)

Phương trình vi phân không hề đáng sợ, nó chỉ đơn giản là cách đo lường "Sự thay đổi":

Hãy tưởng tượng lượng Oxy hòa tan giống như mực nước trong bể cá:

Công thức tính đơn giản: Oxy mới = Oxy cũ + (Lượng Nạp vào - Lượng Tiêu thụ) * Khoảng thời gian.

Nhờ PTVP, hệ thống có thể dự đoán trước xem cá có bị ngạt khí hay không, từ đó tự động ra lệnh bật máy sục khí (Relay) kịp thời.

2. Yêu Cầu Cấu Hình Thiết Bị

Thành Phần Thông Số Yêu Cầu Trạng Thái
Hệ Điều Hành Windows 10/11 (Home 21H2+, Pro, Enterprise) hoặc macOS ✓ Khuyên dùng Win 10/11
Bộ nhớ RAM Tối thiểu 8GB (Khuyến nghị 16GB để chạy Docker tối ưu) ✓ Khuyên dùng
Ổ Cứng trống SSD tối thiểu 10GB dung lượng trống ✓ Tải tài nguyên & build
Quyền Tài Khoản Quyền Quản trị viên (Administrator) để cấu hình ảo hóa & Docker ✓ Bắt buộc
Đường Truyền Mạng Tốc độ ổn định (cần tải khoảng 2-3GB thư viện/images ở lần đầu chạy) ✓ Quan trọng

2 Cài Đặt Git & Visual Studio Code

Cấu hình Git để tải mã nguồn từ GitHub và cài đặt trình soạn thảo VS Code.

1

Cài Đặt Git

1. Truy cập trang tải chính thức và tải bộ cài đặt cho Windows: Tải Git chính thức

2. Nhấp đúp chuột vào file vừa tải về để chạy trình cài đặt. Cứ bấm Next liên tục cho đến khi hoàn thành (giữ nguyên cấu hình mặc định).

3. Kiểm tra: Nhấp vào hộp tìm kiếm trên thanh Taskbar của Windows, gõ PowerShell -> Mở PowerShell lên và chạy lệnh sau để kiểm tra xem đã cài thành công chưa:

powershell 
git --version

Nếu hiển thị phiên bản Git (ví dụ: git version 2.x.x) là thành công!

Cách làm nhanh không cần cài Git
Nếu bạn không sử dụng lệnh git clone, bạn có thể tải file mã nguồn dạng nén ZIP từ liên kết Google Drive ở Phần 4 rồi giải nén ra. Cách này giúp bạn bỏ qua bước cài đặt Git.
2

Cài Đặt Trình Soạn Thảo VS Code

Visual Studio Code (VS Code) là công cụ soạn thảo mã nguồn và quản lý dự án phổ biến nhất hiện nay.

1. Tải bộ cài đặt: Tải VS Code cho Windows

2. Chạy file cài đặt. Lưu ý quan trọng: Tại màn hình cấu hình bổ sung, hãy tích chọn các ô:

  • "Add 'Open with Code' action to Windows Explorer directory context menu" (Để mở nhanh thư mục dự án)
  • "Add to PATH" (Để chạy được lệnh code từ dòng lệnh)

3. Cài đặt các Extension hỗ trợ học tập: Mở VS Code lên, bấm vào biểu tượng Extensions (hình 4 ô vuông nhỏ ở thanh công cụ bên tay trái màn hình, hoặc bấm phím tắt Ctrl + Shift + X), tìm kiếm và bấm **Install** các gói sau:

  • Docker (do Microsoft phát hành): Dùng để theo dõi trạng thái hệ thống chạy ngầm.
  • Prettier - Code formatter: Tự động căn lề và định dạng code đẹp mắt, gọn gàng.
  • Vietnamese Language Pack (Tùy chọn): Nếu bạn muốn chuyển đổi giao diện VS Code sang tiếng Việt để dễ sử dụng.

3 Cài Đặt Docker Desktop & WSL 2

Chuẩn bị nền tảng ảo hóa Docker để chạy đồng bộ hệ thống dịch vụ nhanh chóng.

1

Kích Hoạt Ảo Hóa Trong Windows (Virtualization)

Để chạy được Docker (hệ thống chạy ngầm các dịch vụ), máy tính của bạn phải bật tính năng ảo hóa (Virtualization) trong CPU.

Cách kiểm tra:

  1. Nhấn tổ hợp phím Ctrl + Shift + Esc để mở Task Manager.
  2. Chọn tab Performance ở bên trái (hoặc phía trên) -> Chọn mục CPU.
  3. Nhìn góc dưới cùng bên phải, tìm dòng Virtualization. Nếu thấy hiển thị là Enabled (Đã bật) là bạn đã sẵn sàng!
Nếu Virtualization hiển thị là "Disabled" (Chưa bật)
Bạn cần khởi động lại máy tính, liên tục nhấn phím cấu hình BIOS (thường là F2, F12, hoặc Del tùy dòng máy) và tìm bật tính năng Intel Virtualization Technology (VT-x) hoặc SVM Mode (AMD) lên, sau đó lưu lại và khởi động vào Windows.
2

Cài Đặt WSL 2 (Windows Subsystem for Linux)

WSL 2 giúp chạy nhân hệ điều hành Linux trực tiếp trên Windows, đây là nền tảng bắt buộc để Docker hoạt động siêu nhẹ và nhanh.

1. Nhấp vào thanh tìm kiếm Windows -> Gõ chữ PowerShell -> Nhấp chuột phải vào biểu tượng **Windows PowerShell** -> Chọn Run as administrator (Chạy dưới quyền Admin).

2. Sao chép và dán lệnh sau vào cửa sổ PowerShell vừa hiện ra, rồi nhấn **Enter**:

powershell (admin) 
wsl --install

3. Chờ quá trình cài đặt tự động diễn ra hoàn tất. Sau đó, bạn BẮT BUỘC phải khởi động lại máy tính.

3

Cài Đặt Và Khởi Chạy Docker Desktop

1. Tải về trình cài đặt: Tải Docker Desktop cho Windows

2. Chạy tệp tin cài đặt vừa tải về. Tại màn hình cài đặt đầu tiên, chú ý tích chọn ô "Use WSL 2 instead of Hyper-V (recommended)".

3. Sau khi cài đặt hoàn tất, tìm biểu tượng **Docker Desktop** trên màn hình Desktop và mở nó lên. Nhấn đồng ý điều khoản sử dụng nếu có.

4. Kiểm tra trạng thái: Đợi khoảng 1-2 phút, nhìn vào góc dưới cùng bên trái cửa sổ Docker Desktop. Khi nào thấy **biểu tượng chú cá voi chuyển sang màu xanh lá cây** là Docker đã hoạt động hoàn toàn!

4 Khởi Chạy Hệ Thống Bằng Docker Compose

Cách thức nhanh nhất để dựng đồng thời MQTT Broker, Backend API và Frontend Dashboard chỉ bằng một câu lệnh.

1

Tải Mã Nguồn Và Truy Cập Thư Mục Dự Án

Cách 1: Tải trực tiếp tệp nén ZIP từ Google Drive (Khuyên dùng cho người mới bắt đầu)

Tải toàn bộ thư mục dự án qua liên kết dưới đây:

Tải tệp ZIP dự án từ Google Drive

Sau khi tải về, hãy nhấp chuột phải vào file ZIP -> Chọn Extract All... (Giải nén tất cả) để đưa các file mã nguồn ra một thư mục thường trên ổ đĩa máy tính (ví dụ: ổ D: hoặc C:).


Cách 2: Tải bằng lệnh Git Clone (Khuyến khích nếu bạn muốn hiểu chuyên sâu hơn về lập trình, về Git).

Mở PowerShell thường, di chuyển tới thư mục muốn lưu dự án và chạy các dòng lệnh sau:

powershell 
git clone https://github.com/duongbill/ptvp.git
cd ptvp
2

Mở Thư Mục Bằng VS Code Và Khởi Chạy Hệ Thống

Đây là bước chạy lệnh để Docker tự động cài đặt và ghép nối các dịch vụ (Frontend, Backend, MQTT Broker) lại với nhau.

1. Mở thư mục bằng VS Code:

  • Mở phần mềm VS Code lên.
  • Chọn menu File ở trên cùng bên trái -> Chọn Open Folder... (Mở thư mục).
  • Tìm chọn thư mục dự án ptvp vừa được giải nén ra (hoặc clone về) và nhấn Select Folder.

2. Mở cửa sổ Terminal (dòng lệnh) trong VS Code:

  • Trên thanh menu trên cùng của VS Code, chọn Terminal -> Chọn New Terminal (Cửa sổ Terminal mới sẽ hiện ra ở cạnh dưới màn hình).
  • Hoặc nhấn phím tắt: Ctrl + ` (dấu nháy đơn nằm dưới phím Esc trên bàn phím).

3. Chạy lệnh khởi dựng Docker Compose:

Sao chép câu lệnh dưới đây, dán vào dòng lệnh Terminal trong VS Code và nhấn Enter:

terminal (VS Code) 
docker compose up -d --build
Lưu ý quan trọng về thời gian tải lần đầu
Lần đầu tiên chạy lệnh này, Docker sẽ cần tải các gói cài đặt cơ sở từ Internet (~2-3GB) nên sẽ mất khoảng 5 đến 15 phút tùy thuộc vào tốc độ mạng của bạn. Các lần khởi chạy sau sẽ chỉ mất khoảng vài giây. Hãy kiên nhẫn chờ đến khi cửa sổ Terminal ngừng chạy chữ và hiển thị trạng thái hoàn tất thành công.
3

Truy Cập Ứng Dụng

Sau khi hệ thống khởi chạy thành công, bạn mở trình duyệt và truy cập các địa chỉ sau:

Dịch Vụ Địa Chỉ (URL) Trạng Thái
Frontend Dashboard http://localhost:3000 ✓ Hoạt động
Backend API Docs http://localhost:8000/docs ✓ Swagger UI
MQTT Broker localhost:1883 ✓ Chạy ngầm

5 Kết Nối Phần Cứng ESP32 & Kiến Trúc IoT

Cấu hình kết nối ESP32 qua cáp USB và duy trì kiến trúc Event-driven bằng MQTT bên trong Docker.

1. Lưu Ý Kỹ Thuật Vận Hành

An toàn điện áp thấp
  • Nguồn cấp an toàn: ESP32 chạy hoàn toàn dưới 5V qua USB, an toàn cho người dùng và học sinh.
  • Ổn định cảm biến: Cấp đúng chân 5V/3V3 để tránh sụt áp làm sai số đo.
  • Chống đoản mạch: Không để các đầu nối chạm nhau khi đang cấp nguồn.

2. Kiến Trúc Hệ Thống Mới (Ưu tiên)

Mô hình giữ kiến trúc Event-driven qua MQTT nhưng loại bỏ phụ thuộc Wi-Fi cấu hình phức tạp, vẫn chạy đồng nhất nhờ Docker.

Luồng dữ liệu chuẩn hóa
[ESP32] --(USB/COM)--> [Python Bridge] --(localhost:1883)--> [MQTT Broker (Docker)] --(Subscribe)--> [Backend]
Ưu điểm nổi bật
  • Không bị giới hạn khoảng cách: Có thể đặt ESP32 ở xa khi dùng Wi-Fi hoặc gateway.
  • Hỗ trợ đa thiết bị (Scalability): Nhiều node cảm biến cùng publish về một Broker.
  • Môi trường đồng nhất nhờ Docker: Broker chạy ổn định, dễ nhân bản và triển khai.

3. Thiết Lập Môi Trường

  • Bật Virtualization trong BIOS, sau đó bật WSL 2 và Virtual Machine Platform trong Windows Features.
  • Cập nhật WSL bằng PowerShell (Admin):
powershell (admin) 
wsl --update
wsl --shutdown
  • Khởi chạy hạ tầng Docker tại thư mục dự án:
terminal (VS Code) 
docker compose up -d
Ghi chú
MQTT Broker chạy tại localhost:1883 ngay sau khi Docker khởi chạy thành công.

4. Hướng Dẫn Cấu Hình Kết Nối

Cách 1 (Ưu tiên) - MQTT Client trỏ về IP máy tính :1883

ESP32 publish trực tiếp lên MQTT Broker chạy trong Docker. Trong firmware, thay Serial.println() bằng lệnh publish MQTT và trỏ Broker về IP máy tính.

cpp (ESP32 config) 
// Thay IP_MAY_TINH bằng IP LAN của máy chạy Docker
const char* MQTT_BROKER = "IP_MAY_TINH";
const int MQTT_PORT = 1883;
const char* MQTT_TOPIC = "aquastem/sensors";
Note
Cách này phù hợp khi ESP32 đã có Wi-Fi, không cần bridge Serial.

Cách 2 - USB/COM + Python Bridge

Dùng khi không muốn cấu hình Wi-Fi cho ESP32. Script sẽ đọc COM và publish lên Broker.

python (pyserial + paho-mqtt) 
import json
import time
import serial
import paho.mqtt.client as mqtt

SERIAL_PORT = "COM3"
SERIAL_BAUD = 115200

MQTT_BROKER = "localhost"
MQTT_PORT = 1883
MQTT_TOPIC = "aquastem/sensors"

def connect_serial():
    while True:
        try:
            return serial.Serial(SERIAL_PORT, SERIAL_BAUD, timeout=1)
        except serial.SerialException:
            print(f"⏳ Chưa mở được {SERIAL_PORT}. Đang thử lại...")
            time.sleep(2)

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("✅ Đã kết nối MQTT Broker.")
    else:
        print(f"❌ Lỗi kết nối MQTT, mã lỗi: {rc}")

def main():
    client = mqtt.Client()
    client.on_connect = on_connect
    client.connect(MQTT_BROKER, MQTT_PORT, 60)
    client.loop_start()

    ser = connect_serial()
    print(f"🔌 Đang đọc dữ liệu từ {SERIAL_PORT}...")

    while True:
        try:
            line = ser.readline().decode("utf-8").strip()
            if not line:
                continue
            data = json.loads(line)
            payload = json.dumps(data, ensure_ascii=False)
            client.publish(MQTT_TOPIC, payload)
            print(f"📤 Publish: {payload}")
        except json.JSONDecodeError:
            print("⚠️ Dữ liệu không đúng định dạng JSON, bỏ qua.")
        except serial.SerialException:
            print("⚠️ Mất kết nối Serial, đang kết nối lại...")
            ser = connect_serial()
        except KeyboardInterrupt:
            print("\n👋 Đã dừng script cầu nối.")
            break

if __name__ == "__main__":
    main()
Lưu ý cổng COM
Nếu máy bạn hiển thị cổng khác (ví dụ COM4/COM5), hãy đổi biến SERIAL_PORT trong script.

Cách 3 - Wi-Fi + MQTT (Tuỳ chọn)

Phù hợp khi cần triển khai nhiều node không dây trong cùng mạng LAN. ESP32 publish trực tiếp lên Broker tại IP_MAY_TINH:1883.

Backend Subscribe MQTT (Giữ nguyên code)

Backend kết nối thẳng vào localhost:1883 để subscribe dữ liệu, không cần thư viện đọc cổng COM (như pyserial).

python (paho-mqtt) 
import json
import paho.mqtt.client as mqtt

MQTT_BROKER = "localhost"
MQTT_PORT = 1883
MQTT_TOPIC = "aquastem/sensors"

def on_connect(client, userdata, flags, rc):
    if rc == 0:
        print("✅ Kết nối thành công tới MQTT Broker!")
        client.subscribe(MQTT_TOPIC)
        print(f"📡 Đang lắng nghe dữ liệu từ Topic: {MQTT_TOPIC}")
    else:
        print(f"❌ Kết nối thất bại, mã lỗi: {rc}")

def on_message(client, userdata, msg):
    try:
        payload = msg.payload.decode("utf-8")
        data = json.loads(payload)
        print("\n📥 Nhận thông số cảm biến mới:")
        print(f"  - Độ pH: {data.get('ph')}")
        print(f"  - Nhiệt độ: {data.get('temperature')} °C")
        print(f"  - Độ đục: {data.get('turbidity')} NTU")
    except Exception as e:
        print(f"❌ Lỗi xử lý bản tin JSON: {e}")

client = mqtt.Client()
client.on_connect = on_connect
client.on_message = on_message

try:
    print(f"🔄 Đang kết nối tới MQTT Broker tại {MQTT_BROKER}:{MQTT_PORT}...")
    client.connect(MQTT_BROKER, MQTT_PORT, 60)
    client.loop_forever()
except KeyboardInterrupt:
    print("\n👋 Đã tắt dịch vụ lắng nghe MQTT.")
except Exception as e:
    print(f"❌ Lỗi hệ thống: {e}")

6 Xử Lý Lỗi Thường Gặp & Tham Khảo Nhanh

Giải pháp nhanh cho các sự cố kỹ thuật và danh sách câu lệnh thường trực trong quá trình vận hành Docker.

Khắc phục:

Kiểm tra cấu hình biến môi trường trong file docker-compose.yml của dự án:

  • Nếu không dùng phần cứng thật (chạy mô phỏng): đảm bảo biến SIMULATION_ENABLED có giá trị là true.
  • Nếu dùng phần cứng thật: đảm bảo ESP32 đã kết nối Wifi và gửi được tin nhắn MQTT thành công đến địa chỉ IP của máy tính (Broker cổng 1883).

Khắc phục:

Mở file docker-compose.yml ở thư mục gốc của dự án, tìm dịch vụ bị báo lỗi cổng và thay đổi cổng ánh xạ bên trái:

  • Ví dụ đối với frontend: đổi 3000:3000 thành 3002:3000. Khi đó bạn sẽ truy cập Dashboard bằng địa chỉ http://localhost:3002.

Khắc phục: Mở PowerShell bằng quyền Administrator và chạy lệnh cấp quyền tạm thời dưới đây trước khi gọi script:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

Khắc phục: Chạy lệnh dọn rác hệ thống Docker để thu hồi dung lượng ổ cứng:

docker system prune -a --volumes

Bảng Lệnh Nhanh Docker & Quản Trị

Lệnh Thực Hiện Chức Năng
docker compose up -d --build Khởi chạy toàn bộ hệ thống AquaSTEM ngầm và tự động cập nhật code mới.
docker compose down Dừng và gỡ bỏ toàn bộ container, giúp hạ nhiệt hệ thống và tiết kiệm RAM.
docker compose logs -f backend Xem log thời gian thực của FastAPI backend để kiểm tra các tính toán toán học.
docker compose restart frontend Khởi động lại giao diện Next.js mà không làm gián đoạn backend.

Liên Kết Hữu Ích