TDS Sensor API

Overview

The TDS Sensor endpoint allows you to submit Total Dissolved Solids (TDS) readings from sensors monitoring aquarium water quality. TDS measurements indicate the concentration of dissolved substances in water, which is critical for maintaining healthy aquatic environments.

Endpoint

POST /api/tds/

Model Structure

The Tds model extends the base Sensor model:

class Tds(Sensor):
    tds = models.FloatField(max_length=200, default='00')
    media_tds = models.FloatField(max_length=200, default='30')
    unidade_medida = models.CharField(max_length=50, default='ppm')

Source: models.py:45-50

ViewSet Implementation

class TdsViewset(viewsets.ViewSet):
    permission_classes = (IsAuthenticated,)
    
    def create(self, request):
        serializer = TdsSerializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        the_response = TdsSerializer(serializer.save())
        return Response(the_response.data, status=status.HTTP_201_CREATED)

Source: views.py:142-148

Authentication

This endpoint requires authentication. Include your API token in the Authorization header.

Authorization: Token 2d75140c068049278f9cb7d39b1a20f05aecdc56

See Authentication for details.

Request Parameters

nome

string

required

Sensor name identifierExample: "TDS"

tipo

string

required

Type of sensor locationExample: "Acuario"

grupo

string

required

Sensor group classificationExample: "Grupo A"

tds

float

required

Current TDS reading from the sensor (parts per million)Example: 320.5

media_tds

float

required

Average or target TDS levelDefault: 30Example: 100

unidade_medida

string

required

Unit of measurement for TDSDefault: "ppm"Example: "ppm"

Response Fields

integer

Auto-generated unique identifier for the record

nome

string

Sensor name as provided in request

tipo

string

Sensor type as provided in request

grupo

string

Sensor group as provided in request

tds

float

TDS value submitted (parts per million)

media_tds

float

Average or target TDS level

unidade_medida

string

Unit of measurement for TDS (typically ppm)

data_criacao

datetime

Timestamp when the record was created (auto-generated)

Example Request

curl -X POST http://127.0.0.1:8000/api/tds/ \
  -H "Authorization: Token 2d75140c068049278f9cb7d39b1a20f05aecdc56" \
  -H "Content-Type: application/json" \
  -d '{
    "nome": "TDS",
    "tipo": "Acuario",
    "grupo": "Grupo A",
    "tds": "320.5",
    "media_tds": 100,
    "unidade_medida": "ppm"
  }'

Example Response

Status Code: 201 Created

{
  "id": 52,
  "nome": "TDS",
  "tipo": "Acuario",
  "grupo": "Grupo A",
  "tds": 320.5,
  "media_tds": 100.0,
  "unidade_medida": "ppm",
  "data_criacao": "2026-03-11T10:30:45.123456Z"
}

Error Responses

Missing Authentication Token

Status Code: 401 Unauthorized

{
  "detail": "Authentication credentials were not provided."
}

Invalid Token

Status Code: 401 Unauthorized

{
  "detail": "Invalid token."
}

Missing Required Fields

Status Code: 400 Bad Request

{
  "tds": [
    "This field is required."
  ],
  "nome": [
    "This field is required."
  ]
}

Invalid Data Type

Status Code: 400 Bad Request

{
  "tds": [
    "A valid number is required."
  ],
  "media_tds": [
    "A valid number is required."
  ]
}

MQTT Integration Example

Example from the Raspberry Pi MQTT client:

# From mqtt-django.py:63-75
if message.topic == topic_tds:
    nome = "TDS"
    tipo = "Acuario"
    grupo = "Grupo A"
    tds = str(message.payload.decode("utf-8"))
    media_tds = 100
    unidade_medida = "ppm"
    
    tds = {
        'nome': nome,
        'tipo': tipo,
        'grupo': grupo,
        'tds': tds,
        'media_tds': media_tds,
        'unidade_medida': unidade_medida
    }
    
    headers = {'Authorization': 'Token 2d75140c068049278f9cb7d39b1a20f05aecdc56'}
    url_tds = "http://127.0.0.1:8000/api/tds/"
    send_tds = requests.post(
        url_tds,
        headers=headers,
        json=tds
    )

Serializer Details

The endpoint uses TdsSerializer with depth=1 to include related object details:

class TdsSerializer(serializers.ModelSerializer):
    class Meta:
        model = Tds
        fields = '__all__'
        depth = 1

    def create(self, validated_data):
        tds = Tds.objects.create(**validated_data)
        tds.save()
        return tds

Source: serializers.py:65-74

Use Cases

Monitor water quality in aquariums in real-time
Track dissolved solids concentration over time
Trigger water changes when TDS levels exceed safe thresholds
Ensure optimal water quality for aquatic life
Historical water quality data analysis
IoT device integration via MQTT
Automated filtration system control

Understanding TDS Values

TDS measures the concentration of dissolved inorganic and organic substances in water:

Acceptable TDS Ranges

Freshwater Aquariums: 50-300 ppm
Planted Tanks: 150-250 ppm
Saltwater Aquariums: 30,000-40,000 ppm (measured differently)
Drinking Water: < 500 ppm (EPA standard)

What TDS Measures

Dissolved minerals (calcium, magnesium, sodium)
Salts
Metals
Organic matter
Other dissolved substances

TDS does not measure contaminants, bacteria, or other harmful substances. It’s an indicator of overall dissolved content but should be used alongside other water quality tests.

Best Practices

Regular Monitoring: Submit TDS readings every 10-30 minutes for real-time tracking
Calibration: Calibrate TDS sensors regularly with standard solutions
Temperature Compensation: Many TDS sensors are temperature-dependent; ensure proper compensation
Baseline Tracking: Use media_tds to track target TDS levels for your specific aquarium
Water Changes: Plan water changes when TDS exceeds safe thresholds
Gradual Changes: Avoid sudden TDS changes that can stress aquatic life

Safety Considerations

High TDS levels can stress or harm aquatic life
Sudden TDS changes are more dangerous than gradual increases
Different fish species have different TDS tolerance ranges
Monitor TDS trends, not just absolute values
Combine TDS monitoring with pH and temperature for complete water quality assessment

Troubleshooting High TDS

If TDS levels are too high:

Perform partial water changes with purified water
Check for overfeeding (uneaten food increases TDS)
Inspect filtration system functionality
Test source water TDS before adding to aquarium
Consider using reverse osmosis (RO) water for dilution

Temperature Aquarium API - For aquarium water temperature
Water Level API - For monitoring water levels
Light Sensor API - For monitoring light levels

Sensor Endpoints

Overview

Endpoint

Model Structure

ViewSet Implementation

Authentication

Request Parameters

Response Fields

Example Request

Example Response

Error Responses

Missing Authentication Token

Invalid Token

Missing Required Fields

Invalid Data Type

MQTT Integration Example

Serializer Details

Use Cases

Understanding TDS Values

Acceptable TDS Ranges

What TDS Measures

Best Practices

Safety Considerations

Troubleshooting High TDS

Build docs developers (and LLMs) love

Sensor Endpoints

​Overview

​Endpoint

​Model Structure

​ViewSet Implementation

​Authentication

​Request Parameters

​Response Fields

​Example Request

​Example Response

​Error Responses

​Missing Authentication Token

​Invalid Token

​Missing Required Fields

​Invalid Data Type

​MQTT Integration Example

​Serializer Details

​Use Cases

​Understanding TDS Values

​Acceptable TDS Ranges

​What TDS Measures

​Best Practices

​Safety Considerations

​Troubleshooting High TDS

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Endpoint

Model Structure

ViewSet Implementation

Authentication

Request Parameters

Response Fields

Example Request

Example Response

Error Responses

Missing Authentication Token

Invalid Token

Missing Required Fields

Invalid Data Type

MQTT Integration Example

Serializer Details

Use Cases

Understanding TDS Values

Acceptable TDS Ranges

What TDS Measures

Best Practices

Safety Considerations

Troubleshooting High TDS

Related Endpoints