wiliot-certificate 1.3.0a1__py3-none-any.whl

gw_certificate/tests/bad_crc_to_PER_quantization.csv

@@ -0,0 +1,51 @@
+bad_crc_percent,per_percent
+2,7
+4,11
+6,16
+8,20
+10,25
+12,29
+14,33
+16,37
+18,41
+20,45
+22,49
+24,52
+26,55
+28,58
+30,61
+32,64
+34,67
+36,69
+38,72
+40,74
+42,76
+44,78
+46,81
+48,83
+50,84
+52,86
+54,87
+56,89
+58,90.5
+60,91.5
+62,92.5
+64,93.5
+66,94.5
+68,95.5
+70,96.5
+72,97
+74,97.5
+76,98
+78,98.5
+80,99
+82,99.25
+84,99.5
+86,99.75
+88,100
+90,100
+92,100
+94,100
+96,100
+98,100
+100,100

gw_certificate/tests/connection.py

@@ -0,0 +1,181 @@
+import datetime
+import json
+import time
+import pkg_resources
+import pandas as pd
+from packaging import version
+
+from gw_certificate.tests.static.connection_defines import *
+from gw_certificate.common.debug import debug_print
+from gw_certificate.api_if.gw_capabilities import GWCapabilities
+from gw_certificate.tests.generic import INCONCLUSIVE_MINIMUM, PassCriteria, MINIMUM_SCORE, PERFECT_SCORE, GenericStage, GenericTest, INFORMATIVE
+from gw_certificate.api_if.api_validation import validate_message, MESSAGE_TYPES
+from gw_certificate.interface.mqtt import MqttClient, Serialization
+from gw_certificate.interface.ble_sniffer import BLESniffer, BLESnifferContext
+
+
+class ConnectionStage(GenericStage):
+    def __init__(self, mqttc:MqttClient, **kwargs):
+        self.mqttc = mqttc
+        self.stage_tooltip = "Awaits the gateway to establish MQTT connection and upload it's configurations via the 'status' topic as it's first message"
+        self.__dict__.update(kwargs)
+        super().__init__(stage_name=type(self).__name__, **self.__dict__)
+
+    def run(self):
+        super().run()
+        self.stage_pass = MINIMUM_SCORE
+        input('The GW is expected to publish a configuration JSON/Protobuf message through the status topic upon connecting to mqtt:\n'
+                'Please unplug GW from power. Press enter when unplugged')
+        self.mqttc.flush_messages()
+        input('Please plug GW back to power. Press enter when plugged')
+        debug_print('Waiting for GW to connect... (Timeout 3 minutes)')
+        timeout = datetime.datetime.now() + datetime.timedelta(minutes=3)
+        self.status_message = None
+
+        while datetime.datetime.now() < timeout and self.status_message is None:
+            self.status_message = self.mqttc.get_status_message()
+
+        if self.status_message is not None:
+            ser = self.mqttc.get_serialization()
+            debug_print(self.status_message)
+            if ser == Serialization.JSON:
+                self.validation = validate_message(MESSAGE_TYPES.STATUS, self.status_message)
+                self.stage_pass = PERFECT_SCORE if self.validation[0] else MINIMUM_SCORE
+            else:
+                self.stage_pass = PERFECT_SCORE
+            # set GW Capabilities:
+            for key, value in self.status_message.items():
+                if key in GWCapabilities.get_capabilities() and type(value) is bool:
+                    self.gw_capabilities.set_capability(key, value)
+
+    def generate_stage_report(self):
+        self.add_report_header()
+
+        if self.status_message is not None:
+            ser = self.mqttc.get_serialization()
+            debug_print(f'{ser.value} serialization detected')
+            self.add_to_stage_report(f'{ser.value} serialization detected')
+            self.add_to_stage_report('GW Status packet received:')
+            self.add_to_stage_report(f'{json.dumps(self.status_message)}\n')
+
+            for key, value in self.status_message.items():
+                if key in GWCapabilities.get_capabilities() and type(value) is bool:
+                    self.add_to_stage_report(f'Capability set: {key} - {value}')
+            # Add reason test failed to report if neccessary
+            if self.stage_pass == MINIMUM_SCORE:
+                self.error_summary = "API (JSON structure) is invalid. "
+                self.add_to_stage_report(f'\n{len(self.validation[1])} validation errors:')
+                for error in self.validation[1]:
+                    self.add_to_stage_report(error.message)
+        else:
+            self.error_summary = "No message recieved from GW in status topic after 3 mins."
+            self.add_to_stage_report(self.error_summary)
+
+        self.report_html = self.template_engine.render_template('stage.html', stage=self,
+                                                                stage_report=self.report.split('\n'))
+        debug_print(self.report)
+        return super().generate_stage_report()
+    
+
+class InterferenceAnalysisStage(GenericStage):
+    def __init__(self, sniffer:BLESniffer, **kwargs):
+        self.sniffer = sniffer
+        self.conversion_table_df = None
+        self.stage_tooltip = "Analyze BLE interference level (Bad CRC %)"
+        self.__dict__.update(kwargs)
+
+        # Stage shows warning if CER is >=50%
+        self.result_indication = INFORMATIVE
+        self.pass_min = 51
+
+        super().__init__(stage_name=type(self).__name__, **self.__dict__)
+
+    def get_data_from_quantization_csv(self):
+        relative_path = CSV_NAME
+        csv_path = pkg_resources.resource_filename(__name__, relative_path)
+        conversion_table_df = pd.read_csv(csv_path)
+        self.conversion_table_df = conversion_table_df
+
+    def interference_analysis(self):
+        """Analyze the interference level (PER) before the test begins"""
+        self.report_buffer = []
+        
+        def handle_wrap_around(a):
+            "handle a wrap around of the counter"
+            if a < 0:
+                a = a + MAX_UNSIGNED_32_BIT
+            return a
+        
+        for channel in CHANNELS_TO_ANALYZE:
+            # Send the sniffer a command to retrive the counters and convert them to dict
+            start_cntrs = self.sniffer.get_pkts_cntrs(channel[0])
+            debug_print(f'Analyzing channel {channel[0]}... (30 seconds)')
+            time.sleep(CNTRS_LISTEN_TIME_SEC)
+            end_cntrs = self.sniffer.get_pkts_cntrs(channel[0])
+
+            if start_cntrs == None or end_cntrs == None:
+                debug_print(f'Channel {channel[0]} ({channel[1]} MHz) interference analysis was skipped beacause at least one counter is missing.')
+                self.report_buffer.append(f'Channel {channel[0]} ({channel[1]} MHz) Ambient Interference was not calculated, missing at least one counter.')
+                self.stage_pass = INCONCLUSIVE_MINIMUM
+                continue
+
+            # Calculate the bad CRC percentage
+            diff_dict = dict()
+            for key in CNTRS_KEYS:
+                diff_dict[key] = handle_wrap_around(end_cntrs[key] - start_cntrs[key])
+            if (diff_dict[WLT_RX] + diff_dict[NON_WLT_RX]) > 0:
+                bad_crc_percentage = round((diff_dict[BAD_CRC] / (diff_dict[WLT_RX] + diff_dict[NON_WLT_RX])) * 100)
+            else:
+                bad_crc_percentage = 0
+            self.report_buffer.append(f'Channel {channel[0]} ({channel[1]} MHz) Ambient Interference (bad CRC percentage) is: {bad_crc_percentage}%.')
+            self.report_buffer.append(f'Good CRC packets = {diff_dict[NON_WLT_RX] + diff_dict[WLT_RX] - diff_dict[BAD_CRC]}, bad CRC packets: {diff_dict[BAD_CRC]}')
+
+            good_crc_percentage = 100 - bad_crc_percentage
+            if (self.stage_pass == MINIMUM_SCORE) or (good_crc_percentage < self.stage_pass):
+                self.stage_pass = good_crc_percentage
+                if self.stage_pass < self.pass_min:
+                    self.error_summary = "High bad CRC rate within the current environment."
+        
+            # Uncomment if you want to see PER of the site (will require print adjustments). Below, we use the truth table from the csv to match PER the bad CRC percentage. Require an update of the CSV to the bridge-GW case
+            # closest_index = (self.conversion_table_df['bad_crc_percent'] - bad_crc_percentage).abs().idxmin()
+            # per_percent = self.conversion_table_df.iloc[closest_index]['per_percent']
+            # self.add_to_stage_report(f'Channel {channel} PER is: {per_percent}%')
+
+    def run(self):
+        super().run()
+        # Run interference analysis
+        # Note: there is an infrastructure for converting bad_CRC % to PER, currently unused and commented since the quantization_csv does not match the bridge to GW case.
+        debug_print(f"Starting interference analysis for channels {[ch[0] for ch in CHANNELS_TO_ANALYZE]}. This will take {30 * len(CHANNELS_TO_ANALYZE)} seconds (total)")
+        # self.get_data_from_quantization_csv()
+        self.interference_analysis()
+    
+    def generate_stage_report(self):
+        self.add_report_header()
+        for line in self.report_buffer:
+            self.add_to_stage_report(line)
+
+        self.report_html = self.template_engine.render_template('stage.html', stage=self,
+                                                                stage_report=self.report.split('\n'))
+        debug_print(self.report)
+        return super().generate_stage_report()
+
+STAGES = [ConnectionStage]
+
+class ConnectionTest(GenericTest):
+    def __init__(self, **kwargs):
+        self.test_tooltip = "Stages related to cloud connectivity and environment"
+        self.__dict__.update(kwargs)
+        super().__init__(**self.__dict__, test_name=type(self).__name__)
+        stages = STAGES
+        if version.parse(self.uart.get_version()) >= version.parse(INTERFERENCE_ANALYSIS_FW_VER):
+            stages.append(InterferenceAnalysisStage)
+        self.stages = [stage(**self.__dict__) for stage in stages]
+        
+    def run(self):
+        super().run()
+        self.test_pass = PERFECT_SCORE
+        for stage in self.stages:
+            stage.prepare_stage()
+            stage.run()
+            self.test_pass = PassCriteria.calc_for_test(self.test_pass, stage)
+            self.add_to_test_report(stage.generate_stage_report())

gw_certificate/tests/downlink.py

@@ -0,0 +1,174 @@
+import base64
+import datetime
+import json
+import os
+import time
+import pandas as pd
+import numpy as np
+import plotly.express as px
+from google.protobuf.json_format import MessageToDict
+
+from gw_certificate.common import wltPb_pb2
+from gw_certificate.common.debug import debug_print
+from gw_certificate.interface.ble_sniffer import BLESniffer, BLESnifferContext
+from gw_certificate.interface.if_defines import RX_CHANNELS
+from gw_certificate.tests.static.downlink_defines import *
+from gw_certificate.interface.mqtt import MqttClient
+from gw_certificate.interface.pkt_generator import BrgPktGenerator
+from gw_certificate.tests.generic import PassCriteria, PERFECT_SCORE, MINIMUM_SCORE, INCONCLUSIVE_MINIMUM, GenericTest, GenericStage
+
+class GenericDownlinkStage(GenericStage):
+    def __init__(self, sniffer:BLESniffer, mqttc:MqttClient, pkt_gen:BrgPktGenerator, stage_name, **kwargs):
+        self.__dict__.update(kwargs)
+        super().__init__(stage_name=stage_name, **self.__dict__)        
+        
+        #Clients
+        self.sniffer = sniffer
+        self.mqttc = mqttc
+        self.pkt_gen = pkt_gen
+        
+        #Stage Params
+        self.sent_pkts = []
+        self.sniffed_pkts = pd.DataFrame()
+        
+        #Paths
+        self.sent_csv_path = os.path.join(self.test_dir, f'{self.stage_name}_sent.csv')
+        self.sniffed_csv_path = os.path.join(self.test_dir, f'{self.stage_name}_sniffed.csv')
+        self.graph_html_path = os.path.join(self.test_dir, f'{self.stage_name}.html')
+
+        
+    def prepare_stage(self):
+        super().prepare_stage()
+        self.sniffer.flush_pkts()
+    
+    def send_adv_payloads(self, tx_max_durations=TX_MAX_DURATIONS, retries=RETRIES):
+        sent_pkts = []
+        for tx_max_duration in tx_max_durations:
+            debug_print(f'Tx Max Duration {tx_max_duration}')
+            for retry in retries:
+                self.pkt_gen.increment_all()
+                brg_hb = self.pkt_gen.get_brg_hb()
+                tx_max_retries = tx_max_duration//100
+                sent_payload = self.mqttc.advertise_packet(raw_packet=brg_hb, tx_max_duration=tx_max_duration, use_retries=self.use_retries)
+                if isinstance(sent_payload, wltPb_pb2.DownlinkMessage):
+                    sent_payload = MessageToDict(sent_payload)
+                    # Decode b64-encoded bytes
+                    sent_payload['txPacket']['payload'] = base64.b64decode(sent_payload['txPacket']['payload']).hex().upper()
+                else:
+                    sent_payload = json.dumps(sent_payload)
+                debug_print(f'{sent_payload} sent to GW')
+                sent_pkts.append({'tx_max_duration': tx_max_duration, 'tx_max_retries': tx_max_retries,
+                                    'retry': retry, 'pkt': brg_hb[12:], 'payload': sent_payload, 'time_sent': datetime.datetime.now()})
+                time.sleep(max(MAX_RX_TX_PERIOD_SECS, (tx_max_duration/1000)*1.2))
+        time.sleep(10)
+        return sent_pkts
+        
+    def process_sniffed_pkts(self, sent_pkts, sniffer:BLESniffer):
+        for pkt in sent_pkts:
+            # Get vars from dict
+            raw_packet = pkt['pkt']
+            # Get packets from sniffer
+            sniffed_pkts = sniffer.get_filtered_packets(raw_packet=raw_packet)
+            pkt['channel'] = str(sniffer.rx_channel)
+            pkt['num_pkts_received'] = len(sniffed_pkts)
+            self.sniffed_pkts = pd.concat([self.sniffed_pkts, sniffed_pkts.to_pandas()])
+        self.sent_pkts += sent_pkts
+
+    def generate_stage_report(self):
+        # Create graph and trendline
+        self.add_report_header()
+        self.sent_pkts = pd.DataFrame(self.sent_pkts)
+        x_value = ('tx_max_duration', 'TX Max Duration') if not self.use_retries else ('tx_max_retries', 'TX Max Retries')
+        fig = px.scatter(self.sent_pkts, x=x_value[0], y='num_pkts_received', color='channel', title=f'Packets Received by Sniffer / {x_value[1]}',
+                         trendline='ols', labels={x_value[0]: x_value[1], 'num_pkts_received': 'Number of packets received', 'channel': "BLE Adv. Channel"})
+        fig.update_layout(scattermode="group", scattergap=0.95)
+        trendline_info = px.get_trendline_results(fig)
+        # Calculate whether stage pass/failed
+        self.stage_pass = PERFECT_SCORE
+        for channel, channel_df in trendline_info.groupby('BLE Adv. Channel'):
+            channel_pass = PERFECT_SCORE
+            channel_err_summary = ''
+            channel_pkts = self.sent_pkts[self.sent_pkts['channel'] == channel]
+            channel_trendline = channel_df['px_fit_results'].iloc[0]
+            slope = channel_trendline.params[1]
+            rsquared = channel_trendline.rsquared
+            # Determine Channel Pass
+            channel_pass, channel_err_summary = PassCriteria.calc_for_stage_downlink(rsquared, slope, self.stage_name)
+            if channel_pass < self.stage_pass:
+                self.stage_pass = channel_pass
+                self.error_summary = channel_err_summary
+            self.add_to_stage_report(f"Channel {channel}: {PassCriteria.to_string(channel_pass)}")
+            self.add_to_stage_report(f"- Total {len(channel_pkts['payload'])} MQTT payloads sent")
+            self.add_to_stage_report(f"- Total {sum(channel_pkts['num_pkts_received'])} BLE Packets received by sniffer")
+            self.add_to_stage_report(f"- R Value: {rsquared} | Slope: {slope}")
+        # Export all stage data
+        self.sent_pkts.to_csv(self.sent_csv_path)
+        self.add_to_stage_report(f'Sent data saved - {self.sent_csv_path}')
+        self.sniffed_pkts.to_csv(self.sniffed_csv_path)
+        self.add_to_stage_report(f'Sniffed data saved - {self.sniffed_csv_path}')
+        fig.write_html(self.graph_html_path)
+        self.add_to_stage_report(f'Graph saved - {self.graph_html_path}')
+        debug_print(self.report)
+        
+        # Generate HTML
+        graph_div = fig.to_html(full_html=False, include_plotlyjs='cdn')
+        self.report_html = self.template_engine.render_template('stage.html', stage=self, 
+                                                                stage_report=self.report.split('\n'), graph = graph_div)
+        return self.report
+        
+class SanityStage(GenericDownlinkStage):
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+        self.stage_tooltip = ("Verifies that the gateway advertises requested packets. "
+                              "These are requested via Advertisement actions published to the 'update' topic (MQTT)")
+        super().__init__(**self.__dict__, stage_name=type(self).__name__)
+
+    def run(self):                
+        super().run()
+        for channel in RX_CHANNELS:
+            debug_print(f'RX Channel {channel}')
+            with BLESnifferContext(self.sniffer, channel) as sniffer:
+                # Send the packets
+                sent_pkts = self.send_adv_payloads(STAGE_CONFIGS[SANITY_STAGE][0], STAGE_CONFIGS[SANITY_STAGE][1])
+                # Process sniffed packets
+                self.process_sniffed_pkts(sent_pkts, sniffer)
+        return True
+
+class CorrelationStage(GenericDownlinkStage):
+    def __init__(self, **kwargs):
+        self.__dict__.update(kwargs)
+        self.stage_tooltip = ("Checks how consistently the gateway advertises packets. "
+                              "Expects a consistently increasing packets count with increasing 'txMaxDuration'")
+        super().__init__(**self.__dict__, stage_name=type(self).__name__)
+
+    def run(self):                
+        super().run()
+        for channel in RX_CHANNELS:
+            debug_print(f'RX Channel {channel}')
+            with BLESnifferContext(self.sniffer, channel) as sniffer:
+                # Send the packets
+                sent_pkts = self.send_adv_payloads(STAGE_CONFIGS[CORRELATION_STAGE][0], STAGE_CONFIGS[CORRELATION_STAGE][1])
+                # Process sniffed packets
+                self.process_sniffed_pkts(sent_pkts, sniffer)
+        return True
+    
+STAGES = [SanityStage, CorrelationStage]
+
+class DownlinkTest(GenericTest):
+    def __init__(self, **kwargs):        
+        self.test_tooltip = "Stages examining gateway advertisements by issuing advertisement actions (txPacket)"
+        self.__dict__.update(kwargs)
+        super().__init__(**self.__dict__, test_name=type(self).__name__)
+        self.pkt_gen = BrgPktGenerator()
+        self.pkt_gen.set_bridge_id(DEFAULT_BRG_ID)
+        self.use_retries = self.topic_suffix == '-test'
+        self.stages = [stage(**self.__dict__) for stage in STAGES]
+    
+    def run(self):
+        super().run()
+        self.test_pass = PERFECT_SCORE
+        for stage in self.stages:
+            stage.prepare_stage()
+            stage.run()
+            self.add_to_test_report(stage.generate_stage_report())
+            self.test_pass = PassCriteria.calc_for_test(self.test_pass, stage)

gw_certificate/tests/generic.py

@@ -0,0 +1,161 @@
+import datetime
+import os
+
+from gw_certificate.api.extended_api import ExtendedEdgeClient
+from gw_certificate.common.debug import debug_print
+from gw_certificate.api_if.gw_capabilities import GWCapabilities
+from gw_certificate.interface.ble_simulator import BLESimulator
+from gw_certificate.interface.if_defines import SEP
+from gw_certificate.interface.mqtt import MqttClient
+
+PASS_STATUS = {True: 'PASS', False: 'FAIL'}
+
+# Score values for pass/inconclusive/fail
+PERFECT_SCORE = 100
+PASS_MINIMUM = 80
+INCONCLUSIVE_MINIMUM = 70
+INIT_INCONCLUSIVE_MINIMUM = 40
+MINIMUM_SCORE = 0
+
+# Results indications for stages. Must always be synced with frontend. 
+# 'score' shows as pass/inconclusive/fail. 'info' shows as info/warning.
+SCORE_BASED = 'score'
+INFORMATIVE = 'info'
+OPTIONAL = 'optional'
+
+class PassCriteria():
+    def __init__(self):
+        pass
+        
+    @staticmethod
+    def to_string(pass_value:int) -> str:
+        if pass_value >= PASS_MINIMUM:
+            return 'Pass'
+        elif pass_value >= INCONCLUSIVE_MINIMUM:
+            return 'Inconclusive'
+        else:
+            return 'Fail'
+
+    @staticmethod
+    def missing_score(pass_value:int) -> int:
+        return PERFECT_SCORE - pass_value
+
+    @staticmethod
+    def calc_for_stage_uplink(pass_value:int, stage_name:str) -> int:
+        error_msg = "Insufficient amount of packets were scanned & uploaded by the gateway"
+        return pass_value, error_msg
+
+    @staticmethod
+    def calc_for_stage_stress(pass_value: int, stage_name:str) -> int:
+        return pass_value
+    
+    @staticmethod
+    def calc_for_stage_downlink(rsquared, slope, stage_name:str):
+        error_msg = ''
+        if 'Sanity' in stage_name:
+            if rsquared > 0:
+                return PERFECT_SCORE, error_msg
+            else:
+                error_msg = 'No advertisements were received from the gateway.'
+                return MINIMUM_SCORE, error_msg
+        else:
+            if rsquared > 0.8 and slope > 0:
+                return PERFECT_SCORE, error_msg
+            elif rsquared > 0.5 and slope > 0:
+                error_msg = "The correlation between 'txMaxDuration' and the board advertisements is suboptimal."
+                return INCONCLUSIVE_MINIMUM, error_msg
+            else:
+                error_msg = "The correlation between 'txMaxDuration' and the board advertisements is weak."
+                return MINIMUM_SCORE, error_msg
+
+    @staticmethod
+    def calc_for_test(test_pass_value:int, stage) -> int:
+        if stage.stage_pass < test_pass_value:
+            if 'Geolocation' in stage.stage_name or 'info' in stage.result_indication:
+                return test_pass_value
+            else:
+                return stage.stage_pass
+        else:
+            return test_pass_value
+
+
+class GenericTest:
+    def __init__(self, mqttc: MqttClient, 
+                 gw_capabilities:GWCapabilities, gw_id, owner_id, test_name, ble_sim: BLESimulator = None, **kwargs):
+        # Clients
+        self.mqttc = mqttc
+        self.ble_sim = ble_sim
+        
+        # Test-Related
+        self.gw_capabilities = gw_capabilities
+        self.report = ''
+        self.report_html = ''
+        self.test_pass = MINIMUM_SCORE
+        self.pass_min = PASS_MINIMUM
+        self.inconclusive_min = INCONCLUSIVE_MINIMUM
+        self.start_time = None
+        self.test_name = test_name
+        self.test_dir = os.path.join(self.certificate_dir, self.test_name)
+        self.env_dirs.create_dir(self.test_dir)
+        self.stages = []
+        self.test_tooltip = kwargs.get('test_tooltip', 'Missing tooltip')
+        self.result_indication = kwargs.get('result_indication', SCORE_BASED)
+        
+    def __repr__(self):
+        return self.test_name
+    
+    def run(self):
+        self.start_time = datetime.datetime.now()
+        debug_print(f"Starting Test {self.test_name} : {self.start_time}")
+        
+    def runtime(self):
+        return datetime.datetime.now() - self.start_time
+    
+    def add_to_test_report(self, report):
+        self.report += '\n' + report
+    
+    def create_test_html(self):
+        self.report_html = self.template_engine.render_template('test.html', test=self,
+                                                                running_time = self.runtime())
+    
+    def end_test(self):
+        self.create_test_html()
+
+class GenericStage():
+    def __init__(self, stage_name, **kwargs):
+        #Stage Params
+        self.stage_name = stage_name
+        self.result_indication = kwargs.get('result_indication', SCORE_BASED)
+        self.stage_pass = MINIMUM_SCORE
+        self.pass_min = kwargs.get('pass_min', PASS_MINIMUM)
+        self.inconclusive_min = INCONCLUSIVE_MINIMUM
+        self.report = ''
+        self.report_html = ''
+        self.start_time = None
+        self.csv_path = os.path.join(self.test_dir, f'{self.stage_name}.csv')
+        self.stage_tooltip = kwargs.get('stage_tooltip', 'Missing tooltip')
+        self.error_summary = kwargs.get('error_summary', 'View the stage report for more info')
+        
+    def __repr__(self):
+        return self.stage_name
+    
+    def prepare_stage(self):
+        debug_print(f'### Starting Stage: {self.stage_name}')
+
+    def run(self):
+        self.start_time = datetime.datetime.now()
+
+    def add_to_stage_report(self, report):
+        self.report += f'{report}\n'
+    
+    def generate_stage_report(self):
+        return self.report
+    
+    def add_report_line_separator(self):
+        self.add_to_stage_report('-' * 50)
+    
+    def add_report_header(self):
+        uncapitalize = lambda s: s[:1].lower() + s[1:] if s else ''
+        self.add_to_stage_report(f'Stage run time: {datetime.datetime.now() - self.start_time}')
+        self.add_to_stage_report(f'This stage {uncapitalize(self.stage_tooltip)}.')
+        self.add_report_line_separator()