From fe25fd652b53d581355250ef6155b31374f495bc Mon Sep 17 00:00:00 2001 From: Marco Zeisler Date: Fri, 11 Jun 2021 17:28:57 +0200 Subject: [PATCH] update doc --- components/i_feed/devices/traffic_light.py | 8 +++++ components/i_feed/devices/vehicle.py | 39 ++++++++++++++++++---- 2 files changed, 41 insertions(+), 6 deletions(-) diff --git a/components/i_feed/devices/traffic_light.py b/components/i_feed/devices/traffic_light.py index 22e972b..3b3c7e8 100644 --- a/components/i_feed/devices/traffic_light.py +++ b/components/i_feed/devices/traffic_light.py @@ -39,6 +39,14 @@ class TrafficLight: tlid: str, switching_time: int = SWITCHING_TIME, starting_color: TrafficLightColor = TrafficLightColor.RED): + """ + Init a new Traffic Light client. This will already initialize its message queue. + Start it with self.start(). + + :param tlid: ID of the traffic light + :param switching_time: time in seconds to switch between states (TrafficLightColor.RED and .GREEN) + :param starting_color: TrafficLightColor to start with + """ self.tlid = tlid self.switching_time = switching_time self._starting_color = starting_color diff --git a/components/i_feed/devices/vehicle.py b/components/i_feed/devices/vehicle.py index 64d0b39..ff04790 100644 --- a/components/i_feed/devices/vehicle.py +++ b/components/i_feed/devices/vehicle.py @@ -70,6 +70,19 @@ class Vehicle: vin: str, starting_point: geopy.Point = STARTING_POINT, starting_velocity: float = STARTING_VELOCITY): + """ + Initialize a new vehicle client. Already initializes the corresponding sending and receiving message queue. + A vehicle sends every UPDATE_INTERVAL seconds its current DAF to the orchestrator. It receives as response the + new TargetVelocity to achieve a possible green wave. After a fixed amount of kilometers, the NCE event is + happening. The car then stands still for TIME_TO_RECOVER seconds. Afterwards, it starts driving with the last + known velocity. While it is recovering, it ignores the target velocity responses from the orchestrator. + A vehicle drives a full route between start and end. After reaching the end, it restores the internal state and + starts again from the beginning. + + :param vin: Vehicle Identification Number + :param starting_point: point on globe to start at + :param starting_velocity: velocity to start driving with + """ self.vin = vin self._starting_point = starting_point self._gps_location = starting_point @@ -85,6 +98,10 @@ class Vehicle: def nce(self): """ On accessing this property, it is calculated if the NCE shall happen. NCE only happens up to once per route. + If the NCE happens, the car stopps driving (velocity = 0) for TIME_TO_RECOVER seconds. In this time, + responses from the orchestrator are ignored. After recovery, the vehicle starts driving again with the last + known velocity.z + :return: True if NCE invoked, otherwise False """ if self._nce_possible and not self._nce_happened: @@ -115,7 +132,10 @@ class Vehicle: @property def daf(self): """ - :return: "Datenaufzeichnung für automatisiertes Fahren" (DAF) object + Return the DAF object of the vehicle. The properties are always evaluated on calling. That guarantees accurate + values. + + :return: current "Datenaufzeichnung für automatisiertes Fahren" (DAF) object """ # ATTENTION: ORDER MANDATORY @@ -133,10 +153,10 @@ class Vehicle: @property def gps_location(self): """ - Update self.gps_location with given speed in km/h and the driven time in seconds - :param velocity: in km/h - :param time: in seconds - :param bearing: direction in degrees: 0=N, 90=E, 180=S, 270=W + An accurate current position of the vehicle at the moment the property is called is retunred. + The gps location is derived from the last position this property was called at and the + time the vehicle was driving since then. Therefore, it is not necessary to call this function exactly at a given + time span, because it calculates the driven kms relative to the calling time. """ # Define starting point. start = self._gps_location @@ -165,6 +185,9 @@ class Vehicle: @property def driven_kms(self): + """ + :returns: a string representation of the driven kms + """ return '{}km'.format(round(self._driven_kms, 2)) def start_driving(self): @@ -211,12 +234,16 @@ class Vehicle: @circuit(failure_threshold=10, expected_exception=AMQPConnectionError) def send_status_update(self): + """ + Sends the current DAF to the orchestrator. The orchestrator will then respond asynchronously on the response + queue. + """ print(self.driven_kms, '\t', self.daf) self._daf_mb.send(pickle.dumps(self.daf)) def new_velocity(self, response: bytes): """ - Will be invoked if new target velocity message received + Will be invoked if new target velocity message received from orchestrator. :param response: pickled TargetVelocity object """ response: TargetVelocity = pickle.loads(response)