Quick Start
This page provides a quick start API for using the PV monitoring open platform, aimed at users who are using the system for the first time, to help users quickly view device data. The order of interface introduction corresponds to the system hierarchy, with the system hierarchy being Plant Owner -> Plant -> Datalogger -> Device, and the parameters required for querying and calling the lower-level interfaces can be obtained from the data returned by the upper-level interfaces.
Users must register a new plant owner account using a unique pn code (Register Plant Owner Account). After registration, a default plant is created based on the pn code. Before calling business APIs, the authentication interface must be called. After authentication, the signature is encrypted (see below). The Query Plant List interface displays all plants under the current user and returns basic plant information and profit data. The plant ID (pid) is also obtained from this interface. The Query Plant Active Power for a Day interface provides detailed active power data for a day, with a value every five minutes. For Dataloggers, the Query Dataloggers interface requires a pid to list all Dataloggers under a plant. Device data can be queried using the data obtained from the Datalogger, including Query Device and Query Device Data for a Day. The returned data is related to the device's protocol configuration. To obtain device data, API calls should be made progressively from Plant -> Datalogger -> Device.
Below is a simple explanation of the required interfaces (input and output parameters). Calling these interfaces can quickly build the platform's structure to observe device data. For other needs, please refer to the API documentation.
Signature Encryption
Signature Encryption Explanation (sign)
-
Register User Signature
sign = SHA-1(salt + pwd + action)
pwd = RC4(SHA-1(PN), SHA-1(PWD))
action = "&action=reg&usr=" + usr + "&pwd=" + pwd + "&mobile=" + mobile + "&email=" + email + "&sn=" + sn + "&company-key=" + companyKey;
-
Authentication Signature
sign = SHA-1(salt + SHA-1(pwd) + "&action=auth&usr=" + usr + "&company-key=" + company-key);
-
Business API Call Signature
sign = SHA-1(salt + secret + token + "&action=...");
secret and token are data returned by the authentication interface.
Unified explanation of salt: salt is a readable string with a length of no less than 8 bytes.
company-key acquisition:
Email: market@eybond.com
Phone: +86-13622344534
User
-
Register
To register a user, you need to prepare an unregistered Datalogger code (hereinafter referred to as pn) and the manufacturer's identifier company-key (assigned by the platform). The pn is a required parameter for the user registration interface and is used in signature encryption, password encryption, and parameters (corresponding to sn). For details, see the interface documentation.
After successful registration, a default plant named PLANT will be created based on the pn code.
-
Authentication
Before calling business APIs, it is always necessary to pass identity authentication first. After successful verification, the platform will allocate a secret and token, which are used for sign encryption calculations when calling business interfaces.
Return Data:
{ "err":0, "desc":"ERR_NONE", "dat":{ "secret":"ffa1655ee3726840822063a02ac5017795809b18", "expire":604800, "token":"88d22d819e31897eea2d9d5b9f7792cf4065ac5372aad3672f5e4e147cd25b5f", "role":0 } }
Plant
-
Query Power Plant List
API documentation link: Query Power Plants
Query all power plant information under the current user. Through this interface, you can obtain the power plant ID (pid).
Pid is an important parameter for calling power plant-related interfaces.
Return information:
{ "err":0, "desc":"ERR_NONE", "dat":{ "total":8, "page":0, "pagesize":1, "plant":[ { "pid":1, "uid":1, "name":"PLANT", "status":1, "address":{ "country":"China", "province":"Hunan Province", "city":"Yiyang City", "county":"Anhua County", "town":"Meicheng Town", "village":"Nanjie Village", "address":"Nanjie Village Group 8", "lon":"111.651442", "lat":"28.144826", "timezone":28800 }, "profit":{ "unitProfit":"1.12", "currency":"￥", "currencyCountry":"CNY", "coal":"0.221", "co2":"0.031", "so2":"0.023" }, "nominalPower":"50000", "energyYearEstimate":"5000000", "designCompany":"EYBOND", "picBig":"http://img.shinemonitor.com/picBig.png", "picSmall":"http://img.shinemonitor.com/picSmall.png", "install":"2017-06-29 02:16:21", "gts":"2017-06-29 02:16:21" } ] } } -
Query Power Plant Information
Query the information of a single power plant based on pid. The returned data is the same as the plant in the power plant list.
-
Query the Active Power Output Details of a Power Plant for a Specific Day
Display the active power output of a power plant for a specific day. The pid is a required parameter.
Query the Active Power Output Details of a Power Plant for a Specific Day
Return Parameters
{ "err":0, "desc":"ERR_NONE", "dat":{ "outputPower":[ { "val":"29.0001", "ts":"2016-12-31 06:10:10" }, { "val":"30.0001", "ts":"2016-12-31 06:15:10" } ] } }Return Parameter Description: The outputPower is sorted in ascending order by time, with each value representing a 5-minute interval. Each item includes: - val: Value - ts: Time (Format: yyyy-mm-dd hh:mm:ss)
Datalogger
-
Query Datalogger
The required parameter plantid for querying the list of Dataloggers can be obtained from the data returned by the Query Power Plant interface.
This interface supports pagination. For details, see Query Datalogger.
Key data displayed in the returned data dat.
"dat":{ "collector":[ { "pn":"COLLECTOR0001", "datFetch":60, "timezone":28800, "load":1, "uid":1, "pid":1 }, { "pn":"COLLECTOR0002", "datFetch":300, "timezone":28800, "load":1, "uid":1, "pid":1 } ] } -
Query the Set of Devices Subordinate to a Datalogger
Query the Set of Devices Subordinate to a Datalogger
Query the set of devices subordinate to a Datalogger. The required parameter pn (Datalogger number) can be obtained from the data returned by Query Datalogger.
{ "err":0, "desc":"ERR_NONE", "dat":{ "pn":"COLLECTOR0001", "dev": [ { "devcode":752, "devaddr":1, "sn":"687489900018", "alias":"687489900018" } ] } }
Devices
-
Query Devices
When calling the interface, the parameters pn and pid can be obtained from the data returned by Query Datalogger or Query the Set of Devices Subordinate to a Datalogger.
Key data description for the returned data device
pn: Datalogger Number
sn: Device Serial Number
devcode: Device Protocol Code
devaddr: Device Address (485 Bus)
"device":[ { "pn":"COLLECTOR0001", "devcode":512, "devaddr":1, "sn":"687489900018", "timezone":28800, "status":1, "uid":1, "pid":1 }, { "pn":"COLLECTOR0002", "devcode":512, "devaddr":1, "sn":"687489900018", "timezone":28800, "status":1, "uid":1, "pid":1 } ] -
Query the Data Details of a Device for a Specific Day
Query the Data Details of a Device for a Specific Day
To query the data details of a device for a specific day, the required parameters pn, sn, devcode, and devaddr can be obtained from the data returned by the Query Devices interface.
Return Data Description:
The size of title is always equal to the size of field.
Title stores the names of the device protocol fields, and the values in field correspond one-to-one with the protocol fields.
{ "err":0, "desc":"ERR_NONE", "dat":{ "title":[ { "title":"id" }, { "title":"timestamp" }, { "title":"Serial number" }, { "title":"PV1 input voltage", "unit":"V" }, { "title":"PV2 input voltage", "unit":"V" }, { "title":"PV3 input voltage", "unit":"V" }, { "title":"PV1 input current", "unit":"A" }, { "title":"PV2 input current", "unit":"A" }, { "title":"PV3 input current", "unit":"A" }, { "title":"PV1 input power", "unit":"W" }, { "title":"PV2 input power", "unit":"W" }, { "title":"PV3 input power", "unit":"W" }, { "title":"R-phase grid voltage", "unit":"V" }, { "title":"S phase grid voltage", "unit":"V" }, { "title":"T-phase grid voltage", "unit":"V" }, { "title":"Grid-connected power", "unit":"W" }, { "title":"Radiator temperature", "unit":"°C" }, { "title":"Module temperature", "unit":"°C" }, { "title":"Inverter working mode" }, { "title":"Runtime", "unit":"Hour" }, { "title":"Power generation time", "unit":"Hour" }, { "title":"Number of grid connections" }, { "title":"Total power generation", "unit":"kWh" }, { "title":"Power peak after start-up", "unit":"W" }, { "title":"Power peak of the day", "unit":"W" } ], "row":[ { "field":[ "bcaa940319ac11e7bde91c6f6593e938", "2017-04-05 11:06:40", "687484400018", "608.4", "582.9", "9.8", "1.76", "1.56", "0.07", "1071", "914", "0", "233.1", "240.3", "225.5", "1977", "29.6", "37.4", "normal", "120", "116", "000067", "336", "8668", "3995" ] }, Object{...}, Object{...}, Object{...} ] } }