add important addresses & addr ranges, documentation

src/j1939/address.rs

@@ -1,20 +1,67 @@
-// Copyright 2023 Raven Industries inc.
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 
 use crate::j1939::byte_field::ByteField;
 
-/// J1939 address (8-bits) used to identify ECUs on the network
+/// J1939 address (8-bits) used to identify control applications on the network
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 #[repr(transparent)]
 pub struct Address(u8);
 
 impl Address {
     /// The number of bits in the address
     pub const BIT_LENGTH: u8 = 8;
-    /// Address representing broadcasts for destination specific PGNs
+
+    /// Global Preferred Addresses
+    ///
+    /// only to be used by control applications that handles the given function and
+    /// function instance, if applicable, that is assigned to that address by SAE J1939.
+    ///
+    /// For more information see SAE J1939 4.6.1
+    pub const GLOBAL_PREFERRED_ADDRESSES: (std::ops::Range<u8>, std::ops::Range<u8>) =
+        (0x00..0x7F, 0xF8..0xFD);
+
+    /// Dynamic addresses
+    ///
+    /// any control application executing any system function can claim and use it.
+    /// The supplier of a control application can employ any strategy
+    /// to select the initial address within the range of 128 to 247.
+    ///
+    /// For more information see SAE J1939 4.6.2
+    pub const DYNAMIC_ADDRESSES: std::ops::Range<u8> = 0x80..0xF7;
+
+    /// Global Address
+    ///
+    /// The SAE J1939 source address 255 serves as the global destination address.
+    /// This global destination address is exclusively utilized as the destination
+    /// address in a D_PDU1 data frame to signify that the SAE J1939 data frame is
+    /// intended for all Control Applications (CAs) on the network.
+    ///
+    /// For more information see SAE J1939 4.6.3
     pub const GLOBAL: Address = Self::BROADCAST;
-    /// Alias for the global address
+    /// Alias for the [Address::GLOBAL]
     pub const BROADCAST: Address = Address(0xFF);
-    /// The null address is used by ECUs without an address such as during address claiming
+
+    /// Null Address
+    ///
+    /// The SAE J1939 source address 254 is designated as the Null address.
+    /// This Null address is specifically employed as the source (transmitter) address
+    /// within a D_PDU1 or D_PDU2 data frame.
+    ///
+    /// There are only two approved applications for the Null address:
+    ///
+    /// 1. The Null address can be utilized with an Address Claimed Parameter Group (PG)
+    /// when a Control Application (CA) reports its inability to claim an SAE J1939 Address.
+    ///
+    /// 2. the Null address can be employed with a Request PG soliciting
+    /// the Address Claimed PG when the Request PG is transmitted by a CA
+    /// prior to claiming a source address.
+    ///
+    /// For more information see SAE J1939 4.6.4
     pub const NULL: Address = Address(0xFE);
 
     /// Create a new address

src/j1939/byte_field.rs

@@ -1,3 +1,10 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
+
 use bitvec::order::Msb0;
 use bitvec::view::BitView;
 

src/j1939/extended_id.rs

@@ -1,4 +1,9 @@
-// Copyright 2023 Raven Industries inc.
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use crate::j1939::byte_field::ByteField;
 use crate::j1939::id::{Id, ParseIdError};
 use crate::j1939::priority::Priority;
@@ -68,11 +73,12 @@ impl From<ExtendedId> for EmbeddedId {
     }
 }
 
-impl TryFrom<u32> for ExtendedId {
+impl TryFrom<[bool; 29]> for ExtendedId {
     type Error = ParseIdError;
 
-    fn try_from(raw_id: u32) -> Result<Self, Self::Error> {
-        let bit_data = raw_id.view_bits::<Msb0>().to_bitvec();
+    fn try_from(raw_bits: [bool; 29]) -> Result<Self, Self::Error> {
+        let mut bit_data: BitVec<u8> = BitVec::new();
+        bit_data.extend(raw_bits.iter());
         let mut priority_bits =
             bit_data[ExtendedId::PRIORITY_START..ExtendedId::PRIORITY_END].to_bitvec();
         let mut pgn_bits = bit_data[ExtendedId::PGN_START..ExtendedId::PGN_END].to_bitvec();
@@ -102,6 +108,45 @@ impl TryFrom<u32> for ExtendedId {
     }
 }
 
+impl TryFrom<u32> for ExtendedId {
+    type Error = ParseIdError;
+
+    fn try_from(raw_id: u32) -> Result<Self, Self::Error> {
+        let raw_id_bits = raw_id.view_bits::<Msb0>().to_bitvec();
+        Self::try_from([
+            raw_id_bits[3],
+            raw_id_bits[4],
+            raw_id_bits[5],
+            raw_id_bits[6],
+            raw_id_bits[7],
+            raw_id_bits[8],
+            raw_id_bits[9],
+            raw_id_bits[10],
+            raw_id_bits[11],
+            raw_id_bits[12],
+            raw_id_bits[13],
+            raw_id_bits[14],
+            raw_id_bits[15],
+            raw_id_bits[16],
+            raw_id_bits[17],
+            raw_id_bits[18],
+            raw_id_bits[19],
+            raw_id_bits[20],
+            raw_id_bits[21],
+            raw_id_bits[22],
+            raw_id_bits[23],
+            raw_id_bits[24],
+            raw_id_bits[25],
+            raw_id_bits[26],
+            raw_id_bits[27],
+            raw_id_bits[28],
+            raw_id_bits[29],
+            raw_id_bits[30],
+            raw_id_bits[31],
+        ])
+    }
+}
+
 impl From<ExtendedId> for Id {
     fn from(id: ExtendedId) -> Self {
         Id::Extended(id)
@@ -176,7 +221,6 @@ mod tests {
         );
     }
 
-    /* not finished yet TODO!
     #[test]
     fn test_try_from_u32_for_extended_id() {
         let id = ExtendedId::try_from(0x18A0F25).unwrap();
@@ -205,5 +249,5 @@ mod tests {
                 Pgn::new(true, false, PduFormat::new(0x4C), PduSpecific::new(0x12)),
             )
         );
-    }*/
+    }
 }

src/j1939/frame.rs

@@ -1,4 +1,10 @@
-// Copyright 2023 Raven Industries inc.
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
+
 use crate::j1939::id::Id;
 use embedded_can::{Frame as EmbeddedFrame, Id as EmbeddedId};
 

src/j1939/id.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use crate::j1939::standard_id::StandardId;
 use crate::j1939::{Address, ExtendedId, Pgn, Priority};
 use bitvec::field::BitField;

src/j1939/page.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use bitvec::field::BitField;
 use bitvec::order::Msb0;
 use bitvec::prelude::BitVec;

src/j1939/pdu_format.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use crate::j1939::byte_field::ByteField;
 
 /// PDU format field defined in the PGN

src/j1939/pdu_specific.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use crate::j1939::byte_field::ByteField;
 
 /// PDU specific field defined in the PGN

src/j1939/pgn.rs

@@ -1,4 +1,10 @@
-// Copyright 2023 Raven Industries inc.
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
+
 use crate::j1939::byte_field::ByteField;
 use crate::j1939::page::Page;
 use crate::j1939::pdu_format::PduFormat;

src/j1939/priority.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use bitvec::field::BitField;
 use bitvec::order::Lsb0;
 use bitvec::vec::BitVec;

src/j1939/standard_id.rs

@@ -1,3 +1,9 @@
+/*
+Copyright 2023 Raven Industries inc.
+
+@author Jannes Brands
+@date 2024-02-22
+*/
 use crate::j1939::byte_field::ByteField;
 use crate::j1939::id::Id;
 use crate::j1939::{Address, Priority};