Prerequisites
Before setting up Aqua-IoT, ensure you have the following hardware and software ready:
Hardware Requirements
Microcontroller
- Arduino board (Uno, Mega, or compatible)
- USB cable for programming and serial communication
Edge Device
- Raspberry Pi (any model with USB and network connectivity)
- MicroSD card (8GB minimum) with Raspbian OS
Sensors
- DHT11 temperature/humidity sensor
- DS18B20 waterproof temperature sensor
- HC-SR04 ultrasonic distance sensor
- TDS (Total Dissolved Solids) sensor
- LDR (Light Dependent Resistor)
- 10kΩ resistor for LDR circuit
Additional Components
- Breadboard and jumper wires
- Power supply for Arduino
- Network connection for Raspberry Pi
Software Requirements
- Git: Version control for cloning the repository
- Python 3.7+: For Raspberry Pi MQTT bridge scripts
- Arduino IDE: For uploading firmware to Arduino
- PostgreSQL: Database server (can be local or remote)
This guide assumes basic familiarity with Arduino programming, Linux command line, and Python. If you’re new to these technologies, take time to explore the official documentation for each.
Installation Steps
Clone the Repository
Download the Aqua-IoT source code to your development machine:git clone https://github.com/barrancocarlos/Aqua-IoT.git
cd Aqua-IoT
Set Up Arduino Hardware
Connect your sensors to the Arduino according to the pin configuration in Arduino/sensores.ino: Pin Connections
Power & Ground
// Pin definitions from sensores.ino
#define DHTPIN 2 // DHT11 data pin
#define DS18B20 10 // DS18B20 temperature sensor
#define TdsSensorPin A4 // TDS sensor analog pin
const int echo = 4; // Ultrasonic echo pin
const int trigger = 6; // Ultrasonic trigger pin
const int sensorPin = A0; // LDR analog pin
- Connect all sensor VCC pins to Arduino 5V
- Connect all sensor GND pins to Arduino GND
- LDR requires a 10kΩ pull-down resistor to ground
Ensure the DS18B20 sensor is the waterproof version with a pull-up resistor (typically 4.7kΩ) on the data line. Double-check polarity on all sensors before powering on.
Upload Arduino Firmware
Open Arduino/sensores.ino in the Arduino IDE and install required libraries:// Required libraries (install via Arduino Library Manager)
DHT.h // DHT sensor library by Adafruit
OneWire.h // OneWire protocol library
DallasTemperature.h // Dallas Temperature library
GravityTDS.h // Gravity TDS sensor library
Sensor Ativado
Umidade: 45.00% Temperatura: 23.50°C 74.30°F
Temperatura: 22.80°C
650ppm
Distância: 15.2cm
O valor do sensor é = 512
O valor físico é = 48 lumen
Configure PostgreSQL Database
Install PostgreSQL and create a database for Aqua-IoT:# Install PostgreSQL (Ubuntu/Debian)
sudo apt update
sudo apt install postgresql postgresql-contrib
# Create database and user
sudo -u postgres psql
CREATE DATABASE aqua;
CREATE USER postgres WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE aqua TO postgres;
\q
Update the password in Django/painel/settings.py to match your PostgreSQL credentials. The default configuration uses database name aqua with user postgres.
Set Up Django Web Application
Navigate to the Django directory and install dependencies:cd Django
# Install pipenv for virtual environment management
pip install pipenv
# Create virtual environment and install packages
pipenv shell
pipenv install
python manage.py createsuperuser
from django.contrib.auth.models import User
from rest_framework.authtoken.models import Token
user = User.objects.get(username='your_username')
token = Token.objects.create(user=user)
print(token.key)
# Save this token for MQTT bridge configuration
Configure Raspberry Pi MQTT Bridge
On your Raspberry Pi, install required Python packages:pip3 install paho-mqtt pyserial requests
sudo apt update
sudo apt install mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl start mosquitto
ls /dev/ttyACM*
# Usually /dev/ttyACM0
Raspberry-pi/mqtt-arduino.py if needed (default is /dev/ttyACM0).Edit Raspberry-pi/mqtt-django.py and replace the authentication token on line 30:headers = {'Authorization': 'Token YOUR_TOKEN_HERE'}
url_temperatura_plantas = "http://YOUR_SERVER_IP:8000/api/temperatura-plantas/"
Start All Services
You’ll need three terminal sessions to run all components:cd Django
pipenv shell
python manage.py runserver 0.0.0.0:8000
http://localhost:8000cd Raspberry-pi
python3 mqtt-arduino.py
Conetado ao broker
Temperatura
Umidade
LDR
TDS
Temperatura Agua
Nivel Agua
cd Raspberry-pi
python3 mqtt-django.py
Conetado ao broker
Cliente assinado a sensores/temperatura-plantas
Cliente assinado a sensores/umidade
<Response [201]>
Temperatura Plantas enviado com suceso
Verify Installation
Check Arduino Output
Serial Monitor should show sensor readings every 2 seconds
Verify MQTT Topics
Run mosquitto_sub -t "sensores/#" -v to see published messages
Test API Endpoints
Visit http://localhost:8000/admin to see stored sensor data
View Dashboard
Login at http://localhost:8000 with your superuser credentials
Troubleshooting
Arduino Issues
MQTT Issues
Django Issues
Network Issues
No sensor readings or errors:
- Verify all sensor connections and power
- Check library installations in Arduino IDE
- Test each sensor individually using example sketches
- Confirm DHT11 and DS18B20 sensors are properly pulled up
Serial communication errors:
- Ensure baud rate is 9600 in both Arduino code and Python scripts
- Check USB cable and port permissions on Raspberry Pi
- Try
sudo usermod -a -G dialout $USER and reboot
Connection refused:
- Verify Mosquitto is running:
sudo systemctl status mosquitto
- Check port 18083 is not blocked by firewall
- Confirm broker address in Python scripts matches your setup
No data on topics:
- Run
mqtt-arduino.py with verbose logging
- Check Arduino serial output format matches parsing in Python
- Verify
wrap(string, 5) correctly splits sensor values
Database connection errors:
- Verify PostgreSQL is running and accepting connections
- Check credentials in
Django/painel/settings.py
- Ensure database
aqua exists
API authentication failures:
- Regenerate authentication token if needed
- Verify token in
mqtt-django.py matches database
- Check REST_FRAMEWORK settings include TokenAuthentication
No data in dashboard:
- Verify
mqtt-django.py shows 201 responses
- Check Django admin at
/admin for stored sensor records
- Review Django console for any error messages
Cannot access dashboard remotely:
- Ensure Django runs with
0.0.0.0:8000 not 127.0.0.1
- Add your server IP to
ALLOWED_HOSTS in settings.py
- Check firewall rules allow port 8000
Raspberry Pi connectivity:
- Verify Raspberry Pi has network connection
- Test connectivity to Django server:
curl http://SERVER_IP:8000
- Check
/etc/hosts for correct hostname resolution
Next Steps
Now that your Aqua-IoT system is running:
- Calibrate Sensors: Run the system for 24 hours and verify readings match known values
- Set Alert Thresholds: Configure minimum/maximum values for automated alerts
- Explore the Architecture: Learn how components interact in the architecture guide
- Customize Dashboard: Modify Django templates to add charts or additional metrics
- Scale Up: Add more Arduino sensor nodes or expand to multiple aquaponics systems
For production deployments, implement proper security measures including MQTT authentication, HTTPS for Django, secure passwords, and regular system updates.
