diff --git a/examples/src/SimkitOpenDis7Examples/run/OpenDisHelper.java b/examples/src/SimkitOpenDis7Examples/run/OpenDisHelper.java
new file mode 100644
index 0000000000000000000000000000000000000000..0febac3f0235a08a978e364d68d515b8e59f4a01
--- /dev/null
+++ b/examples/src/SimkitOpenDis7Examples/run/OpenDisHelper.java
@@ -0,0 +1,455 @@
+/**
+ * Copyright (c) 2008-2023, MOVES Institute, Naval Postgraduate School (NPS). All rights reserved.
+ * This work is provided under a BSD open-source license, see project license.html or license.txt
+ * @author brutzman@nps.edu
+ */
+package SimkitOpenDis7Examples.run;
+
+//import edu.nps.moves.dis7.entities.swe.platform.surface._001Poseidon;
+import edu.nps.moves.dis7.entities.swe.platform.surface._002Triton;
+import edu.nps.moves.dis7.entities.usa.platform.air.ScanEagleA15;
+import edu.nps.moves.dis7.enumerations.*;
+import edu.nps.moves.dis7.pdus.*;
+import edu.nps.moves.dis7.utilities.DisChannel;
+import edu.nps.moves.dis7.utilities.PduFactory;
+
+import java.nio.charset.Charset;
+import java.time.LocalDateTime;
+import java.util.logging.Level;
+import java.util.logging.Logger;
+
+import simkit.SimEntityBase;
+
+/** The OpenDisHelper is meant to be a transmitter/recorder of DIS PDUs in a DES environment
+ *
+ * Based on: NetworkedGraphicsMV3500/examples/src/OpenDis7Examples/ExampleSimulationProgram.java
+ *
+ * @author <a href="mailto:tdnorbra@nps.edu?subject=OpenDis7Examples.OpenDisHelper">Terry Norbraten, NPS MOVES</a>
+ */
+public class OpenDisHelper extends SimEntityBase
+{
+ /* **************************** infrastructure code, modification is seldom needed ************************* */
+
+ /** DIS channel defined by network address/port combination includes multiple utility capabilities */
+ protected DisChannel disChannel;
+ /** Factory object used to create new PDU instances */
+ protected PduFactory pduFactory;
+ /** ESPDU for entity 1 */
+ protected EntityStatePdu entityStatePdu_1;
+ /** ESPDU for entity 2 */
+ protected EntityStatePdu entityStatePdu_2;
+ /** FirePdu for entity 1 first weapon (if any) */
+ protected FirePdu firePdu_1a;
+ /** FirePdu for entity 1 second weapon (if any) */
+ protected FirePdu firePdu_1b;
+ /** MunitionDescriptor for these weapons */
+ protected MunitionDescriptor munitionDescriptor1;
+
+ private String descriptor;
+ /** seconds per loop for real-time or simulation execution */
+ private double simulationTimeStepDuration; // seconds TODO encapsulate
+ /** initial simulation time in seconds */
+ private double simulationTimeInitial;
+ /** current simulation time in seconds */
+ private double simulationTimeSeconds;
+ /** Maximum number of simulation loops */
+ private final int MAX_LOOP_COUNT;
+
+ private String narrativeMessage1;
+ private String narrativeMessage2;
+ private String narrativeMessage3;
+
+ // hey programmer, what other state do you want? this is a good place to declare it...
+
+ /**
+ * Constructor to create an instance of this class.
+ * Design goal: additional built-in initialization conveniences can go here
+ * to keep your efforts focused on the runSimulation() method.
+ */
+ // base constructor is not invoked automatically by other constructors
+ // https://stackoverflow.com/questions/581873/best-way-to-handle-multiple-constructors-in-java
+ public OpenDisHelper()
+ {
+ super();
+ OpenDisHelper.this.setDescriptor(this.getClass().getSimpleName());
+ simulationTimeStepDuration = 1.0d;
+ simulationTimeSeconds = simulationTimeInitial = 0.0d;
+ MAX_LOOP_COUNT = 4;
+ initialize();
+ }
+ /**
+ * Constructor to create an instance of this class.
+ * @param newDescriptor describes this program, useful for logging and debugging
+ */
+ public OpenDisHelper(String newDescriptor)
+ {
+ this();
+ OpenDisHelper.this.setDescriptor(newDescriptor);
+ }
+ /**
+ * Utility Constructor that allows your example simulation program to override default network address and port
+ * @param address network address to use
+ * @param port corresponding network port to use (> -1)
+ */
+ public OpenDisHelper(String address, int port)
+ {
+ this();
+
+ if (address != null && !address.isBlank())
+ OpenDisHelper.this.setAddress(address);
+
+ if (port > -1)
+ OpenDisHelper.this.setPort(port);
+ }
+
+ /** Initialize channel setup for OpenDis7 and report a test PDU
+ * @see initializeDisChannel
+ * @see initializeSimulationEntities
+ */
+ private void initialize()
+ {
+ initializeDisChannel(); // must come first, uses PduFactory
+
+ initializeSimulationEntities(); // set unchanging parameters
+
+ disChannel.join(); // TODO further functionality expected
+
+// String timeStepMessage = "Simulation timestep duration " + getSimulationTimeStepDuration() + " seconds";
+// disChannel.sendCommentPdu(simulationTimeSeconds, DisChannel.COMMENTPDU_SIMULATION_TIMESTEP, timeStepMessage);
+ // additional constructor initialization can go here
+ }
+
+ /** Initialize channel setup for OpenDis7 and report a test PDU */
+ private void initializeDisChannel()
+ {
+ if (disChannel == null)
+ disChannel = new DisChannel();
+ else
+ {
+ disChannel.printlnTRACE ("*** warning, duplicate invocation of initializeDisChannel() ignored");
+ return;
+ }
+ pduFactory = disChannel.getPduFactory();
+ disChannel.setDescriptor(descriptor); // ExampleSimulationProgram might be a superclass
+ disChannel.setUpNetworkInterface();
+
+ disChannel.setVerboseComments (false); // TODO rename library method to disambiguate CommentPDU
+ // TODO still seems really chatty... add silent mode?
+ disChannel.setVerboseDisNetworkInterface(false); // Default false
+ disChannel.getPduRecorder().setVerbose (true);
+ // TODO confirm whether recorder is explicitly started by programmer (or not)
+
+// disChannel.sendCommentPdu(VariableRecordType.OTHER, "DisThreadedNetworkInterface.initializeDisChannel() complete"); // hello channel, debug
+ }
+
+ /** Get ready, get set... initialize simulation entities. Who's who in the zoo? */
+ private void initializeSimulationEntities()
+ {
+ if (pduFactory == null)
+ pduFactory = disChannel.getPduFactory();
+ entityStatePdu_1 = pduFactory.makeEntityStatePdu();
+ entityStatePdu_2 = pduFactory.makeEntityStatePdu();
+ firePdu_1a = pduFactory.makeFirePdu();
+ firePdu_1b = pduFactory.makeFirePdu();
+ munitionDescriptor1 = new MunitionDescriptor();
+
+ // Your model setup: define participants. who's who in this zoo?
+ // Assuming you keep track of entity objects... here is some support for for Entity 1.
+
+ // PDU objects are already declared and instances created, so now set their values.
+ // who is who in our big zoo, sufficient for global participation if we need it
+
+ /***** Initialize each PDU to a known state *****/
+ entityStatePdu_1.getEntityID().setSiteID(1).setApplicationID(2).setEntityID(3); // made-up example ID;
+ disChannel.addEntity(entityStatePdu_1.getEntityID());
+ // TODO someday, use enumerations for sites as part of a SimulationManager object; e.g. is there a unique site triplet for MOVES Institute?
+
+ // Essential that we have a known initial state for DeadReckoningParameters
+ DeadReckoningParameters drp = entityStatePdu_1.getDeadReckoningParameters();
+
+ // Set Dead Reckoning Model (DRM), Rotational Velocity in World Coordinates (RVW)
+ drp.setDeadReckoningAlgorithm(DeadReckoningAlgorithm.DRM_RVW_HIGH_SPEED_OR_MANEUVERING_ENTITY_WITH_EXTRAPOLATION_OF_ORIENTATION);
+ /***** End Initialize pdu *****/
+
+ /***** Begin friendly vehicle specific DIS Enumerations *****/
+ entityStatePdu_1.setForceId(ForceID.FRIENDLY);
+ entityStatePdu_1.setEntityType(new ScanEagleA15()); // note import statement above
+ EntityType type = entityStatePdu_1.getEntityType();
+
+ // Use ASCII for the character set
+ entityStatePdu_1.getMarking().setCharacterSet(EntityMarkingCharacterSet.ASCII);
+ Charset cs = Charset.forName("US-ASCII");
+ byte[] charArray = cs.encode(type.toString() + entityStatePdu_1.getEntityID()).array();
+ entityStatePdu_1.getMarking().setCharacters(charArray);
+
+ type.setEntityKind(EntityKind.PLATFORM);
+ type.setDomain(Domain.inst(PlatformDomain.AIR));
+
+ // Zero until we know more about how we want to define capabilities
+ entityStatePdu_1.setCapabilities(new AirPlatformCapabilities());
+
+ // Need to set bits 1-32 for proper initialization
+ entityStatePdu_1.setEntityAppearance(0);
+
+ // Side number of SubCategory
+ type.setSpecific(0);
+
+ // Weapons loading?
+ type.setExtra((short) 0);
+ /***** End friendly vehicle specific DIS Enumerations *****/
+
+ entityStatePdu_2.getEntityID().setSiteID(1).setApplicationID(2).setEntityID(4); // made-up example ID;
+ disChannel.addEntity(entityStatePdu_2.getEntityID());
+ entityStatePdu_2.setForceId(ForceID.OPPOSING);
+ entityStatePdu_2.setEntityType(new _002Triton()); // note import statement above
+ entityStatePdu_2.setMarking("Entity #2");
+
+ // TODO how should we customize this munition? what are key parameters for your simulation?
+ // more is needed here by scenario authors...
+ munitionDescriptor1.setQuantity(1);
+ firePdu_1a.setDescriptor(munitionDescriptor1).setRange(1000.0f);
+
+ simulationTimeSeconds = simulationTimeInitial = entityStatePdu_1.getTimestamp();
+ }
+
+ /**
+ * This runSimulationLoops() method is for you, a customizable programmer-modifiable
+ * code block for defining and running a new simulation of interest.
+ *
+ * Welcome! Other parts of this program handle bookkeeping and plumbing tasks so that
+ * you can focus on your model entities and activities.
+ * Expandable support includes DIS EntityStatePdu, FirePdu and CommentPdu all available for
+ * modification and sending in a simulation loop.
+ * Continuous improvement efforts seek to make this program as easy and straightforward
+ * as possible for DIS simulationists to use and adapt.
+ * All of the other methods are setup, teardown and configuration that you may find
+ * interesting, even helpful, but don't really have to worry about.
+ */
+ @SuppressWarnings("SleepWhileInLoop") // yes we might do that
+ public void runSimulationLoops ()
+ {
+ try
+ {
+ final int SIMULATION_MAX_LOOP_COUNT = 10; // be deliberate out there! also avoid infinite loops.
+ int simulationLoopCount = 0; // variable, initialized at 0
+ boolean simulationComplete = false; // sentinel variable as termination condition, are we done yet?
+
+ // TODO reset Clock Time for today's date and timestamp to zero, providing consistent outputs for each simulation run
+ String timeMessage = "Simulation time " + simulationTimeSeconds + " at LocalDateTime " + LocalDateTime.now();
+ disChannel.sendCommentPdu(simulationTimeSeconds, DisChannel.COMMENTPDU_TIME, timeMessage);
+ // TODO replace enumeration with disChannel.COMMENTPDU_TIME
+ // TODO fix VariableRecordType.TIME_AMP_DATE_VALID
+
+ // ===================================================================================================
+ // loop the simulation while allowed, programmer can set additional conditions to break out and finish
+ while (simulationLoopCount < SIMULATION_MAX_LOOP_COUNT) // are we done yet?
+ {
+ simulationLoopCount++; // good practice: increment loop counter as first action in that loop
+
+ // =============================================================================================
+ // * your own simulation code starts here! *****************************************************
+ // =============================================================================================
+
+ // are there any other variables to modify at the beginning of your loop?
+
+ // are your reading any DIS PDUs from the network? check for them here
+
+ // compute a track, update an ESPDU, whatever it is that your model is doing...
+
+ // Where is my entity? Insert changes in position; this sample only changes X position.
+ entityStatePdu_1.getEntityLocation().setX(entityStatePdu_1.getEntityLocation().getX() + 1.0); // 1m per timestep
+
+ // decide whether to fire, and then update the firePdu. Hmmm, you might want a target to shoot at!
+
+ // etc. etc. your code goes here for your simulation of interest
+
+ // something happens between my simulation entities, la de da de da...
+ System.out.println ("... My simulation just did something, no really...");
+ System.out.flush(); // make sure this arrives to user even if other threads somehow become deadlocked
+
+
+ // make your reports: narrative code for CommentPdu here (set all to empty strings to avoid sending)
+ narrativeMessage1 = "MV3500 ExampleSimulationProgram";
+ narrativeMessage2 = "runSimulation() loop " + simulationLoopCount;
+ narrativeMessage3 = ""; // intentionally blank for testing
+
+ // your loop termination condition goes here
+ if (simulationLoopCount > MAX_LOOP_COUNT) // for example
+ {
+ simulationComplete = true;
+ }
+ // =============================================================================================
+ // * your own simulation code is finished here! ************************************************
+ // =============================================================================================
+
+ // staying synchronized with timestep: wait duration for elapsed time in this loop
+ // Thread.sleep needs a (long) parameter for milliseconds, which are clumsy to use sometimes
+ Thread.sleep((long)(getSimulationTimeStepDuration() * 1000)); // units of seconds * (1000 msec/sec) = milliseconds
+ System.out.println ("... [Pausing for " + getSimulationTimeStepDuration() + " seconds]");
+
+ // OK now send the status PDUs for this loop, and then continue
+ System.out.println ("... sending PDUs of interest for simulation step " + simulationLoopCount + ", monitor loopback to confirm sent");
+ System.out.flush();
+
+ // TODO set timesteps in PDUs
+
+ sendAllPdusForLoopTimestep(simulationTimeSeconds,
+ entityStatePdu_1,
+ firePdu_1a,
+ DisChannel.COMMENTPDU_APPLICATION_STATUS,
+ narrativeMessage1, narrativeMessage2, narrativeMessage3);
+ disChannel.sendSinglePdu(simulationTimeSeconds, entityStatePdu_2); // me too i.e. 2!
+
+ System.out.println ("... [PDUs of interest successfully sent for this loop]");
+ System.out.flush();
+
+ // ===============================
+ // current loop now finished, check whether to terminate if simulation complete, otherwise continue
+ if (simulationComplete || (simulationLoopCount > 10000)) // for example; including fail-safe condition is good
+ {
+ System.out.println ("... [loop termination condition met, simulationComplete=" + simulationComplete + "]"); // ", final loopCount=" + loopCount +
+ System.out.flush();
+ break;
+ }
+ simulationTimeSeconds += getSimulationTimeStepDuration(); // good practice: increment simulationTime as lastst action in that loop
+
+ } // end of simulation loop, continue until done
+ // ===================================================================================================// ===================================================================================================// ===================================================================================================// ===================================================================================================
+
+ narrativeMessage2 = "runSimulation() completed successfully"; // all done, so tell everyone else on the channel
+ // TODO better javadoc needs to be autogenerated for VariableRecordType enumerations
+ disChannel.sendCommentPdu(DisChannel.COMMENTPDU_NARRATIVE, narrativeMessage1, narrativeMessage2, narrativeMessage3);
+ System.out.println ("... [final=completion CommentPdu successfully sent for simulation]");
+
+// disChannel.getPduRecorder(). TODO record XML as well
+ disChannel.leave(); // embedded SimulationManager is expected to send appropriate PDUs for entity, application shutdown <- Does nothing as of 7/17/24
+ }
+ catch (InterruptedException iex) // handle any exception that your code might choose to provoke!
+ {
+ Logger.getLogger(OpenDisHelper.class.getSimpleName()).log(Level.SEVERE, null, iex);
+ }
+ }
+
+ /**
+ * Send EntityState, Fire, Comment PDUs that got updated for this loop, reflecting state of current simulation timestep.
+ * @param simTimeSeconds simulation time in second, applied to PDU as timestamp
+ * @param entityStatePdu the ESPDU to send, if any
+ * @param firePdu the FirePDU to send, if any
+ * @param commentType enumeration value describing purpose of the narrative comment PDU
+ * @param comments String array of narrative comments
+ * @see DisChannel
+// * @see DisTime // TODO find renamed version
+ * @see <a href="https://docs.oracle.com/javase/tutorial/java/javaOO/arguments.html" target="_blank">Passing Information to a Method or a Constructor</a> Arbitrary Number of Arguments
+ */
+ public void sendAllPdusForLoopTimestep(double simTimeSeconds,
+ EntityStatePdu entityStatePdu,
+ FirePdu firePdu,
+ VariableRecordType commentType,
+ // vararg... variable-length set of String comments can optionally follow
+ String... comments)
+ {
+ if (entityStatePdu != null)
+ disChannel.sendSinglePdu(simTimeSeconds, entityStatePdu);
+
+ if (firePdu != null)
+ disChannel.sendSinglePdu(simTimeSeconds, firePdu); // bang
+
+ disChannel.sendCommentPdu(simTimeSeconds, commentType, comments); // empty comments are filtered
+ }
+
+ /**
+ * Initial execution via main() method: handle args array of command-line initialization (CLI) arguments here
+ * @param args command-line parameters: network address and port
+ */
+ protected void handleArguments (String[] args)
+ {
+ // initial execution: handle args array of initialization arguments here
+ if (args.length == 2)
+ {
+ if ((args[0] != null) && !args[0].isEmpty())
+ thisProgram.disChannel.setNetworkAddress(args[0]);
+ if ((args[1] != null) && !args[1].isEmpty())
+ thisProgram.disChannel.setNetworkPort(Integer.parseInt(args[1]));
+ }
+ else if (args.length != 0)
+ {
+ System.err.println("Usage: " + thisProgram.getClass().getSimpleName() + " [address port]");
+ System.exit(-1);
+ }
+ }
+
+ /**
+ * Get simple descriptor (such as parent class name) for this network interface, used in trace statements
+ * @return simple descriptor name
+ */
+ public String getDescriptor() {
+ return descriptor;
+ }
+
+ /**
+ * Set new simple descriptor (such as parent class name) for this network interface, used in trace statements
+ * @param newDescriptor simple descriptor name for this interface
+ */
+ public void setDescriptor(String newDescriptor) {
+ if (newDescriptor == null)
+ newDescriptor = "";
+ setName(this.descriptor = newDescriptor);
+ }
+
+ /** Set an other than default network port
+ *
+ * @param port a network port
+ */
+ public void setPort(int port) {
+ disChannel.setNetworkPort(port);
+ }
+
+ /** Set an other than default network address
+ *
+ * @param address a network address
+ */
+ public void setAddress(String address) {
+ disChannel.setNetworkAddress(address);
+ }
+
+ /**
+ * parameter accessor method
+ * @return the simulationTimeStepDuration in seconds
+ */
+ public double getSimulationTimeStepDuration() {
+ return simulationTimeStepDuration;
+ }
+
+ /**
+ * parameter accessor method
+ * @param timeStepDurationSeconds the simulationTimeStepDuration in seconds to set
+ */
+ public void setSimulationTimeStepDuration(double timeStepDurationSeconds) {
+ this.simulationTimeStepDuration = timeStepDurationSeconds;
+ }
+
+ /** Locally instantiable copy of program, can be subclassed. */
+ protected static OpenDisHelper thisProgram;
+
+ /**
+ * Main method is first executed when a program instance is loaded.
+ * @see <a href="https://docs.oracle.com/javase/tutorial/getStarted/application/index.html" target="_blank">Java Tutorials: A Closer Look at the "Hello World!" Application</a>
+ * @param args command-line parameters: network address and port.
+ * Command-line arguments are an array of optional String parameters that are passed from execution environment during invocation
+ */
+ public static void main(String[] args)
+ {
+ thisProgram = new OpenDisHelper("test constructor"); // create instance of self within static main() method
+
+ thisProgram.disChannel.printlnTRACE("main() started...");
+
+ thisProgram.handleArguments(args); // process any command-line invocation arguments
+
+ thisProgram.runSimulationLoops(); // ... your simulation execution code goes in there ...
+
+ thisProgram.disChannel.tearDownNetworkInterface(); // make sure no processes are left lingering
+
+ thisProgram.disChannel.printlnTRACE("complete."); // report successful completion
+ }
+
+} // end class OpenDisHelper