def _preflight_oadrRegisterReport(message_payload):
for report in message_payload['reports']:
# Check that the report name is preceded by METADATA_ when registering reports
if report['report_name'] in enums.REPORT_NAME.values \
and not report['report_name'].startswith("METADATA"):
report['report_name'] = 'METADATA_' + report['report_name']
# Check that the measurement name and description match according to the schema
for report_description in report['report_descriptions']:
if 'measurement' in report_description and report_description[
'measurement'] is not None:
utils.validate_report_measurement_dict(
report_description['measurement'])
# Add the correct namespace to the measurement
for report_description in report['report_descriptions']:
if 'measurement' in report_description and report_description[
'measurement'] is not None:
if report_description['measurement'][
'name'] in enums._MEASUREMENT_NAMESPACES:
measurement_name = report_description['measurement'][
'name']
measurement_ns = enums._MEASUREMENT_NAMESPACES[
measurement_name]
report_description['measurement']['ns'] = measurement_ns
else:
raise ValueError("The Measurement Name is unknown")
def test_validate_report_measurement_dict_invalid_name(caplog):
measurement = {'name': 'rainbows', 'unit': 'B', 'description': 'Rainbows'}
utils.validate_report_measurement_dict(measurement)
assert measurement['name'] == 'customUnit'
assert (f"You provided a measurement with an unknown name rainbows. "
"This was corrected to 'customUnit'. Please correct this in your "
"report definition.") in caplog.messages
def test_validate_report_measurement_dict_missing_items(caplog):
measurement = {'name': 'rainbows'}
with pytest.raises(ValueError) as err:
utils.validate_report_measurement_dict(measurement)
assert str(err.value) == (
f"The measurement dict must contain the following keys: "
"'name', 'description', 'unit'. Please correct this.")
def test_validate_report_measurement_dict_invalid_description_case(caplog):
measurement = {'name': 'current', 'unit': 'A', 'description': 'CURRENT'}
utils.validate_report_measurement_dict(measurement)
assert measurement['description'] == 'Current'
assert (f"The description for the measurement with name 'current' "
f"was not in the correct case; you provided 'CURRENT' but "
f"it should be 'Current'. "
"This was automatically corrected.") in caplog.messages
def test_validate_report_measurement_dict_invalid_unit():
with pytest.raises(ValueError) as err:
measurement = {
'name': 'current',
'unit': 'B',
'description': 'Current'
}
utils.validate_report_measurement_dict(measurement)
assert str(err.value) == (
f"The unit 'B' is not acceptable for measurement 'current'. Allowed "
f"units are: 'A'.")
def test_validate_report_measurement_dict_missing_power_attributes(caplog):
with pytest.raises(ValueError) as err:
measurement = {
'name': 'powerReal',
'description': 'RealPower',
'unit': 'W'
}
utils.validate_report_measurement_dict(measurement)
assert str(err.value) == (
"A 'power' related measurement must contain a "
"'power_attributes' section that contains the following "
"keys: 'voltage' (int), 'ac' (boolean), 'hertz' (int)")
def _preflight_oadrRegisterReport(message_payload):
for report in message_payload['reports']:
# Check that the report name is preceded by METADATA_ when registering reports
if report['report_name'] in enums.REPORT_NAME.values \
and not report['report_name'].startswith("METADATA"):
report['report_name'] = 'METADATA_' + report['report_name']
# Check that the measurement name and description match according to the schema
for report_description in report['report_descriptions']:
if 'measurement' in report_description and report_description[
'measurement'] is not None:
utils.validate_report_measurement_dict(
report_description['measurement'])
def test_validate_report_measurement_dict_invalid_description(caplog):
with pytest.raises(ValueError) as err:
measurement = {
'name': 'current',
'unit': 'A',
'description': 'something'
}
utils.validate_report_measurement_dict(measurement)
str(err.value) == (f"The measurement's description 'something' "
f"did not match the expected description for this type "
f" ('Current'). Please correct this, or use "
"'customUnit' as the name.")
def test_validate_report_measurement_dict_invalid_power_attributes(caplog):
with pytest.raises(ValueError) as err:
measurement = {
'name': 'powerReal',
'description': 'RealPower',
'unit': 'W',
'power_attributes': {
'a': 123
}
}
utils.validate_report_measurement_dict(measurement)
assert str(err.value) == (
"The power_attributes of the measurement must contain the "
"following keys: 'voltage' (int), 'ac' (bool), 'hertz' (int).")
def add_report(self,
callback,
resource_id,
measurement=None,
data_collection_mode='incremental',
report_specifier_id=None,
r_id=None,
report_name=enums.REPORT_NAME.TELEMETRY_USAGE,
reading_type=enums.READING_TYPE.DIRECT_READ,
report_type=enums.REPORT_TYPE.READING,
sampling_rate=None,
data_source=None,
scale="none",
unit=None,
power_ac=True,
power_hertz=50,
power_voltage=230,
market_context=None,
end_device_asset_mrid=None,
report_data_source=None):
"""
Add a new reporting capability to the client.
:param callable callback: A callback or coroutine that will fetch the value for a specific
report. This callback will be passed the report_id and the r_id
of the requested value.
:param str resource_id: A specific name for this resource within this report.
:param str measurement: The quantity that is being measured (openleadr.enums.MEASUREMENTS).
Optional for TELEMETRY_STATUS reports.
:param str data_collection_mode: Whether you want the data to be collected incrementally
or at once. If the VTN requests the sampling interval to be
higher than the reporting interval, this setting determines
if the callback should be called at the sampling rate (with
no args, assuming it returns the current value), or at the
reporting interval (with date_from and date_to as keyword
arguments). Choose 'incremental' for the former case, or
'full' for the latter case.
:param str report_specifier_id: A unique identifier for this report. Leave this blank for a
random generated id, or fill it in if your VTN depends on
this being a known value, or if it needs to be constant
between restarts of the client.
:param str r_id: A unique identifier for a datapoint in a report. The same remarks apply as
for the report_specifier_id.
:param str report_name: An OpenADR name for this report (one of openleadr.enums.REPORT_NAME)
:param str reading_type: An OpenADR reading type (found in openleadr.enums.READING_TYPE)
:param str report_type: An OpenADR report type (found in openleadr.enums.REPORT_TYPE)
:param datetime.timedelta sampling_rate: The sampling rate for the measurement.
:param str unit: The unit for this measurement.
:param boolean power_ac: Whether the power is AC (True) or DC (False).
Only required when supplying a power-related measurement.
:param int power_hertz: Grid frequency of the power.
Only required when supplying a power-related measurement.
:param int power_voltage: Voltage of the power.
Only required when supplying a power-related measurement.
:param str market_context: The Market Context that this report belongs to.
:param str end_device_asset_mrid: the Meter ID for the end device that is measured by this report.
:param report_data_source: A (list of) target(s) that this report is related to.
"""
# Verify input
if report_name not in enums.REPORT_NAME.values and not report_name.startswith(
'x-'):
raise ValueError(
f"{report_name} is not a valid report_name. Valid options are "
f"{', '.join(enums.REPORT_NAME.values)}",
" or any name starting with 'x-'.")
if reading_type not in enums.READING_TYPE.values and not reading_type.startswith(
'x-'):
raise ValueError(
f"{reading_type} is not a valid reading_type. Valid options are "
f"{', '.join(enums.READING_TYPE.values)}"
" or any name starting with 'x-'.")
if report_type not in enums.REPORT_TYPE.values and not report_type.startswith(
'x-'):
raise ValueError(
f"{report_type} is not a valid report_type. Valid options are "
f"{', '.join(enums.REPORT_TYPE.values)}"
" or any name starting with 'x-'.")
if scale not in enums.SI_SCALE_CODE.values:
raise ValueError(
f"{scale} is not a valid scale. Valid options are "
f"{', '.join(enums.SI_SCALE_CODE.values)}")
if sampling_rate is None:
sampling_rate = objects.SamplingRate(
min_period=timedelta(seconds=10),
max_period=timedelta(hours=24),
on_change=False)
elif isinstance(sampling_rate, timedelta):
sampling_rate = objects.SamplingRate(min_period=sampling_rate,
max_period=sampling_rate,
on_change=False)
if data_collection_mode not in ('incremental', 'full'):
raise ValueError(
"The data_collection_mode should be 'incremental' or 'full'.")
if data_collection_mode == 'full':
args = inspect.signature(callback).parameters
if not ('date_from' in args and 'date_to' in args
and 'sampling_interval' in args):
raise TypeError(
"Your callback function must accept the 'date_from', 'date_to' "
"and 'sampling_interval' arguments if used "
"with data_collection_mode 'full'.")
# Determine the correct item name, item description and unit
if report_name == 'TELEMETRY_STATUS':
item_base = None
elif isinstance(measurement, objects.Measurement):
item_base = measurement
elif isinstance(measurement, dict):
utils.validate_report_measurement_dict(measurement)
power_attributes = object.PowerAttributes(
**measurement.get('power_attributes')) or None
item_base = objects.Measurement(
name=measurement['name'],
description=measurement['description'],
unit=measurement['unit'],
scale=measurement.get('scale'),
power_attributes=power_attributes)
elif measurement.upper() in enums.MEASUREMENTS.members:
item_base = enums.MEASUREMENTS[measurement.upper()]
else:
item_base = objects.Measurement(name='customUnit',
description=measurement,
unit=unit,
scale=scale)
if report_name != 'TELEMETRY_STATUS' and scale is not None:
if item_base.scale is not None:
if scale in enums.SI_SCALE_CODE.values:
item_base.scale = scale
else:
raise ValueError(
"The 'scale' argument must be one of '{'. ',join(enums.SI_SCALE_CODE.values)}"
)
# Check if unit is compatible
if unit is not None and unit != item_base.unit and unit not in item_base.acceptable_units:
logger.warning(
f"The supplied unit {unit} for measurement {measurement} "
f"will be ignored, {item_base.unit} will be used instead. "
f"Allowed units for this measurement are: "
f"{', '.join(item_base.acceptable_units)}")
# Get or create the relevant Report
if report_specifier_id:
report = utils.find_by(self.reports, 'report_name', report_name,
'report_specifier_id', report_specifier_id)
else:
report = utils.find_by(self.reports, 'report_name', report_name)
if not report:
report_specifier_id = report_specifier_id or utils.generate_id()
report = objects.Report(created_date_time=datetime.now(),
report_name=report_name,
report_specifier_id=report_specifier_id,
data_collection_mode=data_collection_mode)
self.reports.append(report)
# Add the new report description to the report
target = objects.Target(resource_id=resource_id)
r_id = utils.generate_id()
report_description = objects.ReportDescription(
r_id=r_id,
reading_type=reading_type,
report_data_source=target,
report_subject=target,
report_type=report_type,
sampling_rate=sampling_rate,
measurement=item_base,
market_context=market_context)
self.report_callbacks[(report.report_specifier_id, r_id)] = callback
report.report_descriptions.append(report_description)
return report_specifier_id, r_id