dis-rs

Crates.io	dis-rs
lib.rs	dis-rs
version	0.9.0
source	src
created_at	2022-11-02 12:57:57.640405
updated_at	2024-06-26 19:32:55.645069
description	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.
homepage
repository	https://github.com/zlubsen/dis-rs
max_upload_size
id	703462
size	6,702,859

Zeeger Lubsen (zlubsen)

documentation

README

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. As a rule of thumb, the lib is modeled mostly towards supporting v7 (in terms of how the data is modelled), and provides compatibility with how thing were in v6 mostly transparent for the user (i.e., an incoming v6 PDU is parsed and then stored in a v7 model and put back on the wire based on the version specified in the header).

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	Support
Other	V
EntityState	V
Fire	V
Detonation	V
Collision	V
ServiceRequest	V
ResupplyOffer	V
ResupplyReceived	V
ResupplyCancel	V
RepairComplete	V
RepairResponse	V
CreateEntity	V
RemoveEntity	V
StartResume	V
StopFreeze	V
Acknowledge	V
ActionRequest	V
ActionResponse	V
DataQuery	V
SetData	V
Data	V
EventReport	V
Comment	V
ElectromagneticEmission	V
Designator	V
Transmitter	V
Signal	V
Receiver	V
IFF	V
UnderwaterAcoustic	V
SupplementalEmissionEntityState	V
IntercomSignal
IntercomControl
AggregateState	V
IsGroupOf	V
TransferOwnership	V
IsPartOf	V
MinefieldState
MinefieldQuery
MinefieldData
MinefieldResponseNACK
EnvironmentalProcess
GriddedData
PointObjectState
LinearObjectState
ArealObjectState
TSPI
Appearance
ArticulatedParts
LEFire
LEDetonation
CreateEntityR	V
RemoveEntityR	V
StartResumeR	V
StopFreezeR	V
AcknowledgeR	V
ActionRequestR	V
ActionResponseR	V
DataQueryR	V
SetDataR	V
DataR	V
EventReportR	V
CommentR	V
RecordR	V
SetRecordR	V
RecordQueryR	V
CollisionElastic	V
EntityStateUpdate	V
DirectedEnergyFire
EntityDamageStatus
InformationOperationsAction
InformationOperationsReport
Attribute	V

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 at version 32.

Usage

Constructing PDUs

PDUs are constructed using a default() or builder() associated functions on the structs for PduHeader or PduBodys. Using SomePdu::builder() constructs a Builder for the PDU. The Builders start with the default values for PDU fields, and you have to set fields using .with_field_name() functions. The build() function turns the Builder into the typed body of the PDU you are building (e.g., Signal). There are no internal validation or checks whether you construct a PDU with valid combinations of fields.

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

Parsing

The library exposes three functions to parse binary data (the DIS wire format) into PDUs from a buffer: parse(), parse_v6_pdus() and parse_v7_pdus(). 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 (the DIS wire format), simply call the serialize() function on a Pdu, providing the buffer as argument.

Resources

SISO: https://www.sisostds.org - Organisation maintaining the DIS standard and reference material.
A lot of great background material on DIS can be found at OpenDIS: http://open-dis.org and https://github.com/open-dis.
Wikipedia: https://en.wikipedia.org/wiki/Distributed_Interactive_Simulation.
DIS Data Dictionary (version 6 only): http://faculty.nps.edu/brutzman/vrtp/mil/navy/nps/disEnumerations/JdbeHtmlFiles/pdu/.

Commit count: 347