bannerb

This version of SWEHB is associated with NPR 7150.2B. Click for the latest version of the SWEHB based on NPR7150.2C

Return to 7.18 - Documentation Guidance

IDD - Interface Design Description

1. Minimum Recommended Content


    1. Priority assigned to the interface by the interfacing entity(ies).
    2. Type of interface (e.g., real-time data transfer, storage-and-retrieval of data) to be implemented.
    3. Specification of individual data elements (e.g., format and data content, including bit-level descriptions of data interface) that the interfacing entity(ies) will provide, store, send, access, and receive.
    4. Specification of individual data element assemblies (e.g., records, arrays, files, reports) that the interfacing entity(ies) will provide, store, send, access, and receive.
    5. Specification of communication methods that the interfacing entity(ies) will use for the interface.
    6. Specification of protocols the interfacing entity(ies) will use for the interface.
    7. Other specifications, such as physical compatibility of the interfacing entity(ies).
    8. Traceability from each interfacing entity to the system or CSCI requirements addressed by the entity's interface design, and traceability from each system or CSCI requirement to the interfacing entities that address it.
    9. Interface compatibility.
    10. Safety-related interface specifications and design features.

              

2. Rationale

The Interface Design Description (IDD) describes the interface characteristics of one or more systems, subsystems, Hardware Configuration Items (HWCIs), Computer Software Configuration Items (CSCIs), manual operations, or other system components. Typical NASA development projects are complex, multi-disciplined activities that consist of systems and systems of systems. These projects usually require integrated product teams working together to achieve the goals and objectives in a timely and cost-efficient manner. The execution of the software development life cycle and its activities by the team requires multiple tasks and work products to be developed and accomplished in parallel. To assure that the assembled systems and integrated systems function as intended, the interfaces for the software work products (components) and systems must be accurately defined, designed, controlled, and communicated. A high-quality IDD document fulfills these needs for the software development team.

3. Guidance

The software IDD document may be a stand-alone entity or part of the Software Design Description document or part of an electronic data system. Center policies and procedures are expected to be followed when determining which documentation approach is suitable for a particular project. It is important that the interface design information be identified and tracked as the software system is being developed, tested, and operated. Software interface designs and requirements tend to drive software designs and can lead to a potential source of anomalies during the development and operational life cycle. The key to implementing this requirement is to have a good description of all software, hardware, operations, and system interfaces and interactions during the design and operational phases of a development cycle. The content of the IDD is defined by PDR (Preliminary Design Review). The preliminary IDDs are expected to be approximately 30 percent completed at PDR. All interface components are to be defined by PDR. The IDDs are completed by CDR (Critical Design Review) and updated as needed after CDR. The final as-built IDD is documented as a part of the as-built design documentation for operational use, software modification, and potential software reuse applications.

The software development team is responsible for preparing an IDD that describes the interface entity characteristics for all defined systems, subsystems, domains, hardware items, software items, manual operations, and other system components. 

The descriptions contain the interface characteristics for systems or configuration items that participate in the interface (including human-system and human-human interfaces), standards and protocols, responsible parties, interface operational schedules, and any error handling routines. The software team also defines those interface characteristics that are existing or permanent, as well as those that are being developed or modified. The applicability of this requirement is highly dependent on the classification level for the software work product(s). Appendix C, Requirements Mapping Matrix, of NPR 7150.2 shows the requirements for each classification level (see SWE-020).

An excellent way to begin the descriptions of the interfaces is with a context or state diagram. A suitably detailed diagram (showing the relationship of the interface with the overall activity) with legends and callouts will easily show the dependencies that must be controlled and satisfied in the software detailed design. Either a single diagram or an interrelated set of diagrams, depending on the complexity of the software work product(s), may be the most appropriate choice.

As shown in the text above, the software IDD document is recommended to contain specific information.  NASA-specific interface design description information and resources are available in Software Processes Across NASA (SPAN), accessible to NASA users from the SPAN tab in this Handbook. 

Below are suggestions for the type of information to consider for the named content.

Document content

The following paragraphs are based on Department of Defense (DoD) DI-IPSC-81436A, Data Item Description Interface Design Description (IDD) 025, along with supporting material from GRC (Glenn Research Center) GRC-SW-TPLT-IDD, Interface Design Description (IDD) Template.

  • Assigned priority.
    This is the priority assigned to the interface by the interfacing entity(ies).The level of the priority allows the software to service higher priority queues ahead of lower priority queues. Complex priority values may allow timeouts and software interrupts to avoid the starving of lower priority interfaces.
  • Type of interface.
    The IDD document includes characteristics about interface types, such as real-time data transfer, storage-and-retrieval of data, remote programming interface, etc., that will be implemented.

Factors like functionality, performance speed, the time needed to use the program, user satisfaction, and the rate of user errors are some criteria for the software development team to consider when designing an interface. The software interface tests are specified in the Software Test Plan.

The two most common ways of expressing interface information are (1) alphabetically by parameter and (2) for data-oriented interfaces, by layers with reference to a level-of-abstraction model such as the Open Systems Interconnection (OSI)-7 Layer model. 303 In the latter case, individual information items (e.g., requirements or characteristics) are framed consistent with the layer definitions and then specified by layer, "physical" up to "application" in that order of the OSI-7 Layer model. Within a layer, control flow sequence is used where applicable to express information; otherwise it is expressed alphabetically by parameter.

  • Specifications of individual data elements
    The IDD document includes characteristics about the individual data elements that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as:
    • Names/identifiers.
        1. Project-unique identifier.
        2. Nontechnical (natural language) name.
        3. Standard data element name.
        4. Technical name, e.g., variable or field name in code or database.
        5. Abbreviation or synonymous names.
  • Data type (alphanumeric, integer, etc.), indicating data types that are not defined until implementation, such as C++ type overloading (templates) and dynamic typecasting.
  • Size and format, i.e., length and punctuation of a character string or bit-level descriptions.
  • Units of measurement, i.e., meters, dollars, or nanoseconds.
  • Range or enumeration of possible values, i.e., 0 to 99.
  • Accuracy (how correct) and precision (number of significant digits).
  • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the data element may be updated and whether business rules apply.
  • Security and privacy constraints.
  • Sources (setting or sending entities) and recipients (using or receiving entities).
  • Safety criticality.
  • Specifications of data element assemblies
    The IDD document includes characteristics about data element assemblies, such as records, messages, files, arrays, displays, reports, etc., that the interfacing entity(ies) will provide, store, send, access, receive, etc., such as:
    • Names/identifiers.
        1. Project-unique identifier.
        2. Nontechnical (natural language) name.
        3. Technical name, e.g., record or data structure name in code or database.Abbreviations or synonymous names.
    • Data elements in the assembly and their structure (number, order, grouping, and bit-level descriptions).
    • Medium, i.e., disk, and structure of data elements or assemblies on the medium.
    • Visual and auditory characteristics of displays and other outputs, i.e., colors, layouts, fonts, icons, and other display elements, beeps, and lights.
    • Relationships among assemblies, such as sorting or access characteristics.
    • Priority, timing, frequency, volume, sequencing, and other constraints, such as whether the assembly may be updated and whether business rules apply.
    • Security and privacy constraints.
    • Sources (setting or sending entities) and recipients (using or receiving entities).
    • Safety criticality.
  • Specifications of communication methods
    The IDD document includes characteristics about communication methods that the interfacing entity(ies) will use for the interface, such as:
    • Project-unique identifier(s).
    • Communication links, bands, frequencies, media, and their characteristics.
    • Message formatting.
    • Flow control, i.e., sequence numbering and buffer allocation.
    • Data transfer rate, whether periodic or aperiodic, and interval between transfers.
    • Routing, addressing, and naming conventions.
    • Transmission services, including priority and grade.
    • Security and privacy considerations, such as encryption, user authentication, compartmentalization, and auditing.
    • Safety criticality.
  • Specifications for communications protocol
    The IDD document includes characteristics about digital message formats and the rules for exchanging those messages. A protocol defines the syntax, semantics, and synchronization of communication, and the specified behavior is typically independent of how it is to be implemented. A protocol can therefore be implemented as hardware or software or both. Characteristics of protocols the interfacing entity(ies) will use for the interface include:
    • Project-unique identifier(s).
    • Priority or layer of the protocol.
    • Packeting, including fragmentation and reassembly, routing, and addressing.
    • Legality checks, error control, and recovery procedures.
    • Synchronization, including connection establishment, maintenance, and termination.
    • Status, identification, and any other reporting features.
  • Other characteristics, such as
    Physical compatibility of the interfacing entity(ies) (dimensions, tolerances, loads, voltages, plug compatibility, etc.).
  • Traceability
    Show the path from each interfacing entity to the system or CSCI (Computer Software Configuration Item) requirement addressed by the design. To complete the bidirectional tracing of the requirements, show from each system or CSCI requirement to the interfacing entity that addresses it. (See SWE-059 on bidirectional traceability.)
  • Interface Compatibility
    The IDD document contains information about the intended compatibility between or among the interfaces being developed. Specifically, will there be uniform or optional approaches to developing weak versus strong compatibility? Will the compatibility of the software components' interaction with their environment be characterized as optimistic or pessimistic in nature?
  • Safety-related interface specifications and design features
    Safety-critical off-the-shelf (OTS) and reused software must undergo safety analysis that considers:
    • Its ability to meet required safety functions.
    • Extra functionality that may be present, even if not planned for use.
    • The impact on safety.
    • Interfaces to developed code.

Additional analysis, testing, or a combination thereof can be performed to verify safety-critical OTS or reused software to the same level required of in-house developed software to the extent possible via black box testing.

The Contract Data Requirements List specifies whether deliverable data are to be delivered on paper or electronic media; may be delivered in developer format rather than in the format specified herein; and may reside in a computer-aided software engineering or other automated tool rather than in the form of a traditional document.

Best practices

The software development team solicits relevant stakeholder involvement to evaluate applicable system interface(s).

Whenever possible, the software development team considers using an industry recognized standard for system interfaces.


4. Small Projects

The proper execution of interfaces among entities in software design activities is no less important for small projects than for large projects. Improper interface development, evaluation, and testing will cause any software work product to fail to function, regardless of the size of the project.

Smaller projects may benefit by using standard interface designs or Interface Design Description (IDD) templates previously developed and cataloged in software reuse repositories or by using personnel with previous experience on identical or similar interfaces. Where applicable, information may be duplicated from IDDs written for previously developed software interfaces. Extreme care is used whenever deciding to reuse software. (See SWE-027 for information that may be applicable.) (See the Center's repository of best practices for additional guidance in this area (see SWE-144).)

 5. Resources

5.1 Tools

Tools relative to this Topic may be found in the table below. You may wish to reference the Tools Table (click here to visit) in this handbook for an evolving list of these and other tools in use at NASA. Note that this table should not be considered all-inclusive, nor is it an endorsement of any particular tool. Check with your Center to see what tools are available to facilitate compliance with this requirement.

No tools have been currently identified for this Topic. If you wish to suggest a tool, please contact the Page Editor listed at the bottom of the page.

 6. Lessons Learned

  • Mars Climate Orbiter Mishap Investigation Board - Phase I Report. Lesson Number 0641: "The MCO Mishap Investigation Board (MIB)...determined that the root cause for the loss of the MCO spacecraft was the failure to use metric units in the coding of a ground software file." The data in the ... file was required to be in metric units per existing software interface documentation, and the trajectory modelers assumed the data was provided in metric units per the requirements. In fact, the angular momentum (impulse) data was in English units rather than metric units. The failure to properly communicate what was in the interface documentation is a warning that the effective implementation of the IDD requirement includes adequate communication of its contents, not just the writing and recording. 513
  • Interface Control and Verification. Lesson Number 0569: Problems occurred during the Mars Pathfinder spacecraft integration and test due to out-of-date or incomplete interface documentation. (While this lesson involves a hardware-related problem, it illustrates the need for accuracy in interface documentation.) Investigation showed that the main wiring harness was built in accordance with documentation that had not been updated after design changes were made. In part, this was due to independently prepared Mechanical Interface Control Drawings by the Government and the contractor. The MICD s should have had periodic verification for accuracy and compatibility. 508
  • No labels