Flip Energy API
Flip Energy API
  • Overview
  • Important concepts
  • Authentication
  • Enrollment process
  • End-user app design
  • Monitoring / Telemetry
  • Control
  • Mobile App API
    • Devices
      • Create Device
      • Read Devices
      • Read Device
      • Update Device
      • Delete Device
    • Enrollments
      • Create Enrollment
      • Read Enrollments
      • Read Enrollment
      • Delete Enrollment
    • Events
      • Read Events
      • Read Event
      • Update Event Participation
    • Programs
      • Read Programs
      • Read Program
    • Sites
      • Read Site
      • Update Site
  • Cloud API
    • Sites
      • Get Site Token
      • Get Sites
    • Commissioning
      • Commission Site And Devices
    • Telemetry
      • Report Battery Telemetry
    • Commands
      • Command Created
      • Update Command Status
    • Webhooks
      • Overview
      • List of events
      • Webhook headers
      • Schemas
        • Command
        • Enrollment
        • Event

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#

Command
id
string <uuid>
read-onlyrequired
event_id
string <uuid> | null 
read-onlyrequired
device_id
string 
required
starts_at
string <date-time>
read-onlyrequired
Time at which the action should start. Note that this may be before the event itself has started. For instance, in order to pre-charge a battery prior to a discharge event.
ends_at
string <date-time> | null 
read-onlyrequired
Time at which the action should stop. If null, the action should continue until replaced by another one.
duration_s
number  | null 
read-onlyrequired
Duration of the action, in seconds. If null, the action should continue until replaced by another one.
is_preparatory_action
boolean 
read-onlyrequired
Whether the command is not part of the event itself but in preparation for the event. For instance, charging a battery before a discharging event.
battery_commands
object (BatteryCommand) 
read-onlyrequired
mode
enum<string> 
required
The mode the battery should go into during this period.
Allowed values:
BACKUPCHARGEDISCHARGESAVINGSSELF_CONSUMPTIONSTANDBY
power_mode
enum<string>  | enum<null> 
read-onlyoptional
Specifies details for the action. Present if the state is CHARGE or DISCHARGE only
Allowed values:
FOLLOW_LOADSETPOINT
setpoint_w
integer  | null 
read-onlyoptional
Defines specific wattage level, only used if power_mode is SETPOINT. In Watts, always a non-zero positive integer.
enable_grid_import
boolean  | null 
read-onlyoptional
Allow importing from the grid if charging.
enable_grid_export
boolean  | null 
read-onlyoptional
Allow exporting to the grid if discharging (battery only).
backup_reserve_percentage
integer  | null 
optional
The minimum state of charge the battery will keep when discharging.
>= 0<= 100
maximum_charge_percentage
integer  | null 
optional
The maximum state of charge the battery will charge to, only when charging from the grid.
>= 0<= 100
status
enum<string> 
read-onlyrequired
The status of the command itself. Only OK means that the command is happening.
Allowed values:
CANCELEDOKOPT_OUT
device_status
enum<string> 
required
The acknowledgment of the command by the device. Only OK means that the device is ready to perform the command.
Allowed values:
FAILEDOKPENDING
device_status_reason
string  | null 
optional
It helps to share more human-readable information when setting the device_status. We will use it when we set device_status to PENDING, and feel free to use it as well when setting to OK or FAILED.
created_at
string <date-time>
read-onlyrequired
updated_at
string <date-time>
read-onlyrequired
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.
Modified at 2024-07-08 20:33:32
Previous
Monitoring / Telemetry
Next
Create Device
Built with