FAQ - SMA Monitoring-API

• An end-customer decided to invest in a SMA PV-system and placed an order with an electrician company
• An installer/employee of the electrician company will build and configure the new solar PV system on-site at the customers location
• With his previously registered/created SMA user account, the installer will login on SMA portals www.sunnyportal.com or ennexos.sunnyportal.com
• Using the SMA setup wizard, the user will then register the new PV-system and connected devices on the SMA portal
• In this setup process, the user will also define (or invite) additional users, such as the plant owner, eligible to access a given system. Each user must be assigned a certain permission-role and a relationship (installer, owner, operator)
• Users with system owner role may then monitor their systems on the SMA portals/Apps or authorize system data transfer to 3rd party applications via the API access flows

SMA will notify the resource owner of a given system using the eMail address provided for the SMA user account. A 3rd party provider will need to know the plant owners SMA eMail-address in order to initiate the custom authorization flow.

The resource owner of a system must be defined for new plants in the PV-plant setup wizards flow or for existing plants in the user administration. Eligible SMA resource owners must be configured on Sunny Portal and SP powered by ennexOS alike.

On SP powered by ennexOS, the plant owner will be defined during Step2 of the setup process (https://ennexos.sunnyportal.com/configuration/view-plant-registration). SMA user (installer) shall provide the plant owners eMail-address in the foreseen input field. In case the plant owners SMA user account already exists, the related PV-system will be added to the user accounts/plant portfolio. Otherwise an invitation to create the SMA account will be send to the provided eMail address.

In the navigation “user management” on both SMA portals the new plant relationship (plantOwner) can be added to an existing SMA user account. Or you may invite a new user to the plant.

From a conceptual point of view, only one plant owner should be configured for each plant. Even though it increases complexity in the current ennexOS SP implementation, it is not yet prevented that more than one plant owner is configured for a given plant.

a. To access the User Management on SMA Sunny Portals, the user must have at least an administrator or installer role.

b. Definition of the “plant owner"

• On SP Classic the "plant owner" flag can be assigned to any user (role : admin, installer, user, guest)
• On ennexOS the "plant owner" flag can be assigned to standard user and administrator

Once this “ownership flag” has been defined for the user, the user has the permission to decide on the 3rd party application request.

Please assure that the user-account on Sunny Portal has been properly created and the user has provided the “country” on user-account registration. This is an essential information for our consent eMails as the language setting depend not the country information.

Furthermore it is highly important that the user created/completed the account setup prior to the permission-request. Sometimes an invitation was send out by the installer and the invited user never completed the registration. In this case we cannot terminate the permission-request for legal reasons (as the invited user never accepted the Portal terms).

Our permission framework intents to capture the system-owners permission to approve a 3rd party application to be fully compliant to GDPR-regulation. So ideally the system-owner (user-account) has been “flagged” as system-owner on our Sunny Portal.

As we recognize that for existing system you (or the installer) may have not invited the system-owner to the SMA Portal, there may be difficult processes involved. If you have captured the system-owner consent in your own service contract, you may use the workaround. By “flagging” your installer/service-account as system-owner, you could permit the access on behalf or the “real” owner (as his delegate).

Down-site to this approach is that the “real owner” may not be able to authorize further 3rd party apps himself (e.g. forward his PV-system data into an EV-app from Audi or Tesla).

As we are still in the beginning of the SMA API journey, currently, there is none configured yet. With increasing API-gateway traffic and experience on traffic priorization, we may introduce client quotas in Autumn 2020.

Please keep in mind that the Monitoring API does NOT provide live data, only “historical data” and it always depends on the configuration of the plant, how often the data is supplied from the plant into our backend systems and then returned in the API with e.g. 5 or 15min resolution.

Any 3rd party application will need to register with SMA and will be provided client credentials in order to access SMA systems.

O&M providers who has been assigned to monitor a SMA system, will initiate the consent-flow by providing the plant owners eMail (SMA user) address in the “bc-authorize” request of the SMA custom flow. Users consuming Smart-Home or eMobility apps will trigger the consent flow them-self by clicking on a “Connect-SMA” button in the 3rd party app.

From a user perspective, the 3rd party authorization request will look the same for both flows. The plant owner will need to login with his user credentials on the SMA systems, review the information on the user-consent screen and take his decision to permit or decline the access request.

SMA user (being plant owner of a certain number of systems) will grant access to all of his systems at a certain point in time. User-consent will remain to be valid until actively revoked by the user on the SMA portal ennexos.sunnyportal.com/configuration/view-third-party-apps.

In case the (commercial) plant owner adds new systems to the portal over-time, user-consent needs to be re-executed to gather the permission for these new systems (“Permission-scope change”). The older consent will though remain to be valid to ensure access according to the prior permission scope assuming that the plant ownership for these plants still exists. Furthermore, a new (additional) consent-request may become necessary in the future, e.g. in order to enable the usage of a SMA Control-API.

Most likely, you have not yet been provided with user-consent for system on the SMA custom flow. Using the Client-Token on the Monitoring API without a valid plant owner permission, will result in an empty response.

The language setting of the resource owner's user profile in SP is used for distinguishing the language (currently either German or English) of the consent request eMail.

Our former “Classic” API provided access to systems which have been setup on the classic portal only and based on XML-data. Our new SMA Monitoring API provides JSON data objects and access to system which have been setup on Classic and ennexOS alike. Key-difference is the new API access / security, which requires that a user with plant owner role/rights must be defined on all systems and on Classic and ennexOS portal alike. This user must permit the access to systems to be consumed by our new API. This was not necessary on the former API.

The most simple answer this question is: Our Monitoring API can only provide the data which is available on our portal(s). If you see the data for a specific system/device on the portal, this data should be served on our API. If for a given system you do not see the EnergyBalance on the UI, the API will not provide it alike.

The availability of the EnergyBalance on a specific system depends on many factors, e.g. overall system setup, connection method of inverters, other devices availability on system, portal configuration. In general, the EnergyBalance can only be provided for systems on which gridConsumption and feedIn values are available.

SMA Monitoring API design provides pre-defined resolutions which depend on the chosen period. For period “recent”, “day” and “week” you will be served the highest resolution available on the specific system or device.

Thus for converting W to kWh, you must use the given timestamps of the provided data in order to do the transformation.

Please be aware, that on SMA Sandbox environment, ennexOS plant data is simulated with a 15min resolution as this environment is only meant for setting up an application/integration initially.

Please make yourself familiar with the following description & dependencies to optimise the request-and data-traffic load of our data integration. There is no need to request data more often than the processing speed (on Classic systems), because no new data will be available.

Most importantly, there is a huge difference regarding the supported data refresh rates for systems on Sunny Portal Classic (Webconnect, Home Manager, Cluster Controller) and the new ennexOS Sunny Portal with Data Managers.

For Sunny Portal Classic systems new data sets are only provided on completion of data processing (validation, aggregation of time-intervals). Even if the system/device uploads new (raw) data every 15 minutes it takes up to 2hours until the new data is provisioned on the UI (and API alike). The refresh rate can be reduced to about 15min by obtaining a “Professional Package” for the individual system (in certain countries). The “Pro” Option can be purchased on “Sunny Portal Online Store”.

On the ennexOS we changed the procedure. Data Manager uploads data as a default every 5 minutes (depending on the communication profile set in the portal). The difference now is the processing of the data. We do the processing on the fly when you either select a view in Sunny Portal or access is it via the API.

--- Classic ----
Home Manager
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Webconnect
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

Cluster Controller
Upload: every 15 minutes
Processing: up to 2 hours
with Professional package for system: about 15 minutes

--- ennexOS ----
Data Manager
Upload: every 5 minutes
Processing: On the fly

Our Monitoring-API will provide access to systems stored in either portal backend. To setup a new system you will either use SMA Sunny Portal or Sunny Portal powered by ennexOS.

• www.sunnyportal.com to setup systems with Home Manager, WebConnect, Cluster Controller and Webbox
• ennexos.sunnyportal.com to setup systems with Data Manager M or Data Manager L

In the API-request you will not need to define the specific portal backend. You can differentiate the PV-system source by the provided plantID-format. SP Classic systems identifiers are defined as GUID (8-4-4-4-12) value and the ennexOS systems id values are pure number format.

In SP powered by ennexOS UI, the Monitoring API plant and device IDs are part of the URL when navigating to the corresponding plant / device.

In SP UI, the Monitoring API plant ID is part of the URL when clicking on the PV System Logbook navigation tree item. The Monitoring API device IDs are not displayed on SP UI.

• For (classic) plants, you can configure for each plant in Sunny Portal UI, in which resolution the data shall be provided in UI and thus also via Monitoring API
• For ennexOS plants, the data is normally uploaded at least every 5 min to the ennexOS backend and thus, normally, can be provided in 5min intervals. For some properties, the interval might be different, see e.g. GridSettings properties.

In our Monitoring API design you cannot request a specific resolution for measurement data and periods “Recent”, “Day” and “Week” as you will be served the highest resolution available. Thus for converting W to kWh, you must use the given timestamps of the provided data in order to do the transformation.

Please be aware, that on Sandbox environment, only ennexOS plant data is simulated with a 15min resolution as this environment is only meant for setting up an application initially.

For ennexOS plants and devices, the logId returned in logs endpoint is the Event ID displayed in SP powered by ennexOS Event monitor.

The messageTagId identifies the message text returned in the logs endpoint.

For classic plants and devices, the logId is currently empty, as the Event ID is not persisted in SP backend.

We plan to implement a mapping from messageTagId to Event ID which is unique in most cases, so that also for classic plants and devices, the logId will contain the Event ID.

If some properties of a measurement set are not available (null) for the requested timespan, then they are not contained in the result set.

If no data is available for the whole timespan, then an empty list is returned.

Example: Request for weekly measurement data (from Mar 1 -> Mar 8), but the plant was not communicating for the last two days of that span. What does the response look like?

Response: Data available between 1st and 8th of May would be provided, thus from 1st to 6th of May. For the 7th and 8th of May, no measurement sets would be returned, if no data values at all are contained in our backend (so it depends also the measurement set properties).

Yes, old data is kept in our backend. In the Portal UIs, you can see this data of deactivated devices. Also e.g. the energy balance of such a plant would still contain the values of the deactivated devices, as the historical data is kept untouched.