diff --git a/crates/coffee-machine/src/ubproject.redirect.toml b/crates/coffee-machine/src/ubproject.redirect.toml new file mode 100644 index 0000000..384f218 --- /dev/null +++ b/crates/coffee-machine/src/ubproject.redirect.toml @@ -0,0 +1 @@ +path = "../../../docs" diff --git a/docs/automotive-adas/swe_3_sw_detailed_design.rst b/docs/automotive-adas/swe_3_sw_detailed_design.rst index 3f80bbe..75373a9 100644 --- a/docs/automotive-adas/swe_3_sw_detailed_design.rst +++ b/docs/automotive-adas/swe_3_sw_detailed_design.rst @@ -8,6 +8,18 @@ SWE.3 Detailed Design This document provides the software implementation documentation as per SWE.1 and SWE.2 requirements. +Codelinks example +------------------ +Using **C** language. + +.. src-trace:: + :project: adas + +Automodule example +------------------ +Using **Python** language. + + .. automodule:: automotive_adas :members: :undoc-members: diff --git a/docs/conf.py b/docs/conf.py index dbe4b24..9e15f04 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ # We need to make Python aware of our project source code, which is stored outside `/docs`, # under `src/` -code_path = os.path.join(os.path.dirname(__file__), "../", "src/") +code_path = os.path.join(os.path.dirname(__file__), "../", "src/python/") sys.path.append(code_path) print(f"CODE_PATH: {code_path}") @@ -99,7 +99,7 @@ "selector": "article#furo-main-content a", # A list of selectors, where no preview icon shall be added, because it makes often no sense. # For instance the own ID of a need object, or the link on an image to open the image. - "not_selector": "div.needs_head a, h1 a, h2 a, a.headerlink, a.back-to-top, a.image-reference, em.sig-param a, a.paginate_button, a.sd-btn", + "not_selector": "div.needs_head a, h1 a, h2 a, a.headerlink, a.back-to-top, a.image-reference, em.sig-param a, a.paginate_button, a.sd-btn, a[href*='#L'], div.highlight a", "set_icon": True, "icon_only": True, "icon_click": True, diff --git a/docs/ubproject.toml b/docs/ubproject.toml index c3b920e..63d65c9 100644 --- a/docs/ubproject.toml +++ b/docs/ubproject.toml @@ -673,6 +673,36 @@ local_url_field = "local-url" # Need's field name for local URL set_remote_url = true # Enable remote url generation remote_url_field = "remote-url" # Need's field name for remote URL + +# ADAS + +# Configuration for the ADAS c project +[codelinks.projects.adas] +remote_url_pattern = "https://github.com/useblocks/sphinx-needs-demo/blob/{commit}/{path}#L{line}" + +[codelinks.projects.adas.source_discover] +src_dir = "../src/c" # Relative path to Rust source +gitignore = true +comment_type ="cpp" + +[codelinks.projects.adas.analyse] +get_need_id_refs = true +get_oneline_needs = true # Extract oneline need definitions from code + +[codelinks.projects.adas.analyse.oneline_comment_style] +start_sequence = "@ " # Start sequence: "// @ " +field_split_char = "," # Separator between fields +# Define the fields in the oneline comments +needs_fields = [ + { "name" = "title", "type" = "str" }, + { "name" = "id", "type" = "str" }, + { "name" = "type", "type" = "str", "default" = "impl" }, + { "name" = "implements", "type" = "list[str]", "default" = [] }, +] + + +# COFFE MACHINE + # Configuration for the coffee-machine Rust project [codelinks.projects.coffee_machine] remote_url_pattern = "https://github.com/useblocks/sphinx-needs-demo/blob/{commit}/{path}#L{line}" diff --git a/pyproject.toml b/pyproject.toml index 542d170..0fba45c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -15,7 +15,8 @@ dependencies = [ "sphinx-test-reports>=1.3.2", # pin as RTD consumes this file, not uv.lock "furo>=2024.8.6", "sphinx-preview>=0.1.2", - "ubt-sphinx==0.7.1" + "ubt-sphinx==0.7.1", + "ubt-runtime==0.6.0" ] readme = "README.md" requires-python = ">= 3.12" diff --git a/src/c/acc.c b/src/c/acc.c new file mode 100644 index 0000000..726866e --- /dev/null +++ b/src/c/acc.c @@ -0,0 +1,49 @@ +/** + * Adaptive Cruise Control - pseudo-code implementation + * + * Covers SWREQ_004, SWREQ_005, SWREQ_006, SWREQ_007 + */ + +#include "acc.h" + +// @ AdaptiveCruiseModule struct, IMPL_ACC_MODULE, impl, [SWREQ_004, SWREQ_005, SWREQ_006, SWREQ_007] +typedef struct { + float distance_m; /* measured distance to vehicle ahead (m) */ + float target_speed_mps; /* current speed setpoint (m/s) */ + float collision_risk; /* normalised risk score 0.0 – 1.0 */ + int emergency_active; /* 1 when emergency brake has been commanded */ +} AdaptiveCruiseModule; + +// @ measure_radar_distance, IMPL_ACC_DISTANCE, impl, [SWREQ_004] +/** + * Read radar return and compute distance to the nearest object ahead. + * Updates acc->distance_m with high-precision measurement (±0.1 m). + */ +void measure_radar_distance(AdaptiveCruiseModule *acc, const RadarFrame *frame) +{ + /* stub: parse frame, calculate distance, write acc->distance_m */ + (void)acc; (void)frame; +} + +// @ adjust_speed, IMPL_ACC_SPEED, impl, [SWREQ_005, SWREQ_013] +/** + * Dynamically update the speed setpoint based on the measured following + * distance, desired headway and detected speed-limit signs. + */ +void adjust_speed(AdaptiveCruiseModule *acc, float speed_limit_mps) +{ + /* stub: headway control law → write acc->target_speed_mps */ + (void)acc; (void)speed_limit_mps; +} + +// @ evaluate_collision_risk, IMPL_ACC_RISK, impl, [SWREQ_006, SWREQ_007] +/** + * Compute a collision-risk score from sensor fusion data. + * Triggers emergency brake autonomously when risk exceeds critical threshold. + */ +void evaluate_collision_risk(AdaptiveCruiseModule *acc, const SensorFusion *sf) +{ + /* stub: predictive analytics → set acc->collision_risk; + if risk > 0.9 set acc->emergency_active and command brakes */ + (void)acc; (void)sf; +} diff --git a/src/c/lane_keeping.c b/src/c/lane_keeping.c new file mode 100644 index 0000000..ff3a819 --- /dev/null +++ b/src/c/lane_keeping.c @@ -0,0 +1,48 @@ +/** + * Lane Keeping Assist - pseudo-code implementation + * + * Covers SWREQ_001, SWREQ_002, SWREQ_003 + */ + +#include "lane_keeping.h" + +// @ LaneKeepingModule struct, IMPL_LKA_MODULE, impl, [SWREQ_001, SWREQ_002, SWREQ_003] +typedef struct { + float lane_offset_m; /* lateral deviation from lane centre */ + int markings_valid; /* 1 = lane markings detected */ + float correction_angle; /* steering correction in degrees */ +} LaneKeepingModule; + +// @ detect_lane_markings, IMPL_LKA_DETECT, impl, [SWREQ_001] +/** + * Process camera frame and update marking validity flag. + * Handles rain, fog and low-light conditions via adaptive thresholding. + */ +void detect_lane_markings(LaneKeepingModule *lka, const CameraFrame *frame) +{ + /* stub: analyse frame, set lka->markings_valid and update lane_offset_m */ + (void)lka; (void)frame; +} + +// @ check_lane_deviation, IMPL_LKA_DEVIATION, impl, [SWREQ_002] +/** + * Return 1 when lateral offset exceeds the warning threshold and no + * turn-signal is active; triggers dashboard / audio warning. + */ +int check_lane_deviation(const LaneKeepingModule *lka, int turn_signal_active) +{ + /* stub: compare lka->lane_offset_m against threshold */ + (void)lka; (void)turn_signal_active; + return 0; +} + +// @ apply_steering_correction, IMPL_LKA_CORRECTION, impl, [SWREQ_003] +/** + * Calculate corrective steering angle to bring the vehicle back to + * lane centre and forward the command to the actuator layer. + */ +void apply_steering_correction(LaneKeepingModule *lka) +{ + /* stub: compute PID correction, write lka->correction_angle, send to actuator */ + (void)lka; +} diff --git a/src/__init__.py b/src/python/__init__.py similarity index 100% rename from src/__init__.py rename to src/python/__init__.py diff --git a/src/automotive_adas.py b/src/python/automotive_adas.py similarity index 100% rename from src/automotive_adas.py rename to src/python/automotive_adas.py diff --git a/src/automotive_adas_tests.py b/src/python/automotive_adas_tests.py similarity index 100% rename from src/automotive_adas_tests.py rename to src/python/automotive_adas_tests.py diff --git a/src/teen_car.py b/src/python/teen_car.py similarity index 100% rename from src/teen_car.py rename to src/python/teen_car.py diff --git a/src/ubproject.redirect.toml b/src/ubproject.redirect.toml new file mode 100644 index 0000000..19cee48 --- /dev/null +++ b/src/ubproject.redirect.toml @@ -0,0 +1 @@ +path = "../docs" diff --git a/uv.lock b/uv.lock index 6bd4dec..6fe753f 100644 --- a/uv.lock +++ b/uv.lock @@ -1679,6 +1679,7 @@ dependencies = [ { name = "sphinx-simplepdf" }, { name = "sphinx-test-reports" }, { name = "sphinxcontrib-plantuml" }, + { name = "ubt-runtime" }, { name = "ubt-sphinx" }, ] @@ -1694,6 +1695,8 @@ requires-dist = [ { name = "sphinx-test-reports", specifier = ">=1.3.2" }, { name = "sphinxcontrib-plantuml", specifier = ">=0.30" }, { name = "ubt-sphinx", specifier = "==0.7.1" }, + { name = "ubt-runtime", specifier = "==0.6.0" }, + ] [[package]]