From c4df00e0b6aa553a965d17f093d37bc5a4cb90d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20P=C4=99dzich?= <contact@maciejpedzi.ch>
Date: Fri, 28 Feb 2025 13:21:07 +0100
Subject: [PATCH] docs: add installation instructions, complex example and FAQs

---
 README.md | 58 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 45 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 4f2cd4f..3aff08a 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,23 @@
 # f1-game-packet-parser
 
-This is a Rust crate that allows you to convert raw binary data from F1 24, F1 23, and F1 22 UDP telemetry into
-organised structs.
+This is a Rust crate that allows you to convert binary data from F1 24, F1 23, and F1 22 UDP telemetry into organised structs.
 
 ## Getting started
 
-Add `f1_game_packet_parser` to your project's `Cargo.toml` file:
+Add `f1-game-packet-parser` to your project by running this command:
 
-```toml
-[dependencies]
-f1_game_packet_parser = "1.0.0"
+```
+cargo add f1_game_packet_parser
 ```
 
 ## Example
 
-This crate doesn't provide a UDP client out of the box. Here's how to write one that will parse and pretty-print
-incoming packets:
+This crate doesn't provide a UDP client out of the box. Here's how to write one that will keep parsing incoming packets until it receives final classification or a _session ended_ event packet. It will then print either the final classification or a _Session has ended!_ message and exit.
 
 ```rust
+use f1_game_packet_parser::packets::event::EventDetails;
 use f1_game_packet_parser::parse;
+
 use std::error::Error;
 use std::net::UdpSocket;
 
@@ -32,19 +31,52 @@ fn main() -> Result<(), Box<dyn Error>> {
         // The buf array should be large enough for all types of packets.
         let (amt, _) = socket.recv_from(&mut buf)?;
 
-        // Convert received bytes to an F1Packet struct and print it.
+        // Convert received bytes to an F1Packet struct.
         let packet = parse(&buf[..amt])?;
-        println!("{:#?}", packet);
+
+        // It's the final classification confirmation.
+        if let Some(final_classification) = packet.final_classification {
+            println!("{:#?}", final_classification);
+            break;
+        }
+        // It's the session ended event.
+        else if packet
+            .event
+            .is_some_and(|event| event.details == EventDetails::SessionEnded)
+        {
+            println!("Session has ended!");
+            break;
+        }
     }
+    
+    Ok(())
 }
 ```
 
 ## Minimum supported Rust version
 
-The minimum supported Rust version is documented in the Cargo.toml file. This may be bumped in minor releases if
-necessary.
+The minimum supported Rust version is documented in the `Cargo.toml` file. It may be bumped in minor releases if necessary.
 
-## Original documentation links
+## FAQ
+
+### What about support for F1 2021-2018?
+
+My initial goal was to provide support from the most recent game all the way to F1 2018, starting development with implementing support for the latter and _working my way up_. I ended up limiting my crate's backwards compatibility to F1 22, because:
+- When I was done with the 2021 format, certain structs had so many fields that got added, removed, or in some cases even reordered with each new format that they became a nightmare to manage and navigate through in the documentation.
+- I realised that most users would probably never end up using formats that are over 2-3 years old anyway. Limiting support to the 3 most recent packet formats also happens to be the actual policy in the latest games.
+
+However, if you believe there's a method in the madness and/or need support for these older packet formats, feel free to open an issue or a pull request.
+
+### Are there any alternatives to this crate?
+
+If you're looking for a crate that supports an older telemetry format or need a built-in UDP client, consider one of the following:
+
++ [f1_game_telemetry](https://crates.io/crates/f1_game_telemetry) - supports the 2022 format and offers a built-in UDP client
++ [f1-telemetry-client](https://crates.io/crates/f1-telemetry-client) - supports the 2020 format and offers a built-in UDP client
+
+### Where can I find the links to the original specification documents?
+
+In the list below:
 
 - [F1 24](https://forums.ea.com/discussions/f1-24-general-discussion-en/f1-24-udp-specification/8369125)
 - [F1 23](https://forums.ea.com/discussions/f1-23-en/f1-23-udp-specification/8390745)