Skip to content
This repository was archived by the owner on Apr 21, 2026. It is now read-only.

getting-started.md

Latest commit

 

History

History
312 lines (247 loc) · 7.86 KB

getting-started.md

File metadata and controls

312 lines (247 loc) · 7.86 KB

Getting Started with Ditto CoT

This guide helps you quickly set up and start using the Ditto CoT library in your preferred programming language.

Quick Navigation: Building Guide | Testing Guide | Integration Examples | API Reference

Table of Contents

Prerequisites

Choose the language(s) you want to work with:

For Rust Development

For Java Development

  • Java JDK 17+: Download JDK
  • Gradle 7.0+: Included via wrapper in repository
  • Git: For cloning the repository

For C# Development (Planned)

Optional but Recommended

  • Make: For unified build commands across languages
  • Ditto Account: For testing P2P synchronization features

Installation

Option 1: Direct Dependency (Recommended)

Rust - Add to your Cargo.toml:

[dependencies]
ditto_cot = { git = "https://github.com/getditto-shared/ditto_cot" }

Java - Add to your build.gradle:

dependencies {
    implementation 'com.ditto:ditto-cot:1.0.0'
}

Maven - Add to your pom.xml:

<dependency>
  <groupId>com.ditto</groupId>
  <artifactId>ditto-cot</artifactId>
  <version>1.0.0</version>
</dependency>

Option 2: Build from Source

# Clone the repository
git clone https://github.com/getditto-shared/ditto_cot.git
cd ditto_cot

# Build all languages (requires prerequisites installed)
make all

# Or build specific language
make rust    # Build Rust library
make java    # Build Java library

First Steps

1. Verify Installation

Rust:

cd rust
cargo test --lib

Java:

cd java
./gradlew test

2. Run a Simple Example

Rust:

use ditto_cot::{cot_events::CotEvent, ditto::cot_to_document};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a simple location event
    let event = CotEvent::builder()
        .uid("USER-123")
        .event_type("a-f-G-U-C")
        .location(34.0522, -118.2437, 100.0)
        .callsign("Test User")
        .build();
    
    // Convert to Ditto document
    let doc = cot_to_document(&event, "peer-123");
    
    println!("Created document: {}", serde_json::to_string_pretty(&doc)?);
    Ok(())
}

Java:

import com.ditto.cot.CotEvent;

public class FirstExample {
    public static void main(String[] args) {
        // Create a simple location event
        CotEvent event = CotEvent.builder()
            .uid("USER-123")
            .type("a-f-G-U-C")
            .point(34.0522, -118.2437, 100.0)
            .callsign("Test User")
            .build();
        
        // Convert to XML
        String xml = event.toXml();
        System.out.println("Created XML: " + xml);
    }
}

Basic Usage Examples

Creating Different Types of CoT Events

Location Update

// Rust
let location_event = CotEvent::builder()
    .uid("TRACKER-001")
    .event_type("a-f-G-U-C")  // Friendly ground unit
    .location_with_accuracy(34.052235, -118.243683, 100.0, 5.0, 10.0)
    .callsign("ALPHA-1")
    .team("Blue")
    .build();
// Java
CotEvent locationEvent = CotEvent.builder()
    .uid("TRACKER-001")
    .type("a-f-G-U-C")
    .point(34.052235, -118.243683, 100.0, 5.0, 10.0)
    .detail()
        .callsign("ALPHA-1")
        .groupName("Blue")
        .build()
    .build();

Chat Message

// Rust
let chat_event = CotEvent::new_chat_message(
    "USER-456",
    "BRAVO-2", 
    "Message received, moving to coordinates",
    "All Chat Rooms",
    "All Chat Rooms"
);
// Java
CotEvent chatEvent = CotEvent.builder()
    .uid("USER-456")
    .type("b-t-f")
    .detail()
        .chat("All Chat Rooms", "Message received, moving to coordinates")
        .callsign("BRAVO-2")
        .build()
    .build();

Working with XML

Parse CoT XML

// Rust
let cot_xml = r#"<event version="2.0" uid="TEST-123" type="a-f-G-U-C"...>"#;
let event = CotEvent::from_xml(cot_xml)?;
// Java
String cotXml = "<event version=\"2.0\" uid=\"TEST-123\" type=\"a-f-G-U-C\"...>";
CotEvent event = CotEvent.fromXml(cotXml);

Generate XML

// Rust
let xml = event.to_xml()?;
// Java
String xml = event.toXml();

Converting to Ditto Documents

// Rust
use ditto_cot::ditto::cot_to_document;

let doc = cot_to_document(&event, "my-peer-id");

match doc {
    CotDocument::MapItem(map_item) => {
        println!("Location: {} at {},{}", 
                 map_item.e, map_item.j.unwrap_or(0.0), map_item.l.unwrap_or(0.0));
    },
    CotDocument::Chat(chat) => {
        println!("Chat: {}", chat.message);
    },
    _ => println!("Other document type"),
}
// Java
import com.ditto.cot.schema.*;

Object doc = converter.convertToDocument(event);

if (doc instanceof MapItemDocument) {
    MapItemDocument mapItem = (MapItemDocument) doc;
    System.out.println("Location: " + mapItem.getE() + 
                      " at " + mapItem.getJ() + "," + mapItem.getL());
} else if (doc instanceof ChatDocument) {
    ChatDocument chat = (ChatDocument) doc;
    System.out.println("Chat: " + chat.getMessage());
}

Common Workflows

1. XML Processing Workflow

CoT XML → Parse → CotEvent → Validate → Process

2. Document Creation Workflow

Builder → CotEvent → Convert → Ditto Document → Store

3. P2P Synchronization Workflow

Local Change → CRDT Update → Differential Sync → Remote Apply

Next Steps

Now that you have the basics working, explore these areas:

🏗️ Architecture Understanding

🛠️ Development

🔌 Integration

📚 Advanced Topics

Getting Help

Common First Steps Issues

Rust Build Errors: Ensure you have Rust 1.70+ and all dependencies installed Java Compilation Issues: Verify JDK 17+ and Gradle wrapper permissions Missing Dependencies: Run make all to ensure all components are built Test Failures: Some tests require Ditto credentials - see Testing Guide

See Also