methods for FP introspection

WolframWilluhn commented 10 months ago

Clients of the SGr library my want to find out about the data points of the function profiles, e. g. names or units of data points, without having to parse the XML files themselves.

The SGr library should offer methods for clients to obtain a list of all data points along with generic information.

WolframWilluhn commented 10 months ago

This information would, for instance, be used by the introspective reader to periodically log the values of all readable data points to the console without any further configuration - just by supplying the FP XML.

WolframWilluhn commented 9 months ago

Proposal for interface declaration:

Retrieve generic functional profiles
- Function name: getfps
- Argument: none
- Return value type: List[FunctionalProfileBase]
Retrieve generic data points
- Function name: getdps
- Argument: functional_profile_name: String
- Return value type: List[DataPointBase]

ChrisBroenni commented 7 months ago

Good point,. @ArndGerns , @ergo-furrer & myself clarified some missunderstandings related to the meaning of generic attributes. ergonomics apply changes to Schema and Java and then we will come back to this issue.

ginoagb commented 6 months ago

@ergo-furrer , what is the status of this issue? Can it be updated following the last discussions about attributes?

ergo-furrer commented 6 months ago

@ginoagb

Regarding Wolframs input: I had a meeting with Wolfram and we discussed the 'introspective-reader' approach. I implemented an introspective reading interface within the SGrJava library that can be used read a functional-profile/data-point list together with the most common attributes for each data-point.

The introspective reader is used to build the user-interface for the manual test-tool. With the test tool you can load an EI-XML and and then read/write to the device:

The left panel shows the functional-profiles with each data-point in a navigation tree
The right panel shows the most common attributes for the selected data-point

Remarks: The current interface is specific to the Java implementation and I know that Robin did something similar in Python. I think we should do some further steps to 'harmonize' the two implementations regarding the API and the properties that should be published by the interface (see the right panel above). I will have a look at what Robin has done and come up with a proposal.

Regarding Chris input: Arnd, Chris and I did define and clarify the misunderstandings mentioned above. We agreed to provide the possibility to define data-points that have constant values in the EI-XML. The constant value is then read from the EI-XML and not the device. We did this because there are certain values that can be read from the device for one product-brand where other brands do not support this and the values must be provided by the EI-XML as constant values (e.g measurement-precision values).

The related changes are in the following pull-request, issue: Pull Request: Add constant data points to Products Issue: Add constant data points to Products

The implementation in the SGrJava library is not done yet, however I will implement this within my next tasks.

ergo-furrer commented 6 months ago

SGr Device Info API Proposal

============================

The API is inspired by the current Python API. It allows retrieving:

general device information
information regarding required configuration parameters
a list with all functional profiles, each functional profile containing a list of according data points.
a single functional profile by functional_profile_name
a list of data points for a single functional profile by functional_profile_name
a single data point by functional_profile_name and data_point_name

API methods

get_device_info() -> DeviceInfo

get_device_configuration_info() -> List<ConfigurationElement>

get_functional_profiles() -> List<FunctionalProfile>

get_functional_profile(functional_profile_name) -> FunctionalProfile

get_data_points(function_profile_name) -> List<DataPoint>

get_data_point(functional_profile_name, data_point_name) -> DataPoint

API data objects

DeviceInfo
- name                  : String
- manufacturer          : String
- versionNumber         : String, EI-XML versionNumber
- softwareVersion       : String
- hardwareVersion       : String
- deviceCategory        : XSD Enum DeviceCategory
- interfaceType         : MODBUS | RESTAPI | MESSAGING
- operationEnvironment  : LOCAL | CLOUD
- genericAttributes     : List<GenericAttribute>
- configurationInfo     : List<ConfigurationElement>

GenericAttribute
- name              : String
- dataType          : String according XSD Enum DataTypeProduct
- value             : according dataType
- unit              : XSD Enum Units
- children          : List<GenericAttribute>

ConfigurationElement
- name              : String
- dataType          : XSD Enum DataTypeProduct
- descriptions      : Map<Langugage, String>

FunctionalProfile
- name
- type              : String
- category          : XSD Enum FunctionalProfileCategory
- genericAttributes : List<GenericAttribute>
- dataPoints        : List<DataPoint>

DataPoint
- name              : String    
- dataType          :  String according XSD Enum DataTypeProduct
- unit              : XSD Enum Units
- permissions       : XSD Enum R, W, RW, RWP, C...
- minimumValue      : optional, according dataType
- maximumValue      : optional, according dataType
- arrayLen          : optional, int
- genericAttributes : List<GenericAttribute>

Remarks:

Currently all devices/EI-XML support only one interfaceType per device. However, the XSD allows adding more than one interface to an EI-XML. The proposed API does not reflect this, neither the getVal(), setVal() API does. Shall we support having several interfaceTypes within the API or shall we stay with one interface only? If we support multiple interfaces, then an API to get a single dataPoint looks as follows:

get_data_point(inteface_type, functional_profile_name, data_point_name) -> DataPoint

ArndGerns commented 6 months ago

IMHO the api definition is ok.

Concerning the remark:

In principle, it could be possible to have a device with e.g. a modbus and with a rest api interface. So in principle, that can be handled with the interface list in the XSD.

But at the end, it would be easier to define 2 XML's - one for each interface, The common part is too small and the access to the data points too difficult to really define an XML with two interfaces.

So at least for now, we should assume that an XML defines only one interface.

ergo-furrer commented 5 months ago

@mkrebs81 The 'Introspective API' and the API to read configuration values as described above is now implemented in SGrJava and merged into 'master'.

I did also a refactoring and moved the Value classes from communicator.common.api to communicator.common.api.values. This will require some refactoring in your code too, is suppose...

mkrebs81 commented 2 days ago

I am closing this issue, because it was already improved by @robin-schoch

SmartGridready / SGrPython