Circutor EDS Instruction sheet

EDS - EDS·3G
XML SERVICES
CONFIGURATION MANUAL
(M081B01-03-15A)

PowerStudio XML SERVICES
2Configuration Manual

XML SERVICES
Configuration Manual 3
DISCLAIMER
CIRCUTOR, SA reserves the right to make modifications to the device or the unit
specifications set out in this instruction manual without prior notice.
CIRCUTOR, SA, on its web site, supplies its customers with the latest versions of the
device specifications and the most updated manuals.
www.circutor.com

PowerStudio XML SERVICES
4Configuration Manual
CONTENTS
DISCLAIMER....................................................................................................................................................... 3
CONTENTS........................................................................................................................................................... 4
LOG OF REVISIONS .......................................................................................................................................... 5
1.- XML SERVICES............................................................................................................................................. 6
1.1. / services / user / devices.xml .............................................................................................................. 6
1.2. /services/user/deviceInfo.xml?id=device?........................................................................................... 6
1.3. /services/user/varInfo.xml?var=device.variable?...?id=device?........................................................ 7
1.4. /services/user/values.xml?var=device.variable?...?id=device?.......................................................... 8
1.5. / services / user / forceVariables.xml? id = device.............................................................................. 9
1.6. /services/user/records.xml?begin=…?end=…?var=…?period=900 ................................................. 9
1.7. /services/user/events.xml?begin=…?end=…?id=…......................................................................... 12
1.8. /services/user/recordsEve.xml?begin=…?end=…?id=…................................................................. 12
2.- MAINTENANCE AND TECHNICAL SERVICE...................................................................................... 14
3.- GUARANTEE................................................................................................................................................ 14

XML SERVICES
Configuration Manual 5
LOG OF REVISIONS
Date
Revision
Description
04/15
M081B01-03-15A
Original version

PowerStudio XML SERVICES
6Configuration Manual
1.- XML SERVICES
PowerStudio provides a range of XML services to enable, in some respects, communication
with other applications.
In requests where it is necessary to express a date and time, both in service request and the
data from the response, these will be represented in UTC (Universal Coordinated Time) with the format
DDMMYYYYHHMMSS (two digits for the day, two for the month, four for the year and two for the hour,
minutes and seconds. It is also possible to represent only a date as DDMMYYYY assuming that the
time is 00:00:00, or represent an hour as HHMMSS. Finally in cases where milliseconds are required
these are represented with three digits after the seconds, DDMMYYYYHHMMSSUUU or
HHMMSSUUU.
The requests must follow the URI standard (RFC 2396), so the user of these requests must
take into account this detail when making such calls (especially in cases where the name of any device
contains non-ASCII characters).It should also be taken into account that the length of the request may
not exceed 4000 characters.
1.1. / services / user / devices.xml
Returns the list of configured devices.
<devices>
<id> … </id>
…
</devices>
Where:
•devices: Main field which will identify the main XML as a response to the device list
request.
•id: Name of each one of the devices.
1.2. /services/user/deviceInfo.xml?id=device?...
Returns information on devices. Each of the devices on which information is required must be
included in the request as:
?id=device2?id=device2
<devices>
<device>
<id> … </id>
<description>… </ description>
<type>… </ type>
<typeDescription>… </ typeDescription>
<var>… </ var>
…
</device>
…
</devices>
Where:
•devices: Main Field which will identify the XML as a response to the device
information request.
•device: Information from each of the devices requested:
id: Name of the device.
description: Description of device
type: Type of device (for example CVM144)
typeDescription: A description of the type of device (for example: CVM-144)

XML SERVICES
Configuration Manual 7
var: Name of each of the variables of the device. The name will be expressed
as device.variable (Refer to the variable appendix in the ‘Devices Manual’).
1.3. /services/user/varInfo.xml?var=device.variable?...?id=device?...
Returns variable information when carrying out the XML request. Each of the variables from
which a value is desired should be included in the request as:
?var=device.variable
And if you want to get information from all the variables of a device this must be indicated as
?id=device
With it being possible to request information from one or more variables and one or more
devices in the same request.
<varInfo>
<var>
<id> … </id>
<title>… </ title>
<hasValue> T </ hasValue>
<hasLogger> T </ hasLogger>
<sampleMode>… </ sampleMode>
<measureUnits>… </ measureUnits>
<unitsFactor>… </ unitsFactor>
<decimals>… </ decimals>
</ var>
…
<varInfo>
Where:
•varInfo: Main field which identifies the XML as a response to the request for
information about variables
•var: Information from each of the variables requested:
id: Name of the variable in device.variable format (Refer to the variable
appendix in the ‘Devices Manual’).
title: Brief description of the variable.
hasValue: Indicates if it is possible to ask the instantaneous value of the
variable (T) or not (F).
hasLogger: Indicates whether it is possible to ask the log value of the variable
(T) or not (F).
sampleMode: Variable type, mode used to group together the values of a
variable:
♦none: Without type
♦average: Average value:
♦max: Maximum value.
♦min: Maximum value.
♦pfAverage: Power factor, average value
♦pfMax: Power factor, maximum value
♦pfMin: Power factor, minimum value
♦last: Last value:
♦differential current: Differential current value between the current
value and the previous one.
♦samples. samples: The value cannot be grouped
♦discrete: Discreet values. The value cannot be grouped
measureUnits: Variable units:
♦#NONE Without units
♦#V Voltage
♦#A Current

PowerStudio XML SERVICES
8Configuration Manual
♦#VA Apparent power
♦#W Active power
♦#VARL Inductive power
♦#VARC Capacitive power
♦#PF Power factor
♦#HZ Frequency
♦#PERCENT Percentage
♦#WH Active energy
♦#VARLH Inductive energy
♦#VARCH Capacitive energy
♦#DATETIME Date and time
♦If not preceded by # it is a user defined unit
unitsFactor: Power of 10 that indicates the value the variable is multiplied by
in the log file.
decimals: Decimals with this variable.
1.4. /services/user/values.xml?var=device.variable?...?id=device?...
Returns the instantaneous value of the variable when the XML request is carried out. Each of
the variables that the value is required from should be included in the request as:
?var=device.variable
If you want to ascertain the value of all the variables of a device it should be indicated as:
?id=device
With it being possible in a single request to request the value of one or more variables and
values of one or more devices
<values>
<variable>
<id> … </id>
<value>… </ value>
</ variable>
…
</values>
Where:
•values: Main field which will identify the XML as a response to the request for variable
values
•variable: List of variables:
id: Identifier of the variable in device.variable format (Refer to the variable
appendix in the ‘Devices Manual’).
value: Value of variable at the time of the request.

XML SERVICES
Configuration Manual 9
1.5. / services / user / forceVariables.xml? id = device
With this request we may send the order to force variables to PowerStudio. The request must
include the name of the device we want to force so that, if necessary, authentication can be checked
(see ¡Error! No se encuentra el origen de la referencia. ¡Error! No se encuentra el origen de la
referencia.). Only variables belonging to the device indicated in the request will be forced.
<forceVariables>
<forceVar>
<forceName>… </ forceName>
<forceValue>… </ forceValue>
</ forceVar>
…
</forceVariables>
Where:
•forceVariables: Main field that will identify the XML as a request to force variables.
•forceVar: Information on each of the variables to be forced:
forceName: Name of the variable in device.variable format (Refer to the
variable appendix in the ‘Devices Manual’).Only variables that can be forced,
for example digital output variables.
forceValue: Value to which we wish to force the variable.
1.6. /services/user/records.xml?begin=…?end=…?var=…?period=900
Returns information on one or more variables between the dates “begin” and “end”. Each of
the variables that the information is required from should be included in the request as:
?var=device.variable
?var = device.variable The format of ”begin” and ”end” will be DDMMYYYY when you wish only
to indicate the date (in this case the hour will 00:00:00) or DDMMYYYYHHMMSS when both the date
and the hour are specified. Both "begin" as "end" must be expressed in UTC (Universal Coordinated
Time).
Finally, we may specify the period of data grouping using the “period” parameter.This value may be:
FILE data not grouped, returning the register as they have saved in the log.
AUTO Grouping will take place automatically depending on the specified dates ”begin” and
”end”
ALL Data is grouped into a single value
> 0 Value in seconds in which the data is grouped.
If the “period” parameter does not appear on the request it shall be considered as value 0 and the data
will not be grouped.
<recordGroup>
<period>… </ period>
<record>
<dateTime> … </dateTime>
<field>… </ field>
<fieldComplex>… </ fieldComplex>
<fieldARM>… </ fieldARM>
<fieldFO> … </fieldFO>
<fieldEVQ>… </ fieldEVQ>
…
</record>
…
</recordGroup>
Where:

PowerStudio XML SERVICES
10 Configuration Manual
•recordGroup: Main field which will identify the XML as a response to the variable
register request.
•period: Register period. Will report on time elapsed between records.
•record: Will Identify each of the records:
dateTime: Date and time of the sample.
field: Standard value register.
fieldComplex: Complex value register
fieldARM: Harmonic value register
fieldFO: Waveform value record
fieldEVQ: EVQ event register
Here are the different types of values that can be returned by this request:
•Standard value registers (voltages, currents, power, energy, etc.).
<field>
<id> … </id>
<value>… </ value>
</ Field>
id: Variable identifier (device.variable)
value: Value
•Complex value register (PLT, etc.).
<fieldComplex>
<id> … </id>
<value>… </ value>
<flags>… </ flags>
</ fieldComplex>
id: Variable identifier (device.variable)
value: Value
flags: Additional information from the variable formed by the union of one or
more of the following values
♦0x0000 The PLT is correct
♦0x0001 The PLT calculation has been done with fewer samples
than expected
♦0x0002 The PLT calculation has been done with more samples
than expected
♦0x0004 The samples used in the PLT calculation do not have an
equidistant separation in the sampling window
♦0x0008 Some PST used in the calculation of the PLT contain
events in phase 1
♦0x0010 Some PST used in the calculation of the PLT contain
events in phase 2
♦0x0020 Some PST used in the calculation of the PLT contain
events in phase 3
♦0x0040 Some PST used in the calculation of the PLT are not
complete
•Harmonic value record
<fieldARM>
<id> … </id>
<element>
<harmonic>… </ harmonic>
<value>… </ value>
</ element>
…
</fieldARM>
id: Variable identifier (device.variable)

XML SERVICES
Configuration Manual 11
Element: Registers from each of the harmonics
♦harmonic: Harmonics number
♦value: Harmonic value.
•Waveform value record
<fieldFO>
<id> … </id>
<element>
<msec>… </ msec>
<value>… </ value>
</ element>
…
</fieldFO>
id: Variable identifier (device.variable)
Element: Information from each of the points that make up the waveform
♦msec: millisecond
♦value: value
•EVQ event Record.
<fieldEVQ>
<id> … </id>
<value>… </ value>
<phase>… </ phase>
<duration>… </ duration>
<averageValue>… </ averageValue>
<previousValue>… </ previousValue>
<eventType>… </ eventType>
<endForced>… </ endForced>
<semicycleVoltage>
<date>… </ date>
<value>… </ value>
</ semicycleVoltage>
…
</fieldEVQ>
id: Variable identifier (device.variable)
value: Value of the event:
Phase: Phase in which the event occurs
duration:Duration of the event in milliseconds
averageValue: Average value:
previousValue: Old value
eventType: Type of event
♦0 Interruption
♦1 gap
♦3 Overvoltage
endForced: Mark if the event has finished correctly (F) or has be forced to
finalise (T)
semicycleVoltage: Each of the points that make up the semi-circular
effective voltage associated with the event. This field is optional and may not
exist.
♦date: Date and time (DDMMYYYYHHMMSSUUU)
♦value: Value

PowerStudio XML SERVICES
12 Configuration Manual
1.7. /services/user/events.xml?begin=…?end=…?id=…
Returns the events log of one or more events between dates “begin” and “end”. Each of the
events on which information is required must be included in the request as:
?id=name_event
?var = device.variable The format of ”begin” and ”end” will be DDMMYYYY when you wish only
to indicate the date (in this case the hour will 00:00:00) or DDMMYYYYHHMMSS when both the date
and the hour are specified. Both "begin" as "end" must be expressed in UTC (Universal Coordinated
Time).
<main>
<recordGroup>
<id> … </id>
<record>
<date>… </ date>
<eventId> … </eventId>
<annotation> … </annotation>
<value>… </ value>
</record>
…
</recordGroup>
…
</main>
Where:
•main:Main field that will identify the XML as a response to the request.
•recordGroup: Field that groups all the records of an event.
•id: Event identifier.
•record: Will Identify each of the records:
date: Event date and hour
eventId:Event identifier.
annotation:Event annotation.
value: Event value.
♦ON Event enabled
♦OFF Event disabled
♦ACK Event acknowledged
1.8. /services/user/recordsEve.xml?begin=…?end=…?id=…
Returns information on events recorded by one or more devices between the dates “begin” and
“end”. Each of the devices on which information is required must be included in the request as:
?id=device
?var = device.variable The format of ”begin” and ”end” will be DDMMYYYY when you wish only
to indicate the date (in this case the hour will 00:00:00) or DDMMYYYYHHMMSS when both the date
and the hour are specified. Both "begin" as "end" must be expressed in UTC (Universal Coordinated
Time).

XML SERVICES
Configuration Manual 13
<main>
<recordGroup>
<device> … </device>
<record>
<dateTime> … </dateTime>
<field>
<id> … </id>
<value>… </value>
</field>
…
</record>
…
</recordGroup>
…
</main>
Where:
•main:Main field that will identify the XML as a response to the request.
•recordGroup: Field that groups all the records of an event.
•device: Device the records refer to.
•record: Will Identify each of the records:
dateTime: Date and time of the sample.
field: Will identify each of the fields.
♦id: Iden
♦value: Value of the event.

PowerStudio XML SERVICES
14 Configuration Manual
2.- MAINTENANCE AND TECHNICAL SERVICE
In the case of any query in relation to unit operation or malfunction, please contact
the CIRCUTOR, SA Technical Support Service.
Technical Assistance Service
Vial Sant Jordi, s/n 08232 - Viladecavalls (Barcelona)
Tel.: [phone] (Spain) / [phone] (outside of Spain)
email: [e-mail]
3.- GUARANTEE
CIRCUTOR guarantees its products against any manufacturing defect for two years after the delivery
of the units.
CIRCUTOR will repair or replace any defective factory product returned during the guarantee period.
•No returns will be accepted and no unit will be repaired or replaced if it is
not accompanied by a report indicating the defe
ct detected or the
reason for the return.
•The guarantee will be void if the units has been improperly used or the
storage, installation and maintenance instructions listed in this manual
have not been followed. "Improper usage" is defined as any operating or
storage condition contrary to the national electrical code or that
surpasses the limits indicated in the technical and environmental
features of this manual.
•CIRCUTOR accepts no liability due to the possible damage to the unit or
other parts of the installation, nor will it cover any possible sanctions
derived from a possible failure, improper installation or "improper usage"
of the unit. Consequently, this guarantee does not apply to failures
occurring in the following cases:
- Overvoltages and/or electrical disturbances in the supply;
- Water, if the product does not have the appropriate IP classification;
- Poor ventilation and/or excessive temperatures;
- Improper installation and/or lack of maintenance;
- Buyer repairs or modifications without the manufacturer's authorisation.

XML SERVICES
Configuration Manual 15

CIRCUTOR, SA
Vial Sant Jordi, s/n
08232 - Viladecavalls (Barcelona)
Tel: [phone] - Fax: [phone]
www.circutor.es [email protected]