Skip to content

Latest commit

 

History

History
562 lines (463 loc) · 14.8 KB

JSON_STRUCTURE.md

File metadata and controls

562 lines (463 loc) · 14.8 KB

Zero Log Parser - JSON Output Structure

This document describes the structure of JSON output generated by the Zero Motorcycle Log Parser, including all structured data formats extracted from both MBB (Main Bike Board) and BMS (Battery Management System) logs.

Table of Contents

Overview

The Zero Log Parser converts binary motorcycle log files into structured JSON format, automatically detecting and parsing various telemetry data types. The JSON output contains both metadata about the log file and a chronologically sorted array of log entries, some containing structured sensor data.

Recent Updates (v2.3.0+): The parser was refactored with centralized processing architecture, improving consistency across all output formats while maintaining backward compatibility. Structured data output was enhanced with better formatting for TXT and CSV formats.

Root JSON Structure

{
  "metadata": {
    "source_file": "path/to/logfile.bin",
    "log_type": "MBB|BMS",
    "parser_version": "zero-log-parser-2.3.0-dev",
    "generated_at": "2025-08-10T15:08:19.890176",
    "timezone": "UTC+2.0",
    "total_entries": 6603
  },
  "log_info": {
    "vin": "VIN_NUMBER|Unknown",
    "serial_number": "SERIAL|Unknown",
    "initial_date": "YYYY-MM-DD|Unknown",
    "model": "MODEL_NAME|Unknown",
    "firmware_rev": "REVISION|Unknown",
    "board_rev": "BOARD_REV|Unknown"
  },
  "entries": [
    // Array of log entries (see Entry Structure below)
  ]
}

Metadata Fields

Field Description
source_file Path to the original binary log file
log_type Type of log: "MBB" (Main Bike Board) or "BMS" (Battery Management System)
parser_version Version of the parser used to generate this output
generated_at ISO timestamp when JSON was generated
timezone Timezone used for timestamp conversion
total_entries Total number of log entries in the file

Log Info Fields

These fields contain extracted motorcycle information when available:

Field Description
vin Vehicle Identification Number
serial_number Board serial number
initial_date Date when logging started
model Motorcycle model
firmware_rev Firmware revision
board_rev Board revision

Entry Structure

Each log entry follows this structure:

{
  "entry_number": 6490,
  "timestamp": "2025-08-03 12:34:32",
  "sort_timestamp": 1754216889.0,
  "log_level": "DATA|INFO|WARN|ERROR",
  "event": "Human readable event name",
  "conditions": "Additional context|null",
  "is_structured_data": true|false,
  "structured_data": {
    // Structured sensor data (only present when is_structured_data=true)
  }
}

Entry Fields

Field Description
entry_number Original entry number from the log file
timestamp Human-readable timestamp in configured timezone
sort_timestamp Unix timestamp used for chronological sorting
log_level Severity level: DATA, INFO, WARN, ERROR
event Descriptive name of the logged event
conditions Additional context or description (optional)
is_structured_data Boolean indicating if structured_data field is present
structured_data Object containing parsed sensor data (when available)

Output Format Differences

The parser supports multiple output formats, each handling structured data differently:

JSON Format

  • Structured Data: Parsed into structured_data object with individual fields
  • Conditions Field: null for entries with structured data
  • Example:
{
  "entry_number": 6,
  "event": "Discharge level",
  "conditions": null,
  "is_structured_data": true,
  "structured_data": {
    "amp_hours": 7,
    "state_of_charge_percent": 94,
    "current_amps": 1,
    "voltage_low_cell_volts": 4.05,
    "pack_temp_celsius": 21
  }
}

CSV/TSV Format

  • Structured Data: JSON-encoded string in conditions column
  • Example:
entry,timestamp,log_level,message,conditions,uninterpreted
6,2025-08-03 12:42:34,DATA,Discharge level,"{""amp_hours"":7,""state_of_charge_percent"":94,""current_amps"":1}",

TXT Format

  • Structured Data: Human-readable key-value pairs with intelligent formatting
  • Unit Detection: Automatic units (%, V, A, mA, mV, °C) based on field names
  • Key Formatting: Snake_case converted to "Title Case"
  • Example:
00006  2025-08-03 12:42:34  DATA  Discharge level  Amp Hours: 7, State Of Charge Percent: 94%, Current Amps: 1A, Voltage Low Cell Volts: 4.05V, Pack Temp Celsius: 21°C

Structured Data Types

The parser automatically detects and structures various telemetry data types. Below are all currently supported structured data formats:

MBB (Main Bike Board) Events

Riding State Data

Event: Riding
Description: Comprehensive telemetry data during active riding
Frequency: High (every few seconds while riding)

{
  "pack_temp_high_celsius": 21,
  "pack_temp_low_celsius": 20,
  "state_of_charge_percent": 95,
  "pack_voltage_volts": 113.618,
  "motor_current_amps": -13,
  "battery_current_amps": 0,
  "modules_status": 10,
  "motor_temp_celsius": 39,
  "controller_temp_celsius": 27,
  "ambient_temp_celsius": 13,
  "motor_rpm": 700,
  "odometer_km": 5646
}

Disarmed State Data

Event: Disarmed
Description: Telemetry data when motorcycle is powered but not in active use
Frequency: Regular intervals while powered

{
  "pack_temp_high_celsius": 21,
  "pack_temp_low_celsius": 20,
  "state_of_charge_percent": 95,
  "pack_voltage_volts": 113.907,
  "motor_current_amps": 0,
  "battery_current_amps": 1,
  "modules_status": 1,
  "motor_temp_celsius": 23,
  "controller_temp_celsius": 19,
  "ambient_temp_celsius": 17,
  "motor_rpm": 0,
  "odometer_km": 5646
}

Charging State Data

Event: Charging
Description: Telemetry data during active charging sessions
Frequency: Regular intervals during charging

{
  "pack_temp_high_celsius": 29,
  "pack_temp_low_celsius": 27,
  "ambient_temp_celsius": 30,
  "state_of_charge_percent": 100,
  "pack_voltage_volts": 116.206,
  "battery_current_amps": -19,
  "modules_status": 1,
  "mbb_charge_enable": "Yes",
  "bms_charge_enable": "No"
}

Module Registration

Event: Module 00 Registered
Description: Registration of battery modules with the system
Frequency: At startup/connection events

{
  "serial_number": "19tb3313",
  "module_voltage_volts": 113.92
}

Contactor Operations

Event: Module 00 Closing Contactor, Module 01 Opening Contactor
Description: Battery contactor state changes with voltage monitoring
Frequency: During power state transitions

{
  "module_voltage_volts": 113.927,
  "max_system_voltage_volts": 113.927,
  "min_system_voltage_volts": 113.927,
  "voltage_difference_volts": 0.0,
  "capacitor_voltage_volts": 101.75,
  "precharge_percent": 89
}

Charger Data

Event: Charger 6 Charging, Charger 6 Stopped
Description: External charger status and AC power characteristics
Frequency: During charging operations

{
  "serial_number": "2329104",
  "software_version": 209,
  "voltage_ac": 237,
  "frequency_hz": 50,
  "evse_current_amps": 16
}

Safety Events

Event: Tipover Detected
Description: Accelerometer data when tipover is detected
Frequency: During tipover events

{
  "measurement_type": "accelerometer",
  "raw_roll_min": -45.2,
  "raw_roll_max": 12.8,
  "filtered_roll_min": -42.1,
  "filtered_roll_max": 10.5,
  "raw_pitch_min": -15.3,
  "raw_pitch_max": 25.7,
  "filtered_pitch_min": -12.9,
  "filtered_pitch_max": 22.4
}

Error Conditions

Event: SEVCON CAN EMCY Frame
Description: Motor controller emergency error frames
Frequency: During fault conditions

{
  "error_code": "0x1000",
  "error_register": "0x01",
  "sevcon_error_code": "0x4884",
  "data": "00 00 00 C0 02",
  "cause": "Sequence Fault"
}

BMS (Battery Management System) Events

Battery Discharge Telemetry

Event: Discharge level
Description: Comprehensive battery state during discharge (most frequent BMS data)
Frequency: Very high (multiple times per minute)

{
  "amp_hours": 7,
  "state_of_charge_percent": 94,
  "current_amps": 1,
  "voltage_low_cell_volts": 4.05,
  "voltage_unloaded_cell_volts": 4.05,
  "voltage_high_cell_volts": 4.05,
  "voltage_balance_mv": 4,
  "pack_temp_celsius": 21,
  "bms_temp_celsius": 27,
  "pack_voltage_volts": 113.4,
  "pack_voltage_mv": 113400,
  "mode": "Bike On"
}

State of Charge Data

Event: SOC Data
Description: Detailed state of charge calculations and cell voltages
Frequency: Very high (multiple times per minute)

{
  "soc_raw_1": 6804,
  "soc_raw_2": 98535,
  "soc_raw_3": 7734,
  "pack_voltage_volts": 114.8,
  "pack_voltage_mv": 114800,
  "soc_percent_1": 94,
  "soc_percent_2": 93,
  "soc_percent_3": 94,
  "balance_count": 2,
  "voltage_max_volts": 4.057,
  "voltage_min_1_volts": 4.049,
  "voltage_min_2_volts": 4.05,
  "voltage_max": 4057,
  "voltage_min_1": 4049,
  "voltage_min_2": 4050,
  "current_ma": 1090,
  "current_amps": 1.09
}

Firmware Information

Event: Firmware Version
Description: BMS firmware build information
Frequency: At startup

{
  "revision": 48,
  "build_date": "2024-11-17",
  "build_time": "14:19:50",
  "build_datetime": "2024-11-17 14:19:50",
  "build_number": 993,
  "branch": "banka"
}

Battery Configuration

Event: Battery Pack Configuration
Description: Physical battery pack specifications
Frequency: At startup/regularly

{
  "pack_type": "2019_monolith",
  "pack_year": "2019",
  "pack_design": "monolith",
  "number_of_bricks": 4
}

Current Sensor Calibration

Event: Current Sensor Zeroed
Description: Current sensor calibration adjustments
Frequency: During calibration events

{
  "old_voltage_mv": 2492,
  "new_voltage_mv": 2493,
  "correction_factor": 7
}

Contactor Monitoring

Event: Voltage Across Contactor
Description: High voltage contactor monitoring
Frequency: During contactor operations

{
  "voltage_mv": 101672,
  "voltage_v": 101.672,
  "status": "Okay"
}

Diagnostic Events

Event: Voltage Reading
Description: Raw voltage measurements from ADC
Frequency: During diagnostics

{
  "hex_value": "0x752",
  "voltage_mv": 1874,
  "voltage_volts": 1.874
}

Fault Conditions

Event: State Machine Charge Fault
Description: Charging state machine fault data
Frequency: During fault conditions

{
  "mode": 2,
  "current_ma": 1272,
  "current_a": 1.272,
  "voltage_rate_mv_per_min": 0,
  "voltage_rate_mv_per_min_alt": 1,
  "tssc_ms": 600014,
  "tsco_ms": 509817,
  "tips_ms": 501590,
  "tssc_seconds": 600.014,
  "tsco_seconds": 509.817,
  "tips_seconds": 501.59
}

Event: Disabling Due to lack of CAN control messages
Description: Communication fault leading to system disable
Frequency: During communication faults

{
  "discharge_current_ma": 908,
  "discharge_current_a": 0.908
}

Field Definitions

Common Field Types

Type Description Example
*_celsius Temperature in Celsius 21
*_percent Percentage value 94
*_volts Voltage in volts 113.4
*_mv Voltage in millivolts 113400
*_amps Current in amperes 1.09
*_ma Current in milliamperes 1090
*_rpm Rotations per minute 700
*_km Distance in kilometers 5646
*_hz Frequency in hertz 50
*_ms Time in milliseconds 600014
*_seconds Time in seconds 600.014

Specific Field Meanings

Battery Fields

  • state_of_charge_percent: Battery charge level (0-100%)
  • pack_voltage_volts: Total battery pack voltage
  • battery_current_amps: Current flow to/from battery (negative = charging)
  • amp_hours: Cumulative amp-hours consumed
  • voltage_balance_mv: Voltage difference between highest/lowest cells

Motor Fields

  • motor_current_amps: Motor current draw (negative = regeneration)
  • motor_rpm: Motor rotational speed
  • motor_temp_celsius: Motor temperature

Temperature Fields

  • pack_temp_high_celsius: Highest battery cell temperature
  • pack_temp_low_celsius: Lowest battery cell temperature
  • ambient_temp_celsius: Environmental temperature
  • controller_temp_celsius: Motor controller temperature
  • bms_temp_celsius: BMS board temperature

Status Fields

  • modules_status: Bitmask of active battery modules
  • mbb_charge_enable: MBB charging permission ("Yes"/"No")
  • bms_charge_enable: BMS charging permission ("Yes"/"No")
  • mode: Operating mode (e.g., "Bike On", charging states)

Usage Examples

Parsing for Data Analysis

import json

# Load parsed log data
with open('motorcycle_log.json') as f:
    log_data = json.load(f)

# Extract all riding telemetry
riding_data = []
for entry in log_data['entries']:
    if entry.get('event') == 'Riding' and entry.get('is_structured_data'):
        riding_data.append({
            'timestamp': entry['timestamp'],
            'soc_percent': entry['structured_data']['state_of_charge_percent'],
            'motor_rpm': entry['structured_data']['motor_rpm'],
            'motor_temp': entry['structured_data']['motor_temp_celsius']
        })

print(f"Found {len(riding_data)} riding data points")

Filtering by Event Type

# Get all structured battery discharge data
discharge_events = [
    entry for entry in log_data['entries']
    if entry.get('event') == 'Discharge level' and entry.get('is_structured_data')
]

# Extract SOC progression
soc_history = [
    (entry['timestamp'], entry['structured_data']['state_of_charge_percent'])
    for entry in discharge_events
]

Error Analysis

# Find all error events
error_events = [
    entry for entry in log_data['entries']
    if entry['log_level'] in ['ERROR', 'WARN'] or 'fault' in entry['event'].lower()
]

for error in error_events:
    print(f"{error['timestamp']}: {error['event']}")
    if error.get('is_structured_data'):
        print(f"  Data: {error['structured_data']}")

Note: This structure documentation is based on analysis of actual Zero Motorcycle log files (VIN: 538SDLZB2NCB19168) from August 2025. Field availability and structure may vary between different motorcycle models, firmware versions, and log types.