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.

The Device API is the integration point for ESP32 microcontrollers and other edge hardware. Devices use these endpoints at boot time to register their sensors and actuators with the server and download the current configuration for their assigned greenhouse. The frontend uses the GPIO availability endpoint to populate pin-picker UI elements.
All device endpoints are served under /api/device. They are designed for firmware-level HTTP calls from ESP32 nodes, though they work from any HTTP client.

​
POST /api/device/register

Registers an ESP32 device and its connected hardware. The device reports its deviceId and greenhouseId, along with lists of sensors and actuators it has wired up. The server upserts each sensor and actuator record so boot-time registration is always safe to call repeatedly. Request body
​
greenhouseId
number
required
ID of the greenhouse this device belongs to. The request fails with 400 if this is missing or zero.
​
deviceId
string
Unique identifier for the ESP32 device, e.g. "esp32-gh3-01". Defaults to "UNKNOWN" if omitted.
​
sensors
array
List of sensor descriptor objects. Each entry follows the same shape as the POST /api/sensors body (see Sensors API). Omit or pass [] if the device has no sensors.
​
actuators
array
List of actuator descriptor objects. Each entry follows the same shape as the POST /api/actuators body (see Actuators API). Omit or pass [] if the device has no actuators.
Response Returns the result of the device registration, including any created or updated sensor and actuator IDs. 
curl -X POST http://localhost:8080/api/device/register \
  -H "Content-Type: application/json" \
  -d '{
    "greenhouseId": 3,
    "deviceId": "esp32-gh3-01",
    "sensors": [
      {
        "name": "Roof Temp",
        "type": "TEMPERATURE",
        "gpioPin": 4,
        "protocol": "DHT22"
      },
      {
        "name": "Roof Humidity",
        "type": "HUMIDITY",
        "gpioPin": 4,
        "protocol": "DHT22"
      }
    ],
    "actuators": [
      {
        "name": "Irrigation Pump",
        "type": "PUMP",
        "gpioPin": 14,
        "activeLow": true
      }
    ]
  }'
Error responses
StatusCause
400greenhouseId is missing or zero.

​
GET /api/device/config/

Downloads the full hardware configuration for a greenhouse. ESP32 devices call this at boot to learn which sensors and actuators they should be managing and what their current states are. Path parameters
​
greenhouseId
number
required
The greenhouse whose configuration to retrieve.
Response Returns a configuration object that includes all sensors, actuators, and the list of GPIO pins currently in use. 
curl http://localhost:8080/api/device/config/3

​
GET /api/device/gpios/

Returns the GPIO pin availability for a greenhouse — which pins are already allocated to sensors or actuators, and which remain free for new hardware. This endpoint is used by the frontend’s GPIO pin-picker when adding new devices. Path parameters
​
greenhouseId
number
required
The greenhouse whose GPIO allocation to query.
Response
​
usedGpios
number[]
List of GPIO pin numbers already assigned to sensors or actuators in this greenhouse.
​
availableForSensors
number[]
GPIO pins that are valid for sensor input and not yet assigned. Drawn from the ESP32 DevKit input-capable pins: 4, 5, 12–19, 23, 25–27, 32–36, 39.
​
availableForActuators
number[]
GPIO pins that are valid for actuator output and not yet assigned. Drawn from the ESP32 DevKit output-capable pins: 4, 5, 12–19, 23, 25–27, 32–33.
curl http://localhost:8080/api/device/gpios/3
GPIO pins 0, 1, 2, 3, 6–11, 21, and 22 are reserved for system use on ESP32 DevKit boards and are never returned as available.

Build docs developers (and LLMs) love

Get started for freeTalk to us