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

Create a new project with this model. If you need any help, consult the following tutorial: Creating a Project from an Existing Model.

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.

Take a look at the path and see if you can connect it to the meaning intended by the engineer from the previous paragraph. Note that this page also captures how the measurement of this concept is expressed (i.e., measurement units and frame of reference). This information is used to construct the Logical Data Model.

Part 1: Documenting Robot Position Status

The first message interface we have to implement is for communicating the Robot_Position_Status. We are given the following interface description:

Robot_Position_Status - This message returns the position information of the robot.

Field ID	Name & Description	Unit	Data Type
1	Robot_Id An alphanumeric string indicating the unique identifier of the robot system.	UTF-8	String
2	Latitude The WGS-84 latitude value.	Radians	Double
3	Longitude The WGS-84 longitude value.	Radians	Double
4	Altitude The altitude value expressed in MSL.	Meters	Float

Before documenting the message, take a look at the entity which this message is meant to describe. In the model we are using, the closest entity is Robot. Once you are logged into PHENOM, make sure that you click on the DATA MODELING button in the left-hand navigation panel. Then, type 'robot' into the search bar on top of Phenom's NavTree and bring up the page describing Robot. You will see that this entity is composed of a few attributes, some of them are observables while another is an entity.

Let's start the documentation by clicking the 'Create' button at the top left of the page and choosing to create a new view.

Give your view a name and a description following the information in the table at the top of this section and click save.

Once saved, you can find your new view in the tree by searching for it or opening its parent package. NOTE: PHENOM creates new views in the PhenomViews package. However, you may drag the elements into locations of your choosing (so long as they are valid).

Now, we can add an attribute to the view to describe the first field of the message - Robot_ID. To start, click on the CREATE button in the Attributes pane.

Fill in the View Attribute field with its name. The table indicates this should be: Robot_Id

Given the name and description from the table, it is not hard to think that the best observable for it is Identifier. Selected that as our observable, then choose a measurement that will likely best fulfill the id being a string - I chose UniqueID_UUID_Text_Meas.

The next step is slightly more complicated. Originally, in PHENOM you could simply select any primitive type, and PHENOM would generate the appropriate results. Unfortunately, this leads to a proliferation of platform data types and users wanted us to provide a little more control for platform type reuse.

This leads to two options. First, you can create a new platform type. This is absolutely necessary when working with a new model. Once some platform types have already been created, the second option will allow you to reuse and existing platform type.

Creating a Platform Type