Software Requirements Specification (SRS) Spinning Dragon Cruise Control Authors: Nathaniel Henry, Forrest Yockey, James Solomon, Peter Chen, Brian Duncan Customer: William Milam Instructor: Dr. Betty H.C. Cheng 1 Introduction This software requirements specification (SRS) document covers a brief introduction consisting of this document's purpose, scope, the definitions, acronyms, and abbreviations of the terms used in this document, and the overall organization of this document. The next section gives the overall description of our system. This overall description includes a product perspective, product function, user characteristics, constraints, assumptions and dependencies, and apportioning of requirements. After that we provide the specific and modeling requirements, respectively. In prototype section is containing information about our system's prototype. This section includes how to run the prototype and some sample scenarios. The last two sections of this document contain references and our point of contact. 1.1 Purpose The purpose of this SRS is to describe the details of the Spinning Dragon Cruise Control (SDCC) system and all subsystems. Moreover, this document explains the purpose of each subsystem, the features of said subsystems, and the interactions between subsystems and external inputs. This document's intended audience includes the developers of the SDCC system, as well as the stakeholders and interested parties in such a system 1.2 Scope The Spinning Dragon Cooperative Adaptive Cruise Control system is an automotive electronic control system designed to assist the driver in maintaining control over a vehicle in a variety of conditions and situations. More specifically, this system provides automated control over the vehicle by attempting to maintain constant vehicle speed based on input from the driver and communication with other vehicles. This software is intended to partially automate vehicle control while allowing the driver to override the system whenever they choose to do so. This system is designed to provide convenience to the driver and help improve traffic flow while maintaining safe control over the motion of the vehicle. 1.3 Definitions, Acronyms, and Abbreviations This section of the SRS contains definitions, acronyms, and abbreviations for the terminology used to describe our system throughout this document. Term Definition CACC Cooperative Adaptive Cruise Control – the system described in this document used to maintain constant vehicle speed with respect to input from the driver and communication with other vehicles. Following Distance The distance between the driver’s vehicle and the vehicle just in front of it. Target Vehicle A vehicle that the CACC system detects in its forward path. ACC Adaptive Cruise Control – a trimmed down version of the CACC represented here. ACC is a system that includes the bare essentials necessary to maintain a following distance behind a target vehicle. CAN Bus Controller-Area Network bus- the physical connection that allows for subsystems of the CACC system to communicate. All messages sent within the car are sent through the CAN Bus. Messages are sent as codes to the whole car not to a particular destination CC Cruise Control – the standard system present in most vehicles to maintain a constant speed on the road. Communication Occurs between two automobiles with CACC over a wireless link. It is used to distribute information among vehicles and communicate with infrastructure. Driver Person who is operating the vehicle Environmental Factors Unpredictable, external conditions (such as slippery roads or rain) that may affect any of the subsystems that makes up the CACC. Platoon A grouping of vehicles that are linked through their enabled CACC systems, attempting to streamline transportation. SRS Software Requirements Specification – this document that fully explains all aspects of the CACC. Subsystem A subsystem is a grouping of sensors or actuators designed for a specific task. The CACC is made up of several interconnected subsystems. Vehicle The vehicle described is a standard automobile with CACC. GPS Global Positioning System – A navigation satellite system that can provide the vehicle’s speed and location. Object Any entity on the road. Can consist of other vehicles, people, animals or other inanimate entities. Radio Communication A subsystem that communicates with target vehicles and trailing vehicles. Radar Sensing A subsystem that detects, identifies, and tracks target vehicles. Camera Sensing A subsystem that visually identifies target vehicles and estimates distance and relative speed. Radio Transponder A subsystem that gives vehicle id information to a requesting trailing vehicle. Vehicle Controller A subsystem that coordinates all other CACC subsystems and maintains vehicle state and operating environment information. Brake by Wire Regulates vehicle speed by applying brakes when commanded. Electronic Throttle Control Regulates vehicle speed by adding and removing power. Vehicle ID The unique identifier number of a vehicle. Status Message The state that the vehicle is in. DSRC Dedicated short-range communications are wireless communication channels specifically designed for automotive use and a corresponding set of protocols and standards. 1.4 Organization The second section of this document, the Overall Description, gives an overview of how the product works. It describes the major functions that the software performs, the intended users, a list of constraints, and assumptions regarding the system. The third part of this document, the Specific Requirements, is an enumerated list of the requirements that the system fulfills. The fourth section of this document, the Modeling Requirements section, explains how the software is designed to meet requirements. In this section diagrams and their associated explanations are used to visualize and specify how the software functions. The fifth part of this document, the Prototype, gives an overview on how to access and run the prototype and includes sample scenarios of the system. The sixth section of this document, the Reference, gives a list of all documents referenced in the Software Requirements Specification. The seventh and final section of this document, the Point of Contact section, gives information on how to obtain more information on this document and product. 2 Overall Description The SDCC system is one of the many electronic systems available to modern vehicles and a part of an increasing number of production vehicles. It is software on a central vehicle controller that builds on the standard cruise control system features into an autonomous system. Where a standard cruise control system allows for a driver to set a speed, a CACC system may use sensors and other subsystems to automatically alter the speed and give information and warnings to the driver. SDCC monitors radar, camera, GPS, and radio systems to autonomously control the vehicle via electronic braking, throttle, and steering systems 2.1 Product Perspective SDCC is a system that gives autonomous traffic adaption based on communication with other vehicles. Traditional cruise control systems allow the driver to set a speed for the vehicle and to increase or decrease the speed. ACC allows the vehicle to automatically increase or decrease speed based on traffic around the vehicle. In CACC, the camera, GPS, radio, and radar system interface with the vehicle controller via the vehicle’s CAN Bus. The vehicle controller handles all messages sent from these systems. Using the GPS, radar, and camera subsystems, the vehicle controller monitors the vehicle’s surroundings and set the cruise speed appropriately by electronically controlling the throttle and brakes to increase and decrease speed. To extend the features of the adaptive cruise control system, this system also communicates with other vehicles using radio communication and negotiates with those vehicles to form platoons. The platoon increases the overall system’s effectiveness, as each leading vehicle shares information, such as vehicle speed and status, with vehicles behind them. The user interface has the following constraints: - Turn system on and turn system off buttons - Increase and Decrease, set, and resume cruise speed buttons - Notification of nearest vehicle (or target vehicle in platoon) gap distance - Warnings (target vehicle slows down) and errors are shown on the user’s display console. - Crash imminent warning system: Users are notified on the dashboard with Red LEDs and a beeping alarm The hardware systems have the following interface constraints: - The system initializes with a fixed amount of memory and allows for only a fixed number of possible target vehicles. - Radar is the primary target acquisition device, camera is secondary. - The radar maintains vision of all objects within in a direct line of sight within 150ft on a 180 degree arc in front of the vehicle. - All subsystems must not have any errors for CACC mode to be engaged. - Once the system is turned on, it is always running unless it is canceled by the driver or an error occurs. The software interface has the following constraints: - 2.2 If any object is determined to be trackable by one of the subsystems, the vehicle controller must add that object in the system. Events, actions, and warnings are conveyed to the vehicle controller through the CAN Bus. The vehicle controller must then make decisions on those messages The vehicle controller must manage situations of conflicting messages, for example, when simultaneously a “user increase cruise speed” message and “target vehicle slowing” message is sent. Product Functions This section of this SRS specifies all major functions of the SDCC system with respect to the customer supplied specifications. - System On: check if all subsystems are working, set cruise to current vehicle speed, begin adaptive cruise systems, and begin communication cruise systems. - System Off: Message communicating vehicles, shutdown cruise systems other than radio communication. - Set Speed: Increase set cruise speed, notify communicating vehicles. - Set Gap Distance: Update subsystems so that target vehicle is followed at desired distance. - Detect Vehicle: The Radar system gives the location metrics of a detected target to the vehicle controller once every second. - Update Position: The GPS system continuously updates the vehicle controller of the vehicle’s exact position. This information is used to monitor upcoming traffic conditions and can be shared with other vehicles. - Identify Target: The Camera system continuously identifies the target vehicle for following. - Estimate Distance: The Radar system calculates the distance of the target vehicle for following. - Estimate Relative Speed: The Radar system estimates the relative speed of target vehicle for following in adaptive situations. - Speed Control: The Electronic Throttle Control applies throttle to maintain and increase speed based on the vehicle controller’s set speed and target vehicles speed and gap distance. The Electronic Throttle Control deactivates when in a state of deceleration. - Brake: The Brake by Wire system must apply brakes as required by the vehicle controller. - Send Message: The Radio system is responsible for updating surrounding CACC vehicles with Spinning Dragon vehicle’s ID, speed, location, and platooning status. - Receive Message: The Radio system is responsible for listening to surrounding CACC vehicle messages. On receive the radio system updates the vehicle controller with IDs, speeds, locations, and surrounding vehicles platooning status. 2.3 User Characteristics The user of the CACC system is expected to have a vehicle operator’s license and a basic knowledge of both the rules of the road and the operation of a standard car. The user is also expected to be capable of learning how to operate CACC systems. 2.4 Constraints The system uses static memory. There is no garbage collection. Memory for all objects is accounted for and they are removed from memory when no longer needed. SDCC must operate within safe following distance. When in adaptive mode, the system must always maintain at least a half-car length per 10 mph, or at minimum, 30 feet of following distance. Though the driver can pick their desired following distance, Spinning Dragon must update this based on traffic conditions. Adaptive Cruise Control requires the Camera and Radar systems to be functioning, while Cooperative Adaptive Cruise Control requires all systems to be working. In the event of imminent crash detection the (CACC) system turns off, a message is sent to the brake system to pressurize and be ready for full deployment, and the radio system sends out a warning message to all surrounding vehicles. Other than imminent crash, CACC does not ever disengage to a lower level (ACC or CC) without being engaged by the driver; if there is an error or an imminent crash is detected, the system shuts off. For a vehicle platoon to form, two vehicles must be going the same direction in the same lane, both vehicles must have a CACC system, both CACC systems must be turned on, the vehicles’ controllers must indicate that the vehicle is capable of supporting platooning, and the drivers must accept platooning. Additional vehicles can enter a platoon that is already formed by following the constraints above. The vehicles communicate with a DRSC 802.11p protocol that allows channel switching to maintain signal and error checking. 2.5 Assumptions and Dependencies It is assumed that a cruise control system is already implemented. It is also assumed that the vehicle driver is familiar with driving a basic cruise control system car. The user interaction with the Spinning Dragon CACC system is minimal: it is only required that the user be able to react to the messages by accepting them or selecting yes or no. 2.6 Apprortioning of Requirements There was some discussion provoked by other groups as to the consideration of environmental factors (such as rain or slippery roads) that would affect following distance or braking capabilities. These ideas were not present in the original project specifications and could be added later if necessary. The original project specifications also made mention of extra feature such as lane keeping and obstacle avoidance. These extra features have very little to do with the design of the CACC system, and the hardware and software required to implement these features are not present. These features may be added later. 3 Specific Requirements The specific requirements section of this SRS document yields a list of enumerated requirements specified by the customer. The SDCC system is designed according to these specified requirements, with an exception for those requirements related to the functions discussed in section 2.6. 1. There is no dynamic memory allocation in automobiles. There is no object oriented programming involved and no garbage collection. Instead it uses fixed memory and a set number of targets. Everything in memory is accounted for, allocated, and deallocated correctly. 2. Following Distance 2.1. Following distance is determined by the driver. 2.2. Following distance is between 30 and 150 ft. 2.3. Distance is based on ½ car length for every 10 mph. 3. Objects 3.1. Objects closer to the vehicle are higher priority. 3.2. GPS can help discern which objects are moving and which are stationary. 4. If any components of the CACC system are not functioning, then the system should not turn on. 5. Targets are acquired through the use of the sensors on the car. Sensors include: 5.1. Radar 5.2. Camera 5.3. GPS 6. Radar 6.1. Main form of target acquisition. 6.2. Radar is necessary for both CACC and ACC. 6.3. Radar is only capable of “seeing” the cars in front of it (no sensing around vehicles). 6.4. Radar has a range of 150 feet and 180 degree field of view in front of the vehicle. 7. Radio 7.1. Sends out a message once a second in every direction regardless of whether or not other vehicles are around. 7.2. The cars radio communicates by using DSRC in the 802.11 range. 7.3. A message contains the following 7.3.1. Vehicle ID 7.3.2. Speed 7.3.3. Direction 7.3.4. GPS location 7.3.5. Status message 7.3 A message is sent to all surrounding vehicles if a collision is imminent. 7.4 Radio transmission can be on even if CC is not on. 8. GPS system 8.1. Provides constant information on the location of the car. 8.2. Combines this information with geographic information (information about the locations of all buildings, vehicles, and terrain) to help eliminate stationary objects as targets. 9. Camera 9.1. Mounted on the front of the car as low as possible. 9.2. Camera captures still frames and discerns between vehicles and stationary objects. 10. Radar Transponder 10.1. Gives vehicle ID information to requesting trailing vehicles in order to establish a radio link between vehicles. 11. Platooning 11.1. Enabled when the following criteria are met. 11.1.1 2 vehicles going the same direction and approximately the same speed. 11.1.2 Both vehicles are in the same lane. 11.1.3 Driver agrees to enter platoon by accepting a platooning message via the user interface. If after 5 seconds there is no response, then do not enter the platoon. 11.2 Changing lanes disengage platooning 12 The CACC system should disengage under certain conditions including: 12.1 Manual breaking occurs 12.2 The cancel button is pressed 12.3 A failure of system component (notify driver) 12.4 Communication is lost (notify driver) 12.5 Changing gears 12.6 Traction is lost and car spins out 13 CACC, ACC, and CC systems are only active above 25 mph. If the vehicle is below 25 mph, the system will turn off. 14 If a collision is imminent, then notify the driver with flashing LED lights on the dashboard and beeping sounds. 4 Modeling Requirements The modeling requirements section of this SRS describes the bridge between the application and machine domain by utilizing use-case, class, state, and sequence diagrams. These diagrams also provide a more functional view of the SDCC system. Figure 1, case diagram for Cruise Control system Use Case: System On Actors: Driver Description: The driver presses the “On” button to turn the system on. The system initializes and checks that all subsystems are functioning. Type: Primary Includes: N/A Extends: N/A Cross-refs: 4 Dependent Use Cases: N/A Use Case: System Off Actors: Driver Description: The driver presses the “Off” button to turn the system off. The system and all subsystems proceed to shut down. The system can also turn off when a crash is imminent or when an error occurs with the system. Type: Primary Includes: N/A Extends: N/A Cross-refs: 1, 12, 14 Dependent Use Cases: N/A Use Case: Speed Control Actors: Driver Description: The driver can change the speed of the vehicle by pressing the “+“ or “-“ button. The throttle control or brake by wire then increases or decreases the speed of the vehicle as necessary Type: Primary Includes: N/A Extends: N/A Cross-refs: 2, Dependent Use Cases: N/A Use Case: Set Speed Actors: Driver Description: The driver sets the speed of the vehicle by pressing the “Set” button. This system then maintains a constant speed. Type: Primary Includes: N/A Extends: N/A Cross-refs: 13 Dependent Use Cases: Coordinate Vehicle Systems Use Case: Set Gap Distance Actors: Driver Description: The driver enters a desired gap distance based on the number of car lengths between each vehicle. Type: Primary Includes: N/A Extends: N/A Cross-refs: 2 Dependent Use Cases: N/A Use Case: Send Message Actors: Driver, Target Vehicle Description: The system is able to send messages to other vehicles with CACC systems equipped. Type: Primary Includes: N/A Extends: N/A Cross-refs: 7, 11 Dependent Use Cases: N/A Use Case: Receive Message Actors: Driver, Target Vehicle Description: The system can receive messages from other vehicles with a CACC system equipped. The system can also display messages to the driver. Type: Primary Includes: N/A Extends: N/A Cross-refs: 7, 11 Dependent Use Cases: N/A Use Case: Enter Platoon Actors: Driver, Target Vehicle Description: The driver and a target vehicle are able to enter a platoon if a platooning message is accepted by the driver. Type: Primary Includes: N/A Extends: N/A Cross-refs: 11 Dependent Use Cases: N/A In the following diagram, the class diagram is shown for the SDCC system. In each box, the name of the class is in bold at the top. Below the class name, the attributes (variables) of each class is listed. In the bottom portion of each box are the operations that each class has. Each line between the classes shows the corresponding associations between the classes. Figure 2, class diagram for cruise control system Vehicle Controller Main controller of CACC Relationships Vehicle Controller connects to all sensors (Camera Sensing, GPS System, Radar Sensing, and Radio) and detects the vehicle information. It is also linked to the Brake By Wire and Electronic Throttle Control to control the speed, and it sends/receives messages through radio system. Attributes vehicle ID Vehicle's ID speed Vehicle’s current speed direction Vehicle’s direction GPS location Location of the vehicle status Vehicle’s status gap distance The minimum Gap distance allowed Operations: on() Ability to turn on the CACC off() Ability to turn off the CACC set speed() Ability to set the speed set gap distance() Ability to set the gap distance UML Extensions N/A Car Contains information of the vehicle Relationships It connects to all the sensors (Camera Sensing, GPS System, Radar Sensing, and Radio) and the Vehicle Controller when they need data of the vehicle. And it also supports the Radio Communication. Operations: detect speed() Detect the current vehicle’s speed update() Update the current vehicle’s information get information() Get the current vehicle’s information connect radio() Connect to target vehicle’s radio UML Extensions N/A Radar Sensing Detects and IDs other vehicles Relationships It detects others vehicles and takes IDs from them and send the data back to Vehicle Controller, and GPS System to help separate between the vehicles and objects. Operations: detect vehicle() Detect vehicles around your vehicle UML Extensions N/A Radio Communication Communicate with other vehicles and infrastructures Relationships Vehicle Controller controls this system and sends/receives messages through this. It needs Radar Transponder’s support to connect to other vehicles. Operations: send message() Send message to the target vehicle receive message() Receive message from other vehicles UML Extensions N/A Electronic Throttle Control Speed control by adding or removing power Relationships Vehicle Controller decides if it is going power up or down Operations: speed control() Adjust the current speed UML Extensions N/A Brake By Wire Regulate speed by braking Relationships Vehicle Controller decides if it is going to brake Operations: brake() Brake the vehicle UML Extensions N/A Radar Transponder Establish radio links between vehicles Relationships Vehicle Controller asks it to get a detected vehicle’s information from Radar Sensing and the helps Radio Communication to connect with the target vehicle Operations: establish radio link() Establish radio link to the target vehicle UML Extensions N/A GPS System Maintains vehicles information Relationships Vehicles Controller uses GPS to update the current position, and GPS also aids Radar Sensing in differentiating between vehicles and fixed objects Operations: update position() Update the current vehicle’s position eliminate object() Eliminate objects from the vehicles UML Extensions N/A Camera Sensing Identify target vehicle and estimate distance and speed Relationships Vehicle Controller calls the Camera Sensing to identifies the target vehicle and other information Operations: identify target() Identify the target estimate distance() Estimate the distance from other vehicle estimate relative speed Estimate relative speed to other vehicles UML Extensions N/A In the Figure 3, state diagram, CACC is initially in the off state. Radio is separate from the CACC, which can be run independently. When you turn on the CACC, you can set your own speed x and gap distance y. From start the CACC goes to the update state. When the current speed is different from the speed x, CACC starts the Throttle control to adjust the vehicle speed to x. When CACC started, the sensors also automatically activate. There are three different sensors: camera, GPS, and radar. Radar doesn’t only detect the vehicle but can also support the radio to connect to other vehicles. Then radio can communicate and send messages to other vehicles. When one of the sensors stops working, the CACC shuts down and gives the control to the driver and issues a warning. And if the sensors detect the object or vehicle get closer in y distance, the CACC breaks to decrease the speed. If the crash is imminent, then the CACC locks the seat belt and gives a warning to driver, and the CACC is then shut down. There are some other cases that turn off the CACC. Driver can manually turn off the CACC, break the vehicle, and change lanes. If the failure of the CACC system occurs or the vehicle loses control, then the CACC shuts down. Figure 3, state diagram for cruise control system In the following sequence diagrams, figures 4.1, 4.2, and 4.2, the sequence begins with the Vehicle Controller (CACC) turning on, and the CACC then calls Radar Sensing to detect vehicles around your vehicle. To separate between vehicles and objects, radar calls the GPS System (GPS) to eliminate objects. After that, radar gets the target information by connecting to the Car (target). Then target then sends back the required information to the CACC. At the same time, the CACC keeps updating the current position by calling GPS, and GPS returns the vehicle’s current position to the CACC. CACC also keeps identifying anything in front of driver’s vehicle by calling Camera Sensing (camera). Camera returns any object or vehicle in front of the driver to CACC. All the status messages mentioned before are updated to Car (mycar). And the information retrieved by radar can be used to help CACC to call the Radar Transponder (transponder) and transponder can have the radio connect with the target. After the connection is ready, CACC can send messages to the target through Radio Communication (radio). Also the CACC always detects its own speed by calling mycar. If the speed is too fast, then CACC calls Brake By Wire (brake) to slow down the vehicle’s speed. The driver can also set the speed of vehicle by calling CACC, and CACC then calls Electronic Throttle Control (throttle) to adjust the speed. Figure 4.1, sequence diagram for sensors delectation Figure 4.2, sequence diagram for communication Figure 4.3, sequence diagram for speed control 5. Prototype Our prototype recreates the dashboard of a car. Our prototype simulates the buttons available for turning on and off the cruise control as well as adjusting the speed and following distance; also the accelerator and breaks are available. It also represents the road with our car and cars in the immediate vicinity. The user is able to adjust speed and following distance, press the accelerator and break, activate platooning and respond to failures. The user is able to load some scenarios such as following a car, platooning with a car and an imminent collision. 5.1 How to Run Prototype Our prototype is implemented in Java. Access to Java is necessary to run our prototype. Any browser with Java installed is able to run our prototype. The URL of our prototype is 5.2 Sample Scenarios Figure 5, prototype sample diagram The diagram above illustrates a sample scenario that the prototype produces. In this scenario, the driver’s vehicle is in a platoon with the vehicle just ahead of it. The target vehicle unexpectedly decelerates quickly and the driver’s vehicle does not have enough time to react. The CACC senses that a crash is imminent. The CACC then turns itself off and warns the driver through a panel of flashing LED lights on the dashboard and by text on the driver’s LED display. 6 [1] [2] [3] References de Bruin, D. Kroon, J. van Klaveren, R. Nelisse, et al. “Design and Test of a Cooperative Adaptive Cruise Control System”. Intelligent Vehicles Symposium, 2004 IEEE. 08 October, 2004. Duncan, Brian, et al. “MSU Software Engineering Spinning Dragon Cruise Control”. Department of Computer Science Michigan State University. October 2011. < http://www.cse.msu.edu/~435cruise2/index.html >. Laumonier, Julien, Charles Desjardins and Brahim Chaib-draa. “Cooperative Adaptive Cruise Control: a Reinforcement Learning Approach“. DAMAS Laboratory, Department of Computer Science and Software Engineering, Laval University, Canada. 2006. [4] [5] Milam, William, Betty H.C. Cheng. “Cooperative Adaptive Cruise Control”. Department of Computer Science Michigan State University. October 2011. Nowakowski, Christopher, Steven E. Shladover, Delphine Cody, et al. “Cooperative Adaptive Cruise Control: Testing Driver’s Choices of Following Distances”. Institute of Transportation Studies University of California, Berkeley. November 2010. 7 Point of Contact For further information regarding this document and project, please contact Prof. Betty H.C. Cheng at Michigan State University (chengb at cse.msu.edu). All materials in this document have been sanitized for proprietary data. The students and the instructor gratefully acknowledge the participation of our industrial collaborators.