Get Started

Before you can connect and control the following needs to have occured.

1. Install CATCH Solar Relay

If you are controlling somebody else's relay then you obviously dont need to do this.

Relays need to be installed by a licensed Electrician. The complete guide to installing the SOLAR Relay can be found here. Note specifically the Electricians Guide.

If you want to be controlling the inverter you need to tell your solar installers before hand so they can configure everything that is needed.

2. Generate a Site Token from the MONOCLE.

The Monocle is the free energy monitoring app used with CATCH Solar Relay.

The Monocle will allow you to see the power flow throughout the premises as well as turn your loads on and off.

In the API menu option for the monocle you will need to generate a new API Token.

This token is needed for gaining access to the site from the API's.

If you are using somebody else's Solar Relay installation you will need them to provide you with the Site Token.

3. Create an API Account

You can Create your Account here.

The Basics of an API request

The Basics

The API's utilise http POST and GET requests for all interactions.
All data being sent to and from the API's is in JSON format.
All requests must be made via https.
The API uses tokens as a means of granting access to a site. If you have a valid token it is assumed you have been granted access.

Authorisation Tokens

EDDE-World uses two types of access tokens to ensure only authorised people are accessing sites.

API Tokens:

When you create your developer account you will need to generate an API Token. This token is sent in the http header of every request you make. This token is how EDDE-World identifies your developer account.

Site Access Tokens:

Every CATCH Solar Relay is attached to a site (a physical location). The site could be your site, or it could be somebody else's site. If they have given you their site Access token you are able to use the API's to control there site.

Site Access Tokens are generated in The Monocle App.

The Site Access Token is sent as part of the http POST payload when requesting data or triggering some kind of action.

The Anatomy of an API request

Server End Point: https://api.edde.world

As mentioned previously, all data is transferred using http GET or POST requests, and all data is in JSON format.

The below request is to get the instantaneous data for a site. Note only the relevant http headers have been shown.

POST /api/data/location/instant HTTP/1.1

Accept: application/json

Content-Type: application/json

Authorization: Bearer <api Token goes here>

{

"siteToken": "<site token goes here>"

}

The response to the above request is shown below;

HTTP/1.1 201 Created
Date: Mon, 24 Apr 2023 05:38:49 GMT
Content-Type: application/json
Content-Length: 436

{
"dataCurrent": true,
"data": {
"serialNumber": "123456",
"siteID": 0,
"timestamp": 0,
"rssi": 0,
"channels": [
{
"channelNo": 0,
"I": 0,
"V": 0,
"WH_IMPORT": 0,
"WH_EXPORT": 0,
"freq": 0,
"pf": 0,
"pwr": 0,
"va": 0,
"var": 0
}
]
}

Note in the above response the http return code is 201. Any response code that is 2xx is considered success.

Rate Limiting

EDDE-World is no ordinary place. when you are playing in EDDE-World you are moving large amounts of energy around. If you switch things on and off too quickly you can cause damage. To protect you from this there is a rate limit applied to the system.

All control commands are limited to 1 request / site / 5 seconds.
All other commands are limited to 1 request / site / seconds.

If you exceed the rate limit the servers will respond with status Code 429 (Too Many Requests)

Details on the Full list of End Points

For more information on all the end points available check out our swagger docs here.