View source for 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|Manage Models]] section of PHENOM.  After logging in, please click on the [[Manage|Manage Models]] icon.

[[File:Phenom navigation bar 5.png|thumb|none]]

===Create a New Project===
It is possible to upload new content and create a new project all at once!  To start, click on the ''Create New Project'' button.

[[File:Phenom-manage-create-new-project.png|frame|none]]


{{Info|heading=Two Buttons? | 1=If you have a project selected, a second button will appear.  This is for [[Creating a Filtered Project|Create Filtered Project]] which will be covered in another article.
[[File:Phenom-manage-create-filtered-project.png|frame|none]]
}}

===Select Models===
Once you click the button, the following screen should appear to the right of the Project listing.

[[File:Phenom-manage-create-new-project-select-models.png|frame|none]]

For the Project Name, please type: ''Robot''

You may leave Description blank.  This field is intended for you to capture notes about the project (or model) and how it will be used.  

In the bottom-left of this display, there is a list of existing models.  This is used to add ''existing'' models to the new project.  Ignore this for now.

In the bottom-right, click on ''Import FACE model''.  This button will add a model entry as follows:

[[File:Phenom-manage-create-new-project-load-model.png|frame|none]]

For the Model Name (the first text field), please enter: Robot_model

As before, Description can be left blank.

Click on '''Select files...''' and a file chooser will appear.  Navigate to where you saved [[Robot_model.face]] from before and choose that file.  PHENOM will immediately start uploading the file.  While the file is uploading and being preprocessed, the following status will appear:

[[File:Phenom-manage-create-new-project-model-loading.png|frame|none]]

Once the file has successfully transferred, PHENOM will show the file uploaded successfully with a green indicator.

[[File:Phenom-manage-create-new-project-model-loaded-successfully.png|frame|none]]

In the event of an error (e.g., invalid file type or invalid model), PHENOM will display an error as follows:

[[File:Phenom-manage-create-new-project-model-load-error.png|frame|none]]

Once the file has been successfully uploaded, click on the SAVE button.

[[File:Phenom-manage-create-new-project-save.png|frame|none]]

==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.

[[File:Phenom-tutorial-documenting-interface-example.png|thumb|none]]