======================================================================
  Cross-Platform SPN Harmonization Template (CSV)
======================================================================

DEFINITION
----------------------------------------
The Cross-Platform SPN Harmonization Template (CSV) is a standardized, human- and
machine-readable spreadsheet format used to map, normalize, and reconcile Suspect
Parameter Numbers (SPNs) across disparate telematics platforms, OEMs, and ECU
implementations. It enables consistent interpretation of diagnostic and operational
vehicle data by resolving semantic, numeric, and contextual discrepancies in SPN
definitions. The template serves as a foundational interoperability artifact for
fleet diagnostics, predictive maintenance, and data federation systems.

OVERVIEW
----------------------------------------
Suspect Parameter Numbers (SPNs) are standardized identifiers defined in SAE J1939
for vehicle parameters such as engine speed, coolant temperature, or fault codes.
However, inconsistencies arise across manufacturers—same SPN may encode different
scaling, units, or bit-lengths; same physical parameter may be assigned different
SPNs; or vendor-specific extensions may lack standardization. The Cross-Platform SPN
Harmonization Template addresses these challenges by providing a structured CSV
schema with columns for canonical SPN ID, OEM-specific SPN aliases, physical
parameter name, engineering units, scaling factor (m), offset (b), bit resolution,
data type (e.g., UINT16, FLOAT32), J1939-defined description, and platform-specific
metadata (e.g., 'Cummins INSITE', 'Volvo VDS', 'Geotab ELD'). Each row represents a
harmonized logical parameter, enabling deterministic translation between raw CAN bus
payloads and unified fleet analytics schemas. The template supports
version-controlled, collaborative curation—often maintained in Git
repositories—and integrates into automated pipelines that generate ontology
mappings, database schemas, or JSON-LD context files for semantic interoperability.
Its adoption significantly reduces integration effort when onboarding heterogeneous
vehicle fleets and underpins regulatory compliance (e.g., FMCSA ELD data validation)
and AI/ML model training on normalized telematics time-series.

KEY COMPONENTS
----------------------------------------
1. Canonical SPN Identifier
2. OEM/Platform-Specific SPN Mappings
3. Parameter Metadata (Units, Scaling, Bit Layout)

APPLICATIONS
----------------------------------------
  - Fleet Management System Integration
  - Cross-OEM Diagnostic Data Normalization
  - Regulatory Compliance Reporting (e.g., FMCSA, ULEZ)

KEY FORMULAS
----------------------------------------
Physical Value Reconstruction: physical_value = (raw_value × scaling_factor) + offset
  -> Converts raw binary or integer CAN payload value to real-world engineering units (e.g., °C, kPa, RPM)
SPN Bit Position Resolution: start_bit = (SPN_start_byte × 8) + SPN_start_bit_offset
  -> Computes the zero-based bit index within a PGN where an SPN's data field begins, critical for correct parsing from CAN frames

RELATED CONCEPTS
----------------------------------------
  - SAE J1939
  - Parameter Group Number (PGN)
  - Telematics Data Ontology

REFERENCES
----------------------------------------
SAE J1939-71: Vehicle Application Layer (https://www.sae.org/standards/content/j1939/71_202304/)
Geotab SPN Mapping Repository (GitHub) (https://github.com/Geotab/public-spns)
ISO 24534-3: Commercial Vehicle Telematics Interoperability Framework (https://www.iso.org/standard/79231.html)

TAGS
----------------------------------------
telematics, SAE-J1939, fleet-diagnostics, data-harmonization, CSV-template