Items/Create
Create an item handle to be notified of the data value of this item.
Request
- ItemName - string - the item name (= browse path) of the item to create
- ClientItemHandle - integer - client-side item handle, used for routing answers and events
Response
- ClientItemHandle - integer - client-side item handle from request
- ServerItemHandle - integer - server-side item handle
- DataType - string - data type of the item, see Data types
- ArraySize - integer - array length if the item is an array; 0 if not known; missing for scalar values
- StringLength - integer - maximum string length for items that have it; missing if not known or item is not a string
- StructureName - string - structure name if DataType == "Structure"
- EnumerationName - string - enumeration name if DataType == "Enumeration"
Event
After creating the item handle, "ValueChanged" events arrive to notify of changes to the item value
- ClientItemHandle - integer - client-side item handle from request
- DataType - string - data type of the value, see Data types
- Value - any - data value
- Quality - integer - data quality, see Quality values, conforming to OPC
Example
in:
{
"function": "Items/Create",
"id": "some-text-or-number",
"data": {
"ItemName": "...",
"ClientItemHandle": 42
}
}
out:
{
"function": "Items/Create",
"id": "some-text-or-number",
"status": 0,
"data": {
"ClientItemHandle": 42,
"ServerItemHandle": 20,
"DataType": "UInt32"
}
}
event:
{
"event": "ValueChanged",
"data": {
"ClientItemHandle": 42,
"DataType": "UInt32",
"Value": 12345,
"Quality": 0
}
}
Items/Delete
Delete an item handle previously created by Items/Create.
Request
- ServerItemHandle - integer - server-side item handle as returned by Create
Response
No data.
Example
in:
{
"function": "Items/Delete",
"id": "some-text-or-number",
"data": {
"ServerItemHandle": 20
}
}
out:
{
"function": "Items/Delete",
"id": "some-text-or-number",
"status": 0,
"data": {}
}
Items/Browse
Browses item names.
Request
- Path - string - the root path for the browse operation; empty or missing for root list
- StartOffset - integer - the start offset of the browse operation; missing value is treated as 0
- MaxResults - integer - maximum number of results; missing value uses a default value
Response
- Results - array of object - results
- Name - string - the item name; to use it, prepend the requested path and a '.' character
- DataType - string - data type of the value, see Data types
- Rights - string - access rights, one or more of the following characters:
- R - read access
- W - write access
- X - expandable
- E - event source
- H - history enabled
- Comment - string - a comment text for this item
- ArrayDimensions - array of integer - the list of array dimensions; missing if not an array
- Blocked - boolean - true if more results exist (and can be requested with a higher StartOffset)
Example
in:
{
"function": "Items/Browse",
"id": "some-text-or-number",
"data": {
"Path": "...",
"StartOffset": 0
}
}
out:
{
"function": "Items/Browse",
"id": "some-text-or-number",
"status": 0,
"data": {
"Results": [
{ "Name": "abc", "Type": "UInt16", ... },
...
],
"Blocked": false
}
}
Items/Write
Writes a new value to an item.
Request
- ItemName - string - the item name (= browse path) of the item to write
- DataType - string - the data type; must match the actual type of the item
- StructureName - string - the structure name if DataType == "Structure"
- EnumerationName - string - the enumeration name if DataType == "Enumeration"
- Value - any - the data value
Response
Example
in:
{
"function": "Items/Write",
"id": "some-text-or-number",
"data": {
"ItemName": "...",
"DataType": "UInt32",
"Value": 42
}
}
out:
{
"function": "Items/Write",
"id": "some-text-or-number",
"status": 0,
"data": {
"Quality": 0
}
}
Items/SyncRead
Read the current value from an item.
Request
- ItemName - string - the item name (= browse path) of the item to create
Response
- DataType - string - data type of the item, see Data types
- ArraySize - integer - array length if the item is an array; missing for scalar values
- StructureName - string - structure name if DataType == "Structure"
- EnumerationName - string - enumeration name if DataType == "Enumeration"
- Value - any - data value
- Quality - integer - data quality, see Quality values, conforming to OPC
Example
in:
{
"function": "Items/SyncRead",
"id": "some-text-or-number",
"data": {
"ItemName": "..."
}
}
out:
{
"function": "Items/SyncRead",
"id": "some-text-or-number",
"status": 0,
"data": {
"DataType": "UInt32",
"Value": 42,
"Quality": 0
}
}
Items/ReadHistory
Reads historical values of one or more items.
Request
- ItemName - string - the item name (= browse path) of the item to read
- StartTime - string - the ISO8601 timestamp of the first value to return
- EndTime - string - the ISO8601 timestamp of the last value to return
- ValueCount - integer - the number of values to return
- IncludeBounds - boolean - optional; true to include one value outside of the specified bounds if no value at the exact bounds exist; default true
- AggregateInterval - double - optional; the aggregation interval (in seconds); must be greater than 0; if missing, unprocessed values are returned
- Aggregate - string - the aggregate value to return; available are: min, max, avg, count, stddev; required if AggregateInterval is set; ignored otherwise
Notes:
- At least 2 of StartTime, EndTime, ValueCount must be given
- If StartTime > EndTime or StartTime is missing, values are returned in reverse order
Response
- Quality - integer - read quality, see Quality values, conforming to OPC
- Blocked - boolean - true if more values exist but could not be returned because of memory limits or ValueCount
- Values - array of object - the read values
- Timestamp - string - the ISO8601 timestamp of the value
- DataType - string - data type of the value, see Data types
- Value - any - data value
- Quality - integer - data quality, see Quality values, conforming to OPC
Example
in:
{
"function": "Items/ReadHistory",
"id": "some-text-or-number",
"data": {
"ItemName": "...",
"StartTime": "2020-01-01T00:00:00Z",
"EndTime": "2020-02-01T00:00:00Z",
"IncludeBounds": true,
"AggregateInterval": 60,
"Aggregate": "min"
}
}
out:
{
"function": "Items/ReadHistory",
"id": "some-text-or-number",
"status": 0,
"data": {
"Values": [
{
"Timestamp": "2020-01-01T00:00:00Z",
"DataType": "UInt32",
"Value": 12345,
"Quality": 0
},...
]
}
}
Items/ReadHistoryDisplay
Reads historical values of one or more items.
Request
- ItemName - string - the item name (= browse path) of the item to read
- StartTime - string - the ISO8601 timestamp of the first value to return
- EndTime - string - the ISO8601 timestamp of the last value to return
- ValueCount - integer - the number of values to return
- IncludeBounds - boolean - optional; true to include one value outside of the specified bounds if no value at the exact bounds exist; default true
- AggregateInterval - double - optional; the aggregation interval (in seconds); must be greater than 0; if missing, unprocessed values are returned
- Aggregate - string - the aggregate value to return; available are: min, max, avg, count, stddev; required if AggregateInterval is set; ignored otherwise
Notes:
- At least 2 of StartTime, EndTime, ValueCount must be given
- If StartTime > EndTime ir StartTime is missing, values are returned in reverse order
Response
- Quality - integer - read quality, see Quality values, conforming to OPC
- Blocked - boolean - true if more values exist but could not be returned because of memory limits or ValueCount
- Values - array of values - the read values
- Offset in the given area, value, quality if not zero
Example
in:
{
"function": "Items/ReadHistoryDisplay",
"id": "some-text-or-number",
"data": {
"ItemName": "...",
"StartTime": "2020-01-01T00:00:00Z",
"EndTime": "2020-02-01T00:00:00Z",
"ValueCount": 1000,
"IncludeBounds": true,
"AggregateInterval": 60,
"Aggregate": "min"
}
}
out:
{
"function": "Items/ReadHistoryDisplay",
"id": "some-text-or-number",
"status": 0,
"data": {
"Values": [
{
"Data": [0, 32]
},
{
"Data": [4, 31, 4]
},...
]
}
}
1.8.14