Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Apogy/UserGuide"

(Working with Perspectives)
(Working with Perspectives)
Line 188: Line 188:
 
| Arguments
 
| Arguments
 
| View used to edit Operation Calls arguments.
 
| View used to edit Operation Calls arguments.
|-
 
 
|-
 
|-
 
| Documentation
 
| Documentation
 
| View used to display documentation associated with the selected Operation Calls or Operation Calls arguments.
 
| View used to display documentation associated with the selected Operation Calls or Operation Calls arguments.
 +
|-
 +
| rowspan="2" | Earth Surface
 +
| rowspan="2" | Perspective used to create / edit Earth Surface Worksites.
 +
| Earth Surface Worksites
 +
| Show the list of available Earth Surface Worksites and allows the user to create / import / export / delete and activate Earth Surface Worksites.
 +
|-
 +
| Maps
 +
| View used to create / edit and delete the Maps contained in a Earth Surface Worksites.
 +
|-
 
|}
 
|}
  

Revision as of 16:24, 4 September 2018

Table Of Contents

Introduction

Apogy was originally developed at the Canadian Space Agency to control space exploration rovers and their associated sensors. Integrating all these systems developed by many different contractors and allowing them to be controlled as an integrated entity represented a challenge. In order works, a tool to plan, validate, execute and monitor integrated operations to support multiple missions was required. The technical team soon realized that a reusable framework could save a lot of work and allow for future growth. Apogy is the result of this thinking.

Apogy was built to:

  1. Be an organizationally neutral core framework (we did not want to be locked in with any particular contractor proprietary tool);
  2. Maximizes reuse between missions (keep the work to the specifics of each mission);

In order to so, Apogy:

  1. Is a component-based architecture that allows systems (ex: instruments, rovers, satellites) to “plug-in” and allow the system developer to concentrate on their system specific needs and the tooling to use them.
  2. Makes use of Open Source librairies that are Eclipse Public License compatible;

Overview

In Apogy, users control Systems by invoking commands (through Programs) and monitor the System's health through telemetry (i.e. states).

These Systems are operated in a Environment which defines such things as Digital Elevation Maps, orbit models, sun position, etc (i.e. what the Environment contains).

User, System, Environment and Data Product.

The System's command produces result (i.e. returned value, such as an Image, an error code, etc.) that Apogy geo-locates and time tags. This allows the results to be displayed within the 3D Environment. This helps in maintaining the situational awareness of the operator and keep the data in context.

Installing Apogy

TODO

Launching Apogy

TODO

Quick Start

To get you started quickly, we will import an existing Session (one of the example) and then used it to command the Integrated Rover example.

Importing an Existing Session

  1. Launch Apogy.
  2. Open the Welcome perspective if not already opened:
    1. In the top menu bar, select Open New Perspective. This will open the Add Perspective pop-up.
    2. In the pop-up, select the Projects perspective;
    3. Press OK.
  3. In the Welcome perspective, select the Projects view;
  4. In the Registry list, select org.eclipse.apogy.example.rover.apogy;
  5. Press Import . This will bring up the New Apogy Project wizard;
  6. Change the name of the project to MyFirstProject, then press Finish.
  7. In the Workspace list, select the project you just created, then press Open.
  8. Verify that the Workspace list displays your project as <Active> MyFirstProject

You now have you first Apogy Session loaded ! This session contains a Integrated Rover System, a Surface Worksite (the Mars Emulation Terrain at the Canadian Space Agency) and a few Programs.

Instantiating the Variables

Before we start our system, we will open the Programs perspective to get ready for invoking commands.

  1. Open the Programs perspective if not already opened:
    1. In the top menu bar, select Open New Perspective. This will open the Add Perspective pop-up.
    2. In the pop-up, select the Programs perspective;
    3. Press OK.

The Programs perspective provides the view required to created, edit, delete and invoque Programs. At this point, we will bring up the 3D Viewer to show what is in the environment:

  1. In the top menu bar, select Window→Show View. This will open the Add View pop-up.
    1. In the pop-up, select the Apogy Views→3D Viewer view;
    2. Press OK.

The 3D Viewer should show the terrain, the sky, and possibly the Sun, the Moon and the stars (depending on the time-of-day). We are ready to instantiate our system:

  1. On the status bar, confirm that the Context shows Simulated.
  2. Press Start. The Start button should become disabled, and the Stop button enabled.

The rover Variable has now been instanciated. In the 3D Viewer, you should see the rover standing on the corner of the terrain. We are almost ready to roll!

Invoking Existing Commands

We are now ready to invoke commands on the rover. For now, we will used the commands (or Operation Call in Apogy parlance) :

  1. In the Programs perspective, select the Programs view;
  2. In the Programs list, select A.B;
  3. Select the Program view: it should be display a list of Operation Call.
  4. In the Operation Call, select Start, then press Invoke. This will start the rover.
  5. Ensure you have the 3D Viewer showing the rover and the terrain.
  6. In the Operation Call, select Move Forward, then press Invoke. The rover should start moving forward.
  7. In the Operation Call, select Stop Motion, then press Invoke. The rover should stop moving.

You may have noticed that flags displaying a date have been popping-up in the 3D Viewer as Operation Call were being invoked. These flags mark the location of the System when the Operation Call returned and show the time at which the Operation Call execution completed.

Preventing the rover from moving through the terrain

You may have noticed that the rover wheels where driving through the terrain, and not on top of it. This is due to the very simple simulation that is updating the rover position based on its speed (the rover only moves on the XY plane and changes its azimuth). This is of course, not very realistic.

Apogy provides a PoseCorrector concept that can be used to maintain a System wheels (or feet in the case of the example Lander) in contact with the ground. Lets enable the pose corrector. For this, we will use the Vehicle Pose view:

  1. In the top menu bar, select Window→Show View. This will open the Add View pop-up.
    1. In the pop-up, select the Vehicle Pose view;
    2. Press OK.
  2. In the Vehicle Pose view, press Select.... This will bring up the Variable Feature Reference wizard.
  3. In the wizard, under Variable, select rover, then under Sub-Type, select mobilePlateform;
  4. Press OK
  5. In the Vehicle Pose, select the Pose Corrector tab;
  6. Check enabled
  7. Invoke the Operation Call used before : The rover wheels should now follow the terrain !

Creating New Commands

Up to now we have been invoking Operation Call that were already defined in a program. Lets now create our own Operation Call:

  1. In the Programs perspective, select the Programs view;
  2. Select the TODO Program Group, then press New Program. This will bring up the New Program Wizard:
  3. On the left side, select OperationCallsList (this is a Program that is a simple list of Operation Call)
  4. Press Next;
  5. Change the program's name to MyFirstProgram; press Finish.
  6. In the Program List, select the program you just created.
    1. Select the Program view, then press New. This will bring up the New Operation Call wizard;
  7. Change the name to Deploy Arm, then press Next;
  8. Select the roboticArm sub-system as the system we want to use:
    1. Under Variable, select rover;
    2. Under Sub-Type, select integratedRoboticArm→roboticArm;
  9. Now lets select the operation we want to call:
    1. Under Operation, select moveTo(EDouble, EDouble, EDouble, EDouble), then press Next;
    2. Lets set the operation parameters (here the destination joint angles values):
    3. In the left end side, select the first argument (turretAngle) and type its value (0.0 degrees) in the Value field on the right.
    4. Repeat the previous step for each of the arguments:
      1. shoulderAngle = 0.0 degrees
      2. elbowAngle = -90.0 degrees
      3. wristAngle = 0.0 degrees
  10. Save the session by pressing the Save button in the top menu.
  11. Test you command by pressing Invoke!

Browsing the Data Product

Up to now, we have been issuing commands, but we have not been looking at the Data Product (i.e. return value) generated by the Operation Calls. Lets do that now:

  1. Open the Data Products perspective if not already opened:
    1. In the top menu bar, select Open New Perspective. This will open the Add Perspective pop-up.
    2. In the pip-up, select the Data Products perspective;
    3. Press OK.
  2. In the Data Products Search, select the first Start operation call.
  3. The Data Products Details view now shows the metadata associated with the result of the operation call such as:
    1. The Context that was active when the call was made;
    2. The name and description that have been associated with result;
    3. The Relative pose of the result relative to the System that executed the call;
    4. The absolute pose of the result relative to the active Worksite;
    5. The time at the reception of the result;
  4. The Data Products Value Details now show the actual value return (in our case, a Boolean value).

The User Interface

Working with Perspectives

Apogy makes use of the Perspective concept as defined in E4. A Perspective is a group of Views that are related to each other or are used together for a given task. In Apogy:


Opening , creating and selecting Perspective is done from the top menu.

Apogy provides a few Perspectives that are used for basics functions:

Name Description Included Views View Description
Welcome Default perspective that is shown when you first launch Apogy. Welcome Show the welcome message for Apogy.
Projects View used to create / load / import and export Sessions.
Systems Perspectives used to defined Variable, Context and Initial Conditions. Programs Views used to display, create and delete Program Groups and Program.
Program View used to edit and invoke a Program and its Operation Calls.
Arguments View used to edit Operation Calls arguments.
Documentation View used to display documentation associated with the selected Operation Calls or Operation Calls arguments.
Earth Surface Perspective used to create / edit Earth Surface Worksites. Earth Surface Worksites Show the list of available Earth Surface Worksites and allows the user to create / import / export / delete and activate Earth Surface Worksites.
Maps View used to create / edit and delete the Maps contained in a Earth Surface Worksites.

The 3D Viewer

The Camera View

Copyright © Eclipse Foundation, Inc. All Rights Reserved.