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.
- Get the points:
GET /sensing/v1/controllers/{serial}/modbus/points. This call reads only. Any token can make it. - Find the point with
writableset totrue. Copy itskey, for examplerelays.relay_1. - 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"
| Field | Meaning |
|---|---|
value | true 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". |
verify | Optional. 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 status | Meaning |
|---|---|
pending | stage is queued or sent. |
confirmed | The Controller reported the new state. |
refused | The Controller did not do the command. reason tells why, for example LEAK_INTERLOCK. |
timed_out | No answer by expiresAt (5 minutes for output commands). A late answer can change it. |
failed | The Edge Server could not send the command. |
Errors
Errors are JSON: {"error": {"code", "message", "reason", "details"}}. See Errors and limits.