Interface Design

Bread Crumbs: Home - SW_Dev_Proc - Arch & Det Des - Xface Des


Interface design of the system needs to stabilize very early in the development process in order to begin creating the stubbed-out function tests that call the API functions that are part of the system's external interface (V-Development).

Note: At this point in the software development process flow, many of the examples will be scoped to a particular part of the overall system under development. Interface artifacts and detailed design artifacts are going to contain a large amount of content and would likely negatively affect the comprehensibility of the content published on this website. The purpose of these examples is to provide additional information on what constitutes a software development process as opposed to providing a complete set of system development artifacts.

Interfaces can be specified in a variety of ways. The specification can be text only, a graphical model such as a UML class diagram, or a combination of text and graphics. I prefer using a combination of text and graphics so that data characteristics, syntax, and semantics can be specified using the most appropriate means of conveyance.

On this page, I will provide examples of the following interface specification artifacts:

At the end of this web page, the V-Model is again referenced with respect to how it applies to interface design.

Component Interface / Interconnection View Diagram

Traditionally, a component-and-connector view will model passive object instances within the context of a thread of execution or active object instances who own their own threads of execution. The components can therefore be modeled as boxes which capture the flow of execution and produce a change of system state as a result of capturing that flow.

The following diagram is a high-level component-and-connector view diagram that represents interfaces as annotated ports. This diagram is similar to a data-flow diagram and is referred to as a Component Interface / Interconnection View diagram. It models the microwave oven example.

 

Component Interface / Interconnection View diagram

Graphical Component Interconnection/Interface Diagram PNG



Data Dictionary:


Term

Description

Type

Requirements Trace

Beeper

Beeper component that encapsulates beeper functionality.

Component

F1, F2, F4.2.5, F4.2.9, F4.5.8, F4.5.10, F4.5.11

Beeper Signal-out

Output from the Output Processing System component that contains signals to the beeper device.

Output Data

F1, F2, F4.2.5, F4.2.9, F4.5.8, F4.5.10, F4.5.11

Command Processing System

Controller component that encapsulates controller functionality.

Component

F4, F4.3.1, F4.3.2, F4.4.2, F4.4.5, F4.4.6

Cooking Function Description

Cooking function description data that flows from the Command Processing System component to the Oven Control System component. This data identifies the cooking function selected.

Data Flow

F5

Cooking Function Desc-in

Oven Control System input cooking data.

Input Data

F4.3.3, F4.4.6, F4.5.6, F4.5.7, F4.5.9, F4.5.10

Cooking Function Desc-out

Command Processing System component output cooking data.

Output Data

F4.3.3, F4.4.6, F4.5.6, F4.5.7, F4.5.9, F4.5.10

Display

Display component that encapsulates display functionality.

Component

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Display Desc

Data that flows from the Output Processing System component to the Display component that contains signals to the display device.

Data Flow

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Display Desc-out

Output from the Output Processing System component that contains signals to the display device.

Output Data

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Door

Door component that encapsulates door functionality.

Component

F2, F4.2.10, F4.5.8, F4.5.9

Door Sensor

Input data to theCommand Processing System (Controller) component that contains door status data.

Input Data

F2, F4.2.10, F4.5.8, F4.5.9

Door Status Data

Data that flows from the door latch sensor to the Command Processing System (Controller) component.

Data Flow

F2, F4.2.10, F4.5.8, F4.5.9

Generator Control-out

Oven Control System component output that contains the control codes for the generator.

Output Data

F4.3.3, F4.4.6, F4.5.6, F4.5.7, F4.5.9, F4.5.10

Input Data Stream

Data that flows from the Keypad component to the Command Processing System (Controller) component. This data contains keycode data from the keypad.

Data Flow

F1, F4

Keypad

Keypad component that encapsulates keypad functionality.

Component

F1, F4

Keypad-in

Input data to the Command Processing System (Controller) component that contains keycode data from the keypad.

Input Data

F1, F4

Microwave Generator

Microwave Generator (cavity magnetron) component that encapsulates generator functionality.

Component

F4.3.3, F4.4.6, F4.5.6, F4.5.7, F4.5.9, F4.5.10

On/Off and Power Level

Data that flows from the Oven Control System component to the Microwave Generator component. This data that contains the current status and power level of the generator.

Data Flow

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2, F4.5.6, F4.5.7, F4.5.9, F4.5.10, F4.5.12

On / Off Signal

Data that flows from the Output Processing System component to the Beeper component. This data contains the status of the beeper device.

Data Flow

F1, F2, F4.2.5, F4.2.9, F4.5.8, F4.5.10, F4.5.11

Output Processing System

Output Processing System component that encapsulates output processing system functionality.

Component

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Oven Control System

Oven Control System component that encapsulates oven control functionality.

Component

F4.3.3, F4.4.6, F4.5.6, F4.5.7, F4.5.9, F4.5.10

Process-Desc

Process-related data that flows from the Command Processing System component to the Output Processing System component.

Data Flow

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Process-Desc-In

Input data to the Output Processing System component that contains cooking process-related data.

Input Data

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6

Process-Desc-Out

Output from the Command Processing System component that contains cooking process-related data.

Output Data

F3, F4, F4.1.1, F4.1.2, F4.1.3, F4.1.4, F4.1.5, F4.1.6, F4.1.7, F4.1.8, F4.1.9, F4.2.1, F4.2.6, F4.2.7, F4.3.1, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.4, F4.4.5, F4.4.6, F4.5.5, F4.5.7, F4.5.8, F5, F6



UML Class Diagram

As was alluded to in the "Inheritance Model:" section of the "Create System Model" activity page of this site, UML class diagrams can capture inheritance relationships (is-a) as well compositional (has-a) relationships. At this point in the development process, the modeling becomes more detailed as the design artifacts must now specify the "how-to" information. Additional details such as full function signatures and class attributes are added to models at this stage to further elaborate the design ideas put forth in the architecture design.


Microwave Oven Input Class Diagram PNG
Auto-defrost Key Interface Specificaton Clock Interface Specification


Data Dictionary:


Term

Description

Type

Requirements Trace

amPm

Contains the time-of-day integer antemeridiem / postmeridiem value. Attribute of Clock class.

int

F4.1

autoCookDuration

Contains the time period value for the amount of time to cook the item. Attribute of AutoCookPresetKeyImpl.

int

F4.3.2

AutoCookImpl

This class contains all of the AutoCookPresetKeyImpl objects as attributes and realizes the AutoCookInterface

Class

F4.3

AutoCookInterface

Interface for the auto-cook functionality. Contains the various preset keys available for the microwave oven.

Interface

F4.3

AutoCookPresetKeyImpl

Manufacturer-defined presets for heating common food items. Implementation class that realizes the AutoCookPresetKeyInteface.

Class

F4.3.1

AutoCookPresetKeyInterface

Interface for auto-cook preset keys.

Interface

F4.3

autoCookPowerLevel

Contains the power level value for the power level at which to cook the item. Attribute of AutoCookPresetKeyImpl.

int

F4.3.2

AutoDefrostKeyImpl

Derived from the AutoCookPresetKeyImpl class. Key used to set power level and time for defrosting frozen food items.

Class

F4.4

AutoDefrostKeyInterface

Interface for the auto-defrost functionality.

Interface

F4.4

beverage

Attribute of the AutoCookImpl class. The beverage auto-cook preset key automatically sets the heating time and power level for hot beverages.

AutoCookPresetKeyImpl

F4.3.1

beeperDuration

Contains the integer beeper duration value. Attribute of Timer class.

int

F4.2.5, F4.5.8, F4.5.10, 4.5.11

Clock

Class that realizes ClockInterface and implements the clock key that is used in conjunction with numeric keys to set the clock.

Class

F4.1

ClockInterface

Interface for the clock functionality.

Interface

F4.1

DoorImpl

Realizes the DoorInterface. Implements door latch sensor signal-handling capabilities.

Class

F4.5.8

DoorInterface

Interface for the door latch sensor input.

Interface

F4.5.8

doorStatus

Attribute of the DoorImpl class. Status input from door latch sensor.

byte

F4.5.8

failure

Attribute of HardwareSignalImpl class. Failure indication from hardware component (if failure occurs).

byte

F6

freshVeg

Attribute of the AutoCookImpl class. The freshVeg auto-cook preset key automatically sets the heating time and power level for fresh vegetables.

AutoCookPresetKeyImpl

F4.3.1

frozenEntrée

Attribute of the AutoCookImpl class. The frozenEntree auto-cook preset key automatically sets the heating time and power level for frozen entrees.

AutoCookPresetKeyImpl

F4.3.1

FunctionImpl

Class that realizes the FunctionInterface and contains the function key objects as class attributes. Allows execution of functions such as PowerLevel, Program, AutoDefrost, Stop/Clear, Start, Clock, and Timer.

Class

F4.1, F4.2, F4.5

FunctionInterface

Interface for the function key functionality of the microwave oven.

Interface

F4.1, F4.2, F4.5

FunctionKeyImpl

Class that realizes the FunctionKeyInterface and provides basic function key functionality.

Class

F5

functionType

Contains the type of function. An attribute of the FunctionKeyImpl class.

byte

F5

getAmPm

Getter method for AM / PM value. Defined in Clock class.

operation

F4.1

getAutoCookDuration

Getter method for auto-cook duration value. Defined in AutoCookPresetKeyImpl class.

operation

F4.3.2

getAutoCookInterface

Getter method for auto-cook interface implementation object that contains all preset functionality. Defined in Keypad class.

operation

F4.3

getAutoCookPowerLevel

Getter method for auto-cook power level value. Defined in AutoCookPresetKeyImpl class.

operation

F4.3.2

getAutoDefrost

Getter method for auto-defrost implementation object. Defined in AutoCookImpl class.

operation

F4.4

getBeeperDuration

Getter method for beeper duration value. Defined in Timer class.

operation

F4.2.5, F4.5.8, F4.5.10, 4.5.11

getBeveragePreset

Getter method for the beverage preset implementation object. Defined in AutoCookImpl class.

operation

F4.3.1

getClock

Getter method for clock implementation object. Defined in FunctionImpl class.

operation

F4.1

getDoorStatus

Getter method for door status value (open / closed). Defined in DoorImpl class.

operation

F4.5.8

getFailure

Getter method for hardware failure value.

operation

F6

getFunctionType

Getter method for active function mode value. Defined in FunctionKeyImpl class.

operation

F5

getFunctionInterface

Getter method for function interface implementation object that contains all oven functions. Defined in Keypad class.

operation

F4

getHour

Getter method for current clock hour value. Defined in Clock class.

operation

F4.1.7, F4.1.8

getInputType

Getter method for current type of input value. Defined in InputInterfaceImpl class.

operation

 

getKeyArray

Getter method for value sequence of numeric keys pressed. Defined in NumericImpl class.

operation

F4.1.5, F4.2.3, F4.5.1

getKeyType

Getter method for type of key pressed value. Defined in KeyImpl class.

operation

4.1, 4.2, 4.3, 4.4, 4.5

getKeyValue

Getter method for numeric value of numeric key pressed. Defined in NumericKeyImpl class.

operation

F4.1.5, F4.2.3, F4.5.1

getLevel

Getter method for current power level value selected. Defined in PowerLevel class.

operation

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

getMinute

Getter method for current minute value of the clock. Defined in Clock class.

operation

F4.1.7, F4.1.8

getMinutes

Getter method for current minutes value of the timer. Defined in Timer class.

operation

F4.2

getNumericInterface

Getter method for auto-cook interface implementation object that contains all preset functionality. Defined in Keypad class.

operation

F4.4.3, F4.4.4, F4.4.5, F4.5.1

getPizzaPreset

Getter method for the pizza preset implementation object. Defined in AutoCookImpl class.

operation

F4.3.1

getPopcornPreset

Getter method for the popcorn preset implementation object. Defined in AutoCookImpl class.

operation

F4.3.1

getPotatoPreset

Getter method for the potato preset implementation object. Defined in AutoCookImpl class.

operation

F4.3.1

getPowerLevel

Getter method for power level implementation object. Defined in FunctionImpl class.

operation

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

getPressed

Getter method for key-pressed status attribute. Defined in KeyImpl class.

operation

 

getRemaining

Getter method for remaining timer duration value. Defined in Timer class.

operation

F4.2.7, F4.2.8

getSeconds

Getter method for current seconds value of timer. Defined in Timer class.

operation

F4.2.4, F4.2.5, F4.2.6

getTimeOfDay

Getter method for current time of day value. Defined in Clock class.

operation

F4.1.4, F4.1.7

getTimer

Getter method for timer implementation object. Defined in FunctionImpl class.

operation

F4.2

getTypeOfMeat

Getter method for type of meat selected value. Defined in AutoDefrostKeyImpl class.

operation

F4.4.1, F4.4.2, F4.4.3

getWeight

Getter method for weight of meat value. Defined in AutoDefrostKeyImpl class.

operation

F4.4.1, F4.4.4, F4.4.5

handleHardwareSignal

Signal handler method that is called when a hardware component sends a signal. Defined in HardwareSignalImpl class.

operation

F2, F4.2.10, F4.5.8, F6

handlePressEvent

Event handler method that is called when a key is pressed by the user. Defined in KeyImpl class.

operation

F1

HardwareSignalImpl

Class that realizes the HardwareSignalInterface and provides the capability to receive hardware component signals as input data.

Class

F6, 4.5.8

HardwareSignalInterface

Interface for the hardware signal handling functionality which provides communication with hardware components.

Interface

F6, 4.5.8

hour

Contains the current clock (time-of-day) integer hour value. Attribute of Clock class.

int

F4.1.7, F4.1.8

InputInterfaceImpl

Parent input class to the following derived classes: DoorImpl, HardwareSignalImpl, KeyImpl.

Class

 

inputType

Contains type of interface data. Attribute of InputInterfaceImpl class.

Attribute

 

KeyImpl

Class that realizes the KeyInterface and provides the capability to process key-press events as input data.

Class

4.1, 4.2, 4.3, 4.4, 4.5

KeyInterface

Interface for key-press event functionality which assists in communicating with the keypad.

Interface

4.1, 4.2, 4.3, 4.4, 4.5

Keypad

Implementation class that is composed of one object of each of the following classes: AutoCookImpl, NumericImpl, FunctionImpl. This class contains all keypad functionality.

Class

4.1, 4.2, 4.3, 4.4, 4.5

keyType

Contains the type of key. Attribute of KeyImpl class.

byte

 

keyValue

Contains the integer value of the numeric key. Attribute of NumericKeyImpl class.

int

F4.4.3, F4.4.4, F4.4.5, F4.5.1

level

Contains the integer value of the selected level of power. Attribute of PowerLevel class.

int

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

minute

Contains the time-of-day integer minute value. Attribute of Clock class.

int

F4.1.7, F4.1.8

minutes

Contains the timer integer minutes value that specifies the current number of minutes. Attribute of Timer class.

int

F4.2

NumericInterface

Interface for the numeric key functionality. This interface contains all of the NumericKeyImpl objects.

Interface

F4.4.3, F4.4.4, F4.4.5, F4.5.1

NumericKeyImpl

Keys are numbered 0-9 for manually entering numeric values used for setting the clock, the timer, the power level, and the cooking time. Implementation class that realizes the NumericKeyInteface.

Class

F4.4.3, F4.4.4, F4.4.5, F4.5.1

NumericKeyInterface

Interface for the numeric key functionality.

Interface

F4.4.3, F4.4.4, F4.4.5, F4.5.1

popcorn

Attribute of the AutoCookImpl class. The popcorn auto-cook preset key automatically sets the heating time and power level for microwave popcorn.

AutoCookPresetKeyImpl

F4.3.1

potato

Attribute of the AutoCookImpl class. The popcorn auto-cook preset key automatically sets the heating time and power level for one potato.

AutoCookPresetKeyImpl

F4.3.1

PowerLevel

Class that realizes PowerLevelInterface and implements the power level key that is used in conjunction with numeric keys to set the power level.

Class

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

PowerLevelInterface

Interface for power level functionality.

Interface

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

pressed

Contains the pressed status of key. Attribute of KeyImpl class.

boolean

 

seconds

Contains the timer integer seconds value that specifies the current number of seconds of timer duration. Attribute of Timer class.

int

F4.2

sendPowerSignal

Method of PowerLevel class that sends the power level signal to the cooker device.

operation

F4.3.1, F4.3.2, F4.3.3, F4.4.1, F4.4.2, F4.4.3, F4.4.6, F4.5.1, F4.5.2

sendClockBytes

Method of Clock class that sends the clock setting bytes to the clock device.

operation

F4.1.3, F4.1.5

sendTimerBytes

Method of Timer class that sends the timer setting bytes to the timer device.

operation

F4.2.3

Timer

Class that realizes TimerInterface and implements the timer key that is used in conjunction with numeric keys to set the timer.

Class

F4.2

TimerInterface

Interface for timer functionality.

Interface

F4.2

typeOfMeat

Type of meat to be defrosted. Attribute of AutoDefrostKeyImpl class.

int

F4.4.1, F4.4.2, F4.4.3

weight

Weight of meat to be defrosted. Attribute of AutoDefrostKeyImpl class.

int

F4.4.1, F4.4.4, F4.4.5



Interface Specification Document

An interface specification document can be created at varying levels of detail. It is important that the interface specification document accurately capture the signatures of all interface functions since any change to these signatures will result in a lot of rework later on. It is equally important that the interface specification document clearly describe the intended semantics of each interface function. Again, other components will rely on the the interface specification document as they define their implementations. If the function ultimately behaves differently than specified in the interface specification document, it will likely break many implementations. The interface specification document should be treated as a contract between the implementers of the interface and those that the interface serves, both within the developing organization and outside of the developing organization if an external API is provided to customers.

1 Interface Definition

 

Note: Parameters are listed by Name, Type, and In/Out/In-Out to indicate if they are read-only (In), write-to (Out), or read-and-write (In-Out). Types that are listed in all caps are variable types that have been defined for this specific application.

 

1.2 Clock Function

Function Name: Clock

Parameters:
Clock_start_time, TIME_H_M, In
Start, ENUMERATION, In
Current_time_of_day, TIME_H_M, Out

Purpose:
The clock function receives an initial time of day setting from the operator then increments the current time value once per minute. Once a minute the current time value is output to the Display Time function for display.

Link to detailed interface specification for the Clock Function:
Interface Specification for the Clock Inteface of the Microwave Oven Example

1.3 Timer Function

Function Name: Timer

Parameters:
Initial_timer_value, TIME_M_S, In
Start, ENUMERATION, In
Stop_Clear_Interrupt
, ENUMERATION, In
Beeper_duration_time
, Integer, Out
Current_timer_value
, TIME_M_S, Out

Purpose:
This function receives an initial timer value that was input from the operator then counts down the time until it reaches zero. As the timer counts down the current time is sent once per second to the Display Time function. Once the timer reaches zero a value is sent to the Beeper function indicating the length of time that the beeper should sound. If a Stop interrupt signal is received during the count down, the time is halted until either a Stop/Clear signal is received (to cancel the timer countdown) or a Start signal is received (to continue the timer countdown).

1.4  Auto Cook Presets Function

Function Name: Auto Cook Presets

Parameters:
Preset_selected, ENUMERATION, In
Cooking_time, TIME_M_S, Out
Power_level, Integer, Out

Purpose:
This function receives an input indicating which operator preset button was pressed. The predefined power level and cooking time associated with that preset button are looked up in the Auto Cook Preset power and cooking time database. The power and cooking time values are output to the Cooking Control
Function.

1.5  Auto Defrost Function

Function Name: Auto Defrost

Parameters:
Meat_type, MEAT_TYPE, In
Weight_of_meat, Float, In
Cooking_time, TIME_M_S, Out
Power_level, Integer, Out

Purpose:
This function receives a type of meat and the weight of the meat from the Monitor and Process Inputs function. Based on the type of meat and the weight of meat the function determines the correct values for power level and cooking time. The power level and cooking time values are then output to the Cooking Control Function.


Link to detailed interface specification for the Auto-Defrost Function:
Interface Specification for the Auto-Defrost Key Inteface of the Microwave Oven Example

 

Each of these interfaces will need to have a specification similar to the following:
Interface Specification Template


V-Model Diagram

As illustrated in the below V-Model diagram, at this point in the software development process, creation of system integration test plans and unit test plans should begin. System integration test plans should focus on testing the syntax and semantics of the interfaces that have been defined. Unit tests must focus on the implementation details of the implementations that realize those interfaces.
V-Model Diagram - Interface Design PNG Sub-system integration testing focuses on testing the external APIs (Application Programming Interfaces) between sub-systems. Unit testing is white-box testing and thus unit test plans require knowledge of the implementation of the code. Unit test plans need to test algorithms, error paths, and provide good code coverage. Sub-system integration testing focuses on testing the external APIs (Application Programming Interfaces) between sub-systems. Unit tests are structural, white box tests that should attempt to provide maximum execution path coverage including off-nominal (error) paths. Module testing is the testing of complete code objects as produced by the compiler when built from source.

No part of this work should be produced or used without the permission of the authors: Michael Turner and Dr. Sharon A White.