Open DIS Rust

Open DIS Rust is an open-source implementation of the IEEE 1278.1-2012 Distributed Interactive Simulation (DIS) application protocol. This library defines all Protocol Data Units (PDUs) listed within the standard documentation as well as all associated data types, records, and enumerations.

Contributing

Open DIS Rust is free and open source. You can find the source code as well as report issues and create feature requests on GitHub.

Acquiring Open DIS Rust

• From Crates.io
• Build from Source

crates.io

In your project, run cargo add open-dis-rust or add open-dis-rust = "<version>" to your Cargo.toml.

Build from Source

Clone the open-dis-rust GitHub repository and build with cargo.

Requirements:

• Rust toolchain
• Git version control

# Clone the repo
git clone https://github.com/crhowell3/open-dis-rust.git

cd open-dis-rust

# Build and test
cargo build --release
cargo test

Getting Started

Get in touch

If you have any questions about Open DIS Rust, feel free to contact a maintainer. If you have any feature requests and/or bugs to report, please open a ticket on GitHub.

Maintainers

• https://github.com/crhowell3

Creating a PDU

The IEEE 1278.1-2012 standard defines 72 PDUs, all of which have been implemented in this crate. While the topics and contents of the PDUs differ, each PDU can be easily instantiated.

Importing Modules

The PDUs are divided into separate protocol families, which are groups of PDUs that serve a similar purpose. To begin creating a PDU, first import the PDU's module, or, if using multiple PDUs from the same family, import the entire protocol family module.

#![allow(unused)]
fn main() {
// Imports just the Acknowledge PDU module
use open_dis_rust::simulation_management::acknowledge_pdu::AcknowledgePdu;

// Imports the entire SIMAN protocol family, including the associated data types
use open_dis_rust::simulation_management::*;
}

Creating a PDU

To instantiate a PDU, use the PDU's default method to pre-populate all its fields with data.

#![allow(unused)]
fn main() {
let mut acknowledge_pdu = AcknowledgePdu::default();
}

It is advised to use the mut keyword so that the default values within the PDU's fields can be manipulated before sending it over UDP.

Editing the PDU Fields

Each PDU has different fields; no two PDUs have the exact same fields. Every PDU is guaranteed to have a pdu_header field that is of type PduHeader. See the crate documentation for more information on this type. It is generally advised that this field and its subfields should not be directly edited because it contains the header information that a receiver would need to correctly parse and interpret the data. Upon calling default, this field is pre-populated with the correct metadata for the PDU, and it should not be edited afterwards.

All other fields within a PDU can be safely edited so long as the data being assigned to them is of the correct type and length. For most fields, editing the value is just a simple assignment, especially with primitive data types. However, there are other types that require a little more work to construct before assigning. Type information can be found within the crate documentation.

The following is an example for editing a PDU field that is a primitive type.

#![allow(unused)]
fn main() {
// Instantiate a default Acknowledge PDU
let mut acknowledge_pdu = AcknowledgePdu::default();

// Valid assignment of the request_id field
acknowledge_pdu.request_id = 14;
}

The following is an example for editing a PDU field that is of a special type.

#![allow(unused)]
fn main() {
// Instantiate a default Acknowledge PDU
let mut acknowledge_pdu = AcknowledgePdu::default();

// Assignment occurring field-wise for the originating_entity_id field
acknowledge_pdu.originating_entity_id.simulation_address.application_id = 1;
acknowledge_pdu.originating_entity_id.simulation_address.site_id = 3;
acknowledge_pdu.originating_entity_id.entity_id = 12;

// Assignment can also occur by creating an EntityId and assigning
let mut origin_id = EntityId::default(1);
origin_id.simulation_address.application_id = 1;
origin_id.simulation_address.site_id = 4;
origin_id.entity_id = 15;
acknowledge_pdu.originating_entity_id = origin_id;
}

Sending PDUs

While the network protocol is not required to be UDP, this crate has been validated against UDP topology, and the example code provided uses UDP as the protocol.

Dependencies

This demonstration utilizes the open_dis_rust crate as well as the bytes and tokio crates.

Create and Serialize the PDU

As shown in the previous section, we can create a PDU as such:

#![allow(unused)]
fn main() {
use open_dis_rust::simulation_management::acknowledge_pdu::AcknowledgePdu;

let mut ack_pdu = AcknowledgePdu::default();
}

Then, we need to create an empty, mutable byte array into which we will serialize the PDU:

#![allow(unused)]
fn main() {
use bytes::BytesMut;

let mut bytes = BytesMut::new();
}

Now, we simply call the serialize function from the PDU and pass in a mutable reference to the byte array:

#![allow(unused)]
fn main() {
ack_pdu.serialize(&mut bytes);
}

The PDU has now been serialized into the byte array and is ready to be sent.

Initializing a UDP Socket

We need to select an address and a port to send the message. For this exercise, we will assume the address is localhost (127.0.0.1), and we will use port 3000. To create the socket, we use the tokio crate:

use bytes::BytesMut;
use std::net::SocketAddr;
use std::io;
use tokio::net::UdpSocket;

use open_dis_rust::simulation_management::acknowledge_pdu::AcknowledgePdu;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = UdpSocket::bind("0.0.0.0:3000").await?;
    let remote_addr = "127.0.0.1:3000";

    socket.connect(remote_addr).await?;
  
    let mut ack_pdu = AcknowledgePdu::default();
    let mut bytes = BytesMut::new();

    ack_pdu.serialize(&mut bytes);
    socket.send(&bytes[..]).await?;
}

We create a UDP socket and bind it to all network interfaces, specifically on port 3000. We then establish a one-to-one connection to 127.0.0.0:3000. Afterwards, we take our serialized PDU and send it via the socket's send() function. Anything listening on 127.0.0.1:3000 will be able to receive the message.

A tutorial on receiving and parsing a PDU is available in the next section.

Receiving PDUs

The same dependencies are required as listed in the previous section.

Receiving and Parsing a PDU

Using the same UDP socket that we created in the previous section, we can receive a PDU and decode it from the byte array.

use bytes::BytesMut;
use std::net::SocketAddr;
use std::io;
use tokio::net::UdpSocket;

use open_dis_rust::simulation_management::acknowledge_pdu::AcknowledgePdu;

#[tokio::main]
async fn main() -> io::Result<()> {
    let socket = UdpSocket::bind("0.0.0.0:3000").await?;
    let remote_addr = "127.0.0.1:3000";

    socket.connect(remote_addr).await?;

    let mut buf = vec![0; 1204];
    let n = socket.recv(&mut buf[..]).await?;
    loop {
        if n > 0 {
          dbg!(AcknowledgePdu::deserialize(BytesMut::from(buf.as_slice())).unwrap());
          break;
        }
    }
    Ok(())
}

In most cases, the receiver is going to be listening for a particular PDU or range of PDUs. Using the above code as an example, if the data received is not able to be deserialized into an AcknowledgePdu, an error will be returned. This can be further handled by the user.

There are other ways to determine what type of PDU the data represents, such as reading the raw byte array and finding the byte that represents the pdu_type field in the header. Then, the user could set up a match tree to attempt to parse the PDU, if they are expected to handle it, of course.