-
Notifications
You must be signed in to change notification settings - Fork 2
SolarUser DNP3 API
The SolarUser DNP3 API provides methods to manage Distributed Network Protocol 3 (DNP3) entities within SolarNetwork, which provides a DNP3 Outstation Server service. All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.
For general information about DNP3 support in SolarNetwork see the DNP3 guide.
For endpoints that return timestamp values (full date and time) the timestamps will be rendered as
string values using the ISO 8601 timestamp format YYYY-MM-dd HH:mm:ss.SSSSSS'Z'
in the UTC time
zone, for example 2020-03-01 10:30:49.346827Z
. The fractional second can contain up to 6 digits
for nanosecond level precision, and will only display up to the precision set in the timestamp. That
means the fractional seconds might not appear if the timestamp has no fractional seconds.
For endpoints that accept timestamp values, the same ISO 8601 timestamp format is required, however
the fractional seconds may be omitted. For example 2020-03-01 10:30:49Z
is a valid value.
Trusted Issuer Certificate entities are X.509 certificates you "trust" to sign client certificates for use with Server Authentication entities.
This method allows you to upload a file containing one or more PEM-encoded X.509 certificates.
POST | /solaruser/api/v1/sec/user/dnp3/trusted-issuer-certs |
---|
The request must be submitted as multipart/form-data
with a file
part that contains one or more
PEM-encoded X.509 certificates. PEM-encoded certificates are text files with marker boundaries. For
example a file with two PEM-encoded certificates would look similar to this (contents truncated for
brevity):
-----BEGIN CERTIFICATE-----
MIID7zCCAtegAwIBAgIBATANBgkqhkiG9w0BAQsFADBlMRUwEwYDVQQKEwxTb2xh
ck5ldHd...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIBATANBgkqhkiG9w0BAQsFADBfMRMwEQYDVQQDDApTTiBU
ZXN0IEN...
-----END CERTIFICATE-----
The response will be a list of Trusted Issuer Certificate entity objects. See Trusted Issuer Certificate list response for more information.
This method updates the enabled status of a specific Trusted Issuer Certificate entity. An
application/json
request body must be included to specify the entity to update and the enabled
state to update it to.
POST | /solaruser/api/v1/sec/user/dnp3/trusted-issuer-certs |
---|
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
subjectDn |
String | The subject distinguished name of the certificate to update. |
enabled |
Boolean | The desired enable state to update the certificate to. |
For example, to disable certificate, make a POST
request to /user/dnp3/trusted-issuer-certs
with
the following body:
{
"subjectDn":"CN=Example Root CA,OU=Example Certification Authority,O=Example Dot Com",
"enabled" : false
}
This method allows you to upload a file containing one or more PEM-encoded X.509 certificates. PEM-encoded certificates are text files with marker boundaries. For example a file with two PEM-encoded certificates would look similar to this (contents truncated for brevity):
GET | /solaruser/api/v1/sec/user/dnp3/trusted-issuer-certs |
---|
The response will be a list of Trusted Issuer Certificate entity objects. Each object has the following properties:
Property | Type | Description |
---|---|---|
userId |
Number | The SolarNetwork account ID. |
subjectDn |
String | The certificate subject distinguished name. |
created |
String | The creation date. |
modified |
String | The modification date. |
enabled |
Boolean | Enabled status indicator. Only enabled entities will be considered during authorization. |
expires |
String | The expiration date of the certificate. |
For example:
{
"success": true,
"data": [
{
"userId": 1,
"subjectDn": "CN=Example Root CA,OU=Example Certification Authority,O=Example Dot Com",
"created": "2023-08-07 02:12:24.789666Z",
"modified": "2023-08-07 02:12:24.789666Z",
"enabled": true,
"expires": "2024-01-20 00:10:12Z"
},
{
"userId": 1,
"subjectDn": "CN=Example Intermediate CA,OU=Example Intermediate Certification Authority,O=Example Dot Com",
"created": "2023-08-07 02:12:24.789666Z",
"modified": "2023-08-07 02:12:24.789666Z",
"enabled": true,
"expires": "2043-07-28 23:43:03Z"
}
]
}
This method will delete a Trusted Issuer Certificate entity. The subject distinguished name
must be provided by a subjectDn
query parameter.
DELETE | /solaruser/api/v1/sec/user/dnp3/trusted-issuer-certs?subjectDn={subjectDn} |
---|---|
subjectDn |
The subject distinguished name of the certificate to delete. |
This method updates the enabled status of a set of Trusted Issuer Certificate entities. An
application/json
request body may be included to narrow the entities the update applies to. If no
request body is provided, then all entities in the account are updated.
POST | /solaruser/api/v1/sec/user/dnp3/trusted-issuer-certs/enabled/{enabled} |
---|---|
enabled |
The desired enabled state to set. |
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
subjectDn |
String | The subject distinguished name of the certificate to update. |
subjectDns |
Array<String> | An array of subject distinguished names of certificates to update (logical OR). |
enabled |
Boolean | Only update entities with the specified enabled state. |
For example, to disable a set of certificates matching a list of subject DNs, make a POST
request
to /user/dnp3/trusted-issuer-certs/enabled/false
with the following body:
{"subjectDns":[
"CN=Example Root CA,OU=Example Certification Authority,O=Example Dot Com",
"CN=Example Intermediate CA,OU=Example Intermediate Certification Authority,O=Example Dot Com"
]}
Server entities are unique DNP3 Outstation instances, that you can configure with independent authorization and data points.
This method creates a new Server entity. An application/json
request body must be provided with
the server details to create.
POST | /solaruser/api/v1/sec/user/dnp3/servers |
---|
The request body accepts a JSON Server object with the following properties:
Property | Type | Description |
---|---|---|
name |
String | A display name. |
enabled |
Boolean | The desired enabled state of the Server. |
The response will be a Server entity object that provides the ID assigned to the new Server. See
Server view response for more information. In addition a Location
HTTP
header will be returned with the path to view the entity, for example:
Location: /solaruser/api/v1/sec/user/dnp3/servers/1
This method displays a list of Server entities matching an optional search filter.
GET | /solaruser/api/v1/sec/user/dnp3/servers |
---|
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
enabled |
Boolean | The desired enabled state to match. |
The response will be a list of Server entity objects. See the Server view response for details.
This method updates an existing Server entity. An application/json
request body must be provided
with the complete server details to save.
PUT | /solaruser/api/v1/sec/user/dnp3/servers/{serverId} |
---|---|
serverId |
The ID of the Server to update. |
The request body accepts a JSON Server object as specified in the Server create method.
This method displays a Server entity.
GET | /solaruser/api/v1/sec/user/dnp3/servers/{serverId} |
---|---|
serverId |
The ID of the Server to view. |
The response will be a Server entity object with the following properties:
Property | Type | Description |
---|---|---|
userId |
Number | The SolarNetwork account ID. |
serverId |
Number | A unique ID assigned to the entity. |
created |
String | The creation date. |
modified |
String | The modification date. |
enabled |
Boolean | Enabled status indicator. Only enabled entities will be considered during authorization. |
name |
String | A display name. |
An example response looks like:
{
"success": true,
"data": {
"userId": 1,
"serverId": 2,
"created": "2023-08-07 04:15:16.221061Z",
"modified": "2023-08-07 04:15:16.221061Z",
"enabled": true,
"name": "Test Server"
}
}
This method deletes a Server entity. All authentication, measurement, and control entities associated with the server will be deleted as well.
DELETE | /solaruser/api/v1/sec/user/dnp3/servers/{serverId} |
---|---|
serverId |
The ID of the Server to delete. |
This method updates the enabled status of a set of Server entities. An application/json
request
body may be included to narrow the entities the update applies to. If no request body is provided,
then all entities in the account are updated.
POST | /solaruser/api/v1/sec/user/dnp3/servers/enabled/{enabled} |
---|---|
enabled |
The desired enabled state to set. |
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
enabled |
Boolean | Only update entities with the specified enabled state. |
Server Authorization entities are X.509 client identifiers that are allowed to connect to a DNP3 Outstation instance based on a Server entity.
⚠️ Note that client identifiers are globally unique within all of SolarNetwork. That means an identifier can only be associated with one Server at a time.
This method creates or updates a Server Authorization entity. An application/json
request body
must be provided with the details to save.
POST | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/auths |
---|---|
serverId |
The ID of the Server to save the entity for. |
The request body accepts a JSON Server Authorization object with the following properties:
Property | Type | Description |
---|---|---|
identifier |
String | The subject distinguished name (DN) of the client X.509 certificate that is allowed to connect. |
name |
String | A display name. |
enabled |
Boolean | The desired enabled state of the Server Authorization. |
The response will be a Server Authorization entity object. See Server Authorization view response for more information.
This method displays a Server Authorization entity.
GET | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/auths?identifier={identifier} |
---|---|
serverId |
The ID of the Server Authorization to view. |
identifier |
The identifier of the Server Authorization to view. |
The response will be a Server Authorization entity object with the following properties:
Property | Type | Description |
---|---|---|
userId |
Number | The SolarNetwork account ID. |
serverId |
Number | A unique ID assigned to the entity. |
identifier |
String | The subject distinguished name (DN) of the client X.509 certificate that is allowed to connect. |
created |
String | The creation date. |
modified |
String | The modification date. |
enabled |
Boolean | Enabled status indicator. Only enabled entities will be considered during authorization. |
name |
String | A display name. |
An example response looks like:
{
"success": true,
"data": {
"userId": 1,
"serverId": 2,
"identifier": "CN=example.com,C=NZ",
"created": "2023-08-14 02:56:27.811161Z",
"modified": "2023-08-14 02:56:27.811161Z",
"enabled": true,
"name": "Test Server Auth"
}
}
This method deletes a Server Authorization entity.
DELETE | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/auths?identifier={identifier} |
---|---|
serverId |
The ID of the Server Authorization to delete. |
identifier |
The identifier of the Server Authorization to delete. |
This method displays a list of Server Authorization entities matching an optional search filter.
GET | /solaruser/api/v1/sec/user/dnp3/servers/auths |
---|
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
identifier |
String | An identifier to match. |
identifiers |
Array<String> | A list of identifiers to match (logical OR). |
enabled |
Boolean | The desired enabled state to match. |
The response will be a list of Server Authorization entity objects. See the Server Authorization view response for details.
This method updates the enabled status of a set of Server Authorization entities. An
application/json
request body may be included to narrow the entities the update applies to. If no
request body is provided, then all entities in the account are updated.
POST | /solaruser/api/v1/sec/user/dnp3/servers/auths/enabled/{enabled} |
---|---|
enabled |
The desired enabled state to set. |
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
identifier |
String | An identifier to match. |
identifiers |
Array<String> | A list of identifiers to match (logical OR). |
enabled |
Boolean | Only update entities with the specified enabled state. |
For example, to disable all authorizations matching a server ID, make a POST
request
to /solaruser/api/v1/sec/user/dnp3/servers/auths/enabled/false
with the following body:
{"serverId":2}
The Server Data Points CSV API is designed to make it easy to maintain the Measurement and Control data points for Server entities. You can see our example Google Sheet to use as a starting point, or use the download API to download a CSV or XLSX example document.
![Example SolarNetworK DNP3 CSV worksheet](images/solardnp3-example-csv-configuration@2x.png)
The Server Data Points CSV format contains the following columns:
# | Name | Type | Description |
---|---|---|---|
A | Node ID | Number | The node ID of the datum stream the DNP3 data point value comes from. |
B | Source ID | Text | The source ID of the datum stream the DNP3 data point value comes from. For Control* types this is also the node control ID. |
C | Property | Text | The name of the property within the datum stream the DNP3 data point value comes from. For Control* types this is optional; if not specified then SolarNetwork will look for a val or value property, and if not found use the first-available status property in the datum stream. |
D | DNP3 Type | Text | The DNP3 Type. |
E | Enabled | Boolean | A flag to indicate if the data point should be included in the server or not. |
F | Multiplier | Number | An optional number to multiply datum stream property values by before saving to the DNP3 server. |
G | Offset | Number | An optional number to add to datum stream property values before saving to the DNP3 server. Applied after the configured Multiplier number. |
H | Decimal Scale | Number | An optional number of decimal places to round datum stream property values to before saving to the DNP3 server. |
The DNP3 Type column must be one of the following values:
Value | Description |
---|---|
AnalogInput |
Analog input. |
AnalogOutputStatus |
Analog output status. |
BinaryInput |
Binary input. |
BinaryOutputStatus |
Binary output status. |
Counter |
Counter. |
DoubleBitBinaryInput |
Double bit binary input. |
FrozenCounter |
Frozen counter. |
ControlAnalog |
Analog control. |
ControlBinary |
Binary control. |
Use this method to download an example Server Data Points CSV or XLSX document. The XLSX example includes handy features like a drop-down menus for the DNP3 Type column and a checkbox for the Enabled column.
GET | /solaruser/api/v1/sec/user/dnp3/servers/csv-example |
---|
You must provide an Accept
HTTP header with one of these supported values:
Accept | Description |
---|---|
text/csv |
Download a comma separated values (CSV) example. |
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
Download an Excel example. |
This method accepts a Server Data Points CSV file as input and configures the Measurement and Control entities for a Server. The measurement and controls will configured with the same order as the rows of the CSV data.
⚠️ Note that all measurements and controls for the given server will be replaced by this method.
POST | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/csv |
---|---|
serverId |
The ID of the Server to save the data points for. |
The request must be submitted as multipart/form-data
with a file
part that contains the CSV
resource to import.
The response will be a JSON object with the following properties:
Property | Type | Description |
---|---|---|
measurementConfigs |
Array<Object> | A list of the imported Measurement entities. |
controlConfigs |
Array<Object> | A list of the imported Control entities. |
An example response looks like:
{
"success": true,
"data": {
"measurementConfigs": [
{
"userId": 1,
"serverId": 2,
"index": 0,
"created": "2023-08-12 20:03:04.828356Z",
"modified": "2023-08-12 20:03:04.828356Z",
"enabled": true,
"nodeId": 179,
"sourceId": "/power/1",
"property": "watts",
"multiplier": 0.001,
"scale": 3,
"type": "AnalogInput",
"valid": true
},
...
],
"controlConfigs": [
{
"userId": 1,
"serverId": 2,
"index": 0,
"created": "2023-08-12 20:03:04.828356Z",
"modified": "2023-08-12 20:03:04.828356Z",
"enabled": true,
"nodeId": 1,
"controlId": "switch/1",
"type": "Binary",
"valid": true
},
...
]
}
}
This method generates a Server Data Points CSV file from the Measurement and Control entities configured on a Server.
GET | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/csv |
---|---|
serverId |
The ID of the Server to save the data points for. |
An example HTTP response looks like this:
HTTP/1.1 200
Content-Disposition: attachment; filename="solarnet-dnp3-server-2.csv"
Node ID,Source ID,Property,DNP3 Type,Enabled,Multiplier,Offset,Decimal Scale
1,/power/1,watts,AnalogInput,true,0.001,,3
1,/power/2,watts,AnalogInput,true,0.001,,3
1,/power/1,voltage,AnalogInput,true,,,1
1,/power/2,voltage,AnalogInput,true,,,1
Server Measurement entities represent DNP3 read-only data points. Each data point includes an
index
property that is used to sort the measurements within the DNP3 Outstation instance. The
index values must be unique within a given server, but can be any integer value.
index
values are used to sort the Server Measurement entities into
DNP3 data points, and can contain arbitrary integer values. Within DNP3 the data points are
accessed starting from 0
and increase by one for each additional data point. Thus the index
defined on the entity might differ from the offset used in DNP3. For example:
Measurement Index | DNP3 Data Point Offset |
---|---|
1 | 0 |
2 | 1 |
100 | 2 |
101 | 3 |
To avoid confusion you could assign index
values that mirror what the DNP3 offset values will be,
by also starting from 0
and increasing by one for each additional Measurement.
This method creates or updates a Server Measurement entity. An application/json
request body
must be provided with the details to save.
POST | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/measurements/{index} |
---|---|
serverId |
The ID of the Server to save the entity for. |
index |
A unique sort order of the entity (lower to higher order). |
The request body accepts a JSON Server Measurement object with the following properties:
Property | Type | Description |
---|---|---|
nodeId |
Number | The node ID of the datum stream the DNP3 data point value comes from. |
sourceId |
String | The source ID of the datum stream the DNP3 data point value comes from. |
property |
String | The name of the property within the datum stream the DNP3 data point value comes from. |
index |
Number | The sort order of the entity. Must be unique within the associated Server. |
type |
String | The Measurement Type to use. |
multiplier |
Number | An optional number to multiply datum stream property values by before saving to the DNP3 server. |
offset |
Number | An optional number to add to datum stream property values before saving to the DNP3 server. Applied after the configured multiplier number. |
scale |
Number | An optional number of decimal places to round datum stream property values to before saving to the DNP3 server. |
enabled |
Boolean | The desired enabled state of the Server Measurement. |
The response will be a Server Measurement entity object. See Server Measurement view response for more information.
Server Measurement entities have a type
property that determines the DNP3 data point type used:
Value | Description |
---|---|
AnalogInput |
Analog input. |
AnalogOutputStatus |
Analog output status. |
BinaryInput |
Binary input. |
BinaryOutputStatus |
Binary output status. |
Counter |
Counter. |
DoubleBitBinaryInput |
Double bit binary input. |
FrozenCounter |
Frozen counter. |
This method displays a Server Measurement entity.
GET | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/measurements/{index} |
---|---|
serverId |
The ID of the Server Measurement to view. |
index |
The index of the Server Measurement to view. |
The response will be a Server Measurement entity object with the following properties:
Property | Type | Description |
---|---|---|
userId |
Number | The SolarNetwork account ID. |
serverId |
Number | A unique ID assigned to the entity. |
index |
Number | The sort order of the entity. |
created |
String | The creation date. |
modified |
String | The modification date. |
enabled |
Boolean | Enabled status indicator. Only enabled entities will be considered during authorization. |
nodeId |
Number | The node ID of the datum stream the DNP3 data point value comes from. |
sourceId |
String | The source ID of the datum stream the DNP3 data point value comes from. |
property |
String | The name of the property within the datum stream the DNP3 data point value comes from. |
type |
String | The Measurement Type to use. |
multiplier |
Number | An optional number to multiply datum stream property values by before saving to the DNP3 server. |
offset |
Number | An optional number to add to datum stream property values before saving to the DNP3 server. Applied after the configured multiplier number. |
scale |
Number | An optional number of decimal places to round datum stream property values to before saving to the DNP3 server. |
An example response looks like:
{
"success": true,
"data": {
"userId": 1,
"serverId": 2,
"index": 0,
"created": "2023-08-12 08:08:03.212448Z",
"modified": "2023-08-12 20:03:04.828356Z",
"enabled": true,
"nodeId": 123,
"sourceId": "/power/1",
"property": "watts",
"type": "AnalogInput",
"multiplier": 0.001,
"scale": 3
}
}
This method deletes a Server Measurement entity.
DELETE | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/measurements/{index} |
---|---|
serverId |
The ID of the Server Measurement to delete. |
index |
The index of the Server Measurement to delete. |
This method displays a list of Server Measurement entities. An application/json
request body may
be provided with a search filter, otherwise all entities in the account will be returned.
GET | /solaruser/api/v1/sec/user/dnp3/servers/measurements |
---|
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
index |
Number | An index to match. |
indexes |
Array<Number> | A list of indexes to match (logical OR). |
enabled |
Boolean | The desired enabled state to match. |
nodeId |
Number | A node ID to match. |
nodeIds |
Array<Number> | A list of node IDs to match (logical OR). |
sourceId |
String | A source ID to match. |
sourceIds |
Array<String> | A list of source IDs to match (logical OR). |
The response will be a list of Server Measurement entity objects. See the Server Measurement view response for details.
This method updates the enabled status of a set of Server Measurement entities. An
application/json
request body may be included to narrow the entities the update applies to. If no
request body is provided, then all entities in the account are updated.
POST | /solaruser/api/v1/sec/user/dnp3/servers/measurements/enabled/{enabled} |
---|---|
enabled |
The desired enabled state to set. |
The request body accepts a JSON search filter object with the following properties:
Property | Type | Description |
---|---|---|
serverId |
Number | The ID of a server to match. |
serverIds |
Array<Number> | A list of server IDs to match (logical OR). |
index |
Number | An index to match. |
indexes |
Array<Number> | A list of indexes to match (logical OR). |
enabled |
Boolean | Only update entities with the specified enabled state. |
nodeId |
Number | A node ID to match. |
nodeIds |
Array<Number> | A list of node IDs to match (logical OR). |
sourceId |
String | A source ID to match. |
sourceIds |
Array<String> | A list of source IDs to match (logical OR). |
For example, to disable all measurements matching a server ID, make a POST
request
to /solaruser/api/v1/sec/user/dnp3/servers/measurements/enabled/false
with the following body:
{"serverId":2}
Server Control entities represent DNP3 writable data points. Each data point includes an
index
property that is used to sort the controls within the DNP3 Outstation instance. The
index values must be unique within a given server, but can be any integer value.
⚠️ See the node in the Server Measurements section about how index values relate to DNP3 data point offset values.
This method creates or updates a Server Control entity. An application/json
request body
must be provided with the details to save.
POST | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/controls/{index} |
---|---|
serverId |
The ID of the Server to save the entity for. |
index |
A unique sort order of the entity (lower to higher order). |
The request body accepts a JSON Server Control object with the following properties:
Property | Type | Description |
---|---|---|
nodeId |
Number | The node ID of the datum stream the DNP3 data point value comes from. |
controlId |
String | The control ID of the node control, as well as the source ID of the datum stream the DNP3 data point value comes from. |
property |
String | The name of the property within the datum stream the DNP3 data point value comes from. If not specified then SolarNetwork will look for a val or value property, and if not found use the first-available status property in the datum stream. |
index |
Number | The sort order of the entity. Must be unique within the associated Server. |
type |
String | The Control Type to use. |
multiplier |
Number | An optional number to multiply datum stream property values by before saving to the DNP3 server. |
offset |
Number | An optional number to add to datum stream property values before saving to the DNP3 server. Applied after the configured multiplier number. |
scale |
Number | An optional number of decimal places to round datum stream property values to before saving to the DNP3 server. |
enabled |
Boolean | The desired enabled state of the Server Control. |
The response will be a Server Control entity object. See Server Control view response for more information.
Server Control entities have a type
property that determines the DNP3 data point type used:
Value | Description |
---|---|
Analog |
Analog control. |
Binary |
Binary control. |
This method displays a Server Control entity.
GET | /solaruser/api/v1/sec/user/dnp3/servers/{serverId}/controls/{index} |
---|---|
serverId |
The ID of the Server Control to view. |
index |
The index of the Server Control to view. |
The response will be a Server Control entity object with the following properties:
Property | Type | Description |
---|---|---|
userId |
Number | The SolarNetwork account ID. |
serverId |
Number | A unique ID assigned to the entity. |
index |
Number | The sort order of the entity. |
created |
String | The creation date. |
modified |
String | The modification date. |
enabled |
Boolean | Enabled status indicator. Only enabled entities will be considered during authorization. |
nodeId |
Number | The node ID of the datum stream the DNP3 data point value comes from. |
controlId |
String | The control ID of the node control, as well as the source ID of the datum stream the DNP3 data point value comes from. |
property |
String | The name of the property within the datum stream the DNP3 data point value comes from. If not specified then SolarNetwork will look for a val or value property, and if not found use the first-available status property in the datum stream. |
type |
String | The Control Type to use. |
multiplier |
Number | An optional number to multiply datum stream property values by before saving to the DNP3 server. |
offset |
Number | An optional number to add to datum stream property values before saving to the DNP3 server. Applied after the configured multiplier number. |
scale |
Number | An optional number of decimal places to round datum stream property values to before saving to the DNP3 server. |
An example response looks like:
{
"success": true,
"data": {
"userId": 1,
"serverId": 2,
"index": 0,
"created": "2023-08-12 08:10:25.086094Z",
"modified": "2023-08-12 20:03:04.828356Z",
"enabled": true,
"nodeId": 1,
"controlId": "switch/1",
"type": "Binary"
}
}```
## Server Control delete
This method deletes a Server Control entity.
| DELETE | `/solaruser/api/v1/sec/user/dnp3/servers/{serverId}/controls/{index}` |
| :-- | :--- |
| `serverId` | The ID of the Server Control to delete. |
| `index` | The index of the Server Control to delete. |
## Server Control list
This method displays a list of Server Control entities. An `application/json` request body may be
provided with a search filter, otherwise all entities in the account will be returned.
| GET | `/solaruser/api/v1/sec/user/dnp3/servers/controls` |
| :-- | :--- |
The request body accepts a JSON search filter object with the following properties:
| Property | Type | Description |
|:---------|:-----|:------------|
| `serverId` | Number | The ID of a server to match. |
| `serverIds` | Array<Number> | A list of server IDs to match (logical OR). |
| `index` | Number | An index to match. |
| `indexes` | Array<Number> | A list of indexes to match (logical OR). |
| `enabled` | Boolean | The desired enabled state to match. |
| `nodeId` | Number | A node ID to match. |
| `nodeIds` | Array<Number> | A list of node IDs to match (logical OR). |
| `sourceId` | String | A source ID to match. |
| `sourceIds` | Array<String> | A list of source IDs to match (logical OR). |
The response will be a list of Server Control entity objects. See the
[Server Control view response](#server-control-view-response) for details.
## Server Control update enabled
This method updates the enabled status of a set of Server Control entities. An
`application/json` request body may be included to narrow the entities the update applies to. If no
request body is provided, then all entities in the account are updated.
| POST | `/solaruser/api/v1/sec/user/dnp3/servers/controls/enabled/{enabled}` |
| :-- | :--- |
| `enabled` | The desired enabled state to set. |
The request body accepts a JSON search filter object with the following properties:
| Property | Type | Description |
|:---------|:-----|:------------|
| `serverId` | Number | The ID of a server to match. |
| `serverIds` | Array<Number> | A list of server IDs to match (logical OR). |
| `index` | Number | An index to match. |
| `indexes` | Array<Number> | A list of indexes to match (logical OR). |
| `enabled` | Boolean | Only update entities with the specified enabled state. |
| `nodeId` | Number | A node ID to match. |
| `nodeIds` | Array<Number> | A list of node IDs to match (logical OR). |
| `sourceId` | String | A source ID to match. |
| `sourceIds` | Array<String> | A list of source IDs to match (logical OR). |
For example, to disable all controls matching a server ID, make a `POST` request
to `/solaruser/api/v1/sec/user/dnp3/servers/controls/enabled/false` with the following body:
```json
{"serverId":2}