Control
The control flow happens in the background, from your cloud to Flip's cloud.
Control flow
Commands are sent to devices whenever utilities desire, within the bounds of the programs. On average, commands should be sent to a specific device no more than once per day.
Push mode / webhooks (recommended)
The preferred method for command delivery is Webhooks. Flip's cloud will deliver commands to an endpoint of your choice. See the Command Created for more details.
Message queue mode
Depending on your system's capabilities, we may also send commands to your servers via HTTP webhooks, or we may open up a Kafka or MQTT messaging queue. The message payload will generally be equivalent to the Command Created payload.
Polling mode (not recommended)
In order to receive commands in polling mode, poll our GET /v1/commands once every minute. Commands are shared in batches whenever we receive them from utilities. They may be sent 24 hours in advance or 10 minutes ahead. They will generally span 1 to 4 hours for batteries.
We recommend scheduling commands directly into the BMS if supported, as it increases reliability and reduces latency. Alternatively, setting them in your cloud scheduler is acceptable as well. If you have no scheduling feature, please let us know, and we will instead send you commands "just in time".
Anatomy of a command
A command is always specific to a device, and always related to an event. It will contain a single action and have a default device_state of PENDING.
A command will always have a start and an end time. Its battery_commands.mode will be one of CHARGE, DISCHARGE, STANDBY, BACKUP, SAVINGS or SELF_CONSUMPTION. Depending on mode, it may also have a power_mode or a setpoint_w attribute.
Confirming (for all modes)
When a command is sent to your servers, device_status is marked as PENDING in ours. We expect each command to be acknowledged once it has been scheduled by setting device_status to OK via PATCH /v1/commands/{id}. Alternatively, if you were not able to schedule it, set device_status to FAILED and describe a reason in device_status_reason. If we do not receive confirmation within 15 minutes we will consider the command to have failed and will send a new one.
Overriding commands
We may update the status of a command, for instance if an event was canceled by a utility (CANCELED), or if a homeowner updated their participation (OPT_OUT). In this case, the device_status will be reset to PENDING and we will request again that you acknowledge the cancelation of the command on your end.