#simulation #dis

dis-rs

An implementation of the Distributed Interactive Simulation protocol in Rust. This main crate contains PDU implementations and facilities to read/write PDUs from Rust data structures to the wire format and vice versa

6 releases

new 0.4.0 Mar 15, 2023
0.3.2 Jan 21, 2023
0.2.1 Nov 7, 2022

#1707 in Network programming

43 downloads per month

MIT license

1MB
8K SLoC

DIS for Rust

dis-rs is an implementation of the Distributed Interactive Simulation (DIS) protocol for Rust. It provides structures and functions to build PDUs in applications, send them out via a network and parse received byte streams into PDUs.

Constructing PDUs is done via builder pattern constructors.

Given a buffer with data from the network, the library can return multiple PDUs in multiple DIS versions present in the buffer.

The library supports both versions 6 and 7 of the standard.

Features

Here is an overview of the DIS PDUs/features supported by dis-rs. 'Read' means reading a PDU from a byte stream. 'Write' means constructing a PDU in a struct and serializing it to a buffer.

PDU / function v6 read v6 write v7 read v7 write
PDU Header V V V V
EntityState V V V V
Fire V V V V
Detonation V V V V
Collision V V V V
ServiceRequestPdu
ResupplyOfferPdu
ResupplyReceivedPdu
ResupplyCancelPdu
RepairCompletePdu
RepairResponsePdu
CreateEntityPdu
RemoveEntityPdu
StartResumePdu V V V V
StopFreezePdu V V V V
AcknowledgePdu V V V V
ActionRequestPdu
ActionResponsePdu
DataQueryPdu
SetDataPdu
DataPdu
EventReportPdu
CommentPdu
ElectromagneticEmissionPdu V V V V
DesignatorPdu V V V V
TransmitterPdu V V V V
SignalPdu V V V V
ReceiverPdu V V V V
AnnounceObjectPdu
DeleteObjectPdu
DescribeApplicationPdu
DescribeEventPdu
DescribeObjectPdu
RequestEventPdu
RequestObjectPdu
TimeSpacePositionIndicatorFIPdu
AppearanceFIPdu
ArticulatedPartsFIPdu
FireFIPdu
DetonationFIPdu
PointObjectStatePdu
LinearObjectStatePdu
ArealObjectStatePdu
EnvironmentPdu
TransferControlRequestPdu
TransferControlPdu
TransferControlAcknowledgePdu
IntercomControlPdu
IntercomSignalPdu
AggregatePdu
'Other' PDU V V V V
Dead Reckoning Algos

Enumerations

dis-rs uses the SISO-REF-010 reference to map the wire level encoding to actual names of enumerations and values in code. E.g., one can use the enum PduType::EntityState in code instead of remembering that a 1 means that specific value.

The code for these enums is generated using a build script from the published SISO-REF-010.xml file. Which is currently a v30.

Usage

Constructing PDUs

PDUs are constructed using idiomatic new() or default() functions on the structs for PduHeader or PduBodys. Some PduBody variants require the new() constructors to have arguments. Further fields are set using .with_field_name() functions.

The main data structure is a Pdu, which consists of a header and a body. The body is a variant of PduBody, an enum that wraps a specific struct for that PDU type in a variant. The specific body structs, e.g. an EntityState, can be wrapped / converted to a PduBody by call the to_pdu_body() function on the struct. Further, the body can be merged with a PduHeader using the associated function finalize_from_parts(header, body, timestamp) of Pdu. This will give you a complete PDU.

Parsing

The library exposes three functions to parse data into PDUs from a buffer: parse(), parse_v6() and parse_v7(). Each function works the same, where the general parse() function returns all valid PDUs from the buffer and the others filter out v6 or v7 version PDUs.

Serializing

To serialize a PDU to bytes (DIS wire format), simply call the serialize() function on a Pdu, providing the buffer as argument.

Resources

Copyright (C) 2022 Zeeger Lubsen

Dependencies