> For the complete documentation index, see [llms.txt](https://docs.ecosuite.io/user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecosuite.io/user-guide/modules/connectivity/integrations.md).
# Integrations
Integrations are the connections that pull readings from vendor monitoring platforms such as SMA, SolarEdge and AlsoEnergy into Ecosuite.
Ecosuite doesn't store readings itself. They live in SolarNetwork, and Ecosuite reads them from there. An Ecosuite integration is a set of SolarNetwork objects that Ecosuite creates and manages for you. This page describes integrations in terms of the two things you deal with directly: nodes and source IDs.
### Key concepts
| Term | Meaning |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Datum | One timestamped reading for a source, e.g. `watts = 9711, wattHours = 5088` at 02:45. |
| Integration (Ecosuite) | Everything needed to pull one project's devices from one vendor and write them to a node as source IDs. It shows up as rows under Connectivity > Integrations. |
| Credential | A SolarNetwork token and secret set up for your organisation. Ecosuite uses it to talk to SolarNetwork. You never enter vendor passwords or API keys in Ecosuite; they're stored on the integration in SolarNetwork. |
A stream is identified by its node and source ID together. The same source ID on two different nodes is two separate streams.
### Where data comes from
Data reaches Ecosuite in one of two ways.
1. Physical nodes. A SolarNode on site reads the meters and inverters and uploads to SolarNetwork. These nodes appear on the Dashboard (Node Health) tab.
2. Cloud integrations. SolarNetwork calls the vendor's API on a schedule and stores the results on a node, with no hardware on site. These appear on the Integrations tab.
Either way the data ends up as ordinary source IDs, and the rest of Ecosuite (Energy, reports, Stream Health) doesn't distinguish between them.
{% hint style="info" %}
Reminder: Ecosuite source IDs follow this pattern:
```
/{projectCode}/{siteCode}/{systemCode}/{DEVICE}/{n}
```
For example, `/NY1/OOC/R1/GEN/2` is generation meter 2 on system `R1`, at site `OOC` of project `NY1`.
The first segment must be the project code. The Integrations and Aliases tabs use it to work out which project a stream belongs to, so a stream whose source ID starts with anything else won't appear under your project. The Integrations table greys out the `/PROJ/SITE/SYS` part to make the device part easier to read.
{% endhint %}
#### Device codes
| Code | Meaning |
| -------------------------- | ----------------------------- |
| `GEN` | Generation (production) meter |
| `INV` | Inverter |
| `CON` | Consumption meter |
| `IMEX` | Import/export meter |
| `PYR` | Pyranometer (irradiance) |
| `WEA` | Weather gauge |
| `STO` | Storage meter |
| `BESS` / `BAT` | Battery |
| `EVSE` | EV supply equipment |
| `MET`, `SWI`, `EXP`, `CAM` | Other recognised device types |
#### Default numbering in the wizards
| Situation | Default suffix |
| --------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Devices added from a vendor | `/INV/1`, `/INV/2` and so on, and `/GEN/1` onwards, numbered in the order you add them |
| Virtual meter (sum of inverters, no physical meter) | `/GEN/100` |
| Enphase system totals | `/INV/100` and `/GEN/100` |
| Solcast irradiance | `/PYR/2` |
| Solcast weather | `/WEA/2` |
| OpenWeatherMap | `/WEA/1` |
You can change any suffix before saving, as long as it starts with `/`.
### What an integration is in SolarNetwork
When you click Create Integration, Ecosuite sets up four SolarNetwork objects, each hanging off the one before it:
1. The SolarNetwork integration holds the vendor account and its credentials, e.g. "Acme SMA".
2. The mapping says which vendor values become which properties, such as `watts` and `wattHours`.
3. The datum stream says which node to write to, which devices to collect, what source IDs to give them and how often to poll.
4. The poll task is the scheduler that runs the datum stream.
| SolarNetwork object | Who creates it | What you control from Ecosuite |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Integration (vendor account) | Someone sets it up in SolarNetwork beforehand, and Ecosuite lists the existing ones. Virtual meters are the exception: Ecosuite creates that integration itself. | Which one to use |
| Mapping | Ecosuite, or you reuse an existing one | Property names, types, multipliers, rounding |
| Datum stream | Ecosuite | Target node, devices, source IDs, granularity, schedule |
| Poll task | Ecosuite, queued to run about 30 minutes after creation | Nothing directly. Its next run shows as Next Data. |
A single datum stream can collect many devices. SolarNetwork keeps a lookup table (`sourceIdMap`) from each vendor device key, e.g. SMA system `12345` device `678`, to the Ecosuite source ID you chose, e.g. `/NY1/OOC/R1/INV/1`. Any device that isn't in the table is skipped without warning, so an inverter the vendor adds or replaces isn't collected until you edit the integration and add it. Two vendor devices can point at the same source ID, which is how a replacement inverter keeps writing to `/INV/1`. All sources in a datum stream go to the one node chosen for that stream.
#### Shared mappings
More than one datum stream can use the same mapping. The wizard lets you pick New mapping or an existing one, and explains that "Reusing one mapping across streams keeps their properties in step." Editing a shared mapping changes every stream that uses it, and the editor warns you ("Saving will change N streams") before you save.
### Supported providers
| Provider | Used for | Notes |
| ----------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SMA | Inverters (Sunny Portal) | 5-minute data. Only active "Solar Inverters" devices are offered. SMA uses OAuth tokens, so if another app refreshes the same token the integration stops working until new tokens are entered in SolarNetwork. |
| SolarEdge | Inverters and meters | 15-minute data by default. |
| AlsoEnergy (PowerTrack) | Inverters, meters, weather stations | Defaults to the site logger's own interval ("Site logger"). kW values are converted to W. |
| SolrenView | Inverters | SolrenView can't list sites, so you type in the numeric site ID (e.g. `5017`). Granularity is 1 minute to hourly, 5 minutes by default. |
| Enphase | System-level inverter and meter totals | Not per microinverter. The system has to report inverter W, inverter Wh, meter W and meter Wh. |
| Solcast | Irradiance (`/PYR/2`) | Uses the site's latitude and longitude, which have to be set on the site. |
| Solcast Weather | Temperature, wind, cloud (`/WEA/2`) | Uses the site's coordinates. |
| OpenWeatherMap | Weather observations (`/WEA/1`) | Uses the site's coordinates. |
| Virtual Meter | A production meter calculated from inverters already in SolarNetwork | No vendor involved. See Virtual meters. |
### Adding an integration
Go to Connectivity > Integrations, click Add Integration and pick a provider. For SMA, SolarEdge, AlsoEnergy and SolrenView the wizard has these steps:
1. Site & System Selection. Pick the project site and system. They give the source ID base, `/{project}/{site}/{system}`.
2. SolarNetwork Credentials. Pick your organisation's SolarNetwork token.
3. Integration Discovery. Pick the vendor account, which must already exist in SolarNetwork. If there isn't one you'll see "No {Provider} integrations exist for the selected credential. Please configure one in SolarNetwork first." That setup happens in SolarNetwork, not Ecosuite.
4. SolarNetwork Node. This is where the collected data will be stored. Nodes the project already uses are listed first, and you'd normally pick one of those.
5. Sources. Ecosuite fetches the vendor's systems and devices live. Add the ones you want, or click Add all, and check each source ID suffix.
6. Data Granularity (SolrenView only). This sets how fine-grained the data is. Ecosuite chooses a poll schedule to match, since there's no point polling more often than the data changes.
7. Virtual Meter Configuration (SMA, SolarEdge and SolrenView, only if you didn't add a meter). The wizard offers a virtual meter that adds up the inverter readings, with the source ID `…/GEN/100` by default.
8. Mapping designer. Check which properties will be recorded, usually `watts` and `wattHours`. You can also do a dry run here. Ecosuite creates a temporary stream, pulls the last 24 hours from the vendor and shows the result as a graph or JSON. Then it deletes the temporary stream, so nothing is kept.
9. Create Integration.
Enphase, Solcast, Solcast Weather and OpenWeatherMap have shorter wizards that create one source ID, or two for Enphase (inverter and meter).
If creation fails partway through, Ecosuite deletes whatever it had already created in SolarNetwork. If it can't delete all of it, it lists what was left behind. If you create an integration that already exists (same node, provider and devices), Ecosuite updates the existing one rather than creating a duplicate.
### Polling
SolarNetwork polls the vendor on a schedule. Each poll asks for everything from where the previous poll stopped up to the current time, so a late or missed poll doesn't lose any data; the next one picks it up.
The default schedule is every 15 minutes for SMA, every 10 minutes for OpenWeatherMap and every 30 minutes for everything else. A schedule can't be faster than the data's granularity, and SolarNetwork rejects one that is. The first poll runs about 30 minutes after the integration is created. The Next Data column on the Integrations tab shows when the next poll is due.
Data is written to the node and source IDs you picked, and Ecosuite reads it back like any other source. If a poll fetches a timestamp that's already stored, the new reading replaces the old one. Each poll usually fetches the latest interval again because vendors often keep updating it after the fact, so this is normal.
#### Errors
Temporary problems, such as the vendor API being down or timing out, are retried automatically, and no time range is skipped. Configuration problems, such as a stream with no properties or a node the account doesn't own, stop polling until someone fixes the configuration. If a single property fails, for example an expression that errors, SolarNetwork skips that property without reporting it and stores the rest of the reading. That's the usual reason a property goes missing from the data.
### Historical data: backfill and rake
Both are in the source's row menu on the Integrations tab.
| | Backfill | Rake tasks |
| -------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| When to use it | Loading past data for a new integration, or replacing a date range that's wrong | Regularly re-checking for data the vendor fills in late |
| What it does | Deletes the existing data in the date range, imports it again from the vendor and recalculates aggregates | Re-polls the last N days (`P1D`, `P7D`, `P1M` and so on) once a day and replaces any reading that has changed |
| Scope | One source, one provider or the whole project | One datum stream |
| When it runs | In the background, with a notification when it's done | Every day at midnight in the node's time zone |
Backfill deletes data before re-importing it. The dialog warns: "This will delete existing data in the selected date range and re-import it from the provider."
Don't backfill or rake a virtual meter. Its values are calculated from live data rather than fetched from a vendor, so rebuilding its history produces wrong numbers and overwrites the correct ones.
### Aliases
Under Connectivity > Aliases you can make an existing stream available under a different node and source ID without copying any data. For example, a physical meter might report as `gen/200` on node 696 while Ecosuite expects `/H4/S1/S1/GEN/200` on the project's node 126. An alias makes the second name read from the first. Aliases are also a way to rename a source without moving its history.
A query for an alias returns the original stream's data under the alias name. Deleting an alias leaves the original data alone. The alias can be on a different node from the original, but both nodes have to belong to the same SolarNetwork account, and the alias node and source ID can't already be in use by another alias or a real stream.
Integrations always write to real source IDs, never to aliases. Calculations that run inside SolarNetwork, such as virtual meters and expressions, only see real source IDs on their own node, so they can't see aliases. On the Integrations tab, each source has a "Create an alias pointing to this source" action.
### Virtual meters
A virtual meter gives a system without a physical production meter one built from inverter streams SolarNetwork already holds. It runs on SolarNetwork's built-in "fixed" integration, so no vendor account or credentials are needed, and Ecosuite creates that integration ("Ecosuite virtual meters") itself.
Every interval (15 minutes by default) the meter records two values. `watts` is the sum of the latest watts from the contributing sources, multiplied by an optional loss factor. Any source that has been silent for longer than the offline threshold (15 minutes by default) counts as zero. `wattHours` is a running energy total that the meter works out from its own `watts` over time.
A few rules apply:
* All the contributing sources have to be on the same node, because SolarNetwork only looks at one node. If the inverters are aliases, pick the real sources behind them, then alias the meter's output back under the project path.
* The output source ID defaults to `…/GEN/100`.
* The newest interval is provisional. The following poll recalculates it, so each value is final one poll later.
* Changing the sources or the loss factor makes the energy total jump by some amount from that moment on. Past values aren't recalculated.
* Never backfill or rake a virtual meter.
### Editing and deleting
The Edit this datum stream action reopens the wizard. Site, credential, vendor account, node and mapping can't be changed, but you can add and remove devices and change source ID suffixes and properties.
You can delete a single source, all of one provider's sources, or everything in a project. If you tick Also delete imported data, the stored readings are deleted too; otherwise the history stays on the node. A mapping is only deleted once no other stream uses it.
Ecosuite has no switch to enable or disable an integration. You pause one in SolarNetwork, and when you enable it again there, polling carries on from where it stopped.
### Checking health
| Where | What it tells you |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Status dot on the Integrations tab | Red means no data has ever arrived, amber means nothing in the last 24 hours, green means recent data |
| Most Recent Datum and Next Data columns | When the last reading was stored and when the next poll is due |
| Check data coverage | Compares the vendor's history with what's stored, up to 5 years back, and marks the gaps where the vendor has data we don't |
| Stream Health tab | Rules based on source ID patterns (`*` matches one segment, `**` any number of segments) that flag unhealthy streams and data spikes |
| Dashboard (Node Health) | CPU, memory, disk and uptime for physical nodes. Organisations that only use integrations can hide it in organisation settings. |
#### Troubleshooting
1. A source doesn't appear under my project. Check that its source ID starts with the project code.
2. I created an integration but no data has arrived. The first poll runs about 30 minutes after creation. After that, check Next Data. If it's empty, polling has stopped.
3. A device is missing. It's probably not in the stream's device list. Edit the integration and add it.
4. One property, such as `wattHours`, is missing. Either the vendor didn't send it or the calculation for it failed. Do a dry run from the mapping designer to see which.
5. The source exists but has never had any data. A source can be registered on a node (in its SolarNetwork metadata) without any integration or SolarNode writing to it. Find out what's supposed to be sending it data.
6. SMA or Enphase stopped suddenly. The OAuth tokens have probably expired or been refreshed somewhere else. Authorise again in SolarNetwork.
### Permissions
You need the `connectivity` permission group to view the Connectivity module. To create, edit, delete, backfill or alias, you also need one of `solarnetwork`, `user-admin-settings`, `user-admin-org-config` or `user-limited-admin`. The buttons appear either way, but the server refuses the action without one of these groups.
Ecosuite only shows nodes that are enabled under Settings > Organization > Node settings and that the credential's token policy allows. Disabled or expired tokens show no data.
### References
* SolarNetwork Cloud Integrations API:
* SolarNetwork Datum Stream Alias API:
* SolarNetwork Cloud Integrations expressions: