updated docs, bump to 4.4.0

Author: thatzok

.github/workflows/buildandpublish.yml

@@ -28,4 +28,4 @@ jobs:
     - name: Build binaries in "release" mode
       run: cargo build -r
     - name: "Publish to crates.io"
-      run: cargo publish # publishes your crate as a library that can be added as a dependency
+      run: cargo publish

Cargo.toml

@@ -1,13 +1,14 @@
 [package]
 name = "the-bus-telemetry"
-version = "4.3.0"
+version = "4.4.0"
 edition = "2024"
+rust-version = "1.93.1"
 description = "Library for handling data exchange with the api (called telemetry) of the simulation software The Bus"
-license = "MIT"
+license = "MIT OR Apache-2.0"
 readme = "README.md"
 repository = "https://github.com/thatzok/TheBusTelemetry"
 [dependencies]
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 reqwest = { version = "0.12", features = ["json","blocking"] }
-komsi = "1.1"
+komsi = "1.5.1"

src/api.rs

@@ -1,17 +1,27 @@
+//! This module handles the raw interaction with The Bus Telemetry API.
+
 use serde::Deserialize;
 use std::string::ToString;
 use std::time::Duration;
 
+/// Configuration for API requests.
 pub struct RequestConfig {
+    /// Host address of the telemetry server (default: "127.0.0.1").
     pub host: String,
+    /// Port of the telemetry server (default: "37337").
     pub port: String,
+    /// Name of the vehicle to query (default: "Current").
     pub vehicle_name: String,
+    /// Model of the vehicle to query (default: "Current").
     pub vehicle_model: String,
+    /// Request timeout (default: 300ms).
     pub timeout: Duration,
+    /// Enable debug logging of URLs and data.
     pub debugging: bool,
 }
 
 impl RequestConfig {
+    /// Creates a new `RequestConfig` with default values.
     pub fn new() -> Self {
         Self {
             host: "127.0.0.1".to_string(),
@@ -22,126 +32,170 @@ impl RequestConfig {
             debugging: false,
         }
     }
+    /// Sets the host address.
     pub fn host(mut self, host: String) -> Self {
         self.host = host;
         self
     }
 
+    /// Sets the port.
     pub fn port(mut self, port: String) -> Self {
         self.port = port;
         self
     }
+    /// Sets the vehicle name.
     pub fn vehicle_name(mut self, vehicle_name: String) -> Self {
         self.vehicle_name = vehicle_name;
         self
     }
+    /// Sets the vehicle model.
     pub fn vehicle_model(mut self, vehicle_model: String) -> Self {
         self.vehicle_model = vehicle_model;
         self
     }
 
+    /// Sets the request timeout.
     pub fn timeout(mut self, timeout: Duration) -> Self {
         self.timeout = timeout;
         self
     }
+    /// Sets the debugging flag.
     pub fn debugging(mut self, debugging: bool) -> Self {
         self.debugging = debugging;
         self
     }
 }
 
+/// World telemetry data.
 #[derive(Deserialize, Debug, PartialEq)]
 pub struct ApiWorldType {
+    /// Name of the current level.
     #[serde(rename = "LevelName")]
     pub level_name: String,
+    /// Current date and time in the game.
     #[serde(rename = "DateTime")]
     pub date_time: String,
+    /// Time acceleration factor.
     #[serde(rename = "TimeFactor")]
     pub time_factor: f32,
+    /// Latitude of the world origin.
     #[serde(rename = "BaseLatitude")]
     pub base_latitude: f64,
+    /// Longitude of the world origin.
     #[serde(rename = "BaseLongitude")]
     pub base_longitude: f64,
 }
 
+/// Vehicle telemetry data.
 #[derive(Deserialize, Debug, PartialEq)]
 pub struct ApiVehicleType {
+    /// Internal actor name.
     #[serde(rename = "ActorName")]
     pub actor_name: String,
+    /// Vehicle model name.
     #[serde(rename = "VehicleModel")]
     pub vehicle_model: String,
+    /// Whether the ignition is enabled (string "true"/"false").
     #[serde(rename = "IgnitionEnabled")]
     pub ignition_enabled: String,
+    /// Whether the engine is started (string "true"/"false").
     #[serde(rename = "EngineStarted")]
     pub engine_started: String,
+    /// Whether warning lights are active (string "true"/"false").
     #[serde(rename = "WarningLights")]
     pub warning_lights: String,
+    /// Whether any passenger door is open (string "true"/"false").
     #[serde(rename = "PassengerDoorsOpen")]
     pub passenger_doors_open: String,
+    /// Whether the fixing (parking) brake is engaged (string "true"/"false").
     #[serde(rename = "FixingBrake")]
     pub fixing_brake: String,
+    /// Current speed in km/h.
     #[serde(rename = "Speed")]
     pub speed: f32,
+    /// Allowed speed limit.
     #[serde(rename = "AllowedSpeed")]
     pub allowed_speed: f32,
+    /// Fuel level on display (0.0 to 1.0).
     #[serde(rename = "DisplayFuel")]
     pub display_fuel: f32,
+    /// Indicator state (-1: left, 0: off, 1: right).
     #[serde(rename = "IndicatorState")]
     pub indicator_state: i8,
+    /// Status of all external and internal lamps.
     #[serde(rename = "AllLamps")]
     pub all_lamps: ApiLamps,
+    /// List of buttons and their states.
     #[serde(rename = "Buttons", default)]
     pub buttons: Vec<ApiButton>,
 }
 
+/// Represents various lamp intensities or states.
 #[derive(Deserialize, Debug, PartialEq)]
 pub struct ApiLamps {
+    /// Main headlight intensity (0.0 to 1.0).
     #[serde(
         rename = "LightHeadlight",
         alias = "LightHeadlight1",
         alias = "Light Headlight"
     )]
     pub light_main: f32,
+    /// High beam / traveller light intensity (0.0 or 1.0).
     #[serde(
         rename = "LightTraveling",
         alias = "LightTraveling1",
         alias = "Light Travelling"
     )]
     pub traveller_light: f32,
+    /// Front door light state.
     #[serde(rename = "Door Button 1", alias = "ButtonLight Door 1", default)]
     pub front_door_light: f32,
+    /// Second door light state.
     #[serde(rename = "Door Button 2", alias = "ButtonLight Door 2", default)]
     pub second_door_light: f32,
+    /// Third door light state.
     #[serde(rename = "Door Button 3", alias = "ButtonLight Door 3", default)]
     pub third_door_light: f32,
+    /// Fourth door light state.
     #[serde(rename = "Door Button 4", alias = "ButtonLight Door 4", default)]
     pub fourth_door_light: f32,
+    /// Stop request LED intensity.
     #[serde(rename = "LED StopRequest", default)]
     pub led_stop_request: f32,
+    /// Bus stop brake light intensity.
     #[serde(rename = "ButtonLight BusStopBrake", default)]
     pub light_stopbrake: f32,
 }
 
+/// Represents a button in the vehicle and its current state.
 #[derive(Deserialize, Debug, PartialEq, Default, Clone)]
 pub struct ApiButton {
+    /// Button name.
     #[serde(rename = "Name")]
     pub name: String,
+    /// Tooltip text for the button.
     #[serde(rename = "Tooltip", default)]
     pub tooltip: String,
+    /// Current state of the button (e.g. "on", "off", "Drive", "Neutral").
     #[serde(rename = "State", default)]
     pub state: String,
+    /// Numeric value as string, if applicable.
     #[serde(rename = "Value", default)]
     pub value: String,
+    /// Possible actions for this button.
     #[serde(rename = "Actions", default)]
     pub actions: Vec<String>,
+    /// Possible states for this button.
     #[serde(rename = "States", default)]
     pub states: Vec<String>,
 }
 
 impl ApiVehicleType {
+    /// Returns the button with the given name, if found.
     pub fn get_button(&self, name: &str) -> Option<ApiButton> {
         self.buttons.iter().find(|b| b.name == name).cloned()
     }
+    /// Returns the state of the button with the given name, or an empty string if not found.
     pub fn get_button_state(&self, name: &str) -> String {
         self.buttons
             .iter()
@@ -150,6 +204,7 @@ impl ApiVehicleType {
             .unwrap_or_else(|| "".to_string())
     }
 
+    /// Returns the state of the first button whose name contains the given part.
     pub fn get_button_state_contains(&self, part: &str) -> String {
         self.buttons
             .iter()
@@ -158,6 +213,7 @@ impl ApiVehicleType {
             .unwrap_or_else(|| "".to_string())
     }
 
+    /// Returns all buttons with the exact given name.
     pub fn filtered_buttons(&self, name: &str) -> Vec<ApiButton> {
         self.buttons
             .iter()
@@ -166,10 +222,12 @@ impl ApiVehicleType {
             .collect()
     }
 
+    /// Keeps only the buttons with the exact given name in the vehicle.
     pub fn retain_buttons_by_name(&mut self, name: &str) {
         self.buttons.retain(|b| b.name == name);
     }
 
+    /// Returns a vector of tuples containing (name, state) for all buttons.
     pub fn buttons_name_state(&self) -> Vec<(String, String)> {
         self.buttons
             .iter()
@@ -178,6 +236,7 @@ impl ApiVehicleType {
     }
 }
 
+/// Sends a command to the vehicle via the telemetry API.
 pub async fn send_telemetry_bus_cmd(
     config: &RequestConfig,
     cmd: &str,
@@ -199,6 +258,7 @@ pub async fn send_telemetry_bus_cmd(
     Ok(())
 }
 
+/// Fetches raw JSON telemetry data from a specific API path.
 pub async fn get_telemetry_data(
     config: &RequestConfig,
     path: &str,
@@ -220,6 +280,8 @@ pub async fn get_telemetry_data(
     Ok(value)
 }
 
+/// Returns the current vehicle name from the "player" telemetry endpoint.
+/// Returns an empty string if the player is not in a vehicle or if the request fails.
 pub async fn get_current_vehicle_name(config: &RequestConfig) -> String {
     let result = get_telemetry_data(&config, "player").await;
 
@@ -259,6 +321,7 @@ pub async fn get_current_vehicle_name(config: &RequestConfig) -> String {
     bus
 }
 
+/// Fetches telemetry data for the vehicle specified in `config`.
 pub async fn get_vehicle(
     config: &RequestConfig,
 ) -> Result<ApiVehicleType, Box<dyn std::error::Error>> {
@@ -282,6 +345,7 @@ pub async fn get_vehicle(
     Ok(api_vehicle)
 }
 
+/// Fetches world telemetry data (time, weather, etc).
 pub async fn get_world(config: &RequestConfig) -> Result<ApiWorldType, Box<dyn std::error::Error>> {
     let path = "world";
 
@@ -302,6 +366,7 @@ pub async fn get_world(config: &RequestConfig) -> Result<ApiWorldType, Box<dyn s
     Ok(api_world)
 }
 
+/// Extracts the state of a button by name from a raw JSON value containing a "Buttons" array.
 pub fn get_button_by_name(data: &serde_json::Value, name: &str) -> String {
     let ret = data
         .get("Buttons")

src/api2vehicle.rs

@@ -1,6 +1,9 @@
+//! This module provides functions to map API-specific telemetry data to type-safe komsi vehicle states.
+
 use crate::api::ApiVehicleType;
 use komsi::vehicle::VehicleState;
 
+/// Maps `ApiVehicleType` data to a `VehicleState` structure.
 pub fn get_vehicle_state_from_api(av: ApiVehicleType) -> VehicleState {
     let mut s = VehicleState::default();
 
@@ -29,7 +32,7 @@ pub fn get_vehicle_state_from_api(av: ApiVehicleType) -> VehicleState {
         _ => s.fixing_brake = false,
     }
 
-    // we only check if set, not in which direction (in api: -1,0,1 for left,off,right)
+    // we only check if set and in which direction (in api: -1,0,1 for left,off,right)
     match av.indicator_state {
         0 => s.indicator = 0,  // off
         -1 => s.indicator = 1, // on left

src/lib.rs

@@ -1,3 +1,21 @@
+//! This crate provides a client for The Bus Telemetry API.
+//! It fetches telemetry data from the game "The Bus" and maps it to common vehicle states.
+
 // This file exposes the modules used by both binary targets and integration tests
 pub mod api;
 pub mod api2vehicle;
+
+pub use api::ApiButton;
+pub use api::ApiLamps;
+pub use api::ApiVehicleType;
+pub use api::ApiWorldType;
+pub use api::RequestConfig;
+pub use api::get_current_vehicle_name;
+pub use api::get_vehicle;
+pub use api::get_world;
+pub use api::send_telemetry_bus_cmd;
+pub use api::get_telemetry_data;
+pub use api::get_button_by_name;
+
+pub use api2vehicle::get_vehicle_state_from_api;
+