Document Interfaces using PHENOM Portal

Documenting communication interfaces using good data modeling practices is easy in PHENOM Portal. This quick assignment will get you up and running documenting your own interfaces, creating valid and informative paths, and mapping your interface to others already documented.

Preparing PHENOM

In this tutorial, you will be documenting interfaces. However, in order for you to be able to do this, you need a data model that corresponds with this tutorial. Since there is already a tutorial for Developing an Entity Model, this tutorial will start by loading a data model into PHENOM.

Start by downloading this data model: File:Robot model.face

Creating a New Project

Switch to Manage Mode

All model management functions are performed in the Manage Models section of PHENOM. After logging in, please click on the Manage Models icon.

Create a New Project

It is possible to upload new content and create a new project all at once!

Prelude: Views, View-Characteristic, and Paths - What and Why

In the task of documenting the Simple Operating Robot Data Interface, our main focus will be in Views. Views can be understood as the documentation of messages that the interface describes. A view documents a message interface, and each view-characteristic documents a single field of the message. More specifically, a view-characteristic contains information about the logical level of the message field (such as the measurement and unit being used) as well as information about the conceptual level of the message field (which entities and properties of entities are being talked about).

If you click on a view-characteristic, you will see that each has a name, an observable, a measurement and axis (which further characterizes the observable), and a path documenting the entities and its context. Path development is the primary focus of this assignment - paths communicate the semantics of message fields in a machine understandable fashion. Engineer-written documentation for data coming in over the wire might indicate "Temperature of the main unit of an air system's propulsion system." which, though concise and informative, might not mean much to a machine. Paths allow us to write standardized descriptions of view-attributes, linking together different entities, such as engines, propulsion systems, and air vehicles, to create semantic, machine-readable documentation for the contents of a message. Below is an example view attribute describing the message field documented in the sentence above.