Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/diarpicu2022-commits/backend-AgroPulse/llms.txt

Use this file to discover all available pages before exploring further.

Actuators represent the physical devices — pumps, fans, heaters, lights, valves, and irrigation systems — that AgroPulse controls in response to sensor readings or automation rules. Each actuator is linked to a greenhouse, optionally mapped to a GPIO pin on an ESP32 device, and carries a live status field (ON, OFF, or AUTO) that the firmware reads to drive its output.
POST /api/actuators performs an upsert: if an actuator already exists with the same type, gpioPin, and greenhouseId, the API updates that record instead of creating a duplicate. This keeps firmware boot-time registration idempotent.

​
Actuator types

The type field must be one of the following string values, drawn from the ActuatorType enum:
ValueDescription
FANVentilation fan
PUMPWater or nutrient pump
HEATERHeating element
LIGHTSGrow lights
VENTILATIONRoof vent or louvre motor
IRRIGATIONDrip or sprinkler irrigation head

​
Endpoints

​
GET /api/actuators

Returns all actuators. Pass greenhouseId to scope the response to a single greenhouse. Query parameters
​
greenhouseId
number
Filter results to actuators belonging to this greenhouse ID. Omit to return all actuators across all greenhouses.
Response The response is a JSON object with a single actuators key containing an array.
​
actuators
object[]
Array of actuator objects. See the actuator object section for field definitions.
curl http://localhost:8080/api/actuators
example response
{
  "actuators": [
    {
      "id": 1,
      "name": "Main pump",
      "type": "PUMP",
      "status": "OFF",
      "greenhouseId": 3,
      "active": true,
      "gpioPin": 14,
      "activeLow": true,
      "deviceSource": "esp32-gh3-01",
      "createdAt": "2024-03-12T08:00:00"
    }
  ]
}

​
POST /api/actuators

Creates a new actuator, or updates an existing one if type + gpioPin + greenhouseId match a record already in the database. Request body
​
name
string
required
Human-readable label for the actuator, e.g. "Row-2 irrigation valve".
​
type
string
required
Actuator category. Must be one of FAN, PUMP, HEATER, LIGHTS, VENTILATION, or IRRIGATION.
​
greenhouseId
number
required
ID of the greenhouse this actuator belongs to. Required for the upsert lookup.
​
gpioPin
number
GPIO pin number on the ESP32 that drives this actuator. Required for the upsert lookup; must be >= 0.
​
status
string
default:"OFF"
Initial operating state. Accepted values: ON, OFF, AUTO.
​
active
boolean
default:"true"
Whether this actuator is enabled and visible to the automation engine. Defaults to true on creation.
​
activeLow
boolean
default:"false"
Set to true for relay modules wired active-low (e.g. HW-383 relay boards), where a LOW GPIO signal turns the relay on. When true, the firmware inverts the output signal before driving the pin.
​
deviceSource
string
Identifier of the ESP32 device that owns this GPIO pin, e.g. "esp32-gh3-01". Used to route commands to the correct device when multiple microcontrollers share a greenhouse.
Response Returns the created or updated actuator object directly (not wrapped in an envelope). 
curl -X POST http://localhost:8080/api/actuators \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Row-2 irrigation valve",
    "type": "IRRIGATION",
    "greenhouseId": 3,
    "gpioPin": 18,
    "activeLow": true,
    "deviceSource": "esp32-gh3-01"
  }'
example response
{
  "id": 7,
  "name": "Row-2 irrigation valve",
  "type": "IRRIGATION",
  "status": "OFF",
  "greenhouseId": 3,
  "active": true,
  "gpioPin": 18,
  "activeLow": true,
  "deviceSource": "esp32-gh3-01",
  "createdAt": "2024-03-15T10:22:00"
}

​
GET /api/actuators/

Returns a single actuator by its database ID. Path parameters
​
id
number
required
The actuator’s integer ID.
Returns 404 Not Found if no actuator exists with that ID.
example request
curl http://localhost:8080/api/actuators/7

​
PUT /api/actuators/

Updates one or more fields on an existing actuator. Only fields present in the request body are changed; omitted fields retain their current values.
This endpoint enforces ownership. If the authenticated user does not own the actuator, the server returns 403 Forbidden with {"error": "No tienes permiso para modificar este actuador"}.
Path parameters
​
id
number
required
The actuator’s integer ID.
Request body All body fields are optional. Include only the fields you want to change.
​
name
string
New display name.
​
type
string
New actuator type. Must be a valid ActuatorType value.
​
status
string
New operating state: ON, OFF, or AUTO.
​
greenhouseId
number
Reassign the actuator to a different greenhouse.
​
active
boolean
Enable or disable the actuator.
​
gpioPin
number
Reassign the GPIO pin.
​
activeLow
boolean
Change the active-low wiring flag.
​
deviceSource
string
Change the owning ESP32 device identifier.
Returns the updated actuator object. Returns 404 if the ID does not exist, 403 if the caller does not own the record.
example request
curl -X PUT http://localhost:8080/api/actuators/7 \
  -H "Content-Type: application/json" \
  -d '{"status": "ON", "active": true}'
example response
{
  "id": 7,
  "name": "Row-2 irrigation valve",
  "type": "IRRIGATION",
  "status": "ON",
  "greenhouseId": 3,
  "active": true,
  "gpioPin": 18,
  "activeLow": true,
  "deviceSource": "esp32-gh3-01",
  "createdAt": "2024-03-15T10:22:00"
}

​
DELETE /api/actuators/

Permanently removes an actuator record.
Deletion is irreversible. Any automation rules that reference this actuator by actuatorId will reference a non-existent device. Clean up associated rules before deleting.
Path parameters
​
id
number
required
The actuator’s integer ID.
Returns {"deleted": true} on success, 404 if not found, 403 if the caller does not own the record.
example request
curl -X DELETE http://localhost:8080/api/actuators/7
example response
{
  "deleted": true
}

​
The actuator object

​
id
number
required
Auto-generated integer primary key.
​
name
string
required
Human-readable label.
​
type
string
Actuator category string: FAN, PUMP, HEATER, LIGHTS, VENTILATION, or IRRIGATION.
​
status
string
Current operating state: ON, OFF, or AUTO. Defaults to OFF on creation.
​
greenhouseId
number
ID of the greenhouse this actuator belongs to.
​
active
boolean
Whether the actuator is enabled. Defaults to true.
​
gpioPin
number
GPIO pin number on the controlling ESP32. null if not mapped to hardware.
​
activeLow
boolean
true if the relay or driver is wired active-low. The firmware inverts the pin signal when this flag is set.
​
deviceSource
string
Identifier of the ESP32 that controls this actuator’s GPIO pin. null if not assigned.
​
createdAt
string
ISO-8601 timestamp of when the record was first created.

Build docs developers (and LLMs) love

Get started for freeTalk to us