Custom Simulated Entities

Glossary Item Box

Custom Simulated Entities

This tutorial shows how to write custom entities in C# that automatically start their appropriate services when they are loaded from a simulation engine scene file. This tutorial assumes you have completed the "Simulation Empty Project" tutorial. This tutorial begins where the "Simulation Empty Project" tutorial left off.

This tutorial teaches you how to:

• Adding the required references
• Creating the SimulatedLRFEntity
• Creating additional custom entities

This tutorial is provided in the C# language. You can find the project files for this tutorial at the following location under the Microsoft Robotics Developer Studio installation folder:

Samples\SimulationTutorials\Intermediate\Custom Simulated Entities

Adding the required references

We will be creating simulated entity versions for the following services:

• SimulatedLRF
• SimulatedSonar
• SimulatedIR
• SimulatedColorSensor
• SimulatedGPSSensor
• SimulatedBrightnessSensor
• SimulatedCompass

Add the following references as shown in the "Simulation Empty Project" tutorial.

• SimulatedLRF.Y2006.M05.proxy
• SimulatedSonar.Y2006.M05
• SimulatedSonar.Y2006.M05.proxy
• SimulatedIR.Y2006.M05.proxy
• SimulatedIR.Y2006.M05
• SimulatedColorSensor.Y2006.M05.proxy
• SimulatedGPSSensor.Y2006.M05.proxy
• SimulatedBrightnessSensor.Y2006.M05.proxy
• SimulatedCompass.Y2008.M11.proxy

Remember to set "CopyLocal" to false on the reference properties. Also, if you did not previously add the Microsoft.Xna.Framework assembly to the list of references, you will need to add that assembly as well.

The non-proxy versions of the SimulatedSonar and SimulatedIR services are needed because they define an entity in their service. The SimulatedSonarEntity and SimulatedIREntity will need to derive from the entity in the assembly and not the proxy (since it is a different type). It is important to derive a custom entity from the non-proxy version of the entity. Otherwise the entity will not behave as expected in the simulator.

Creating the SimulatedLRFEntity

We will walk through creating a custom entity for the SimulatedLRF service. Creating the other entities follow a very similar process. In most cases, there already exists an entity in the SimulationEngine assembly that is somewhat related to one of the simulation sample services. Consider the SimulatedLRF service. There is an entity called LaserRangeFinderEntity in the SimulationEngine that the SimulatedLRF service uses. All we want to do is extend this entity so it creates the SimulatedLRF service when it is loaded by the simulator. To do this, we derive a new VisualEntity from the LaserRangeFinderEntity and set the ServiceContract to the SimulatedLRF's Contract.Identifier member.

The code for this is shown below. Insert this code outside of the service class. We do not support nested classes when the nested class contains the [DataContract] attribute.

/// <summary>
/// SimulatedLRFEntity is a LaserRangeFinderEntity that automatically starts the simulated 
/// LRF service
/// </summary>
[DataContract]
public class SimulatedLRFEntity : LaserRangeFinderEntity
{
    public SimulatedLRFEntity() { }
    public SimulatedLRFEntity(Pose localPose) : base(localPose) { }

    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        ServiceContract = simlrf.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

Before building, you should add the below using statements.

using Microsoft.Robotics.Simulation.Engine;
using Microsoft.Robotics.PhysicalModel;
using xna = Microsoft.Xna.Framework.Graphics;
using Microsoft.Robotics.Simulation.Physics;

using simlrf = Microsoft.Robotics.Services.Simulation.Sensors.LaserRangeFinder.Proxy;
using simsonar = Microsoft.Robotics.Services.Simulation.Sensors.Sonar.Proxy;
using siminfrared = Microsoft.Robotics.Services.Simulation.Sensors.Infrared.Proxy;
using simcolorsensor = Microsoft.Robotics.Services.Simulation.Sensors.ColorSensor.Proxy;
using simbrightnesssensor = Microsoft.Robotics.Services.Simulation.Sensors.BrightnessSensor.Proxy;
using simcompass = Microsoft.Robotics.Services.Simulation.Sensors.Compass.Proxy;
using simgps = Microsoft.Robotics.Services.Simulation.Sensors.Compass.Proxy;
using Microsoft.Dss.Services.Constructor;
using System.Runtime.InteropServices;

Creating additional custom entities

The process to create the other entities is very similar to the SimulatedLRFEntity. The source for the other entities is shown below.

/// <summary>
/// SimulatedSonarEntity is a SonarEntity that automatically starts the simulated
/// sonar service
/// </summary>
[DataContract]
public class SimulatedSonarEntity : Microsoft.Robotics.Services.Simulation.Sensors.Sonar.SonarEntity
{
    public SimulatedSonarEntity() { }
    public SimulatedSonarEntity(Pose localPose) : base(localPose) { }

    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        ServiceContract = simsonar.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

/// <summary>
/// SimulatedIREntity is an IREntity that automatically starts the simulated
/// IR service
/// </summary>
[DataContract]
public class SimulatedIREntity : engine.IREntity
{
    public SimulatedIREntity() { }
    public SimulatedIREntity(Pose localPose) : base(localPose) { }

    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        ServiceContract = siminfrared.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

/// <summary>
/// SimulatedColorSensorEntity is an CameraEntity that automatically starts the simulated
/// color sensor service
/// </summary>
[DataContract]
public class SimulatedColorSensorEntity : CameraEntity
{
    public SimulatedColorSensorEntity() { }

    public SimulatedColorSensorEntity([DefaultParameterValue(32)] int viewSizeX,
        [DefaultParameterValue(32)] int viewSizeY, [DefaultParameterValue(2.0f * (float)Math.PI / 180.0f)] float halfViewAngle)
        : base(viewSizeX, viewSizeY, halfViewAngle)
    {
    }

    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        IsRealTimeCamera = true;
        ServiceContract = simcolorsensor.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

/// <summary>
/// SimulatedBrightnessSensorEntity is an CameraEntity that automatically starts the 
/// simulated brightness sensor service
/// </summary>
[DataContract]
public class SimulatedBrightnessSensorEntity : CameraEntity
{
    public SimulatedBrightnessSensorEntity() { }

    public SimulatedBrightnessSensorEntity([DefaultParameterValue(32)] int viewSizeX,
        [DefaultParameterValue(32)] int viewSizeY, [DefaultParameterValue(2.0f * (float)Math.PI / 180.0f)] float halfViewAngle)
        : base(viewSizeX, viewSizeY, halfViewAngle)
    {
    }

    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        IsRealTimeCamera = true;
        ServiceContract = simbrightnesssensor.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

/// <summary>
/// SimulatedCompassEntity is a VisualEntity that automatically starts the 
/// simulated compass sensor service
/// </summary>
[DataContract]
public class SimulatedCompassEntity : VisualEntity
{
    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        ServiceContract = simcompass.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

/// <summary>
/// SimulatedGPSEntity is a VisualEntity that automatically starts the 
/// simulated GPS sensor service
/// </summary>
[DataContract]
public class SimulatedGPSEntity : VisualEntity
{
    public override void Initialize(xna.GraphicsDevice device, PhysicsEngine physicsEngine)
    {
        ServiceContract = simgps.Contract.Identifier;

        base.Initialize(device, physicsEngine);
    }
}

After building this project, you can then use these custom entities in future tutorials by adding a reference to CustomSimulatedEntities.dll which can be found in the bin folder relative to where you install Microsoft Robotics Developer Studio.

Summary

In this tutorial, you learned how to:

• Adding the required references
• Creating the SimulatedLRFEntity
• Creating additional custom entities

© 2012 Microsoft Corporation. All Rights Reserved.