# 18649 - Behavioral Requirements I

# System Objects and Message Dictionary

18649 <semester>
Group x - Student names and andrewIds

## Table of Contents

- Elevator Top-Level Requirements
- Building Description
- Notation

- Replication Notation
- Replication in Sequence Diagrams
- Replication in Behavioral Requirements

- Initialization
- System Elements

- The Car
- Physical State Sensors
- Smart Sensors
- Environment-only System State
- System Actuators
- Environment-only Actuators
- Control System Objects

- Network Message Dictionary

- Environment Object Messages
- Controller Messages
- Removed Messages

## Elevator High-Level Requirements

R-T1. All passengers shall eventually be delivered to their intended destination floor.
R-T2. Any unsafe condition shall cause an emergency stop.
R-T3. An emergency stop should never occur.
R-T4. Performance shall be optimized to the extent possible, where performance is defined by the formula:

- ( 4 * average_passenger_delivery_time) + maximum_passenger_delivery_time
- Performance is improved by reducing that value (short delivery times are better). Delivery time is counted from the time a passenger arrives at a floor to begin a trip and ends when that passenger exits the elevator car. (Note: this is an arbitrary formula for this project, but the general idea holds true for real elevators.)

R-T5. Passenger satisfaction shall be optimized to the extent possible, where satisfaction is defined by the formula:

- ( 4 * average_passenger_satisfaction) + minimum_passenger_satisfaction

Note: The full set of example requirements provided should result in an elevator with safe behavior that meets top-level requirements other than having poor optimization of performance. While it is obvious that the Dispatcher behavior can be optimized, there are also other, more subtle, behavioral optimizations possible as well.

## Building description

The Building the elevator is in has floors numbered from 1 .. MaxFloor. In this case, MaxFloor = 8
The setup of hallway entrances is as follows:

Floor Number | Hallway Description
8 | FH only
7 | FH and BH
6 | FH only
5 | FH only
4 | FH only
3 | FH only
2 | BH only
1 (lobby) | FH and BH

"FH" is a shorthand for front hallway, and "BH" is a shorthand for back hallway Floor #1, the lobby, is the lowest floor in the building.

## Notation

### Replication Notation

- f - floor, 1-8
- b - hallway, FRONT or BACK
- r - side, LEFT or RIGHT
- d - direction, UP or DOWN

"[...]" indicates an array of objects or values. There are 10 valid hallways, and so there are 17 separate and distinct HallCall[f, b, d] sensors -- 2 of them at each valid hallway, except for the top and bottom floors which only have 1 sensor per valid hallway.

"(...)" indicates a list of values associated with a sensor/actuator. Single-valued inputs/outputs can have the "(" and ")" omitted as a notational convenience.

The suffixes "_up", "_down", "_front", and "_back" may be used in lieu of a direction subscript, to make things more readable. e.g.:
HallCall_up[f, b] means HallCall[f, b, up]
HallCall_down[f, b] means HallCall[f, b, down]
HallCall_front[f, d] means HallCall[f, front, d]
HallCall_back[f, d] means HallCall[f, back, d]
HallCall_up_front[f] means HallCall[f, front, up]
and so on...

Similarly, subscripting may be eliminated in general if desired using an underscore notation. e.g.:
CarLantern_down means CarLantern[down]

Multi-attributed items may have a particular state referred to by concatenating elements, e.g.: Motor might have state FastUp or SlowDown. ("StopStop" can always be abbreviated by "Stop")

Single attributes of a multi-attribute item are referred to using "." notation. For example DesiredFloor.f refers to attribute "f" of "DesiredFloor".

If a letter instead of a value is used in a subscript, it is assumed that it can take any valid value. If the same letter is used in multiple clauses within a single requirement element, it is assumed that the letter takes the same value in all instances. For example, in the phrase:
"AtFloor[f, b] ... CarCall[f, b] ... HallCall[g, b, d]"
The Floor f and Hallway b for AtFloor and CarCall can be any valid floor and valid hallway, but would have to be the same floor and hallway. However, the floor for HallCall might or might not be the same floor as for AtFloor and CarCall since it is a different symbolic letter.

### Replication in Sequence Diagrams

Replication is a problem in UML Sequence Diagrams. Rather than introducing an attempt at formal notation (which gets very confusing quickly), we will resort to using comments when multiple instances of something are supposed to be coordinated (e.g., "wait for all doors to close" will be a text comment in Sequence Diagrams, but shall be represented rigorously in behavioral requirements).

### Replication in Behavioral Requirements

Because the controllers are written in a generic way, it's important to pay attention to the way the replication notation is used in the behavioral requirements. Here are some general guidelines:

- "set mDoorMotor[b,r] to CLOSE" - refers to the particular mDoorMotor output for hallway b, side r.
- "if any mDoorMotor[b,r] is set to CLOSE" - this statement would be considered true if any of the four door motor messages (front-left, front-right, back-left, back-right) were set to CLOSE.
- "if all mDoorMotor[b,r] are set to CLOSE" - considered true if all four door motors were set to CLOSE
- "if any mDoorReversal[b,*] is true" - use the star notation to denote replication in one dimension but not another. This statement would be considered true either the left or right door reversal on the b hallway of the car was true. This notation does not check the door reversals on the opposite hallway.

## Initialization

Because ultimately we will do this all in simulation, we're going to make your life easy by telling you the initial state of the system (the "initialization" state) such as putting the elevator car at the lobby floor with the doors closed. In a real elevator the controllers have to figure out the system state for themselves when power is applied.

## System Elements

This section describes the elements of the system that are already provided

### The Car

The notation "Car" refers to the elevator Car that travels in a hoistway. The movement of the Car itself is hidden within the environment model, so it can only be observed through sensors and controlled through actuators.

### Physical State Sensors

These objects are instantiate in the system but do not have a network interface. These objects must be read through the physical interface of a controller.

- CarCall[f, b](v): Car Call buttons. v = {True, False}.
- - One per Floor and Hallway [f, b] combination, all located in the CAR. No button object is instantiated for [f,b] combinations where there is no landing.
  - CarCall objects do not send network messages.
  - Set to False at initialization.
- HallCall[f, b, d](v): Hall Call buttons. v = {Pressed, Idle}.
  - One per Floor, Hallway, and Direction [f, b, d] combination, all located in the hallways. No button is instantiated for floors that have no landing. Also, the topmost floor does not have Up buttons; bottommost floor does not have Down buttons.
  - HallCall objects do not send network messages.
  - Set to False at initialization.
  DriveSpeed(s,d): main drive speed readout. s is speed s = {double 0 .. } in meters/sec d is direction d = {Up, Down, Stop}
  - One per Car.
  - Provides information about the current drive speed set by Drive(s,d) !! but this is the actual drive status rather than the status commanded by Drive(s,d). (Note that there will be a time delay between commanding the drive to change speed and the drive actually attaining that speed. This lets you know when the commanded speed is actually attained.)
  - Initialized to (0, Stop).

### Smart Sensors

These sensor values are available for use by the control system. The below-listed values will correspond to network messages in the implementation phase.
Note: If an object that sends a network message is not instantiated (such as an atFloor sensor at a [f,b] without a landing), then no network message with that CAN id is ever sent.

- AtFloor[f, b](v): Floor proximity sensor. v = {True, False}.
  - One per Floor and Hallway [f, b] combination.
  - Indicates True at a point where the Car is approximately level with floor f. If there is no landing at a particular hallway on a particular floor, then no sensor is instantiated for that landing, so no network messages will be sent. For example, there is a back landing but no front landing at the second floor, so an AtFloor[2,back] sensor will be instantiated, but an AtFloor[2,front] sensor will not be instantiated. It is assumed that the width of the Stop zone is such that the Drive has enough time to switch from going at Slow speed to Stop and still have the car level with the floor.
  - - Set to False at initialization, except the lobby switch is set to True at initialization.
    - AtFloor[f, b] shall be set True if and only if CarPosition is within 150 msec of travel time of floor position f at Slow speed in either direction and there is a hallway at [f, b].
    - Note: the AtFloor sensor will not be triggered if the car is going faster than Slow.

- CarLevelPosition(x): Car position sensor. x = {integer 0 .. } in millimeters
  - One per Car.
  - Reports approximate position of car in hoistway based on position sensors placed at 10 cm intervals in the hoistway. Gets updated each time the car passes one of these sensors.
  - Set to Lobby position at initialization.
- DoorClosed[b, r](v): Door Closed switches. v = {True, False}.
  - One per Door [b, r] for b = {Front, Back} and r = {Left, Right}.
  - Indicates True when the Door[b, r] is fully closed.
  - Set to True at initialization.
  - DoorClosed[b, r] shall be True if and only if DoorPosition[b, r] has a value less than 1.
- DoorOpened[b, r](v): Door Opened switches. v = {True, False}.
  - One per Door [b, r] for b = {Front, Back} and r = {Left, Right}.
  - Indicates True when the Door[b, r] is fully open.
  - Set to False at initialization.
  - DoorOpened[b, r] shall be True if and only if DoorPosition[b, r] has a value greater than 490.
- DoorReversal[b, r](v): Door Reversal sensors. v = {True, False}.
  - One per Door [b, r] for b = {Front, Back} and r = {Left, Right}.
  - Indicates True whenever the Door [b, r] senses an obstruction in the doorway.
  - Set to False at initialization.

- Level[d](v): Leveling sensors. v = {True, False}. These sensors allow for more accurate leveling of the car.

- One per direction, affixed to the car a fixed distance above and below the car.
- In addition to the sensors, there is a leveling vane at every floor. The leveling vane is a protrusion that is exactly centered on the floor position.
- The leveling sensors are beam sensors. When the car is level, one sensor is above the vane and the other is below. Since the vane does not obstruct either sensor, both read true. If the car is out of level, one or the other of the sensors will be blocked by the vane and read false.
- The width of the vane and position of the level sensors is configures so that when the atFloor[f,b] sensor becomes true (as the car approaches the floor), one of the leveling sensors will already be blocked. Thus, if any mAtFloor[f,b] is true and both leveling sensors are true, the car is level.
- When the car is at a floor and both sensors are true, the level error is less than or equal to 5mm.

- HoistwayLimit[d](v): Safety limit switches in the hoistway. v = {True, False}. One pair per Car, d = {Up, Down}.
  - A HoistwayLimit[d] switch activates when the car has over-run the hoistway limits (used as a trigger for emergency stopping). The d=Up switch is at top of hoistway; d=Down switch is at bottom of hoistway.
  - Set to False at initialization.
- CarWeight(x): Car weight sensor. x = {int 0 .. } in tenths of pounds (lbs)
  - One per Car.
  - Provides information about current total weight of passengers in the car in tenths of pounds (lbs). The car weight sensor shall not be affected by the acceleration/deceleration of the car. MaxCarCapacity is the maximum allowable weight for safe travel in car.
  - CarWeight is set to 0 at initialization. (Car is empty)
- CarWeightAlarm(v): v = {True, False}
- - One per Car
  - Provides information about the status of the buzzer. The buzzer rings any time the car is overweight.
  - Set to false at initialization

### Environmental-Only System State:

These values keep track of current system state. They are not accessible to the control system, but have been used in the specifications for building the simulation system.

- DoorPosition[b, r](x): Amount that the door is open. x = {integer 0 .. 500}
- - One per Door [b, r] for b = {Front, Back} and r = {Left, Right}.
  - Value is the amount the door is open as a thousandth of doorway width. Each DoorPosition[b, r] can range from 0 to 500. With both Door_Front[r] open at 500 the entire front doorway is opened overall. With both Door_Back[r] open at 500 the entire back doorway is opened overall.
  - Set to 0 at initialization (front doors closed).
- CarPosition(x): Vertical position of car. x = {integer 0.. } in millimeters
- - Tracks the position of the car in meters (not the same as floor number or CarLevelPosition).
  - Set to Lobby position at initialization.

### System Actuators

The below-listed values will correspond to network messages in the implementation phase. All actuators are assumed to "remember" their last commanded value and stay there unless commanded otherwise or forced otherwise by system/environment constraints.

- DoorMotor[b, r](m): Door motor. m = {Open, Close, Nudge, Stop}
- - One per Door [b, r] for b = {Front, Back} and r = {Left, Right}.
  - Opens and closes the door. It is permissible to transition directly from Open to Close, Open to Nudge, Nudge to Open, and Close to Open without first commanding a Stop, although the door requires some time to change directions.
  - Set to Stop at initialization; see DoorMotor object description for details.
- CarLantern[d](k): Car Lanterns. k = {On, Off}.
- - One set per Car, d = {Up, Down}.
  - These are the Up/Down arrows placed on the car door frames. Used by Passengers on a Floor to figure out whether to enter the Car.
  - Set to Off at initialization.
- CarLight[f, b](k): Car Call Button lights. k = {On, Off}.
- - One per CarCall[f, b] button.
  - The light inside the car call button, used to indicate to passengers that a car call has been registered by the dispatcher.
  - Set to Off at initialization.
- CarPositionIndicator(f): Position Indicator in Car. f = {integer 1..MaxFloor}.
- - One per Car.
  - Displays floor status information to the passengers in the Car.
  - Set to 1 at initialization.
- HallLight[f, b, d](k): Hall Call Button lights. k = {On, Off}.
- - One per HallCall[f, b, d] button.
  - The light inside the hall call button, used to indicate to passengers that a hall call at that Floor f has been registered by the Dispatcher for direction d.
  - Set to Off at initialization.
- Drive(s,d): 3-speed main elevator drive. s is speed s = {Fast, Slow, Level, Stop}, d is direction d = {Up, Down, Stop}
- - One per Car.
  - Moves the Car up and down the hoistway according to a velocity profile that depends on a variety of physical factors.
  - Set to (Stop, Stop) at initialization; see Drive object for details.
  - Note that current Drive speed can be determined via DriveSpeed(s,d) and is not necessarily the same as the Drive command because of the acceleration profile.
  - While the drive is stopped, if the car weight changes, the car may move downward as a result of cable slip.

- CarWeightAlarm(k): Car weight overload alarm. k = {On, Off}.

- Buzzer that sounds when the CarWeight sensor detects that the elevator is weight overloaded (above MaxCarCapacity). It's the signal to the passengers that at least one must step off the elevator before it continues operation.

- Set to Off at initialization.

### Environmental-Only Actuators

- EmergencyBrake(b): Emergency stop brake. b = {On, Off}
- - Supplies emergency braking in case of safety violation such as hoistway limit over-run or movement with doors open. One per Car. Can be used exactly one time, after which elevator hoistway requires significant repair maintenance. Triggering the EmergencyBrake in simulation means that either a safety-critical sensor/actuator has been broken or your elevator controller has attempted unsafe operation. (If the EmergencyBrake activates during your final project demo due to an attempt of unsafe operation, there will be a scoring penalty.)
  - Set to Off at initialization.

### Control System Objects

In addition to the objects described above, there are several complex control system objects. These objects are summarized below. The detailed specification of these objects can be found in the Behavioral Requirements II document. Environmental objects have already been designed and are provided by the system. The other control objects will be the primary focus of your design effort.

1. Passenger (environmental) - the simulated passenger that interacts with the physical interface of the elevator
2. Safety Sensor (environmental) - monitors the system state and triggers the emergency brake if an unsafe condition is detected.
3. Drive (environmental) - moves the car according to the Drive commands and the elevator acceleration profile.
4. DoorMotor[b,r] (environmental) - moves the doors according to the DoorMotor commands.
5. DoorControl[b,r] - controls the motion of the doors
6. DriveControl - controls the motion of the car
7. LanternControl[d] - controls a the direction lanterns
8. HallButtonControl[f,b,d] - controls the hall lights and and monitors hall buttons at the landings
9. CarButtonControl[f,b] - controls the car lights and and monitors car buttons inside the car
10. CarPositionControl - controls the output of the car position indicator
11. Dispatcher - determines the order in which floors and hallways are serviced

## Network Message Dictionary

This section defines the network messages that may be sent. The design MUST follow the message dictionary. Following the message dictionary means:

- Every message defined in the message dictionary is sent.
- No message not defined in the message dictionary is sent.
- Each message carries the information described in the dictionary.

### Environmental Object Messages

These messages are sent by environmental objects and smart sensors provided in the system

Source Node Name | Message Name | Replication | Number of fields | Description
Safety Object | mEmergencyBrake | none | 1 | see object description
AtFloor Sensor | mAtFloor | floor, hall | 1 | see object description
Level Sensor | mLevel | direction | 1 | see object description
CarLevelPosition Sensor | mCarLevelPosition | none | 1 | see object description
Door Closed Sensor | mDoorClosed | hall, side | 1 | see object description
Door reversal Sensor | mDoorReversal | hall, side | 1 | see object description
Weight Sensor | mCarWeight | none | 1 | see object description
Weight Sensor | mCarWeightAlarm |  | 1 | see object description
Door Opened Sensor | mDoorOpened | hall, side | 1 | see object description
Hoistway Limit Sensor | mHoistwayLimit | direction | 1 | see object description

### Controller Messages

These messages are sent by the controllers that you will design. In the later projects, you will be allowed to modify the message dictionary for the controllers in a limited way, but for the time being, you must implement the message dictionary given below:

Source Node Name | Message Name | Replication | Number of Fields | Description
Drive Control | mDriveSpeed | none | 2 | The current speed and direction of the car Speed - a numeric value Direction - one of {STOP, UP, DOWN}
Drive Control | mDrive | none | 2 | The commanded speed and direction of the car Speed - one of {STOP, LEVEL, SLOW, FAST} Direction - one of {STOP, UP, DOWN}
Dispatcher | mDesiredDwell* | hallway | 1 | A numeric value indicating the desired dwell time for the door.
Dispatcher | mDesiredFloor** | none | 3 | The desired floor, hallway, and direction floor - the next floor to be serviced, [1,8] hallway - the hallway to be serviced, one of {FRONT, BACK, BOTH, NONE} direction - the intended direction of travel after servicing the desired floor, one of {UP, DOWN, STOP}
Door Control | mDoorMotor | hall, side | 1 | The current command to the door. One of {STOP, OPEN, CLOSE}
Hall Button | mHallCall | floor, hall, direction | 1 | Indicate the presence of a hall call in the direction at the floor and hall. One of {true, false}
Hall Button | mHallLight | floor, hall, direction | 1 | Indicate the state of the hall light One of {true, false}
Car Button | mCarCall | floor, hall | 1 | Indicate the presence of a car call for a certain floor and hall. One of {true, false}
Car Button | mCarLight | floor, hall | 1 | Indicate the state of the car light One of {true, false}

### Removed messages

- Starting in Project 10, you will be allowed to remove unused messages. Any message that is otherwise removed from the documentation should be listed here. See the project 10 writeup for more details. You MAY NOT remove messages from the message dictionary prior to Project 10.

Notes:
*mDesiredDwell:

- There is a separate message for the Front and Back floor.
- This is an optional way for the Dispatcher to override any dwell time used by the DoorController[b].

**mDesiredFloor:

- The dispatcher uses this to indicate the next floor to stop at. A direction of Stop means that there is no preferred direction. Directions of Up and Down have the implication that the next direction the elevator will move in is up or down, respectively.
- Note: the value of desired direction is not necessarily the current direction of motion. The car may be moving Up with a desired direction of Down, which means that the elevator will go down after it stops at a floor.
- The value of DesiredFloor may change dynamically and non-monotonically.
- Once doors begin opening the elevator is committed to perform a full door cycle operation.
- The f field (desired floor) value must change to the next floor by the time the doors are fully open.
- The d field (desired direction) value must not change while the doors are open.