Moxie Tutorials
Overview
Whether you are new to Moxie or already experienced, Moxie comes with several self-paced tutorials to advance your skills:
- Creating your first Moxie simulation
- Enhancing your simulation with useful SysML features
- Integrating with STK to create a digital mission simulation
Each of these tutorials is also broken up into several sections that focus on specific topics. Each tutorial builds on the preceding tutorial, and each section builds on the preceding section, with the complexity increasing as you progress. You can walk through the tutorials from start to finish, or customize your learning experience and skip around, as each section specifies the prerequisite No Magic project file (.mdzip) and/or STK scenario file (.vdf) that you will need from the Moxie installation in order to get started.
After completing the tutorials, you will have learned how to:
- Construct a Moxie simulation from scratch.
- Integrate an external analysis tool into your simulation using the Moxie delegate architecture.
- Perform continuous and discrete event detection using Moxie's core models, opaque expressions, and delegates.
- Debug a Moxie simulation in your modeling tool and Java IDE.
- Use Moxie's reports and utilities to streamline your development experience.
Thank you for choosing Moxie, and please be sure to reach out if you have any questions or feedback for our team.
Creating your first Moxie simulation
In this tutorial, you will quickly learn how to set up and run a Moxie simulation project. In doing so, you will create a simple SysML model of an Unmanned Aerial Vehicle (UAV), its power system, and onboard computer, which you will expand upon in the next tutorials. In this first tutorial, you will not bother with any actual physics modeling, just a basic model of the system's internal behavior. In the next tutorial, you will continue to build out the SysML model, and in the final tutorial, you will add the physics using STK.
| Section | Description |
|---|---|
| Configuring a Moxie Simulation Project |
Before you can run a simulation with Moxie, you need to ensure your No Magic project (.mdzip) is configured correctly. There are two ways to do this:
This section covers the following concepts: |
| Modeling a System with a Block Definition Diagram |
When modeling a system or system of systems in SysML, you should start by creating a block definition diagram (BDD). A BDD is simply a view of the structural elements of your system (the blocks) and their relationships with one another. In this section, you will create a high-level BDD that models an Unmanned Aerial Vehicle (UAV), its power system, and its onboard computer. This section covers the following concepts:
|
| Adding Properties and Operations to Blocks |
After outlining a system by creating a BDD, you need to fill in the details of the blocks so that they accurately model your system. Properties, operations, and relationships all help describe blocks and their interactions. In this section, you will add properties and operations to your blocks and create composite and associative relationships between them. This section covers the following concepts:
|
| Creating Instances with an Instance Specification Diagram |
After defining your blocks, you need to create instance specifications for them so that you can use them in your simulation. Instance specifications allow you to set the initial property values for the blocks in your simulation. In this section, you will create an instance specification diagram containing instance specifications for each of the blocks in your BDD. This section covers the following concept:
|
| Modeling Behavior in a Simple State Machine |
Before you can run a simulation using Moxie, you need to create a state machine to describe the behavior of your system. If you are not familiar with the concept of a state machine, you may want to read the introductory paragraphs of the state machines section in the SysML Modeling Reference. In this section, you will create a simple SysML state machine to model the behavior of powering on the UAV. This section covers the following concept:
|
| Running a Simulation with Moxie |
Once you have described both the structure and behavior of your system, you are ready to run a simulation! If you completed the previous sections, then you already modeled a simple system of a UAV, its power system, and its onboard computer. In this section, you will execute the state machine for your system and observe its operation. This section covers the following concepts:
|
Start Tutorial!
Enhancing your simulation with useful SysML features
In the previous tutorial, you created a basic SysML model of a UAV. In this tutorial, you will learn about useful SysML features for simulation, and add them to that model, improving the subsystems' behavior and adding interactions between the subsystems. You will use an even further expanded version of this UAV system model in the final tutorial when you integrate it with STK to model an entire digital mission.
| Section | Description |
|---|---|
| Executing Multiple State Machines |
Simulating behaviors at the mission level often requires multiple state machines. In this section, you will create a state machine for the UAV's onboard computer and a simulation dashboard that allows you to view the execution of both the computer and power system's state machines at the same time. You will also use the simulation state history log to help debug your simulation. This section covers the following concepts: |
| Adding Execution Logic with Guards and Effects |
State machine execution logic is defined by triggers, guards, and effects. A trigger is an event that indicates when a transition should be traversed (immediately, if unspecified); you will explore triggers in later sections. A guard specifies whether a transition may be traversed, and an effect specifies what happens if it is traversed. In this section, you will use an effect to turn on the power system and then a choice and guards to determine the power system's state. This section covers the following concepts:
|
| Identifying Errors with the Model Validation Report |
Opaque expressions require precise syntax, but since they are manually typed into your modeling tool, they are prone to error. Even a single misspelled block property or operation in a transition effect will cause Moxie to throw an exception at simulation run time. Fortunately, Moxie provides a model validation report to assist you in identifying these errors before you run your simulation. In this section, you will intentionally introduce a couple of errors into your simulation and then use the model validation report and element locator to find the errors so that you can fix them. This section covers the following concepts:
|
| Coordinating State Machines with Call Events |
In a complex mission simulation, the systems involved interact with one another as you carry out the mission objectives. So, in SysML, the state machines for those systems must interact with each other. You can achieve this in Moxie in two ways: call events and signal events. However, signal events in Moxie require using the delegate architecture, so you will not use them until the Signal Events section of the next tutorial. Call events enable state machines to invoke operations on their owning instance or on instances that their owning instance refers to. In this section, you will use a call event to have the computer turn on the power system instead of having the power system turn itself on at the start of the simulation. This section covers the following concept: |
| Scheduling Transitions with Time Events |
Most complex simulations require the execution of behaviors at specific times, which you can do with either absolute or relative time events. Absolute time events allow you to specify a precise moment in time to trigger a transition, while relative time events allow you to specify a time duration to wait before triggering a transition. In this section, you will use time events to specify the simulation time at which the computer should turn on the power system, and how long to wait before checking whether or not the power system successfully turned on. This section covers the following concept:
|
| Simulating Simultaneous Behaviors with Composite States |
In order to simulate simultaneous behaviors within a state machine, you must use a composite state. A composite state is a single state divided into orthogonal regions, each of which contains substates that represent that region's behavior. The substates are only mutually exclusive within each region, not across regions, so that all of the regions can execute at the same time. In this section, you will use a composite state to simulate the computer interacting simultaneously with both the power system and the flight controller. This section covers the following concepts: |
| Creating Reactive Transitions with Change Events |
In addition to call events and time events, another way to initiate behaviors in a Moxie simulation is through change events.
A change event evaluates a boolean expression over time
and triggers its transition when the expression changes from This section covers the following concept: |
| Handling Multiplicity in State Machines |
Multiplicity defines the number of instances that can exist for a given part or reference property.
For example, assume the UAV in this tutorial is a quadcopter with exactly four distinct motors: one to power each propeller.
This translates to a multiplicity of This section covers the following concepts:
|
Start Tutorial!
Integrating with STK to create a digital mission simulation
In the first and second tutorials, you modeled the subsystems of a UAV in SysML, and used Moxie to simulate various interactions between those subsystems. In this final tutorial, you will integrate a final version of that UAV system model with a physical environment modeled in STK to collectively model an entire digital mission. You will then run the digital mission simulation to see how well the UAV carries out its objective as it reacts to other objects in the environment.
In this tutorial, you will write Java delegates, build them with Gradle, and run STK. Please make sure you have installed all of the prerequisites before beginning.
| Section | Description |
|---|---|
| Examining the Mission Components |
Modeling a mission in SysML is essentially the same as modeling a system. You define the blocks, instance specifications, and state machines for the actors in the mission, and then you can use Moxie to execute the simulation. The difference is that mission simulations often require modeling high-fidelity, time-dynamic, physics-based aspects of the systems and environment. With Moxie, you can integrate analysis tools like Systems Tool Kit (STK) into your simulation and let them handle those physics complexities implicitly, without needing to explicitly build the physics into your SysML. In this section, you will examine a pre-made STK scenario of a UAV flying a mission, as well as a SysML model based on the previous tutorials but updated to include the important elements of the mission. |
| Creating a Delegate Module |
A delegate is a Java interface or class that uses custom code to implement the properties and operations of its corresponding SysML block. A delegate module is just a JAR file containing a group of delegates for Moxie to use as it executes a simulation. In this section, you will configure a delegate module project template for your environment and then build and install a delegate module JAR file for the UAV mission. Since you will not have written any delegates, the JAR file will not do anything yet. You will simply have verified that you are set up to start writing custom delegates. This section covers the following concept: |
| Streamlining Development with the Java Delegate Code Generator |
Moxie provides a Java delegate code generator that can generate delegate interfaces for all of the blocks in a SysML model, class stubs for the blocks, and a delegate provider that registers the delegate module with the Moxie Engine at runtime. These generated files include everything that the Moxie Engine needs in order to connect the delegates to the SysML model, allowing you to focus on the methods that need custom implementations. In this section, you will generate delegates for the UAV mission and install them for Moxie to use. This section covers the following concepts:
|
| Handling Circular Dependencies with Delegate Wire-Up |
SysML permits circular dependencies, and it can be very useful for two blocks to each have a reference to the other, but it can also cause instantiation problems in executable software. Fortunately, the Moxie Engine wires up the delegates in such a way that you can avoid these problems while retaining the usefulness of mutual references. In this section, you will use the delegate wire-up to safely establish the circular dependencies between the UAV, computer, and ground station delegates. This section covers the following concept:
|
| Logging Messages and Debugging Delegates |
As when writing any custom code, when writing your delegates you will likely want to have them log messages and to debug them in your Integrated Development Environment (IDE). Moxie makes both of these tasks more convenient by providing a built-in simulation logger and by configuring your No Magic modeling tool for debugging for you. In this section, you will debug an exception using both log messages and your Java IDE's debugger. This section covers the following concepts:
|
| Coordinating State Machines with Signal Events |
Similarly to call events, which you learned about in the previous tutorial, signal events enable state machines to interact with each other. Signal events, however, are less direct: they trigger in response to a signal from another state machine instead of being called directly by that state machine. Additionally, these signals can only be sent in a Moxie simulation from within the delegate code. In this section, you will replace the ground station's call to shutdown the UAV with a signal event. This section covers the following concepts:
|
| Connecting to STK from Delegates |
The Moxie Engine uses analysis tool controllers to communicate with external tools like STK. At the start of a simulation, an analysis tool controller instantiates all of the delegates associated with it, injecting dependencies from the external tool into the delegates for them to use. You can implement custom analysis tool controllers for other tools, but since the UAV mission only requires STK, you will just use Moxie's STK controller in this tutorial. In this section, you will set up the STK controller and its STK toolbox dependency, initialize the STK object data, and use a SysML stereotype to configure the simulation to start the STK scenario when the simulation starts. This section covers the following concepts:
|
| Integrating with STK from Delegates |
Integrating with external analysis tools like STK involves passing information back and forth to control all of the tools together as a single simulation. Timing information is especially important, and this is where Moxie excels. Moxie manages time continuously instead of requiring external tools to use discrete time steps, and it supports multiple time formats, including ISO8601, Gregorian, Julian, and STK's native representations. In this section, you will use the delegates to set (1) the UAV takeoff time in the STK scenario based on the SysML model, and (2) the flight duration in the SysML based on the route in the scenario. This section covers the following concepts:
|
| Detecting Events using Continuous Time |
Moxie allows external tools to perform complex analysis over time naturally, instead of forcing them to use shared discrete time steps. This is especially helpful for analytical calculations that do not require time steps at all. The Moxie Engine can then ingest this analysis as time-varying values and use those values for triggering change events. In this section, you will use STK Access to compute the BooleanValue for when the sensor should take a photo. You will also control the camera in the STK scenario to point at and actually take photos of the objects of interest. This section covers the following concepts: |
Start Tutorial!