Controllers

A Growbud Controller has four outputs. With the Write API, you can switch an output on or off.

A Controller can also control Modbus devices on its RS-485 bus, for example a Waveshare Modbus RTU Relay board. With the Write API, you can write one point of such a device, for example a relay coil.

To read a Controller, use the Read API. To change schedules, use the Growbud app.

Address

Use the serial on the Controller label, for example F1000000. The outputs are 0 to 3.

GET  /sensing/v1/controllers/F1000000
POST /control/v1/controllers/F1000000/outputs/0/switch   {"on": true}
GET  /sensing/v1/controllers/F1000000/modbus/points
POST /control/v1/controllers/F1000000/modbus/points/relays.relay_1/write   {"value": true}

The output must have a load type. Set it in the Growbud app. An output without one gets 409 failed_precondition with reason CAPABILITY_MISMATCH.

Switch an output

POST .../outputs/{ch}/switch with {"on": true} sends one command. The Edge Server does not send it again.

Add "retry": true to keep the output in that state. The Edge Server then sends commands until the Controller confirms: 5 commands maximum, for 10 minutes maximum. If the Controller refuses, it does not send again. The answer has desired, with status converging, converged, failed, overridden or superseded.

Write a Modbus point

First, add the Modbus device to the Controller in the Growbud app. The Controller must confirm the configuration before you can write a point.

  1. Get the points: GET /sensing/v1/controllers/{serial}/modbus/points. This call reads only. Any token can make it.
  2. Find the point with writable set to true. Copy its key, for example relays.relay_1.
  3. Write the point: POST /control/v1/controllers/{serial}/modbus/points/{key}/write. This call needs a control token.
curl -sk -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"value": true}' \
  "https://192.0.2.10:8443/control/v1/controllers/F1000000/modbus/points/relays.relay_1/write?wait=30"
FieldMeaning
valuetrue or false for a coil, such as a relay. A number for a register. The label for a register with named values, for example "Toggle".
verifyOptional. The default is true: the Controller reads the register back after the write.

The answer has command.modbus. verified is true when the read-back value is the written value. deviceStatus is the result from the Modbus device, for example ok or timeout.

The write goes over LoRaWAN. A result can take some seconds, so use wait=30.

To send a write again safely, add the header Idempotency-Key (8 to 128 characters). The same key with the same body does not write again. It gives the first command.

If the Controller has not confirmed its Modbus configuration, you get 409 with reason MODBUS_CONFIG_NOT_ACKNOWLEDGED. A read-only point gives 422 with reason MODBUS_ENTRY_NOT_WRITABLE.

Wait for the result

Add ?wait=0 to 30 (seconds). You get 200 when the result is final in that time. If not, you get 202 and a poll path. A final result is not always a success. Read command.status.

Command statusMeaning
pendingstage is queued or sent.
confirmedThe Controller reported the new state.
refusedThe Controller did not do the command. reason tells why, for example LEAK_INTERLOCK.
timed_outNo answer by expiresAt (5 minutes for output commands). A late answer can change it.
failedThe Edge Server could not send the command.

Errors

Errors are JSON: {"error": {"code", "message", "reason", "details"}}. See Errors and limits.