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"

(→‎Introduction)
(→‎Apogy User's Guide)
Line 1: Line 1:
 
= Apogy User's Guide =
 
= Apogy User's Guide =
  
−
== Table Of Contents ==
+
= Table Of Contents =
 
__TOC__
 
__TOC__
  
−
== Introduction ==
+
= 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 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.
  
Line 17: Line 17:
 
# Makes use of Open Source librairies that are Eclipse Public License compatible;
 
# Makes use of Open Source librairies that are Eclipse Public License compatible;
  
−
== Concepts ==
+
= Overview =
  
 
In Apogy, users control Systems by invoking commands (through Programs) and monitor the System's health through telemetry (i.e. states).  
 
In Apogy, users control Systems by invoking commands (through Programs) and monitor the System's health through telemetry (i.e. states).  
Line 31: Line 31:
 
The System's command produces result (i.e. returned value, such as an Image, an error code, etc.) that Apogy geo 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.
 
The System's command produces result (i.e. returned value, such as an Image, an error code, etc.) that Apogy geo 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.
  
−
=== Session ===
+
== Installing Apogy ==
  
−
In Apogy, the ''Session'' is the entity that contains all the configuration and data that are required to make use of ''Systems''. The session is implemented as an Eclipse Project with an Apogy nature, and as such, is mapped to the host file system. Sessions can be exported/imported to and from archived files (''.zip'').
+
== Launching Apogy ==
  
−
The ''Session'' project includes a central resource (''session.sym'') that contains most of the configuration elements (Variable, Context, InitialCondition, etc) and also has referecens to other ressources contained in the project (scripts, data products, etc). In Apogy there is <u>at most one active Session at any given time</u>.
+
= Quick Start =
  
−
The Session contains:
+
To get started quickly, we will import an existing session (one of the example) and then used it to command the Rover example.
  
−
# the [[Apogy/UserGuide#Environment|''Environment'']] being used;
+
== Importing an Existing Session ==
−
# the list of [[Apogy/UserGuide#Programs|''Programs'']] that can be executed;
+
−
# the list of available [[Apogy/UserGuide#Initial Conditions|''InitialConditions'']];
+
−
# the list of [[Apogy/UserGuide#Tools|''Tools'']] that are available.
+
  
−
=== Systems ===
+
#Launch Apogy.
 +
#Open the ''Welcome'' perspective if not already opened:
 +
##In the top menu bar, select [[Image:Apogy_Perspective_Icon.png|Open New Perspective]]. This will open the ''Add Perspective'' pop-up.
 +
## In the pip-up, select the '''''Projects''''' perspective;
 +
## Press ''OK''.
 +
#In the ''Welcome'' perspective, select the '''''Projects''''' view;
 +
#In the ''Registry'' list, select '''''org.eclipse.apogy.example.rover.apogy''''';
 +
#Press ''Import'' . This will bring up the ''New Apogy Project'' wizard;
 +
#Change the name of the project to '''''MyFirstProject''''', then press ''Finish''.
 +
#In the ''Workspace'' list, select the project you just created, then press ''Open''.
 +
#Verify that the ''Workspace'' list displays your project as '''''<Active> MyFirstProject'''''
  
−
In Apogy, a ''System'' is an entity that can execute commands and provide its state information. Typically ''Systems'' represent actual hardware (ex: a rover, a camera, a robotic arm) but can be used to represent something more abstract (a planning system, a resource dispatcher, etc.).  
+
You now have you first Apogy Session loaded ! This session contains a Rover System, a Surface Worksite (the Mars Emulation Terrain at the Canadian Space Agency) and a few Programs.  
  
−
In Apogy, a user makes use of the ''Systems'' to perform tasks in a given ''Environment''. The ''System'' supports commands and reports on it status through its telemetry : the ''System'' is defined by its interfaces. Given this definition, a ''System'' can be modeled as a class : ''methods'' represent commands (with their parameters and return value) and the ''attributes'' represent states returned as part of telemetry. In Apogy, a ''System'' is defined using the [https://www.eclipse.org/modeling/emf/ Eclipse Modeling Framework].
+
== Instanciating the Variables ==
  
−
In Apogy a ''System'' is named and is defined in EMF model. This model includes:
+
Before we start our system, we will open the ''Programs'' perspective to get ready for invoking commands.
 +
#Open the ''Programs'' perspective if not already opened:
 +
##In the top menu bar, select [[Image:Apogy_Perspective_Icon.png|Open New Perspective]]. This will open the ''Add Perspective'' pop-up.
 +
## In the pip-up, select the '''''Programs''''' perspective;
 +
## Press ''OK''.
  
−
# The [[Apogy/UserGuide#System Interface Class|System Interface Class]] defining the commands and attributes it supports;
+
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:
−
# A list of Connection Points where other sub-system can be attached;
+
#In the top menu bar, select Window-Show View. This will open the ''Add View'' pop-up.
−
# A list of Assembly Links that are used to assemble a System's sub-System (in composite Systems);
+
## In the pip-up, select the '''''Apogy Views-3D Viewer''''' view;
−
# A topology of nodes that are used to defined the system representation in 3D;
+
## Press ''OK''.
−
# A list of Topology Bindings that are used to bind attributes of the interface class to behavior in the topology (ex: binding the value of a 3D transform  to the value of a revolute joint position);
+
  
 +
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 inctanciate our systems:
  
−
Simple ''Systems'' can be assembled together to create composites ''Systems'' (ex: [[Apogy/Examples#Integrated Rover | Integrated Rover Example]]). This allows sub-systems to be modeled independently and reused as part of different assemblies. The assemblies of ''Systems'' is supported through ''System Type Members'', ''Connection Points'' and ''Assembly Links''.
+
#On the status bar, confirm that the Context shows Simulated.
 +
#Press ''Start''. The ''Start'' button should become disabled, and the ''Stop'' button enabled.
  
−
==== System Interface Class ====
+
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!
  
−
The System's Interface Class refers to the ''EClass'' that defined the methods and attributes of the System. Only methods and attributes defined in the interface can be accessed by Apogy to create commands, display values, bind attributes, etc.
+
== Invoking Existing Commands ==
  
−
==== System Type Members ====
+
We are now ready to invoke commands on the rover. For now, we will used the commands (or ''Operation Call'' in Apogy parlance) :
  
−
Composite System contains ''Type Members'' that refers to other ''System''. This is the pattern used by Apogy to implement ''composite data type'' (ex: [https://en.wikipedia.org/wiki/Struct_(C_programming_language)  struct in C programming language] ). These ''Type Members'' can be made accessible to the parent ''System''.  
+
#In the ''Programs'' perspective, select the '''''Programs''''' view;
 +
#In the ''Programs'' list, select ''A.B'';
 +
#Select the ''Program'' view: it should be display a list of ''Operation Call''.
 +
#In the ''Operation Call'', select ''Start'', then press ''Invoke''. This will start the rover.
 +
#Ensure you have the 3D Viewer showing the rover and the terrain.
 +
#In the ''Operation Call'', select ''Move Forward'', then press ''Invoke''. The rover should start moving forward.
 +
#In the ''Operation Call'', select ''Stop Motion'', then press ''Invoke''. The rover should stop moving.
  
−
{| class="wikitable"
+
== Preventing the rover from moving through the terrain ==
−
|-
+
−
|  colspan="1" style="text-align:center; | [[File:Apogy_Composite_System.png|500px|alt=]]
+
−
| ''An example of a composite System and its Type Members. For example, type member platform is of type MobilePlatform.
+
−
|}
+
−
 
+
−
 
+
−
Apogy allows operations to be called on a composite System's Type Member (ex: calling rover→mobilePlateform.moveForward(1.25)) in a hierarchical fashion. In the same way, attributes of sub-system can be accessed (rover→mobilePlateform.leftWheelPosition).
+
−
 
+
−
System can be compose at multiple levels (i.e. a System can have type members that are themselves composites Systems and so on.). The [[Apogy/Examples#Integrated Rover | Integrated Rover]] is an example of such a System.
+
−
 
+
−
==== Connection Points ====
+
−
 
+
−
''Connection Points'' define physical locations where other sys-system are expected to be connected. To used the analogy of a construction toy's blocks, connections point points define the brick studs.
+
−
 
+
−
{| class="wikitable"
+
−
|-
+
−
|  colspan="1" style="text-align:center; | [[File:Apogy_System_Connection_Points_And_Topology.png|300px|alt=]]
+
−
| A System connection points and relationship to the System's topology. connection points (yellow rectangles) and topology Nodes (blue rounded rectangles).
+
−
|}
+
−
 
+
−
They are named and refer to a Node defined in the System's topology. The ''root connection point'' is implicit and always refer to the System's root topology node.
+
−
 
+
−
==== Assembly Links ====
+
−
 
+
−
''Assembly Links'' describe how systems are attached to each other in composite ''Systems''.
+
−
 
+
−
{| class="wikitable"
+
−
|-
+
−
|  colspan="1" style="text-align:center; | [[File:Apogy_Composite_System_Assembly.png|300px|alt=]]
+
−
| A composite system assembly using connection points (yellow rectangles) and assembly links (black arrows). The ''IntegratedRoboticArm'' sub-system is attached to the ''Front'' Connection Point located on the ''MobilePlateform'', while the ''Camera1'' sub-system is connected to the ''Top'' connection point.
+
−
|}
+
−
 
+
−
 
+
−
In the construction toy's analogy, the assembly links represent a construction set's instructions. The assembly links are named and refers to their parent's connection point to which the subsystem ''root connection point'' is attached.
+
−
 
+
−
=== Variables ===
+
−
 
+
−
A user can define multiple instances for a given ''System'' (ex: '''''vehicle1''''' and '''''vehicle2''''' of type [[Apogy/Examples#Skid-Steered Wheeled Mobile Platform | MobilePlateformApogySystem]]). Similar to the way multiple variables of a given type can be defined in programming languages, Apogy uses the concept of ''Variable''.
+
−
 
+
−
Each ''Variable'' has a name (that should be unique) and refers to the type of ''System'' it represents. ''Variable'' can refer to simple or complex ''System''.
+
−
 
+
−
=== Contexts ===
+
−
 
+
−
When developing complex operations sequence or testing scripts that command ''Systems'' to perform tasks, a user often needs to run such commands on some sort of simulated version of the ''Systems''.
+
−
 
+
−
In other cases, during development, a specific sub-system of a larger assembly may not yet have an implementation that communicates with it's hardware (or the hardware may not yet be available). A way for the user to work on operational sequence or scripts should be made available.
+
−
 
+
−
In order to addresses such cases, Apogy makes use of ''Context''. At it's base, a ''Context'' maps ''Variable'' to actual implementations of the Interface Class of its ''System'' and sub-systems. By doing so, when a ''Variable'' is instanciated, the actual ''Interface Class Implementation'' specified in the ''Context'' is used. Used together with a ''System Interface'' sub-classes, the ''Context'' allows commands and script to be executed in a transparent fashion in diverse implementation settings.
+
−
 
+
−
{| class="wikitable"
+
−
|-
+
−
| colspan="1" style="text-align:center; | [[File:Apogy_Context_Example_1.png|600px|alt=Simulated Context active.]]
+
−
| colspan="1" style="text-align:center; | [[File:Apogy_Context_Example_2.png|600px|alt=Real Context active.]]
+
−
|-
+
−
| colspan="1" style="text-align:center; | ''Simulated'' Context selected as the active context.
+
−
| colspan="1" style="text-align:center; | ''Real'' Context selected as the active context.
+
−
|}
+
−
 
+
−
In the example above, 3 ''Variable'' have been defined:
+
−
 
+
−
# '''''myRover''''' : Refers to a System which Interface Class is ''Rover'', which has 2 sub-classes:
+
−
## ''RoverSimulated'' : A simulated implementation of the Rover;
+
−
## ''RoverReal'' : An implementation that connects to the actual hardware rover.
+
−
# '''''myArm''''' : Refers to a System which Interface Class is ''Arm'', which has 2 sub-classes:
+
−
## ''ArmSimulated'' : A simulated implementation of the Arm;
+
−
## ''ArmReal'' : An implementation that connects to the actual hardware robot.
+
−
# '''''myLidar''''' :  Refers to a System which Interface Class is ''Lidar''. In this cas, the Lidar hardware being no yet completed, only 1 sub-class is available:
+
−
## ''LidarSimulated'' : A simulated implementation of the Lidar;
+
−
 
+
−
The user has created 2 ''Context'' : '''''Simulated''''' and '''''Real'''''. In this case, both real and simulated version of the rover and arm are used, but the Lidar hardware not being available, both ''Context'' make use of the simulated implementation (LidarSimulated) of the Lidar. This setup allows command sequence or scripts to be developed and tested now using the Simulated context, and later used with the real world implementation when the actual Systems become available.
+
−
 
+
−
While many ''Context'' can be defined in a given ''Session'', only one can be selected as the active context. The ''Context'' definition includes:
+
−
# A name (should be unique);
+
−
# The DataSet where results will be stored. This allows result from different Context to be saved separately (this is often useful to keep data from a simulated run separate from data produced by actual, real System).
+
−
 
+
−
=== Environment ===
+
−
 
+
−
The Environment contains the following:
+
−
 
+
−
# the ''Variables'' in use
+
−
# the list of available ''Contexts'' and the one currently active;
+
−
# the list of available ''Worksite'' and the one currently active;
+
−
# the list of available ''Time Source'' and the one currently active;
+
−
 
+
−
Contains the definitions of worksite, time sources and Systems;
+
−
 
+
−
Defines what the user has to work with in a specific mission such as the System instances.
+
−
 
+
−
# Contains the definitions of the ''Worksite'', ''Time Sources'' and the registered ''Apogy Systems'';
+
−
# Defines what you have to work with in a specific deployment;
+
−
 
+
−
=== Time Source ===
+
−
 
+
−
Time Sources are used to feed the time to the Session. This in turns updates the position of the sky elements (Sun, Moon, Stars).
+
−
 
+
−
The Time Sources element contains the available Time Source, only one is set as the Session Active Time Source.
+
−
 
+
−
{| class="wikitable"
+
−
|-
+
−
! Type
+
−
! Description
+
−
|-
+
−
| Fixed Time Source
+
−
| A time source representing a fixed date and time.
+
−
|-
+
−
| Current Time Source
+
−
| A time source that represent the current time, updated a regular interval.
+
−
|-
+
−
| Selection based Time Source
+
−
| A time source that updates its time upon selection of any Timed element in the UI.
+
−
|-
+
−
| Browseable Time Source
+
−
| A time source that can browsed, reset, play forward or reverse and accelerated.
+
−
|}
+
−
 
+
−
=== Worksites ===
+
−
 
+
−
A ''Worksite'' represent the physical environment where the ''Systems'' are being used. While many ''Worksite'' can be defined in a given ''Environment''
+
−
 
+
−
# Defines the area that the System are operating in for the particular mission;
+
−
# Include a priori information about the area (e.g. Digital Elevation Maps (DEMs), orbital imagery, etc.);
+
  
 +
You may have noticed that the rover wheel 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 it azimuth). This is of course, not very realistic.
  
−
=== Programs ===
+
== Creating New Commands ==
  
−
TODO
+
== Browsing the Data Product ==

Revision as of 14:37, 28 August 2018

Apogy User's Guide

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

Launching Apogy

Quick Start

To get started quickly, we will import an existing session (one of the example) and then used it to command the 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 pip-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 Rover System, a Surface Worksite (the Mars Emulation Terrain at the Canadian Space Agency) and a few Programs.

Instanciating 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 pip-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 pip-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 inctanciate our systems:

  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.

Preventing the rover from moving through the terrain

You may have noticed that the rover wheel 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 it azimuth). This is of course, not very realistic.

Creating New Commands

Browsing the Data Product

Retrieved from "https://wiki.eclipse.org/index.php?title=Apogy/UserGuide&oldid=427241"

Back to the top