EMOG Specification

Extended Motorsport Open Gauge

A structured JSON telemetry standard and UDP transport protocol for interoperability between automotive software, simulation platforms, ECUs, hardware dashboards, motion rigs, and telemetry tools.

Version: 0.3
Status: Active Development

---

Overview

EMOG defines three core components:

1. Telemetry Data Model – A structured JSON format for motorsport and vehicle telemetry.
2. Transport Protocol – A UDP-based beacon + stream architecture (see transport.md).
3. Mappings System – Declarative .emog mapping specifications for translating external formats to and from EMOG.

The goal is simple:

Any telemetry producer should be able to communicate with any telemetry consumer.

Whether native or via a mapping layer.

---

Repository Structure

EMOG/
├── transport.md        # Transport protocol specification
├── mappings/           # .emog mapping specifications
└── libraries/          # Language implementations

Each language implementation provides:

• emog.send(data)
• emog.get()
• Transport handling (beacon, merge, packetization)
• Optional direct endpoint mode
• Mapping integration

---

Transport

Default EMOG Beacon Port: 9997

The transport layer includes:

• UDP beacon-based discovery
• Dynamic telemetry port negotiation
• Core + group packet structure
• MTU-aware packet splitting
• Rolling merge state on consumer
• Direct endpoint compatibility mode

See:

→ Transport Specification

---

Mappings

EMOG uses declarative Mapping Specifications (.emog files) to translate between foreign telemetry formats and EMOG.

Mappings are portable and language-agnostic.

Example structure:

{
  "name": "example_format",
  "version": "0.1",
  "endpoint": "0.0.0.0:9998",
  "mappings": {
    "to_emog": [
      { "from": "rpm", "to": "vehicle.rpm", "op": "copy" }
    ],
    "from_emog": [
      { "from": "vehicle.rpm", "to": "rpm", "op": "copy" }
    ]
  }
}

• to_emog maps external format → EMOG
• from_emog maps EMOG → external format
• Operations include copy, mul, div, add, clamp, enum_map, bool

Mappings are data-only and do not contain executable code.

---

Data Model

All EMOG data is structured into logical groups.

Groups are optional. Fields are optional. Unsupported fields may be omitted or set to null.

Consumers must tolerate missing groups and fields.

---

Type Definitions

• float32
• int32
• uint32
• bool
• string
• enum
• float32[4]
• object

---

Field State Rules

If a field is not supported by the data source:

• Numeric types → null
• Boolean types → false
• String types → null
• Enum types → null
• Object types → null

Fields may also be omitted entirely.

No other fallback values are permitted.

---

meta

• timestamp_ms: uint32
• source: string
• source_version: string
• session_id: string
• seq: uint32
• sample_hz: float32
• spec_version: string

---

identity

• game: string
• vehicle_id: string
• vehicle_name: string
• vehicle_class: string
• track_id: string
• track_name: string
• player_name: string

---

vehicle

• speed_mps: float32
• speed_kph: float32
• speed_mph: float32
• rpm: float32
• rpm_max: float32
• gear: int32
• gear_display: string
• engine_on: bool
• ignition_on: bool

---

input

• throttle: float32
• brake: float32
• clutch: float32
• steering: float32
• steering_angle_deg: float32
• handbrake: float32

---

controls_state

• abs_active: bool
• tc_active: bool
• esc_active: bool
• pit_limiter: bool
• drs_active: bool
• engine_map: int32
• tc_level: int32
• abs_level: int32

---

engine

• load_pct: float32
• throttle_pct: float32
• coolant_temp_c: float32
• oil_temp_c: float32
• oil_pressure_kpa: float32
• fuel_level_pct: float32
• fuel_rate_lph: float32
• fuel_pressure_kpa: float32
• map_kpa: float32
• boost_kpa: float32
• boost_target_kpa: float32
• iat_c: float32
• afr: float32
• lambda: float32
• timing_advance_deg: float32
• knock_level: float32
• battery_voltage: float32

---

drivetrain

• drivetrain_layout: enum
• diff_lock_pct: float32
• clutch_slip_rpm: float32
• trans_temp_c: float32

---

dynamics

• g_long: float32
• g_lat: float32
• g_vert: float32
• yaw_rate_dps: float32
• pitch_rate_dps: float32
• roll_rate_dps: float32
• orientation_yaw_deg: float32
• orientation_pitch_deg: float32
• orientation_roll_deg: float32

---

position

• world_x_m: float32
• world_y_m: float32
• world_z_m: float32
• velocity_x_mps: float32
• velocity_y_mps: float32
• velocity_z_mps: float32
• gps_lat: float32
• gps_lon: float32
• gps_alt_m: float32
• heading_deg: float32

---

wheels

• wheel_speed_fl_kph: float32
• wheel_speed_fr_kph: float32
• wheel_speed_rl_kph: float32
• wheel_speed_rr_kph: float32
• brake_temp_fl_c: float32
• brake_temp_fr_c: float32
• brake_temp_rl_c: float32
• brake_temp_rr_c: float32
• tyre_temp_fl_c: float32
• tyre_temp_fr_c: float32
• tyre_temp_rl_c: float32
• tyre_temp_rr_c: float32
• tyre_pressure_fl_kpa: float32
• tyre_pressure_fr_kpa: float32
• tyre_pressure_rl_kpa: float32
• tyre_pressure_rr_kpa: float32
• tyre_wear_fl_pct: float32
• tyre_wear_fr_pct: float32
• tyre_wear_rl_pct: float32
• tyre_wear_rr_pct: float32
• slip_ratio_fl: float32
• slip_ratio_fr: float32
• slip_ratio_rl: float32
• slip_ratio_rr: float32
• slip_angle_fl_deg: float32
• slip_angle_fr_deg: float32
• slip_angle_rl_deg: float32
• slip_angle_rr_deg: float32
• ride_height_fl_m: float32
• ride_height_fr_m: float32
• ride_height_rl_m: float32
• ride_height_rr_m: float32

---

aero

• drs_available: bool
• downforce_n: float32
• drag_n: float32

---

damage

• engine_damage_pct: float32
• aero_damage_pct: float32
• body_damage_pct: float32
• suspension_fl_pct: float32
• suspension_fr_pct: float32
• suspension_rl_pct: float32
• suspension_rr_pct: float32
• tyre_puncture_fl: bool
• tyre_puncture_fr: bool
• tyre_puncture_rl: bool
• tyre_puncture_rr: bool

---

session

• state: enum
• mode: enum
• on_track: bool
• is_paused: bool
• lap: int32
• lap_time_ms: uint32
• best_lap_time_ms: uint32
• last_lap_time_ms: uint32
• sector: int32
• sector_time_ms: uint32
• position: int32
• cars_total: int32
• track_temp_c: float32
• air_temp_c: float32
• rain_level: float32
• flag: enum

---

hardware

• ffb_torque_nm: float32
• ffb_clip: bool
• wheel_rotation_deg: float32
• base_temp_c: float32
• pedal_raw_throttle: int32
• pedal_raw_brake: int32
• pedal_raw_clutch: int32