This document applies to the RPC interface of the Sunny WebBox and the Sunny WebBox with
Bluetooth
1.2 Nomenclature
In this document, the Sunny WebBox with Bluetooth® Wireless Technology is referred to as
Sunny WebBox with Bluetooth.
1.3 Acronyms and Abbreviations
APIApplication Programmers Interface
HTTPHypertext Transfer Protocol
JSONJavascript Object Notation
UDPUser Data Protocol
URLUniform Resource Locator
RASRemote Access Service
RFCRequest for Comment
RPCRemote Procedure Call
®
Wireless Technology.
1.4 Referenced Documents and Sources
[1]
RFC 4627: The application/json Media Type for Javascript Object Notation (JSON)
http://www.ietf.org/rfc/rfc4627.txt?number=4627
[2]
JSON-RPC 1.1 Working Draft August 2006
http://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/rfc/rfc1321.txt?number=1321
User ManualSWebBoxRPC-BA-en-145
2 System OverviewSMA Solar Technology AG
2 System Overview
2.1 Sunny WebBox RPC
The da ta loggers Sunny Web Box and Sunny WebBox with Bluetooth contin uous ly r eco rd a ll th e da ta
of a PV plant. This is then averaged over a configurable interval and cached. The data can be
transmitted at regular intervals to the Sunny Portal for analysis and visualization.
Via the Sunny WebBox and Sunny WebBox with Bluetooth RPC interface, selected data from the
PV plant can be transmitted to a remote terminal by means of an RPC protocol (Remote Procedure
Call protocol).
To do this, the Sunny WebBox provides a pool of service procedures (see Section6 "Object
Definitions", page12) that 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 Section3 "JavaScript Object Notation",
page7).
2.2 Differences between Sunny WebBox and Sunny WebBox with
Bluetooth
Different representation for Sunny WebBox and Sunny WebBox with Bluetooth
The presentation of the plant data transmitted via the RPC interface is different for the
Sunny WebBox and the Sunny WebBox with Bluetooth.
This document only contains sample responses for the Sunny WebBox and none from the
Sunny WebBox with Bluetooth.
You will find a list of measured values and parameters for the Sunny WebBox with Bluetooth
in the technical description "Measured Values and Parameters" at www.SMA-Solar.com.
Available service proceduresSunny WebBoxSunny WebBox with
Bluetooth
RPC_GET_PLANT_OVERVIEW++
RPC_GET_DEVICES++
RPC_GET_PROCESS_DATA_CHANNELS++
RPC_GET_PROCESS_DATA++
RPC_GET_PARAMETER_CHANNELS+–
RPC_GET_PARAMETER+–
RPC_SET_PARAMETER+–
6SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG3 JavaScript Object Notation
3 JavaScript Object Notation
A description and explanation of JavaScript Object Notation (JSON) can be found on the website
http://www.json.org.
3.1 Example
The f oll owing example shows an illustr ation of a device list. It defines an object made up of the values
"totalDevicesReturned" and "devices".
"totalDevicesReturned" is a figure with the value 4. The array "device" has 2 fields, each having one
device object
objects.
RPC={
"totalDevicesReturned":4,
"devices":
[
{
"key":"SCC250H9:1390148531",
"name":"Sunny Central E1",
"children":
[
{
"key":"SCBFS016:8945",
"name":"Sunny BFS E1",
"children":null
},
{
"key":"SMU8b004:2567",
"name":"String Monitoring Unit E1",
"children":null
}
]
},
{
"key":"SCC250H9:1390148538",
"name":"Sunny Central E2",
"children":
(see Section6.1 "Device Object", page12), which in turn contains nested device
User ManualSWebBoxRPC-BA-en-147
3 JavaScript Object NotationSMA Solar Technology AG
[
{
"key":"SCBFS016:8956",
"name":"Sunny BFS E2",
"children":null
},
{
"key":"SMU8b004:2534",
"name":"String Monitoring Unit E2",
"children":null
}
]
}
]
}
8SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG4 Procedure Conventions
4 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.
4.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) which serves to assign a response to
the request.
• format — a character sequence defining the data exchange format of the procedure's result
(see Section4.2 "Return Value (Response)", page10).
• 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 Sunny 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.
User ManualSWebBoxRPC-BA-en-149
4 Procedure ConventionsSMA Solar Technology AG
4.2 Return Value (Response)
The data exchange format of the response is defined by the character sequence transmitted in the
request.
The following formats are currently available:
•JSON
4.2.1 JSON
The response to a request consists of a serialized 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 serves to assign the request and response. Contains the ID
from the respective request.
• result — the result of the executed procedure as a serialized JSON object. If d ue t o an err or 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.
4.3 Query Interval
The interval between two queries should not be less than 30 seconds.
10SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG5 Interfaces
5 Interfaces
The Sunny WebBox provides two different access options which differ in the implementation effort
required and their runtime utilization
5.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 beyond the limits of local networks, the port will normally need to be
opened by the appropriate firewalls.
5.2 RPC via HTTP
Data exchange takes place by means of the Hypertext Transfer Protocol via a TCP/IP connection to
the web server port configured in the Sunny WebBox.
The default setting is port 80.
The URL for all requests is: http://IP address/rpc
The IP address in each case is the currently configured 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 4.1.
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.
of resources.
User ManualSWebBoxRPC-BA-en-1411
6 Object DefinitionsSMA Solar Technology AG
6 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 accordingly to all
other data transmission formats.
6.1 Device Object
Describes a device within the plant (e.g. Sunny Boy, Sunny Sensor Box).
name:The user-definable name of the device (e.g. "INV left"). Defining this element is optional.
If the element is used but no name was defined, "null" is entered.
channels:An array of channel objects of the device. Defining this el eme nt is opt ion al. If t he eleme nt
is used but no channels exist, "null" is entered.
children:An array of objects containing sub-devices. Defining this element is optional. If the
element is used but no sub-devices exist, "null" is entered.
12SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG6 Object Definitions
6.2 Channel Object
Describes a process data or parameter channel of a device.
RPC={
"meta": "string",
"name": "string" (optional),
"value": "string",
"unit": "string" (optional),
"min": "string" (optional),
"max": "string" (optional),
"options": [array] (optional)
}
meta:The meta name which uniquely defines the channel (e.g. "ExtSolIrr").
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 which have no u nit, an empty st ring
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:A list with the possible values of a parameter channel. Defining this element is optional.
User ManualSWebBoxRPC-BA-en-1413
7 Service ProceduresSMA Solar Technology AG
7 Service Procedures
This section describes the structure of the available service procedures.
For each procedure, a brief 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 4 and it is not necessary to differentiate between all
procedures here.
7.1 RPC_GET_PLANT_OVERVIEW
7.1.1 Version 1.0
Returns an object with the following plant data:
•POWER
•DAILY-YIELD
• TOTAL-YIELD
•STATUS
• ERROR
Structure:
RPC={
"version": "1.0",
"proc": "GetPlantOverview",
"id": "ID",
"format": "FORMAT"
}
Sample request:
RPC={
"version": "1.0",
"proc": "GetPlantOverview",
"id": "1",
"format": "JSON"
}
14SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
Sample response:
RPC={
"version": "1.0",
"proc": "GetPlantOverview",
"id": "1",
"result":
{
"overview":
[
{
"meta": "GriPwr",
"name": "Momentanleistung",
"value": "4250",
"unit": "W"
},
{
"meta": "GriEgyTdy",
"name": "Tagesenergie",
"value": "45.23",
"unit": "kWh"
},
{
"meta": "GriEgyTot",
"name": "Gesamtenergie",
"value": "7821",
"unit": "kWh"
},
{
"meta": "OpStt",
"name": "Status",
"value": "MPP",
"unit": null
},
{
"meta": "Msg",
User ManualSWebBoxRPC-BA-en-1415
7 Service ProceduresSMA Solar Technology AG
"name": "Fehler",
"value": null,
"unit": null
}
]
}
}
The following data was transmitted:
Power = 4,250 W,
E-Today = 45.23 kWh,
E-Total = 7,821 kWh,
Status = MPP,
No error
7.2 RPC_GET_DEVICES
7.2.1 Version 1.0
Returns a hierarchical list of all detected plant devices.
Structure:
RPC={
"version": "1.0",
"proc": "GetDevices",
"id": "ID",
"format": "FORMAT"
}
Sample request:
RPC={
"version": "1.0",
"proc": "GetDevices",
"id": "1",
"format": "JSON"
}
16SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
Sample response:
RPC={
"version": "1.0",
"proc": "GetDevices",
"id": "1",
"result":
{
"totalDevicesReturned": 6,
"devices":
[
{
"key":"SCC250H9: 1390148531",
"name":" Sunny Central E1",
"children":
[
{
"key": "SCBFS016:8945",
"name": "Sunny BFS E1",
"children": null
},
{
"key": "SMU8b004:2567",
"name": "String Monitoring Unit E1",
"children": null
}
]
},
{
"key": "SCC250H9:1390148538",
"name": "Sunny Central E2",
"children":
[
{
"key": "SCBFS016:8956",
"name": "Sunny BFS E2",
"children": null
User ManualSWebBoxRPC-BA-en-1417
7 Service ProceduresSMA Solar Technology AG
},
{
"key": "SMU8b004:2534",
"name": "String Monitoring Unit E2",
"children": null
}
]
}
]
}
}
7.3 RPC_GET_PROCESS_DATA_CHANNELS
7.3.1 Version 1.0
Returns a list with the meta names of the available process data channels for a particular device type.
Structure:
RPC={
"version": "1.0",
"proc": "GetProcessDataChannels",
"id": "ID",
"format": "FORMAT",
"params":
{
DEVICE_KEY
}
}
DEVICE_KEY:The device key of a device of the type for which the process data channels are to
be returned.
18SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
Sample request:
RPC={
"version": "1.0",
"proc": "GetProDataChannels",
"id": "1",
"format": "JSON",
"params":
{
"device": "WR715-19:263415747"
}
}
Sample response:
RPC={
"version": "1.0",
"proc": "GetProcessDataChannels",
"id": "1",
"result":
{
"WR715-19:263415747":
[
"Upv-Soll",
"h-Total",
"Zac",
"Status",
"E-Total",
"Upv-Ist",
"Riso",
"Uac",
"Pac",
"Fehler-Cnt",
"Ipv",
"Netz-Ein",
"Seriennummer",
"Fac"
"Fehler"
User ManualSWebBoxRPC-BA-en-1419
7 Service ProceduresSMA Solar Technology AG
"Iac-Ist"
]
}
}
7.4 RPC_GET_PROCESS_DATA
7.4.1 Version 1.0
Returns process data for up to 5 devices per request.
Structure:
RPC={
"version": "1.0",
"proc": "GetProcessData",
"id": "ID",
"format": "FORMAT",
"params":
{
"DEVICES":
[
{
"key": DEVICE_KEY,
"channels": [CHANNELS]
}
]
}
}
A list with the device keys whose process data is to be provided must be transferred as a parameter.
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 array containing objects with the device keys of those devices for which process
data is to be returned, and optional CHANNELS.
DEVICE_KEY:The corresponding device key (see Section6.1 "Device Object", page12).
CHANNELS:An 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.
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 MD5 hash value of the
respective password in the request header.
Structure:
RPC={
"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 desired access level.
DEVICE_KEY:The device key of a device for whose type the parameter channels are to be
returned.
Sample request
RPC={
"version": "1.0",
"proc": "GetParameterChannels",
"id": "1",
"format": "JSON",
"passwd": "a289fa4252ed5af8e3e9f9bee545c172",
"params":
{
"device": "WR715-19:263415747"
}
}
User ManualSWebBoxRPC-BA-en-1423
7 Service ProceduresSMA Solar Technology AG
Sample response:
RPC={
"version": "1.0",
"proc": "GetParameterChannels",
"id": "1",
"result":
{
"WR715-19:263415747":
[
"Plimit",
"SMA-Grid-Guard",
"SMA-SN",
"Betriebsart",
"Control",
"Ripple-Ctl-Frq",
"PowerBalancer",
"Usoll-Konst",
"Upv-Start",
"Default",
"T-Start",
"Ripple-Ctl-Lev",
"Storage",
"Ripple-Ctl-Rcvr",
"Software-SRR",
"T-Stop",
"Software-BFR",
"Hardware-BFS"
]
}
}
24SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
7.6 RPC_GET_PARAMETER
7.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.
Structure:
RPC={
"version": "1.0",
"proc": "GetParameter",
"id": "ID",
"format": "FORMAT",
"passwd": "PASSWORT",
"params":
{
"DEVICES":
[
{
"key": DEVICE_KEY,
"channels": [CHANNELS]
}
]
}
}
A list with the device objects whose parameters are to be provided must be transferred as a
parameter. 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 desired access level.
DE VIC ES:An arr ay conta ini ng t he devic e ob jects fo r wh ich par ame ters are to b e return ed, and
an optional selection of certain channels.
DEVICE_KEY:The corresponding device key (see Section6.1 "Device Object", page12).
CHANNELS:An 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 ManualSWebBoxRPC-BA-en-1425
7 Service ProceduresSMA Solar Technology AG
Sample request
RPC={
"version": "1.0",
"proc": "GetParameter",
"id": "1",
"format": "JSON",
"passwd": "a289fa4252ed5af8e3e9f9bee545c172",
"params":
{
"devices":
[
{
"key": "WR715-19:263415747"
}
]
}
}
Sample response:
RPC={
"version": "1.0",
"id": "1",
"format": "JSON",
"proc": "GetParameter",
"result":
{
"devices":
[
{
"key": "WR21TL06:2000101000"
"channels":
[
{
"min": "0",
"max": "7",
"meta": "Betriebsart",
26SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
"options":
[
"Stop",
"Konstantspg.",
"Mpp-Betrieb",
"Res1",
"Res2",
"Res3",
"Res4",
"Res5"
],
"value": "Mpp-Betrieb",
"name": "Betriebsart",
"unit": ""
},
{
"min": "2150",
"max": "2150",
"meta": "Plimit",
"value": "2150",
"name": "Plimit",
"unit": "W"
},
{
"min": "0",
"max": "4294900000",
"meta": "SMA-SN",
"value": "2000101000",
"name": "SMA-SN",
"unit": ""
},
{
"min": "125",
"max": "600",
"meta": "Upv-Start",
"value": "150",
"name": "Upv-Start",
User ManualSWebBoxRPC-BA-en-1427
7 Service ProceduresSMA Solar Technology AG
"unit": "V"
},
{
"min": "1",
"max": "300",
"meta": "T-Stop",
"value": "4",
"name": "T-Stop",
"unit": "s"
},
{
"min": "125",
"max": "600",
"meta": "Usoll-Konst",
"value": "600",
"name": "Usoll-Konst",
"unit": "V"
},
{
"min": "5",
"max": "300",
"meta": "T-Start",
"value": "10",
"name": "T-Start",
"unit": "s"
},
{
"min": "0",
"max": "100",
"meta": "Software-SRR",
"value": "2",
"name": "Software-SRR",
"unit": "Version"
},
{
"min": "0.005",
"max": "4",
28SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
"meta": "dFac-Max",
"value": "0",
"name": "dFac-Max",
"unit": "Hz/s"
},
{
"min": "0",
"max": "7",
"meta": "Storage",
"options":
[
"permanent",
"volatile",
"Res1",
"Res2",
"Res3",
"Res4",
"Res5",
"Res6"
],
"value": "permanent",
"name": "Storage",
"unit": ""
},
{
"min": "0",
"max": "100",
"meta": "Software-BFR",
"value": "2",
"name": "Software-BFR",
"unit": "Version"
},
{
"min": "0",
"max": "100",
"meta": "Hardware-BFS",
"value": "1",
User ManualSWebBoxRPC-BA-en-1429
7 Service ProceduresSMA Solar Technology AG
"name": "Hardware-BFS",
"unit": "Version"
}
]
}
]
}
}
7.7 RPC_SET_PARAMETER
7.7.1 Version 1.0
Sets parameter values of up to 5 devices and returns the device list submitted in the request with the
corresponding current parameter values. A check to see whether every parameter value was set
successfully must be carried out by the application used.
Structure:
RPC={
"version": "1.0",
"proc": "SetParameter",
"id": "ID",
"format": "FORMAT",
"passwd": "PASSWORT",
"params":
{
"DEVICES":
[
{
key,
"channels": [CHANNELS]
}
]
}
}
30SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
A list with the device objects whose parameters are to be changed must be transferred as a
parameter. Every device object contains a list with the parameters that must be set.
Configuration of the parameters is performed synchronously. Thus, the response time depends 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 desired access level.
DEVICES:An array containing 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 Section6.1 "Device Object", page12).
CHANNELS:An 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:
RPC={
"version": "1.0",
"proc": "SetParameter",
"id": "1",
"format": "JSON",
"passwd": "a289fa4252ed5af8e3e9f9bee545c172",
"params":
{
"devices":
[
{
"key": "WR21TL06:2000101000",
"channels":
[
{
"meta": "Betriebsart",
"value": "Mpp-Betrieb"
}
]
},
{
"key": "WR21TL06:2000101001",
"channels":
User ManualSWebBoxRPC-BA-en-1431
7 Service ProceduresSMA Solar Technology AG
[
{
"meta": "Betriebsart",
"value": "Stop"
}
]
}
]
}
}
Sample response:
RPC={
"version": "1.0",
"id": "1",
"format": "JSON",
"proc": "SetParameter",
"result":
{
"devices":
[
{
"key": "WR21TL06:2000101000",
"channels":
[
{
"min": "0",
"max": "7",
"meta": "Betriebsart",
"options":
[
"Stop",
"Konstantspg.",
"Mpp-Betrieb",
"Res1",
"Res2",
"Res3",
32SWebBoxRPC-BA-en-14User Manual
SMA Solar Technology AG7 Service Procedures
"Res4",
"Res5"
],
"value": "Mpp-Betrieb",
"name": "Betriebsart",
"unit": ""
}
]
},
{
"key": "WR21TL06:2000101001",
"channels":
[
{
"min": "0",
"max": "7",
"meta": "Betriebsart",
"options":
[
"Stop",
"Konstantspg.",
"Mpp-Betrieb",
"Res1",
"Res2",
"Res3",
"Res4",
"Res5"
],
"value": "Stop",
"name": "Betriebsart",
"unit": ""
}
]
}
]
}
}
User ManualSWebBoxRPC-BA-en-1433
SMA Solar Technology AGLegal Provisions
Legal Provisions
The information contained in this document is the property of SMA Solar Technology AG. Publishing its content, either partially or
in full, requires the written permission of SMA Solar Technology AG. Any internal company copying of the document for the
purposes of evaluating the product or its correct implementation is allowed and does not require permission.
Declaration of Conformity
SMA Solar Technology AG hereby declares that this equipment is in c ompli ance wit h the ess enti al req uirem ents and ot her rele vant
provisions of Directive 1999/5/EC. You can find the entire CE declaration of conformity at www.SMA-Solar.com.
Trademarks
All trademarks are recognized if these are not marked separately. Missing designations do not mean that a product or brand is
not a registered trademark.
The Bluetooth
SMA Solar Technology AG is under license.