# RFE Design Document

**Version :** 1.0.3
## 1) Authors

* Saurabh Gawande | [e-mail]
* Baris Süslü | [e-mail]

## 2) Team and Organisation

Team Dolphins (RFE & USS) from [96250 Platform SW](https://c1.confluence.cm.volvocars.biz/display/ARTADADAS/Team+Dolphins) of the ART AD & ADAS Platform

## 3) Abbreviations

Abb | Expansion
----|------
VCC | Volvo Cars Corp.
AD | Autonomous Drive
ADAS | Advanced Driver Assistance Systems
RFE | Road Friction Estimation
HAL | Hardware Abstraction Layer
SRA | Slippery Road Alert

## 4) General information about the document

Since we do not have a responsible software architect, this document v1.0 has been peer-reviewed by the following people:

Ashwin Kumar Ganesan | [e-mail]

Robert Fekete | [e-mail]

Liselott Lökholm | [e-mail]

## 5) Introduction

Road friction is one of the most critical variables that affects vehicle motion control. Current system, Slippery Road Alert, warns drivers to provide safer drive. Our aim is to compliment SRA function with our new developed function (RFE) to have better friction estimation accuracy. RFE algorithm relies on machine learning model.

This document intends to give a description of the Road Friction Estimation (RFE) ML API component. This API component is developed by department 96250 Platform SW, which is part of ART AD & ADAS.

## 6) HAL and Device Proxy

RFE API Component will not be communicating with HAL and Device proxy directly. Required inputs will be given by road state service internally. Road state service will call those required properties from vehicle motion state service and power steering HAL.

## 7) Dependencies

There is no dependencies for the RFE API Component. It will be called by road state service to obtain road friction estimation.
### Outbound dependency modules
There is no outbound dependency.
### Inbound dependency modules
**Road state service:** The inputs specified in section 9.1 are provided as an argument to the RFE API Component by the Road State service which consequently published resulting friction prediction as a property. RFE API Component is not dependant on any cs-modules in the system.
## 8) Modules intended to integrate to HPA

### **8.1) ID: road-friction-estimation**

This cs module installs the following files:

|RFE API Components|Description|
| -------- |-------- |
| roadfrictionestimator.cpp |Function and variable definitions for road friction estimation algorithm|
|roadfrictionestimator.hpp| Function and variable declerations for road friction estimation algorithm|
|roadfrictionestimator_types.hpp| Type definitions under "roadfrictionestimator" namespace.|
|rfe_model_s.hpp|Machine learning model consists of many nested "if statements"|

RFE API Component implementation is handled by: Team Dolphins (Saurabh Gawande, Baris Suslu)

## 9) Road Friction Estimation API Component

This API component is developed by Team Dolphins RFE team and it is developed as API component in VCU HPA.

### 9.1) API Available

### Methods

* **EstimateFriction**
* **Description:**
Calculates the road friction by utilizing ML model.
* **Inputs:**
* **struct VehicleInputs**{ EstimatedSteeringRackForce, SteerAngleFront }
-- steering_wheel_angle (**type**: int32_t, **Public Attribute**: force)
-- rack_force (**type**: front.value, **Public Attribute**: front.nominal.value)
* **struct VelocityInputs**{ VelocityLongitudinal, AngularVelocity, WheelVelocityLeftFront, WheelVelocityRightFront, WheelVelocityLeftBack, WheelVelocityRightBack}
-- vel_long (**type**: float, **Public Attribute**: nominal.value)
-- yaw_rate (**type**: float, **Public Attribute**: yaw.value )
-- wheel_ang_vel_1 (**type**: float, **Public Attribute**: front_left.value )
-- wheel_ang_vel_2 (**type**: float, **Public Attribute**: front_right.value )
-- wheel_ang_vel_3 (**type**: float, **Public Attribute**: rear_left.value )
-- wheel_ang_vel_4 (**type**: float, **Public Attribute**: rear_right.value )

* **Outputs:**
- road_friction_ml (**type**: float, **Public Attribute**: nominal.value )

### Properties
* There are no properties available to be published by RFE API Component.
* The friction estimation from the RFE API Component will be published by the road-state service directly.

## 10) Architecture


RFE API Component is planned to be used by road state service which is utilized to publish metrics about the road. Road state service will call "EstimateFriction" method defined in RFE API Component. It will provide required inputs (mentioned in API Available section 9.1) to "EstimateFriction" method which calls RFE machine learning model (Random Forest Regressor). Any service that wants to have an access on road friction value will call it from road state service.


A random forest is a meta estimator that fits a various of classifying decision trees on various sub-samples of the dataset and uses averaging to improve the predictive accuracy and control over-fitting (scikit-learn). In our application, it is used to regress road friction value .

## 11) Data Forwarding & Unaddressed issues

There can be a potential CPU issue regarding our RFE ML model part of the RFE API Component. Current RFE ML model size ranges between 2MB and 11 MB and further investigation needs to be conducted on the impact of model size on performace.