Skip to content

ar-dehghan-a/smart-pot

BranchesTags

Repository files navigation

Smart Pot - IoT Device Management System

A complete IoT device management system with ESP32 devices, Node.js TypeScript backend, PostgreSQL database, and MQTT communication.

🏗️ Architecture

┌─────────────┐    MQTT     ┌─────────────┐    REST API     ┌─────────────┐
│   ESP32     │ ──────────► │   Backend   │ ──────────────► │   Clients   │
│  Devices    │             │ (Node.js)   │                 │ (Web/Mobile)│
└─────────────┘             └─────────────┘                 └─────────────┘
     │                            │                              │
     │                            │                              │
     ▼                            ▼                              ▼
┌─────────────┐            ┌─────────────┐                ┌─────────────┐
│   Sensors   │            │   MQTT      │                │   REST API  │
│ (DHT22, etc)│            │   Broker    │                │   Endpoints │
└─────────────┘            └─────────────┘                └─────────────┘
                                │
                                ▼
                         ┌─────────────┐
                         │ PostgreSQL  │
                         │  Database   │
                         └─────────────┘

🚀 Quick Start

Prerequisites

  • Node.js >= 20.0.0
  • npm >= 9.0.0
  • Docker and Docker Compose (for PostgreSQL and MQTT broker)
  • ESP32 development board
  • DHT22 temperature/humidity sensor
  • Soil moisture sensor
  • Light sensor
  • Relay modules (for water control)

1. Start Infrastructure Services

Start PostgreSQL and Mosquitto MQTT broker using Docker Compose:

docker compose up -d
# or from repository root (npm workspaces helper)
npm run compose:up

This will start:

  • PostgreSQL on port 5432
  • Mosquitto MQTT broker on port 1883 (MQTT)

2. Backend Setup

  1. Navigate to the backend directory:
cd backend
  1. Install dependencies:
npm install
  1. Create a .env file in the backend directory:
# Server Configuration
NODE_ENV=development
PORT=8000

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=smart_pot
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

# MQTT Configuration
MQTT_URL=mqtt://localhost:1883
MQTT_USERNAME=
MQTT_PASSWORD=

# JWT Configuration
JWT_SECRET=your_jwt_secret_key_here_change_in_production
JWT_EXPIRY_HOURS=24

# Telemetry Retention (days)
TELEMETRY_RETENTION_DAYS=30

# Aggregation Worker (cron expression)
AGGREGATION_CRON=0 * * * *
  1. Run database migrations:
npm run migration:run
  1. Start the development server:
npm run dev

The server will run on http://localhost:8000

3. Frontend Setup

  1. Navigate to the frontend directory:
cd frontend
  1. Install dependencies:
npm install
  1. Configure environment variables (optional but recommended). Create a .env file in frontend:
VITE_API_BASE_URL=http://localhost:8000/api/v1
  1. Start the development server:
npm run dev

The web dashboard will be available on http://localhost:5173 (default Vite port).

4. ESP32 Setup

  1. Update the ESP32 configuration in esp32/config.h:

    #define WIFI_SSID "your_wifi_ssid"
#define WIFI_PASSWORD "your_wifi_password"
#define MQTT_BROKER "192.168.1.100"  // Your server IP
#define MQTT_PORT 1883

  2. Upload the ESP32 code using Arduino IDE

  3. Ensure the ESP32 device publishes telemetry to the correct MQTT topics (see MQTT Topics section below)

📁 Project Structure

smart-pot/
├── backend/                    # Node.js TypeScript backend API
│   ├── src/                    # Source code
│   │   ├── config/             # Configuration (env, swagger, etc.)
│   │   ├── controllers/        # Request handlers
│   │   ├── db/                 # Database config and entities
│   │   │   ├── entities/       # TypeORM entities
│   │   │   └── migrations/     # Database migrations (generated)
│   │   ├── dto/                # Request/response validation schemas (Zod)
│   │   ├── middlewares/        # Express middlewares
│   │   ├── routes/             # API route definitions
│   │   ├── services/           # MQTT, logger, graceful shutdown, etc.
│   │   ├── utils/              # Helpers and shared utilities
│   │   ├── workers/            # Background workers (e.g. aggregation)
│   │   ├── app.ts              # Express app setup
│   │   └── server.ts           # Server entry point
│   ├── package.json            # Backend dependencies & scripts
│   └── tsconfig.json           # TypeScript configuration
│
├── frontend/                   # React + TypeScript + Vite web dashboard
│   ├── src/
│   │   ├── features/           # Feature-based modules (auth, device, profile, home)
│   │   ├── components/         # Reusable UI components & layouts (shadcn/ui)
│   │   ├── router/             # React Router configuration
│   │   ├── lib/                # HTTP client, env helpers, utils
│   │   └── providers/          # Global providers (React Query, theme, auth, etc.)
│   ├── public/                 # Static assets & icons
│   └── package.json            # Frontend dependencies & scripts
│
├── esp32/                      # ESP32 Arduino firmware
│   ├── esp32.ino               # Main firmware entry
│   ├── config.h                # Board- and network-level configuration
│   ├── wifi_manager.*          # WiFi connection management
│   ├── mqtt_manager.*          # MQTT topics, connection and messaging
│   ├── relay_manager.*         # Channel modes, auto config and scheduling
│   ├── time_manager.*          # RTC/time utilities
│   ├── sms_manager.*           # SMS control interface (SIM800L)
│   ├── utils.*                 # Shared helper functions
│   └── README.md               # ESP32 documentation
│
├── mosquitto/                  # Mosquitto MQTT broker configuration
│   └── config/                 # Mosquitto config files
├── docker-compose.yml          # Docker Compose for Postgres + Mosquitto
├── package.json                # Root monorepo config (npm workspaces)
└── README.md                   # This file

🔧 Configuration

Backend Environment Variables

Create backend/.env with the following variables:

# Server Configuration
NODE_ENV=development
PORT=8000

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=smart_pot
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres

# MQTT Configuration
MQTT_URL=mqtt://localhost:1883
MQTT_USERNAME=              # Optional
MQTT_PASSWORD=              # Optional

# JWT Configuration
JWT_SECRET=your_jwt_secret_key_here_change_in_production
JWT_EXPIRY_HOURS=24

# Telemetry Retention (days)
TELEMETRY_RETENTION_DAYS=30

# Aggregation Worker (cron expression - runs every hour by default)
AGGREGATION_CRON=0 * * * *

ESP32 Configuration

Update esp32/config.h:

// WiFi Configuration
#define WIFI_SSID "your_wifi_ssid"
#define WIFI_PASSWORD "your_wifi_password"

// MQTT Configuration
#define MQTT_BROKER "192.168.1.100"  // Your server IP
#define MQTT_PORT 1883
#define MQTT_USERNAME ""              // Optional
#define MQTT_PASSWORD ""              // Optional

📡 MQTT Topics

Device → Backend

  • esp/{deviceId}/telemetry - Telemetry data from device

    {
  "temperature": 25.6,
  "humidity": 60.2,
  "soilMoisture": 450,
  "lightLevel": 1,
  "timestamp": 1640995200
}

  • esp/{deviceId}/status - Device online/offline status

    {
  "online": true
}

  • esp/{deviceId}/ack - Command acknowledgments

    {
  "commandId": "uuid",
  "type": "delivery" | "execution",
  "success": true,
  "errorMessage": "optional error message"
}

Backend → Device

  • esp/{deviceId}/command - Commands sent to device

    {
  "commandId": "uuid",
  "type": "water" | "stop-water" | "set-mode" | "set-profile" | "custom",
  "payload": { ... }
}

🌐 API Endpoints

All API endpoints are prefixed with /api/v1

Authentication

  • POST /api/v1/auth/signup - Register a new user

    {
  "email": "user@example.com",
  "password": "securepassword",
  "name": "User Name"
}

  • POST /api/v1/auth/login - Login and get JWT token

    {
  "email": "user@example.com",
  "password": "securepassword"
}

  • GET /api/v1/auth/me - Get current user info (requires authentication)

Device Management

  • GET /api/v1/devices - List all devices owned by authenticated user

    • Query params: page, limit, search

  • POST /api/v1/devices/pair - Pair a device to authenticated user

    {
  "deviceId": "esp32_001",
  "name": "My Device"
}

  • GET /api/v1/devices/:deviceId - Get device details with current status

  • PATCH /api/v1/devices/:deviceId - Update device settings

    {
  "name": "Updated Name",
  "mode": "auto" | "manual",
  "profile": { ... }
}

  • POST /api/v1/devices/:deviceId/unpair - Unpair device from user

Device Status & Telemetry

  • GET /api/v1/devices/:deviceId/status - Get current device status

  • GET /api/v1/devices/:deviceId/history - Get telemetry history

    • Query params: from, to, type (raw or hourly), page, limit

  • POST /api/v1/devices/:deviceId/telemetry - Ingest telemetry data (internal use)

Device Commands

  • POST /api/v1/devices/:deviceId/commands/water - Send water command

    {
  "duration": 30,
  "zone": 1
}

  • POST /api/v1/devices/:deviceId/commands/stop-water - Stop watering

  • POST /api/v1/devices/:deviceId/commands/set-mode - Change device mode

    {
  "mode": "auto" | "manual"
}

  • POST /api/v1/devices/:deviceId/channels/auto-config - Set auto mode configuration

    {
  "threshold": 30,
  "durationSec": 300
}

  • POST /api/v1/devices/:deviceId/commands/custom - Send custom command

    {
  "action": "custom_action",
  "params": { ... }
}

  • GET /api/v1/devices/:deviceId/commands - Get command history

    • Query params: page, limit, status

Health

  • GET /api/v1/health - Health check endpoint

🧪 Testing

API Testing

# Health check
curl http://localhost:8000/api/v1/health

# Sign up
curl -X POST http://localhost:8000/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123",
    "name": "Test User"
  }'

# Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "password123"
  }'

# List devices (requires JWT token)
curl http://localhost:8000/api/v1/devices \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Send water command (requires JWT token)
curl -X POST http://localhost:8000/api/v1/devices/esp32_001/commands/water \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 30,
    "zone": 1
  }'

🚀 Deployment

Local Development

# Start infrastructure
docker compose up -d

# Start backend
cd backend
npm run dev

Production

# Build backend
cd backend
npm run build

# Run migrations
npm run migration:run

# Start production server
npm start

Docker Compose

The project includes Docker Compose configuration for PostgreSQL and Mosquitto:

# Start services
docker compose up -d

# Stop services
docker compose down

# Stop and remove volumes
docker compose down -v

🔒 Security

  • JWT Authentication - Token-based authentication for API endpoints
  • Password Hashing - Bcrypt password hashing
  • CORS Protection - Cross-origin resource sharing configuration
  • Input Validation - Zod schema validation for all requests
  • Security Headers - Helmet security middleware
  • MQTT Authentication - Optional username/password authentication

📊 Features

  • ✅ User authentication and authorization
  • ✅ Device pairing and management
  • ✅ Real-time telemetry ingestion via MQTT
  • ✅ Telemetry history (raw and hourly aggregated)
  • ✅ Device command system with acknowledgments
  • ✅ Background workers for data aggregation
  • ✅ PostgreSQL database for data persistence
  • ✅ RESTful API with comprehensive endpoints
  • ✅ TypeScript for type safety
  • ✅ Request validation with Zod
  • ✅ Structured logging with Winston

🌍 Frontend Web Dashboard

The frontend workspace provides a modern web dashboard built with React + TypeScript + Vite + shadcn/ui:

  • Authentication: Sign up, sign in, and persistent sessions using JWT.
  • Device overview: Home page with a list of paired devices and high-level status.
  • Device details: Per-device pages showing live status, channel modes, and auto-config.
  • Channels control: Manual channel activation/deactivation and per-channel scheduling UI.
  • Telemetry views: History and report pages with charts for hourly telemetry.
  • User profile: Basic profile and preferences section.

By default the dashboard talks to the backend via VITE_API_BASE_URL (see Frontend Setup).

📊 Monitoring

Logs

The backend uses Winston for structured logging. Logs are output to the console in development and can be configured for file output in production.

Health Checks

  • GET /api/v1/health - Server health status

Database Migrations

# Generate migration
npm run migration:generate

# Run migrations
npm run migration:run

# Revert last migration
npm run migration:revert

# Show migration status
npm run migration:show

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run linting and type checking in relevant workspaces (e.g. npm run lint / npm run typecheck inside backend, npm run lint inside frontend)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

📝 License

MIT License - see LICENSE file for details.

🆘 Support

For issues and questions:

  1. Check the documentation in each component
  2. Review the example code
  3. Check the ESP32 README for device-specific issues
  4. Create an issue with detailed information

🔄 Roadmap

  • Database integration for sensor data storage
  • User authentication and authorization
  • Device management and pairing
  • Telemetry ingestion and history
  • Command system with acknowledgments
  • Data aggregation workers
  • Dashboard web interface (React-based web dashboard)
  • Mobile app (React Native or Flutter)
  • Cloud deployment options
  • Advanced analytics and visualization

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages