DOCS: added Apollo 3.5 technical tutorial, software architecture, and dual IPC how to

Author: natashadsouza

README.md

@@ -182,7 +182,7 @@ Apollo 3.0's main focus is to provide a platform for developers to build upon in
     * Monitor
     * Additional drivers to support Hardware
 
-[**Apollo 3.5:**](docs/quickstart/apollo_updated_quick_start.md)
+[**Apollo 3.5:**](docs/quickstart/apollo_3_5_quick_start.md)
 
 Apollo 3.5 is capable of navigating through complex driving scenarios such as residential and downtown areas. The car now has 360-degree visibility, along with upgraded perception algorithms to handle the changing conditions of urban roads, making the car more secure and aware. Scenario-based planning can navigate through complex scenarios including unprotected turns and narrow streets often found in residential areas and roads with stop signs. 
 
@@ -244,7 +244,7 @@ If at this point, you do not have a Hardware setup, please go to [Without Hardwa
 
 * [Apollo 3.0 QuickStart Guide](docs/quickstart/apollo_3_0_quick_start.md)
 
-* [Apollo 3.5 QuickStart Guide](docs/quickstart/apollo_updated_quick_start.md)
+* [Apollo 3.5 QuickStart Guide](docs/quickstart/apollo_3_5_quick_start.md)
 
 
 ### Without Hardware:

docs/howto/README.md

@@ -43,6 +43,7 @@
 - [How to Run MSF Localization Module On Your Local Computer](how_to_run_MSF_localization_module_on_your_local_computer.md)
 - [How to train Prediction's MLP model](how_to_train_prediction_mlp_model.md)
 - [How to use the navigation mode of Apollo 2.5](how_to_use_apollo_2.5_navigation_mode.md)
+- [How to setup Dual IPCs for Apollo 3.5](how_to_setup_dual_ipc.md)
 
 ### Chinese versions
 

docs/howto/how_to_setup_dual_ipc.md

@@ -0,0 +1,168 @@
+# How to set up Apollo 3.5's software on Dual-IPCs 
+
+The modules of Apollo 3.5 are separately launched from two industrial PCs. This guide introduces the hardware/software setup on two parallel IPCs.
+
+## Software
+
+  - nVidia GTX 1080 Driver
+  - Apollo 3.5
+  - Apollo Kernel RT (based upon linux kernel 4.4.32)
+  - Linux precision time protocol 
+ 
+## Runtime Framework
+  - CyberRT
+
+## Installation
+
+There are two steps in the installation process:
+ - Clone and install linux PTP code on both of IPCs
+ - Clone Apollo 3.5 Github code on both of IPCs
+
+### Clone and install linux PTP
+  Install PTP utility and synchorize the system time on both of IPCs.
+  
+  ```sh
+    git clone https://github.com/richardcochran/linuxptp.git
+    cd linuxptp
+    make
+ 
+    # on IPC1:
+    sudo ./ptp4l -i eth0 -m &
+ 
+    # on IPC2:
+    sudo ./ptp4l -i eth0 -m -s &
+    sudo ./phc2sys -a -r &
+   ```
+ 
+### Clone Apollo 3.5
+  Install Apollo 3.5 on local ubuntu machine
+  ```sh
+    git clone https://github.com/ApolloAuto/apollo.git
+  ```
+
+  ### Build Docker environment
+  Refer to the [How to build and release docker](https://github.com/ApolloAuto/apollo/blob/master/docs/howto/how_to_build_and_release.md) guide
+
+  ### Run CyberRT on both of IPCs
+  1. Change directory to apollo
+  ```sh
+     cd apollo
+  ```
+  2. Start docker environment
+  ```sh
+     bash docker/scripts/dev_start.sh
+  ```
+  3. Enter docker environment
+  ```sh
+     bash docker/scripts/dev_into.sh
+  ```
+  4. Build Apollo in the Container:
+  ```sh
+     bash apollo.sh build_opt_gpu
+  ```
+  5. Start CyberRT and Dreamview:
+  ```sh
+     bash scripts/bootstrap.sh
+  ```
+
+  6. Open Chrome and go to localhost:8888 to access Apollo Dreamview:
+
+      - on IPC1 
+  
+
+ 
+        The header has 3 drop-downs, mode selector, vehicle selector and map selector. 
+
+        ![IPC1 Task](images/IPC1_dv.png)
+
+
+        Select mode, for example "ipc1 Mkz Standard Debug" 
+
+        ![IPC1 mode](images/IPC1_mode.png) 
+
+
+
+        Select vehicle, for example "Mkz Example"
+
+        ![IPC1 car](images/IPC1_car.png)
+
+
+
+        Select map, for example "Sunnyvale Big Loop"  
+
+        ![IPC1 map](images/IPC1_map.png) 
+
+
+
+        All the tasks that you could perform in DreamView, in general, setup button turns on all the modules. 
+
+        ![IPC1 setup](images/IPC1_setup.png)
+
+  
+        All the hardware components should be connected to IPC1 and the modules, localization, perception, routing, recorder, traffic light and transform, are allocated on IPC1 also.
+
+        Module Control on sidebar panel is used to check the modules on IPC1   
+
+        ![IPC1 check](images/IPC1_check.png) 
+
+        In order to open dreamview on IPC2, user must stop it on IPC1 by using the below command:
+        ```sh
+          # Stop dreamview on IPC1
+          bash scripts/bootstrap.sh stop
+        ```
+  
+      - on IPC2 
+
+        Start dreamview on IPC2 by using the below command:
+
+        ```sh
+          # Start dremview on IPC2
+          bash scripts/bootstrap.sh
+        ```
+
+        Select mode, vehicle and map on dreamview as the same operations on IPC1
+        ![IPC2 Task](images/IPC2_setup.png)
+
+
+        The modules - planning, prediction and control are assigned on IPC2.
+
+        Module Control on sidebar panel is used to check the modules on IPC2   
+
+        ![IPC2 modules](images/IPC2_check.png) 
+
+        
+        [See Dreamview user's guide](https://github.com/ApolloAuto/apollo/blob/master/docs/specs/dreamview_usage_table.md)
+
+7. How to start/stop Dreamview:
+
+  The current version of Dreamview shouldn't run on the different IPCs simultaneously, so the user must perform it alternatively on IPC1 or IPC2. 
+ 
+  The code below can be used to stop Dreamview on IPC2 and start it on IPC1.
+ 
+  ```sh
+     # Stop Dreamview on IPC2
+     bash scripts/bootstrap.sh stop
+
+     # Start Dreamview on IPC1
+     bash scripts/bootstrap.sh
+  ```
+ 
+  8. Cyber monitor
+
+      Cyber monitor is CyberRT's tool used to check the status of all of the modules on local and remote machines. The User may observe the activity status of all the hardware and software components and ensure that they are working correctly.   
+ 
+## Future work (To Do)
+  - Multiple Dreamviews may run simultaneously
+  - Fix a bug that modules are still greyed-out after clicking the setup button. Users may check each modules' status by using the command
+  ```sh
+     ps aux | grep mainboard
+  ```
+ 
+
+# License
+
+  [Apache license](https://github.com/natashadsouza/apollo/blob/master/LICENSE)
+
+
+
+

docs/howto/images/IPC1_car.png

@@ -2,7 +2,7 @@
 
 ## Apollo 3.5
 
-- [Apollo 3.5 quick start](apollo_master_quick_start.md)
+- [Apollo 3.5 quick start](apollo_3_5_quick_start.md)
 - [Apollo 3.5 hardware system installation guide](apollo_3_5_hardware_system_installation_guide.md)
 
 ## Apollo 3.0

docs/howto/images/IPC1_check.png

@@ -0,0 +1,119 @@
+# Apollo 3.5 Software Architecture
+
+Core software modules running on the Apollo 3.5 powered autonomous vehicle include:
+
+- **Perception** — The perception module identifies the world surrounding the autonomous vehicle. There are two important submodules inside perception: obstacle detection and traffic light detection.
+- **Prediction** — The prediction module anticipates the future motion trajectories of the perceived obstacles.
+- **Routing** — The routing module tells the autonomous vehicle how to reach its destination via a series of lanes or roads.
+- **Planning** — The planning module plans the spatio-temporal trajectory for the autonomous vehicle to take.
+- **Control** — The control module executes the planned spatio-temporal trajectory by generating control commands such as throttle, brake, and steering.
+- **CanBus** — The CanBus is the interface that passes control commands to the vehicle hardware. It also passes chassis information to the software system.
+- **HD-Map** — This module is similar to a library. Instead of publishing and subscribing messages, it frequently functions as query engine support to provide ad-hoc structured information regarding the roads.
+- **Localization** — The localization module leverages various information sources such as GPS, LiDAR and IMU to estimate where the autonomous vehicle is located.
+- **HMI** - Human Machine Interface or DreamView in Apollo is a module for viewing the status of the vehicle, testing other modules and controlling the functioning of the vehicle in real-time.
+- **Monitor** - The surveillance system of all the modules in the vehicle including hardware.
+- **Guardian** - A new safety module that performs the function of an Action Center and intervenes should Monitor detect a failure.
+
+
+```
+Note: Detailed information on each of these modules is included below.
+```
+
+The interactions of these modules are illustrated in the picture below.
+
+![img](images/Apollo_3.0_SW.png)
+
+Every module is running as a separate CarOS-based ROS node. Each module node publishes and subscribes certain topics. The subscribed topics serve as data input while the published topics serve as data output. The detailed interactions are described in the following sections.
+
+## Perception
+
+Apollo Perception 3.5 has following new features:
+
+ * **Support for VLS-128 Line LiDAR**
+ * **Obstacle detection though multiple cameras**
+ * **Advanced traffic light detection**
+ * **Configurable sensor fusion**
+
+The perception module incorporates the capability of using 5 cameras (2 front, 2 on either side and 1 rear) and 2 radars (front and rear) along with 3 16-line LiDARs (2 rear and 1 front) and 1 128-line LiDAR to recognize obstacles and fuse their individual tracks to obtain a final track list. The obstacle sub-module detects, classifies and tracks obstacles. This sub-module also predicts obstacle motion and position information (e.g., heading and velocity). For lane line, we construct lane instances by postprocessing lane parsing pixels and calculate the lane relative location to the ego-vehicle (L0, L1, R0, R1, etc.).
+
+## Prediction
+
+The prediction module estimates the future motion trajectories for all the perceived obstacles. The output prediction message wraps the perception information. Prediction subscribes to localization, planning and perception obstacle messages as shown below.
+
+![img](images/pred.png)
+
+When a localization update is received, the prediction module updates its internal status. The actual prediction is triggered when perception sends out its perception obstacle message.
+
+## Localization
+
+The localization module aggregates various data to locate the autonomous vehicle. There are two types of localization modes: OnTimer and Multiple SensorFusion.
+
+The first localization method is RTK-based, with a timer-based callback function `OnTimer`, as shown below.
+
+![img](images/localization1.png)
+
+The other localization method is the Multiple Sensor Fusion (MSF) method, where a bunch of event-triggered callback functions are registered, as shown  below.
+
+![img](images/localization2.png)
+
+## Routing
+
+The routing module needs to know the routing start point and routing end point, to compute the passage lanes and roads. Usually the routing start point is the autonomous vehicle location. The `RoutingResponse` is computed and published as shown below.
+
+![img](images/routing1.png)
+
+## Planning
+
+Apollo 3.5 uses several information sources to plan a safe and collision free trajectory, so the planning module interacts with almost every other module. As Apollo matures and takes on different road conditions and driving use cases, planning has evolved to a more modular, scenario specific and wholistic approach. In this approach, each driving use case is treated as a different driving scenario. This is useful because an issue now reported in a particular scenario can be fixed without affecting the working of other scenarios as opposed to the previous versions, wherein an issue fix affected other driving use cases as they were all treated as a single driving scenario.
+
+Initially, the planning module takes the prediction output. Because the prediction output wraps the original perceived obstacle, the planning module subscribes to the traffic light detection output rather than the perception obstacles output.
+
+Then, the planning module takes the routing output. Under certain scenarios, the planning module might also trigger a new routing computation by sending a routing request if the current route cannot be faithfully followed.
+
+Finally, the planning module needs to know the location (Localization: where I am) as well as the current autonomous vehicle information (Chassis: what is my status).  
+
+![img](images/planning1.png)
+
+## Control
+
+The Control takes the planned trajectory as input, and generates the control command to pass to CanBus.  It has five main data interfaces: OnPad, OnMonitor, OnChassis, OnPlanning and OnLocalization.
+
+![img](images/control1.png)
+
+The `OnPad` and `OnMonitor` are routine interactions with the PAD-based human interface and simulations. 
+
+## CanBus
+
+The CanBus has two data interfaces as shown below.
+
+![img](images/canbus1.png)
+
+The first one is the `OnControlCommand` which is an event-based publisher with a callback function, which is triggered when the CanBus module receives control commands and the second one is `OnGuardianCommand`.
+
+## HMI
+
+ Human Machine Interface or DreamView in Apollo is a web application that:
+    -	visualizes the current output of relevant autonomous driving modules, e.g. planning trajectory, car localization, chassis status, etc.
+    -	provides human-machine interface for user to view hardware status, turn on/off of modules, and start the autonomous driving car.
+    -	provides debugging tools, such as PnC Monitor to efficiently track module issues.
+
+## Monitor
+
+The surveillance system of all the modules in the vehicle including hardware. Monitor receives Data from different modules and passes them on to HMI for the driver to view and ensure that all the modules are working without any issue. In the event of a module or hardware failure, monitor sends an alert to Guardian (new Action Center Module) which then decides on which action needs to be taken to prevent a crash.
+
+## Guardian
+
+This new module is basically an action center that takes a decision based on the data that is sent by Monitor. There are 2 main functions of Guardian:
+- All modules working fine - Guardian allows the flow of control to work normally. Control signals are sent to CANBus as if Guardian were not present.
+- Module crash is detected by Monitor - if there is a failure detected by Monitor, Guardian will prevent Control signals from reaching CANBus and bring the car to a stop. There are 3 ways in which Guardian decides how to stop the car, and to do so, Guardian turns to the final Gatekeeper, Ultrasonic sensors,
+    - If the Ultrasonic sensor is running fine without detecting an obstacle, Guardian will bring the car to a slow stop 
+    - If the sensor is not responding, Guardian applies a hard brake to bring the car to an immediate stop.
+    - This is a special case, If the HMI informs the driver of an impending crash and the driver does not intervene for 10 seconds, Guardian applies a hard brake to bring the car to an immediate stop.
+
+```
+Note: 
+1. In either case above, Guardian will always stop the car should Monitor detect a failure in any module or hardware.
+2. Monitor and Guardian are decoupled to ensure that there is not a single point of failure and also that with a module approach, the action center can be modified to include additional actions without affecting the functioning of the surveillance system as Monitor also communicates with HMI.
+
+```
+

docs/howto/images/IPC1_dv.png

@@ -5,4 +5,5 @@ Refer these documents as a guide to all other relevant documents for the version
 - [Apollo 3.0](apollo_3.0_technical_tutorial.md)
 - [Apollo 3.0 cn](apollo_3.0_technical_tutorial_cn.md)
 - [Apollo 2.5](apollo_2.5_technical_tutorial.md)
-- [Navigation mode cn](navigation_mode_tutorial_cn.md)
+- [Navigation mode cn](navigation_mode_tutorial_cn.md)
+- [Best Coding Practtice](best_coding_practice.md)