Remote-Procedure-Call Description/Interfaces and API
Contents
1. 4 Res5 Res l value permanent name Storage n n unit min O max 100 meta Firmware BFR value 2 name Firmware BFR unit Version 32 SWebboxRPC eng BUS1 12713 User manual SMA America LLC Service Procedures min 1 00 A meta Hardware BFS value name Hardware BFS unit Version 6 7 RPC SET PARAMETER 6 7 1 Version 1 0 Sets parameter values of up to 5 devices and returns the device list submitted in the request with the apropriate current parameter values The calling application verifies whether each parameter value has been set correctly Assembly version 1 0 proc SetParameter id ID format FORMAT passwd PASSWORD DEVICES key channels CHANNELS User manval SWebboxRPC eng BUS112713 33 Service Procedures SMA America LLC Submit as parameters a list with the device objects whose parameter values are to be changed Each device object contains a list of the parameters to be set Configuration of the parameters is performed synchronously Response times depend on the number of parameters to be set For the next example the response time is approx 10 seconds PASSWORD The MD5 coded hash value of the password for the required access level e g the user or installation password of the Sunny WebBox DEVICES An array contai2. System monitoring SUNNY WEBBOX RPC User Manual Remote Procedure Call Description Interfaces and API Definition SWebBoxRPC eng BUS112713 Version 1 3 ODA SMA America LLC Legal Restrictions Copyright 2011 SMA America LLC All rights reserved No part of this document may be reproduced stored in a retrieval system or transmitted in any form or by any means electronic mechanical photographic magnetic or otherwise without the prior written permission of SMA America LLC Neither SMA America LLC nor SMA Solar Technology Canada Inc makes representations express or implied with respect to this documentation or any of the equipment and or software it may describe including with no limitation any implied warranties of utility merchantability or fitness for any particular purpose All such warranties are expressly disclaimed Neither SMA America LLC nor its distributors or dealers nor SMA Solar Technology Canada Inc nor its distributors or dealers shall be liable for any indirect incidental or consequential damages under any circumstances The exclusion of implied warranties may not apply in all cases under some statutes and thus the above exclusion may not apply Specifications are subject to change without notice Every attempt has been made to make this document complete accurate and up to date Readers are cautioned however that SMA America LLC and SMA Solar Technology Canada Inc reserve the right to make
3. changes without notice and shall not be responsible for any damages including indirect incidental or consequential damages caused by reliance on the material presented including but not limited to omissions typographical errors arithmetical errors or listing errors in the content material All trademarks are recognized even if these are not marked separately Missing designations do not mean that a product or brand is not a registered trademark The Bluetooth word mark and logos are registered trademarks owned by Bluetooth SIG Inc and any use of such marks by SMA America LLC and SMA Solar Technology Canada Inc is under license SMA America LLC 3801 N Havana Street Denver CO 80239 U S A SMA Solar Technology Canada Inc 2425 Matheson Blvd E 8th Floor Mississauga ON LAW 5K5 Canada User manval SWebboxRPC eng BUS112713 3 Important Safety Instructions IMPORTANT SAFETY INSTRUCTIONS SAVE THESE INSTRUCTIONS This manual contains important instructions for the following products Remote Procedure Call Description Interfaces and API Definition This manual must be followed during installation and maintenance 4 SWebboxRPC eng BUS112713 SM America LLC User manual SMA America LLC Important Safety Instructions General warnings General warnings Before installing or using the product read all of the instructions cautions and warnings in this manual User manual SWebboxRPC eng BUS11271
4. description of its task is given This is followed by the structure of the request Variable elements are represented by placeholders in upper case characters In this manual the placeholders VERSION FORMAT and ID are not described for each procedure since their meaning has already been described in section 3 Procedure Conventions page 12 and it is not necessary to differentiate between all procedures here 6 1 RPC GET PLANT OVERVIEW 6 1 1 Version 1 0 Returns an object with the following plant data ETODAY ETOTAL MODE ERROR Structure version 1 0 proc GetPlantOverview id ID format FORMAT Sample request version 1 0 proc GetPlantOverview id 1 format JSON User manual SWebboxRPC eng BUS112713 17 Service Procedures SMA America LLC Sample response version 1 0 proc GetPlantOverview id 1 result overview meta GriPwr name current power value 4 250 unit W meta GriEgyTdy name Day energy value 45 23 unit kWh meta GriEgyTot name Total energy value 7 821 unit kWh meta Opstt name Mode value MPP unit null 18 SWebboxRPC eng BUS1 12713 User manual SMA America LLC Service Procedures meta Msg name Error value null unit null The following d
5. proc GetParameter id ID format FORMAT passwd PASSWORD params DEVICES key DEVICE_KEY channels CHANNELS You should submit as parameters a list of those device objects for which the parameters are to be returned You can submit a selection of requested parameters to each device If this selection is omitted all parameters will be transmitted PASSWORD The MD5 coded hash value of the password for the required access level e g the user or installation password of the Sunnv WebBox DEVICES An arrav containing the device objects for which parameters are to be returned and an optional selection of certain channels DEVICE KEY The corresponding device key See section 5 1 Device Object page 15 CHANNELS array containing the meta names of the required process data The available meta names can be identified with the command RPC GET PROCESS DATA CHANNELS 28 SWebboxRPC eng BUS1 12713 User manual SMA America LLC Sample request version 1 0 proc GetParameter id 1 format JSON passwd a289fa4252ed5af8e3e9f9bee545c172 params devices key WR715 19 263415747 Sample response version 1 0 id wl a format JSON proc GetParameter result devices key WR21TL06 2000101000 channels min Z meta Mode User manual S
6. 3 5 SMA America LLC SWebboxRPC eng BUS112713 User manual SMA America LLC Table of Contents Table of Contents 1 1 1 1 2 1 3 1 4 1 5 2 2 1 3 3 1 3 2 3 2 1 3 3 4 4 1 4 2 5 5 1 5 2 6 6 1 6 1 1 6 2 6 2 1 6 3 6 3 1 User manual Information on this Manual 9 genua bal BAG au N R 9 Target Group S Ee vw vv 9 9 Abbreviations 9 System Overview 9 JavaScript Object 10 Example 10 Procedure Conventions 12 Procedure Call Request 12 Return Value 12 a pa kis 13 Query Intervol 13 Interfaces A ra RE 9 669 WR e 14 RPG via DUDP Sfredtms do ada 14 RPC vig FIT TP a a e Pusaq apu ta l 14 Object Definifions 15 Device Open ie al AT ars 15 Channel ODE Ci adco ace a ase 16 Service Procedures 17 RPC_GET_PLANT_OVERVIEW 17 Version 1 0 n zn ee sca aas 17 RPGS DEVIGES 2 e re a 19 Version oer ar E
7. 5 1 Device Object page 15 CHANNELS array containing the meta names of the required process data The available meta names can be identified with the command RPC GET PROCESS DATA CHANNELS User manual SWebboxRPC eng BUS112713 23 Service Procedures Sample request version 1 0 proc GetProcessData id 1 format JSON params devices key WR715 19 263415747 channels null key WR715 19 263415748 channels Pac Sample response version 1 0 proc GetProcessData id 1 result devices key WR715 19 263415747 24 SWebboxRPC eng BUS112713 SMA America LLC User monuol SMA America LLC Service Procedures channels meta E total name null value 1 160 987 unit kWh meta name null value 49 98 unit Hz meta Zac name null value 1 346 unit Ohm key WR715 19 263415748 channels meta Pac name null value 630 unit W User manual SWebboxRPC eng BUS112713 25 Service Procedures SMA America LLC 6 5 RPC GET PARAMETER CHANNELS 6 5 1 Version 1 0 Returns a list with the meta names of the available parameter channels for a particular device type depending on access level The level is determined by transmitting the 5 hash value of the respective p
8. RES 19 _ _ _ _ 21 Version ls Pe RR RP 21 SWebboxRPC eng BUS112713 7 Table of Contents SMA America LLC 6 4 6 4 1 6 5 6 5 1 6 6 6 6 1 6 7 6 7 1 7 8 RPC GET PROCESS d a asa deno 23 Version Orc l 23 RPC GET PARAMETER CHANNELS 26 Version gia a dL 26 RPC GET PARAMETER 28 Version kahata qaa erento e oe ba 28 RPC_SET_PARAMETER 33 Version 1 04 sus hn AD ays 33 SOUICes ere ne ee AER OA RARIOR EGO 38 usas ben RR IA RR DX a 39 SWebboxRPC eng BUS1 12713 User manual SMA America LLC Information on this Manual 1 Information on this Manual 1 1 Validity This manual describes a uniform software interface and the relevant data exchange formats for the Sunny WebBox This manual does not include any information on the devices communicating with the software interface Information on such devices is obtainable from the device manufacturers 1 2 Target Group This manual is intended for software developers and end users 1 3 Nomenclature In this document SMA America Production LLC and SMA Solar Technology Canada Inc are hereinafter referred to as SMA 1 4 Abbreviations Abbreviation Description API Application Programmers Interface HTTP Hypertext Tran
9. ailable for Canada Service SMA Canada ca www SMA Canada ca User manual SWebboxRPC eng BUS112713 39 Contact SMA America LLC 40 SWebboxRPC eng BUS112713 User manual SMA Solar Technology SMA America LLC www SMA America com a YOUR SMA DISTRIBUTOR SOLIGENT Soligent 222222 g www soligent net
10. antspg Mpp Betrieb Res1 Res2 Res3 Res4 Res5 36 SWebboxRPC eng BUS112713 SMA America LLC User manual SMA America LLC Service Procedures value Stop name Mode n n unit User manual SWebboxRPC eng BUS112713 37 Sources SMA America LLC 7 Sources 1 RFC 4 627 The application json Media Type for Javascript Object Notation JSON hitp www ietf org rfc rfc4627 4 627 2 JSON RPC 1 1 Working Draft August 2006 hitp json rpc org wd JSON RPC 1 1 WD 20060807 html 3 Introducing JSON http www json org 4 The MD5 Message Digest Algorithm http www ietf org rc rfc 132 1 txt number 1 321 38 SWebboxRPC eng BUS1 12713 User manual SMA America LLC 8 Contact Contact If you have technical problems concerning our products contact the SMA Serviceline We need the following information in order to provide you with the necessary assistance Inverter Serial Number and Type Serial Number and firmware version of the Sunny WebBox SMA Solar Technology America LLC 6020 West Oaks Blvd Ste 300 Rocklin CA 95765 Tel 1 916 625 0870 Tel 1 877 MY SMA TECH Tel 1 877 697 6283 Toll free available for USA Canada and Puerto Rico Fax 1 916 625 0871 Service8SMA America com www SMA America com SMA Solar Technologv Canada Inc 2425 Matheson Blvd E 8th Floor Mississauga ON LAW 5K5 Canada Tel 1 877 506 1756 Toll free av
11. arams DEVICE KEV DEVICE KEY The device key of a device of the type for which the process data channels are to be returned User manual SWebboxRPC eng BUS112713 21 Service Procedures Sample request version 1 0 proc GetProDataChannels id 1 format JSON params device WR715 19 263415747 Sample response version 1 0 proc GetProcessDataChannels id 1 result WR715 19 263415747 Vpv Soll h Total Zac Mode E total Vpv Ist Riso Voc Pac Error Cnt Ipv Power On Serial Number Fac Error 22 SWebboxRPC eng BUS1 12713 SMA America LLC User manual SMA America LLC lac 6 4 RPC GET PROCESS DATA 6 4 1 Version 1 0 Returns process data for up to 5 devices per request Structure version 1 0 proc GetProcessData id ID format FORMAT params DEVICES key DEVICE_KEY channels CHANNELS Service Procedures As parameters you should submit a list of device keys from which process data is to be returned You can submit a selection of required process data to each device If a selection is omitted all process data will be transmitted DEVICES An arrav containing objects with the device kevs of those devices from which process data is to be returned and optional CHANNELS DEVICE KEY The corresponding device key See section
12. assword in the request header Assembly version 1 0 proc GetParameterChannels id ID format FORMAT passwd PASSWORD params key DEVICE_KEY PASSWORD The MD5 coded hash value of the password for the required access level e g the user or installation password of the Sunny WebBox DEVICE_KEY The device key of a device for whose type the parameter channels are to be returned Sample request version 1 0 proc GetParameterChannels id 1 format JSON passwd a289fa4252ed5af8e3e9f9bee545c172 params device WR715 19 263415747 26 SWebboxRPC eng BUS1 12713 User manual SMA America LLC Service Procedures Sample response version 1 0 proc GetParameterChannels id 1 result WR715 19 263415747 Plimit SMA Grid Guard SMA SN Operating Mode Control Ripple Cil Fra PowerBalancer Vconst Setpoint Vpv Start Default T Start Ripple Ctl Lev Storage Ripple Cil Rcvr Firmwore SRR T Stop Firmware BFR Hardware BFS User manual SWebboxRPC eng BUS112713 27 Service Procedures SMA America LLC 6 6 RPC GET PARAMETER 6 6 1 Version 1 0 Returns the parameter values of up to 5 devices depending on the access level The level is determined by transmitting the MD5 hash value of the respective password in the request header Assembly version 1 0
13. ata was transmitted Pac 4 250 W E Today 45 23 kWh E total 7 821 kWh Mode MPP no error 6 2 RPC GET DEVICES 6 2 1 Version 1 0 Returns a hierarchical list of all detected plant devices Structure version 1 0 proc GetDevices id ID format FORMAT Sample request version 1 0 proc GetDevices id 1 format JSON User manual SWebboxRPC eng BUS112713 19 Service Procedures Sample response version 1 0 proc GetDevices id s result totalDevicesReturned 6 devices key SCC250H9 1390148531 name Sunny Central E1 children key SCBFSOT 6 8945 name Sunny BFS ET children null key SMU8b004 2567 name String Monitoring Unit E1 children null key SCC250H9 1390148538 name Sunny Central E2 children key SCBFSO16 8956 name Sunny BFS E2 20 SWebboxRPC eng BUS1 12713 SMA America LLC User manual SMA America LLC Service Procedures children null key SMU8b004 2534 name String Monitoring Unit E2 children null 6 3 RPC GET PROCESS DATA CHANNELS 6 3 1 Version 1 0 Returns a list with the meta names of the available process data channels for a particular device type Structure version 1 0 proc GetProcessDataChannels id ID format FORMAT p
14. ch serves to assign a response to the request format a character sequence defining the data exchange format of the procedure s result see Section 3 2 Return Value Response page 12 passwd a character sequence comprising the hash value of the password for the desired access level user installer The hash value is calculated using the MD5 algorithm see 4 Password allocation is performed via the security settings in the WebBox If the object is not transmitted the user level is automatically assumed params an object whose elements are transferred to the procedure as arguments Each parameter must be available in the form of a named JSON object Hence the sequence is arbitrary The number of parameters depends on the given service procedure see section 7 If the requested procedure does not expect any arguments the entry is omitted 3 2 Return Value Response The data exchange format of the response is defined by the character sequence transmitted in the request At present the following format is available JSON SWebboxRPC eng BUS1 12713 User manual SMA America LLC Procedure Conventions 3 2 1 JSON The response to a request consists of a seriolized JSON object made up of the following compulsory objects version a character sequence which defines the underlying RPC version proc a character sequence which contains the called procedure id a character sequence which assigns a re
15. ervice Procedures SWebboxRPC eng BUS1 12713 29 Service Procedures 30 options Stop Konstantspg Mpp Betrieb Res1 Res2 Res3 Res4 Res5 value Operation name Mode n unit min 2 150 max 2 150 meto Plimit value 2 150 name Plimit Unit W min O mox 4294900000 meta SMA SN value 2 000101000 name SMA SN UU unit min 25 600 meta Vpv Start SWebboxRPC eng BUS112713 SMA America LLC User manual SMA America LLC Service Procedures value 150 name Vpv Start unit V min 1 max 300 meta T Stop value 4 name T Stop ne unit s min 25 gt max 600 meta Vconst Setpoint value 600 name Vconst Setpoint unit min 5 300 meta T Start value nome T Start nom unit s min O max 100 meta Firmwore SRR value 2 name Firmwore SRR unit Version User manual SWebboxRPC eng BUS112713 31 Service Procedures SMA America LLC min 0 005 max 4 meta dFac Max value O name dFac Max Unit Hz s min O meta Storage options permanent volatile Res Res2 Res3
16. esReturned is a figure with the value 4 The devices array has 2 fields each having one device object see section 5 1 Device Object page 15 which in turn contains nested device objects totalDevicesReturned 4 devices key SCC250H9 1390148531 name Sunny Central E1 children key SCBFS016 8945 nome Sunny BFS E1 children null key SMU8b004 2567 name String Monitoring Unit E1 children null key SCC250H9 1390148538 name Sunny Central E2 children 10 SWebboxRPC eng BUS1 12713 User manual SMA America LLC JavaScript Object Notation key SCBFS016 8956 name Sunny BFS E2 children null key SMU8b004 2534 name String Monitoring Unit E2 children null User manual SWebboxRPC eng BUS1 12713 11 Procedure Conventions SMA America LLC 3 Procedure Conventions All identifiers used are case sensitive This means that Power and power for instance designate two different objects All characters are transmitted using Unicode in UTF 8 format 3 1 Procedure Call Request Each request consists of one serialized JSON object which possesses the following obligatory members version a character sequence which defines the underlying RPC version proc a character sequence which contains the procedure to be called id a random character sequence max 16 characters whi
17. nfigured IP address of the Sunny WebBox The default setting is 192 168 0 168 Hence the default URL is the following http 192 168 0 168 rpc The request is transmitted via HTTP POST in the body of the HTTP request as a serialized JSON object according to the conventions established in section 3 1 Procedure Call Request page 12 Both the client side implementation effort and the resource requirements are relatively high As a general rule communication takes place via the standard port 80 which means that there is no need to make any changes to active firewalls 14 SWebboxRPC eng BUS112713 User manual SMA America LLC Object Definitions 5 Object Definitions This section defines the structure of frequently used objects using the JSON syntax In the description the values of the object members define the type of data used All definitions apply in the same way to other data exchange formats 5 1 Device Object Describes a device within the plant e g Sunny Boy Sunny Sensor Box key string name string or null optional channels array or null optional children array or null optional unique device key e g WR21TLO6 2000106925 name The user definable name of the device e g inverter left Defining this element is optional If the element is used but no name was defined enter zero channels array of channel objects of the device Defining this element is op
18. ning objects with the device keys of the devices and an array with the CHANNELS whose parameter values are to be set DEVICE KEY The corresponding device key See section 5 1 Device Object page 15 CHANNELS array containing the channel objects to be set for the respective device A list with the available parameter channels can be obtained by means of the command RPC GET PARAMETER CHANNELS Sample request version 1 0 proc SetParameter id 1 format JSON passwd a289fa4252ed5af8e3e9f9bee545c172 params devices key WR21TLO6 2000101000 channels meta Mode value Mpp Operation 34 SWebboxRPC eng BUS112713 User monuol SMA America LLC key WR21TL06 2000101001 channels meta Mode value Stop Sample response version 1 0 tid format JSON proc SetParameter result devices key WR21TL06 2000101000 channels min NS meta Mode options User manual Service Procedures SWebboxRPC eng BUS112713 35 Service Procedures Stop Konstantspg Mpp Betrieb Res1 Res2 Res3 Res4 Res5 value Operation name Mode unit key WR21TL06 2000101001 channels min Z meto Mode options Stop Konst
19. quest to a response Contains the ID from the respective request result the result of the executed procedure as a serialized JSON object If due to an error the procedure cannot be executed successfully the error object will be transmitted instead error an object containing a character string with a description of the error encountered If the procedure is executed without errors this object will not be transmitted 3 3 Query Interval The interval between two queries should not be less than 30 seconds User manual SWebboxRPC eng BUS112713 13 Interfaces SMA America LLC 4 Interfaces The Sunny WebBox provides two different access options which differ in the implementation effort required and their runtime utilization of resources 4 1 RPC via UDP Stream The procedure call is transmitted to port 34268 of the Sunny WebBox in the usable data part of the UDP protocol Responses are also sent to port 34268 UDP transport requires a relatively low implementation effort on the client side and saves runtime resources For communication bevond the limits of local networks the port will normallv need to be opened by the appropriate firewalls 4 2 RPC via HTTP Data exchange takes place by means of the Hypertext Transfer Protocol via a TCP IP connection to the webserver port configured in the Sunny WebBox The default port is 80 The URL for all requests is http IP address rpc The IP address in each case is the currently co
20. sfer Protocol JSON Javascript Object Notation UDP User Data Protocol URL Uniform Resource Locator RAS Remote Access Service RFC Request for Comment PV Photovoltaics RPC Remote Procedure Call 1 5 System Overview The Sunny WebBox data logger continuously captures all the process data of a PV plant This is then averaged over a configurable interval and cached The data is transmitted at regular intervals to the Sunny Portal for analysis and visuolizotion Via the data interface described here the Sunny WebBox makes raw process data unaveraged instantaneous values available to external data processing svstems for further processing To do this the Sunnv WebBox provides a pool of service procedures see section 5 Object Definitions page 15 which can be accessed from the remote terminal by means of a Remote Procedure Call protocol RPC protocol via a network or RAS connection The data exchange format used here is the JavaScript Object Notation JSON see section 2 JavaScript Object Notation page 10 User manual SWebboxRPC eng BUS112713 9 JavaScript Object Notation 2 JavaScript Object Notation SMA America LLC A description and explanation of JavaScript Object Notation JSON is to be found on the website http www json org 2 1 Example The following example shows an illustration of a device list It defines an object made up of the values totalDevicesReturned and devices totalDevic
21. tional If the element is used but no channels exist enter zero children An array of objects containing sub devices Defining this element is optional If the element is used but no sub devices exist enter zero User manual SWebboxRPC eng BUS112713 15 Object Definitions SMA America LLC 5 2 Channel Object Describes a process data or parameter channel of a device meta string name string optional n value string n unit string optional min string optional n string optional options array optional meta The meta name which uniquely defines the channel e g ExtSollrr name The translated display name e g External irradiation Defining this element is optional value The value of the channel e g 843 Defining this element is optional unit The unit of the channel e g W m 2 For channels not having any unit an empty string must be entered min The minimum possible value of a channel Defining this element is optional max The maximum possible value of a channel Defining this element is optional options list with the possible values of a parameter channel Defining this element is optional 16 SWebboxRPC eng BUS112713 User manual SMA America LLC Service Procedures 6 Service Procedures This section describes the structure of the available service procedures For each procedure a brief
Download Pdf Manuals
Related Search