Documentation

Complete documentation for setting up, configuring, and using the Cannabis Grow Management System.

Getting Started

Quick start guide for setting up the Cannabis Grow Management System.

System Requirements

Prerequisites

Quick Setup

  1. Clone the repository: 
    git clone https://github.com/[your-username]/Canna_Projects.git
cd Canna_Projects
  2. Configure environment variables: 
    cp backend/.env.example backend/.env
cp docker/compose/.env.example docker/compose/.env
    Edit the `.env` files and set strong passwords.
  3. Start services: 
    sudo docker compose -f docker/compose/docker-compose.yml up -d
  4. Create admin user: 
    sudo docker compose -f docker/compose/docker-compose.yml exec backend node scripts/create-admin.js
  5. Access the application:
    • Frontend: http://localhost:5173
    • Backend API: http://localhost:3000
    • Portainer: http://localhost:9000

ESP32 Setup Guide

Complete guide for setting up ESP32 sensor devices.

Hardware Requirements

Wiring Instructions

See the Hardware Setup Guide for detailed wiring diagrams and pin connections.

Firmware Installation

  1. Install PlatformIO or Arduino IDE
  2. Navigate to firmware directory: 
    cd backend/firmware/source/esp32/sensor-v1.0.0
  3. Configure WiFi and MQTT credentials in `config.h`
  4. Build and upload firmware: 
    pio run --target upload

Device Registration

  1. Access the Sensor Devices page in the web interface
  2. Click "Register New Device"
  3. Enter device ID, name, type (ESP32), and location
  4. MQTT credentials are automatically generated
  5. Update device firmware with MQTT credentials

API Documentation

RESTful API endpoints for programmatic access to the system. All endpoints return JSON responses.

Base URL

API base URL depends on deployment:

Authentication

All API endpoints require JWT authentication via HTTP-only cookies. The token is automatically included in requests from the frontend.

POST /api/auth/login
Content-Type: application/json
Body: {
  "email": "user@example.com",
  "password": "password"
}
Response: {
  "success": true,
  "data": {
    "user": { ... },
    "token": "jwt_token_here"
  }
}
Sets HTTP-only cookie with JWT token

Response Format

All API responses follow a consistent format:

// Success Response
{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

// Error Response
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": { ... }
}

Pagination

List endpoints support pagination with query parameters:

GET /api/plants?page=1&limit=20&sort=plantingDate&order=desc
Response: {
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

Core Endpoints

Grows

Plants

Environmental Data

Devices

Automation

Device Control

Response Format

All API responses use JSON format:

{
  "success": true,
  "data": { ... },
  "message": "Operation successful"
}

Error Handling

Error responses include detailed information:

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    "field": "validation error details"
  }
}

Common Error Codes

Rate Limiting

API endpoints are rate-limited to prevent abuse:

MQTT Topics

MQTT topic structure for IoT device communication.

Sensor Data Topics

sensors/{growId}/{plantId}/data - Complete sensor payload
sensors/{growId}/{plantId}/temperature - Individual temperature reading
sensors/{growId}/{plantId}/humidity - Individual humidity reading
sensors/{growId}/{plantId}/soilMoisture - Soil moisture reading
sensors/{growId}/{plantId}/pH - pH reading
sensors/{growId}/{plantId}/ec - EC reading
sensors/{growId}/{plantId}/light - Light intensity reading
sensors/{growId}/{plantId}/co2 - COâ‚‚ reading

Device Topics

devices/{deviceId}/status - Device status/heartbeat
devices/{deviceId}/config - Device configuration updates (from server)
devices/{deviceId}/ota/status - OTA update progress
devices/{deviceId}/control - Device control commands

Message Format

Sensor data messages use JSON format:

{
  "deviceId": "esp32-001",
  "timestamp": "2024-01-01T00:00:00Z",
  "growId": "507f1f77bcf86cd799439011",
  "plantId": "507f191e810c19729de860ea",
  "metrics": {
    "temperature": 72.5,
    "humidity": 65.0,
    "pH": 6.5,
    "co2": 400,
    "ec": 1.2,
    "soilMoisture": 45
  }
}

OTA Firmware Updates

Over-the-air firmware updates for ESP32 and ESP8266 devices.

Prerequisites

Update Process

  1. Generate firmware from template or upload custom firmware
  2. Select target devices for update
  3. Initiate OTA update via web interface
  4. Monitor update progress via device status
  5. Device automatically reboots after successful update

Firmware Templates

Firmware templates are stored in backend/firmware/templates/ and are processed to inject device-specific configuration.

Troubleshooting

Common issues and solutions.

Device Connection Issues

Backend Issues

Frontend Issues

Docker Issues

Configuration

System configuration options and environment variables.

Backend Environment Variables

Variable Required Default Description
NODE_ENV No development Environment mode: development or production
PORT No 3000 API server port
MONGODB_URI Yes (Production) - MongoDB connection string with credentials
JWT_SECRET Yes - JWT signing secret (min 32 characters recommended)
MQTT_BROKER_URL No mqtt://mosquitto:1883 MQTT broker URL
MQTT_BROKER_USERNAME Yes (Production) mqtt_user MQTT broker username
MQTT_BROKER_PASSWORD Yes (Production) - MQTT broker password
WEBSOCKET_PORT No 3001 WebSocket server port
CORS_ORIGIN No * Allowed CORS origins (comma-separated)
LOG_LEVEL No info Pino log level: debug, info, warn, error

Frontend Environment Variables

Docker Compose Environment Variables

Security

Security best practices and recommendations.

Authentication

Network Security

Data Security

Back to Home View Features