SMA SUNNY WEBBOX RPC User Manual
EN
Remote Procedure Call Description
Interfaces and API Definition
Plant Monitoring
SUNNY WEBBOX RPC
User Manual
SWebBoxRPC-BA-en-14 | Version 1.4
SMA Solar Technology AG Table of Contents
Table of Contents
1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Validity. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 Nomenclature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.3 Acronyms and Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.4 Referenced Documents and Sources. . . . . . . . . . . . . . . . . . . . . . . . . . 5
2 System Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.1 Sunny WebBox RPC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.2 Differences between Sunny WebBox and Sunny WebBox with
Bluetooth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3 JavaScript Object Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
3.1 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
4 Procedure Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.1 Procedure Call (Request). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Return Value (Response) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.2.1 JSON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4.3 Query Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.1 RPC via UDP Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.2 RPC via HTTP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6 Object Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.1 Device Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
6.2 Channel Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
7 Service Procedures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1 RPC_GET_PLANT_OVERVIEW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.1.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
7.2 RPC_GET_DEVICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
7.2.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
User Manual SWebBoxRPC-BA-en-14 3
Table of Contents SMA Solar Technology AG
7.3 RPC_GET_PROCESS_DATA_CHANNELS . . . . . . . . . . . . . . . . . . . . 18
7.3.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.4 RPC_GET_PROCESS_DATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.4.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
7.5 RPC_GET_PARAMETER_CHANNELS. . . . . . . . . . . . . . . . . . . . . . . . 23
7.5.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.6 RPC_GET_PARAMETER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.6.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
7.7 RPC_SET_PARAMETER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.7.1 Version 1.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
4 SWebBoxRPC-BA-en-14 User Manual
SMA Solar Technology AG 1 Introduction
1 Introduction
1.1 Validity
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
API Application Programmers Interface
HTTP Hypertext Transfer Protocol
JSON Javascript Object Notation
UDP User Data Protocol
URL Uniform Resource Locator
RAS Remote Access Service
RFC Request for Comment
RPC Remote 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 Manual SWebBoxRPC-BA-en-14 5
2 System Overview SMA 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 procedures Sunny WebBox Sunny 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 + –
6 SWebBoxRPC-BA-en-14 User Manual
SMA Solar Technology AG 3 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 Manual SWebBoxRPC-BA-en-14 7
3 JavaScript Object Notation SMA Solar Technology AG
[
{
"key":"SCBFS016:8956",
"name":"Sunny BFS E2",
"children":null
},
{
"key":"SMU8b004:2534",
"name":"String Monitoring Unit E2",
"children":null
}
]
}
]
}
8 SWebBoxRPC-BA-en-14 User Manual
SMA Solar Technology AG 4 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 Manual SWebBoxRPC-BA-en-14 9
4 Procedure Conventions SMA 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.
10 SWebBoxRPC-BA-en-14 User Manual
SMA Solar Technology AG 5 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 Manual SWebBoxRPC-BA-en-14 11
Loading...