sonnen ecoLinx

Version: 20220906

Official API Local 

 OS 2.10 OS 3 


Existing systems will require update to V2 API.

9.2022, sonnen will begin pushing out the new API V2 to all ecoLinx products.  If you have already implemented an older version of Control4 driver in your project (below 20220811), you will need to update to the latest version to continue to use.  See Driver Documentation for new setup procedures.


Dark Sky Integration End-of-Life (Jan. 2023)

  Currently the Control4 driver uses Dark Sky for weather integration.  This Cloud API will be shutting down starting 1.2023.  Cindev has updated the driver to support two other weather APIs for continued integration.  Dealers will need to select the appropriate Weather API in the driver to continue to use weather integration.

National Weather Service.  This API supports receiving weather alerts without requiring an API key.  For more information on this API click here  This API allows for weather alerts and cloud coverage data.  The alerts are also aggregated from multiple sources.  It does require an API key which can easily be obtained from their website.  Currently, a free API key allows for 500 API requests each day.  By default, the driver requests weather alert data every 30 minutes, or 48 requests per day.  For more information this api click here




Smart energy management using sonnen ecoLinx and Control4. Developed by Cindev, Control4 systems now can control the clean energy stored in ecoLinx batteries dynamically in their smart home.


Use Control4 with energy automation

Energy automation is the convergence of home automation and energy management, specifically enabling intelligent energy storage to manage how smart homes are powered, including the addition of clean energy.  The ecoLinx “energy ecosystem” augments Control4 systems by integrating them with residential solar and energy storage, bringing clean tech to smart homes and enabling the ecoLinx to manage how energy is consumed and devices are powered throughout the home.  

The operation of a smart home can be significantly enhanced by properly controlling how homes use energy. Traditional use cases center the home automation experience on providing the ultimate comfort and convenience to the homeowner by tailoring each system to their specific needs and wants. Smart homes, with energy automation, take this experience to another level by managing the energy consumption of the home without requiring the owner to plan or react to changes in energy availability, e.g., power outages or peak times of day.


The use cases for energy automation/Control4 Integration

Smart Configurable Backup

Users with the ecoLinx and Control4 automation system can benefit from the smart configurable backup functionality that provides optimal control over their home automation system.  Using smart power devices (ADAPT Energy, EMCB breakers, WattBox, Pakedge, Panamax, etc...) allow dealers to configure the home for optimal battery strategies for each homeowner.  This allows the ecoLinx to not only focus on managing excess energy production over what is consumed but further tailor the consumption based on need and priority defined by the homeowner.  In the event of a power outage, the ecoLinx will provide backup power to energized circuits.  The decision as to which circuits and devices get energized is based on the Energy Profile the customer requests and can be a part of predefined rules set by the user’s home automation dealer.  An example scenario is presented below:

  1. A power outage occurs and the ecoLinx begins providing backup power to the main panel (which is also feeding the home network equipment).
  2. The Control4 driver determines the amount of energy left on the battery based on current consumption then activates the customized backup profile for this event.
    1. Smart Configurable Backup. Intended for normal power outages keeping common use and essential loads and devices on
    2. Smart Configurable Backup Extended. Activated when battery reserves are below 20% and is intended to power only the essential devices in home
  3. The driver will then configure home based on profile selected and continue to monitor power usage.

Dealers also can configure home actions when power is restored, thereby returning devices back on and life back to normal.

Smart Weather Forecasting

The sonnen ecoLinx Control4 driver also uses weather forecast data to dynamically modify the ecoLinx’s backup reserve setting.  For example, if the energy automation system detects a severe thunderstorm warning in the user’s area, the system will automatically increase the ecoLinx unit’s energy reserve percentage 100% to prepare the user for the incoming storm and potential loss of grid power.

This further enhances the level of flexibility as it then can reserve the battery capacity for backup when it is really needed. In a static configuration this can lead to losing the optimization range when the likelihood of a power outage is very low.

*** New to OS 3.0 ***
The Control4 driver now uses Dark Sky for weather data.  This API allows for better analytics and access to multiple sources of weather data.  For more information about Dark Sky:

Smart Demand Control and Load Management

Control4 dealers can customize load shedding and load shifting principles via Composer programming actions.  What this means is that the ecoLinx works with the home automation system to decrease load usage and discharge the battery when appropriate.

Let’s say a customer wants to employ their ecoLinx in daily cycling during their peak time-of-use (TOU) window to effectively “flood the peak”.  In a TOU scenario, the energy automation system employs load shedding to maximize the amount of energy the ecoLinx provides during the peak period.  If, for example, the energy automation system lowered the shades, dimmed the lights, increased the thermostat by 1-2 degrees, and turned off non-essential loads that could decrease consumption by say 2,000W.  On a 10 kWh ecoLinx, that is an additional 2 hours’ worth of energy that can be used to “flood the peak” instead of contributing to the peak.

Most importantly, the sonnen ecoLinx discharges its stored off-peak power and locally-generated stored sunlight, to meet the majority of the home’s load during this expensive, dirty peak time, rendering the home invisible to the grid, while saving money.


Controlling Breakers, Power Devices

The sonnen has licensed the Cinegration Power Agent driver which allows the control of relay type devices from the main Control4 screen and has a variety of icon styles and themes to configure and group your devices together.  The Power Agent driver connects via a relay connection to the control drivers Wattbox, Pakedge, and Panamax for power strip device level control.  Breaker or circuit level control can be accomplished via the ADAPT energy system or Lumin Smart.  For more information on the Power Agent, click here.


The future of energy automation

With the smart demand control and load management capabilities now available to Control4 systems, the natural extension of this feature would be to allow for utility demand response program integration.  Thus, providing ecoLinx owners and utilities benefits from programs in place to utilize the ecoLinx’s dynamic clean energy capacity that would be dispatchable on demand.

As the energy and home automation ecosystems expand the ecoLinx will remain the link that allows for the application of other use cases that can leverage further management of loads for the better optimization of the operation of a smart home.


Contacts for additional information and assistance:

sonnen Applications Engineering Team


Energy automation with Control4 - Cinegration

Cinegration Development LLC

6425 W 52nd Ave., Suite 1

Arvada, CO 80002



Control4 Integration Benefits

  • Control4 UI button icon for home battery state
  • Control4 webview (launch sonnen battery dashboard) from a T3/T4 touchscreen
  • Complete two-way communication (via local IP)
  • Control4 Composer Events, Variables, Actions and Conditionals for all normal operation
  • Control reserve level via T3/T4 touchscreen or Control4 Composer programming
  • Simple Email, Text, Push, and Voice announcements pre-built into driver
  • Weather Alerts from DarkSky
  • Energy Profile Buttons for complete custom control of all energy applications
  • Control a variety of power integrations, Wattbox, Pakedge, Eaton, ADAPT Energy and others.


Energy Profile Buttons


The sonnen ecoLinx Control4 driver comes with Energy Profile Button drivers.  These drivers are like mini scenes, macros, modes the home and energy system can be set to.  Have a customer that wants a setting for Summer, Winter Home and Away?  Simply add 4 of the Profile buttons to the home and label them accordingly.  Each button can be a different color helping customers distinguish between actions.  

Button colors can be blue, green, orange, pink, purple, red, salmon and yellow.  The driver has a number of options for simple 'then' actions

  • (General Alert and Notifications) Push, Email (Service and Customer), Voice alerts and Navigator popups are routed through the sonnen ecoLinx driver. This means that a Control4 integrator only has a single email address field to fill out and all emails, text, etc... are automatically created.  Customization via Composer programming is always acceptable as well.
  • Trigger announcement, lighting scene, set the battery reserve level of the ecoLinx, turn on/off Power Agent and Relay (2.9+).drivers and turn off Audio/Video Rooms
  • Composer Programming for advanced solutions



Compatible Hardware

Sonnen ecoLinx batteries.



Compatible Control4 Systems
This driver is compatible with Control4 2.10.6 or higher.


Warranty and Disclaimer

For a full description of terms and conditions pertaining to Cinegration Development's drivers please visit


sonnen Factory Limited Warranty

Driver is provided by Cinegration Development LLC.  All rights reserved.

Driver Download Latest (20220811) (, 6,607 Kb) [Download]

Driver Download (Legacy - V1 API) (, 8,657 Kb) [Download]

No posts found

Write a review

General Installation Notes:

When the home loses power, the ecoLinx will take up to 100 milliseconds to transfer over to the battery. This is very fast, and most devices will not notice. However, it is recommended that a small UPS be installed on all devices that control the home network and the main Control4 unit. Other devices that may need a UPS are: Microsoft Xbox One (S), PS4, PS5 and other large solid-state devices.

The ecoLinx and driver work via a local api. Cloud/Internet connectivity is required for weather alert information.


A word of advice... Please do not attempt to add this driver (or any new driver) that you've never used on a Friday afternoon right before you hand over to the client. This driver has a lot of features and options. Please review these and create an energy plan both for the different profiles and actions for weather alerts and power events (grid outage).  

Setup (hardware / main driver):

Install sonnen ecoLinx according to hardware manual
Verify you can access the battery's local ip address via a web browser (http://sonnenip:8080)
Add driver to project (main driver: sonnen_ecoLinx.c4z)

If there is more than one ecoLinx in the home, select it under the property Device List. Each ecoLinx will require one sonnen_ecoLinx.c4z driver

At this point the driver should be communicating with the battery and the property Device Connection should read Online. If this is not the case, please verify IP address and setup of ecoLinx

Below are optional settings and configurations the dealer should adjust to best fit the project.  

Optional: Set Notifications (OFFLINE, GRID_LOSS, ALERT, NORMAL)

The sonnen ecoLinx driver has different general events and actions that are pre-built in.  Below is a description of each with the default settings.  For more information on Notify Actions and how they work click here

  • -> Message.  This is the default message that can be sent via Push, Email/Text and Voice Alerts.
    • [NAME] is a variable of the device name (default: sonnen ecoLinx)
    • [TIME_LEFT] is a variable that stores the amount of time left on the battery based on past 30 minutes of usage
    • [ALERT] is the specific weather or utility alert that was triggered (example: Tornado Warning)
    • OFFLINE: [NAME] is offline or not communicating with Control4
    • NORMAL: Power restored. Home returning to normal
    • GRID_LOSS: Power outage detected. Home has [TIME_LEFT] hours remaining of power
    • [NAME] has received an alert. [ALERT]
  • -> Push. This sends the Control4 push notification at the level specified.  Options are: No, Info, Alert, Alarm
    • OFFLINE: No
    • NORMAL: Alert
    • GRID_LOSS: Alarm
    • ALERT: Alert
  • -> Service_Email.  Sends an email or text to the service email that is listed under property Email: Service.  The subject line of the email will be: Control4 System: [PROJECT_NAME].  Email is sent via SendGrid and does NOT require Control4 4Sight subscription
    • OFFLINE: Yes
    • NORMAL: No
    • GRID_LOSS: No
    • ALERT: No
  • -> Customer_Email.  Same as Service_Email except it will send an email to the customer.  Email subject is defined under property Email: Subject
    • OFFLINE: No
    • NORMAL: Yes
    • GRID_LOSS: Yes
    • ALERT: Yes
  • -> Voice.  Send a voice alert to either Control4 T3 touchscreens or the voice announcement created with the Voice Agent driver.  Dealer must have the Voice Agent driver installed and activated to use voice alerts.
    • OFFLINE: No
    • NORMAL: No
    • GRID_LOSS: Touchscreens 
    • ALERT: Touchscreens
  • -> Navigators. Creates a popup on Control4 T3 touchscreens and displays the -> Message property.
    • OFFLINE: No
    • NORMAL: No
    • GRID_LOSS: No
    • ALERT: No

Optional:  Set Weather Alerts (sonnen weather response whitepaper)

The driver integrates with Dark Sky to deliver weather alerts to Control4 systems.  Every 10 minutes the driver will check with Dark Sky to see if there are any weather alerts.  Weather alerts are then checked against the property Weather: Alert Types.  If a match exists, the driver will activate the ALERT event.  Programming including triggering Energy Profiles should be done via Composer Programming.  

The default weather types are: Hurricane, Thunderstorm Warning, Tornado, Blizzard, Winter Storm Warning, Tropical Storm Warning, Flood

Note: Add Watch, Advisory or Warning to a weather event to customize exactly when a weather event should be triggered

Note: Weather alerts that are NOT in the Weather: Alert Types property will not trigger the weather event

The Composer variable Weather_Alerts contains the alert (or alert separated by a comma) that have been received.
Composer Variable Weather_Alerts_Message is a preformatted message that provides a better description to the customer.  Here is the default message ([ALERTS] would be the same as Weather_Alerts variable example: Tornado Warning, Flash Flood Watch):

National Weather Service has issued a [ALERTS] in your area.


Optional: Create Energy Profile Buttons (via the sonnen_energy_profile.c4z)

Most customers will want different profiles, scenes or macros to be triggered either by themselves or automatic programming.  These are programmed and configured via the Energy Profile Button driver.  Similar to the sonnen driver's Notifications, the Energy Profile button simplifies the programming for the dealer and gives the customer an awesome mode selection via the Control4 GUI.  If the home has 3.0 dealers can also create a special room/dashboard (aka Energy Automation) and place all the icons to control the energy of the home from a single menu.


Energy Profiles come with a variety of actions for general notifications and triggers.  Service_Email and Customer_Email use the sonnen ecoLix driver's Email properties for event for processing.  This allows dealers to only enter the customer's info into a single place for all the energy drivers. Below is the list of what the Action the Energy Profile buttons can do when activated

  • -> Message
    • ACTIVATED: Home is now set to [NAME] mode
    • DEACTIVATED: [NAME] has deactivated
  • -> Push
    • ACTIVATED: Alert
  • -> Service_Email
  • -> Customer_Email
    • ACTIVATED: Yes
  • -> Voice
    • ACTIVATED: Touchscreens
  • -> Navigators
  • -> Announcement.  Will trigger a Control4 announcement
  • -> Lighting Scene. Will trigger a Control4 lighting scene
  • -> Battery Reserve Level.  Adjust the battery reserve level of the connected ecoLinx.  If set to -1 the driver WILL NOT change battery reserve level
  • -> Turn Off Devices.  Turns off (opens) relay-controlled devices connected via the Power Agent or Relay (2.9+) driver
  • -> Turn On Devices. Same as off only turns on (closes) the relay
  • -> Turn Off Rooms.  Rooms that should have audio/video turned off

 Additional programming and options can be done via Composer Programming.


Using 3.0?

If the home will be using 3.0, dealers can take advantage of the Control4 dashboard and create a personalized Energy Automation dashboard for their customer. Integrators should implement this interface on all projects.


Create a new room in the project and label Energy Automation

Add all profile buttons, sonnen ecoLinx and other energy automation devices to the dashboard (ex. power agent, relay-controlled power devices, thermostats)

Create favorites on the room and arrange to fit home


UI Button and Webview:

The driver comes with a Control4 UI button that can be used to access the sonnen dashboard and show grid online/offline state. By default, when the icon is pressed (Single Tap) the driver will tell the T3 touchscreen to launch the sonnen dashboard. Webview support is only available on the T3 touchscreens. Dealers can also use Composer programming for advanced actions or hide the icon from customer's view.


If the home is connected to the DriverCentral portal, the driver can use auto update for new and improved software as it becomes available. To enable auto update, change the Automatic Updates property to On. For more information on DriverCentral and the project portal, click here


Control4 Events, Variables and Actions


  • Grid Power Outage
  • Grid Power Restore
  • Is Discharging
  • Is Charging
  • Battery Level Changed
  • Battery Reserve Level Changed
  • Battery Mode Changed
  • Grid Voltage Changed
  • House Consumption Changed
  • Solar Production Changed
  • Solar Power Creation Starts
  • Solar Power Creation Stops
  • Time Remaining Changed
  • Driver Communication Failed
  • Energy Alert
  • Weather Alert Started
  • Weather Alert Ended
  • All Weather Alerts End

Composer Variables

  • Battery_Charging_PrettyState (string) ex. charging 2.3kW
  • Battery_Charging_State (string) ex. charging
  • Battery_Current_Level (number) 0 - 100
  • Battery_Mode (string) ex. Backup Power, Self Consumption, Time of Use
  • Battery_Reserve_Level (number) 0 - 100
  • DeviceConnectionStatus (string) ex. Online, Offline, Failed to check-in, Polling Stopped, Polling Started
  • Driver_State (string) ex. OFFLINE, NORMAL, GRID_LOSS, ALERT
  • Grid_Voltage (number) ex. 240
  • House_Consumption_Watts (number) ex. 7400
  • Solar_Production_Watts (number) ex. 4351
  • Time_Remaining_On_Battery (level) ex. 3.1  (this would be 3.1 hours remaining)
  • Weather_Alert_Message (string) ex. National Weather Service has issued a Tornado Warning in your area
  • Weather_Alert (string) ex. Tornado Warning

Composer Actions

  • Trigger Driver Event.  Puts the ecoLinx driver into this event state
    • Event -> offline, normal, grid_loss, alert
    • Message -> custom message for this event
  • Set Battery Mode.  Changes the operating mode of the battery
    • Mode -> Backup Power, Self Consumption, Time of Use
  • Set Battery Reserve Level.  Change the reserve level of the ecoLinx
    • Level
  • Set Energy Profile
    • Profile -> List of Energy Profile Buttons in project



Cinegration strives to provide fully working drivers without defects.  However, changes and bugs may be found.  Because of this, any bug/maintenance update to this driver will be free of charge.  However, due to the ever-changing nature of computer and audio/video systems, if a new version of the Control4® software creates issues with this driver, or feature enhancements, an upgrade version will be provided.


  • 20220906
    • Improved dashboard loading on init
    • General updates/improvements
  • 20220817
    • General improvements/updates. Additional changes part of update
  • 20210816
    • Updated UI package to support new Control4 OS
  • 20201201 (Major Update)
    • Added new Control4 dashboard. This new dashboard allows homeowners to adjust their Energy Automation settings and see in real time energy consumption, production, and battery information. This is available on Control4 2.10.6 and 3.0 systems. The Dashboard can be accessed via any Control4 touchscreen.
    • Updated monitoring of battery data and improved grid loss notifications
    • General bug fixes and improvements
  •  1069
    • Dealers can now type IP address manually into driver (Network Connections)
    • Bug and Performance updates 
  • 1068
    •  Integration with Lumin Energy
    •  Addition of Cloudy Weather Auto Charge
    •  Bug and Performance updates
  • 1016
    • Change to new driver (sonnen_ecoLinx.c4z).  Existing systems MUST replace outdated driver to continue support and configuration.
    • Created new Energy Profile Button
    • Streamlined interface for OS3.0
    • Change over of Weather to Dark Sky
    • Improved communication with ecoLinx
  • 1012
    • Support for sonnen Global Firmware
    • Updated for Voice Agent integration
    • Improved weather monitoring notifications
  • 1009
    • Updated to sonnen USA firmware
    • Driver now monitors for firmware updates and prevents driver from going into loop state 
  • 1008
    • Eaton API Communication updates
    • Driver now can be loaded using Virtual Composer
    • Improved polling and monitoring of events
  • 1007
    • Initial Release