{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/am32-firmware/AM32/am32-eeprom-schema.json",
  "title": "AM32 EEPROM Settings Schema",
  "description": "Unified schema for AM32 ESC EEPROM layout, settings metadata, and version-specific behavior",
  "version": "1.0.1",

  "eepromVersions": {
    "2": {
      "description": "Legacy EEPROM format (pre-extended settings)",
      "minSize": 48,
      "bufferSize": 192,
      "notes": "Original format without extended settings like current PID. Offsets 5-16 contained ESC name string."
    },
    "3": {
      "description": "Extended settings format",
      "minSize": 48,
      "bufferSize": 192,
      "notes": "Added current PID, ramp rate, min duty cycle, absolute voltage cutoff at offsets 5-12"
    },
    "4": {
      "description": "CAN settings format",
      "minSize": 184,
      "bufferSize": 192,
      "notes": "Added CAN bus configuration at offset 176-191"
    }
  },

  "fields": {
    "bootByte": {
      "offset": 0,
      "size": 1,
      "type": "uint8",
      "name": "Boot Byte",
      "description": "Boot indicator byte (0x01 = valid)",
      "readOnly": true,
      "cName": "reserved_0"
    },

    "eepromVersion": {
      "offset": 1,
      "size": 1,
      "type": "uint8",
      "name": "EEPROM Version",
      "description": "Layout revision number",
      "readOnly": true,
      "cName": "eeprom_version"
    },

    "bootloaderVersion": {
      "offset": 2,
      "size": 1,
      "type": "uint8",
      "name": "Bootloader Version",
      "readOnly": true,
      "cName": "reserved_1"
    },

    "firmwareMajor": {
      "offset": 3,
      "size": 1,
      "type": "uint8",
      "name": "Firmware Major Version",
      "readOnly": true,
      "cName": "version.major"
    },

    "firmwareMinor": {
      "offset": 4,
      "size": 1,
      "type": "uint8",
      "name": "Firmware Minor Version",
      "readOnly": true,
      "cName": "version.minor"
    },

    "maxRampSpeed": {
      "offset": 5,
      "size": 1,
      "type": "number",
      "name": "Max Ramp Speed",
      "description": "Maximum throttle ramp rate",
      "unit": "% per ms",
      "minEepromVersion": 3,
      "cName": "max_ramp",
      "raw": {
        "min": 1,
        "max": 200
      },
      "display": {
        "min": 0.1,
        "max": 20.0,
        "factor": 0.1,
        "offset": 0,
        "decimals": 1
      }
    },

    "minDutyCycle": {
      "offset": 6,
      "size": 1,
      "type": "number",
      "name": "Minimum Duty Cycle",
      "description": "Minimum motor duty cycle",
      "unit": "%",
      "minEepromVersion": 3,
      "cName": "minimum_duty_cycle",
      "raw": {
        "min": 0,
        "max": 50
      },
      "display": {
        "min": 0.0,
        "max": 25.0,
        "factor": 0.5,
        "offset": 0,
        "decimals": 1
      }
    },

    "disableStickCalibration": {
      "offset": 7,
      "size": 1,
      "type": "bool",
      "name": "Disable Stick Calibration",
      "description": "Disable automatic throttle range calibration",
      "minEepromVersion": 3,
      "cName": "disable_stick_calibration"
    },

    "absoluteVoltageCutoff": {
      "offset": 8,
      "size": 1,
      "type": "number",
      "name": "Absolute Voltage Cutoff",
      "description": "Fixed voltage cutoff threshold (when low voltage mode = Absolute)",
      "unit": "V",
      "minEepromVersion": 3,
      "cName": "absolute_voltage_cutoff",
      "raw": {
        "min": 1,
        "max": 100
      },
      "display": {
        "min": 0.5,
        "max": 50.0,
        "factor": 0.5,
        "offset": 0,
        "decimals": 1
      }
    },

    "currentPidP": {
      "offset": 9,
      "size": 1,
      "type": "number",
      "name": "Current PID P",
      "description": "Proportional gain for current control loop",
      "minEepromVersion": 3,
      "cName": "current_P",
      "raw": {
        "min": 0,
        "max": 255
      },
      "display": {
        "min": 0,
        "max": 510,
        "factor": 2,
        "offset": 0,
        "decimals": 0
      }
    },

    "currentPidI": {
      "offset": 10,
      "size": 1,
      "type": "uint8",
      "name": "Current PID I",
      "description": "Integral gain for current control loop",
      "minEepromVersion": 3,
      "cName": "current_I",
      "raw": {
        "min": 0,
        "max": 255
      }
    },

    "currentPidD": {
      "offset": 11,
      "size": 1,
      "type": "number",
      "name": "Current PID D",
      "description": "Derivative gain for current control loop",
      "minEepromVersion": 3,
      "cName": "current_D",
      "raw": {
        "min": 0,
        "max": 255
      },
      "display": {
        "min": 0,
        "max": 510,
        "factor": 2,
        "offset": 0,
        "decimals": 0
      }
    },

    "activeBrakePower": {
      "offset": 12,
      "size": 1,
      "type": "uint8",
      "name": "Active Brake Power",
      "description": "Active braking duty cycle",
      "unit": "%",
      "minEepromVersion": 3,
      "cName": "active_brake_power",
      "raw": {
        "min": 0,
        "max": 10
      }
    },

    "reserved0": {
      "offset": 13,
      "size": 4,
      "type": "reserved",
      "name": "Reserved",
      "description": "Reserved bytes for future use",
      "cName": "reserved_eeprom_3",
      "hidden": true
    },

    "directionReversed": {
      "offset": 17,
      "size": 1,
      "type": "bool",
      "name": "Direction Reversed",
      "description": "Reverse motor rotation direction",
      "cName": "dir_reversed"
    },

    "bidirectionalMode": {
      "offset": 18,
      "size": 1,
      "type": "bool",
      "name": "Bidirectional Mode",
      "description": "Enable 3D mode (forward and reverse)",
      "cName": "bi_direction"
    },

    "sineStartup": {
      "offset": 19,
      "size": 1,
      "type": "bool",
      "name": "Sinusoidal Startup",
      "description": "Use sinusoidal commutation during startup",
      "cName": "use_sine_start"
    },

    "complementaryPwm": {
      "offset": 20,
      "size": 1,
      "type": "bool",
      "name": "Complementary PWM",
      "description": "Enable complementary PWM mode",
      "cName": "comp_pwm"
    },

    "variablePwmFreq": {
      "offset": 21,
      "size": 1,
      "type": "enum",
      "name": "Variable PWM Frequency",
      "description": "PWM frequency mode",
      "cName": "variable_pwm",
      "versions": {
        "default": {
          "values": [
            { "raw": 0, "name": "Off", "description": "Fixed PWM frequency" },
            { "raw": 1, "name": "On", "description": "Variable PWM frequency" }
          ]
        },
        "firmware:2.18+": {
          "values": [
            { "raw": 0, "name": "Fixed", "description": "Fixed PWM frequency" },
            { "raw": 1, "name": "Variable", "description": "Variable PWM frequency" },
            { "raw": 2, "name": "By RPM", "description": "PWM frequency varies with RPM" }
          ]
        }
      }
    },

    "stuckRotorProtection": {
      "offset": 22,
      "size": 1,
      "type": "bool",
      "name": "Stuck Rotor Protection",
      "description": "Stop motor if rotor is stuck",
      "cName": "stuck_rotor_protection"
    },

    "timingAdvance": {
      "offset": 23,
      "size": 1,
      "type": "number",
      "name": "Timing Advance",
      "description": "Motor commutation timing advance angle (0.9375° per internal unit)",
      "unit": "°",
      "cName": "advance_level",
      "versions": {
        "default": {
          "raw": {
            "min": 0,
            "max": 3
          },
          "display": {
            "min": 0,
            "max": 22.5,
            "factor": 7.5,
            "offset": 0,
            "decimals": 1
          },
          "notes": "Old format: raw 0-3 maps to 0°, 7.5°, 15°, 22.5°"
        },
        "eeprom:3+": {
          "raw": {
            "min": 10,
            "max": 42
          },
          "display": {
            "min": 0,
            "max": 30,
            "factor": 0.9375,
            "offset": -9.375,
            "decimals": 1
          },
          "notes": "New format: raw 10-42 stored in EEPROM, internally converted to 0-32, then multiplied by 0.9375 for degrees"
        }
      }
    },

    "pwmFrequency": {
      "offset": 24,
      "size": 1,
      "type": "uint8",
      "name": "PWM Frequency",
      "description": "Base PWM switching frequency",
      "unit": "kHz",
      "cName": "pwm_frequency",
      "versions": {
        "default": {
          "raw": {
            "min": 8,
            "max": 48
          }
        },
        "eeprom:3+": {
          "raw": {
            "min": 8,
            "max": 144
          }
        }
      }
    },

    "startupPower": {
      "offset": 25,
      "size": 1,
      "type": "uint8",
      "name": "Startup Power",
      "description": "Power level during motor startup",
      "unit": "%",
      "cName": "startup_power",
      "raw": {
        "min": 50,
        "max": 150
      }
    },

    "motorKv": {
      "offset": 26,
      "size": 1,
      "type": "number",
      "name": "Motor KV",
      "description": "Motor KV rating (RPM per volt)",
      "cName": "motor_kv",
      "raw": {
        "min": 0,
        "max": 255
      },
      "display": {
        "min": 20,
        "max": 10220,
        "factor": 40,
        "offset": 20,
        "decimals": 0
      }
    },

    "motorPoles": {
      "offset": 27,
      "size": 1,
      "type": "uint8",
      "name": "Motor Poles",
      "description": "Number of motor magnetic poles",
      "cName": "motor_poles",
      "raw": {
        "min": 2,
        "max": 36
      }
    },

    "brakeOnStop": {
      "offset": 28,
      "size": 1,
      "type": "enum",
      "name": "Brake on Stop",
      "description": "Braking behavior when throttle is at minimum",
      "cName": "brake_on_stop",
      "values": [
        { "raw": 0, "name": "Off", "description": "No braking when stopped" },
        { "raw": 1, "name": "Brake", "description": "Apply brake when throttle is at minimum" },
        { "raw": 2, "name": "Active Brake", "description": "Active braking mode (requires arming)" }
      ]
    },

    "stallProtection": {
      "offset": 29,
      "size": 1,
      "type": "bool",
      "name": "Stall Protection",
      "description": "Anti-stall protection during low-speed operation",
      "cName": "stall_protection"
    },

    "beepVolume": {
      "offset": 30,
      "size": 1,
      "type": "uint8",
      "name": "Beep Volume",
      "description": "Startup beep volume level",
      "cName": "beep_volume",
      "raw": {
        "min": 0,
        "max": 11
      }
    },

    "telemetry30ms": {
      "offset": 31,
      "size": 1,
      "type": "bool",
      "name": "30ms Interval Telemetry",
      "description": "Use 30ms telemetry interval instead of default",
      "cName": "telemetry_on_interval"
    },

    "servoLowThreshold": {
      "offset": 32,
      "size": 1,
      "type": "number",
      "name": "Servo Low Threshold",
      "description": "Minimum servo pulse width for zero throttle",
      "unit": "us",
      "cName": "servo.low_threshold",
      "raw": {
        "min": 0,
        "max": 250
      },
      "display": {
        "min": 750,
        "max": 1250,
        "factor": 2,
        "offset": 750,
        "decimals": 0
      }
    },

    "servoHighThreshold": {
      "offset": 33,
      "size": 1,
      "type": "number",
      "name": "Servo High Threshold",
      "description": "Maximum servo pulse width for full throttle",
      "unit": "us",
      "cName": "servo.high_threshold",
      "raw": {
        "min": 0,
        "max": 250
      },
      "display": {
        "min": 1750,
        "max": 2250,
        "factor": 2,
        "offset": 1750,
        "decimals": 0
      }
    },

    "servoNeutral": {
      "offset": 34,
      "size": 1,
      "type": "number",
      "name": "Servo Neutral",
      "description": "Servo pulse width for neutral position (3D mode)",
      "unit": "us",
      "cName": "servo.neutral",
      "raw": {
        "min": 0,
        "max": 255
      },
      "display": {
        "min": 1374,
        "max": 1629,
        "factor": 1,
        "offset": 1374,
        "decimals": 0
      }
    },

    "servoDeadband": {
      "offset": 35,
      "size": 1,
      "type": "uint8",
      "name": "Servo Deadband",
      "description": "Deadband around neutral position",
      "cName": "servo.dead_band",
      "raw": {
        "min": 0,
        "max": 100
      }
    },

    "lowVoltageCutoff": {
      "offset": 36,
      "size": 1,
      "type": "enum",
      "name": "Low Voltage Cutoff",
      "description": "Low voltage protection mode",
      "cName": "low_voltage_cut_off",
      "versions": {
        "default": {
          "values": [
            { "raw": 0, "name": "Off", "description": "No low voltage protection" },
            { "raw": 1, "name": "On", "description": "Cell-based voltage cutoff" }
          ]
        },
        "firmware:2.19+": {
          "values": [
            { "raw": 0, "name": "Off", "description": "No low voltage protection" },
            { "raw": 1, "name": "Cell Based", "description": "Per-cell voltage threshold" },
            { "raw": 2, "name": "Absolute", "description": "Fixed voltage threshold" }
          ]
        }
      }
    },

    "lowVoltageThreshold": {
      "offset": 37,
      "size": 1,
      "type": "number",
      "name": "Low Voltage Threshold",
      "description": "Per-cell voltage cutoff threshold",
      "unit": "V",
      "cName": "low_cell_volt_cutoff",
      "raw": {
        "min": 0,
        "max": 100
      },
      "display": {
        "min": 2.50,
        "max": 3.50,
        "factor": 0.01,
        "offset": 2.50,
        "decimals": 2
      }
    },

    "rcCarReversing": {
      "offset": 38,
      "size": 1,
      "type": "bool",
      "name": "RC Car Reversing",
      "description": "Enable RC car style brake-then-reverse behavior",
      "cName": "rc_car_reverse"
    },

    "hallSensors": {
      "offset": 39,
      "size": 1,
      "type": "bool",
      "name": "Hall Sensors",
      "description": "Use hall sensor feedback for commutation",
      "cName": "use_hall_sensors"
    },

    "sineModeRange": {
      "offset": 40,
      "size": 1,
      "type": "uint8",
      "name": "Sine Mode Range",
      "description": "Throttle range for sine mode operation",
      "unit": "%",
      "cName": "sine_mode_changeover_thottle_level",
      "raw": {
        "min": 5,
        "max": 25
      }
    },

    "dragBrakeStrength": {
      "offset": 41,
      "size": 1,
      "type": "uint8",
      "name": "Drag Brake Strength",
      "description": "Brake strength when throttle released",
      "cName": "drag_brake_strength",
      "raw": {
        "min": 1,
        "max": 10
      }
    },

    "runningBrakeLevel": {
      "offset": 42,
      "size": 1,
      "type": "uint8",
      "name": "Running Brake Level",
      "description": "Brake level during deceleration",
      "cName": "driving_brake_strength",
      "raw": {
        "min": 1,
        "max": 10
      }
    },

    "temperatureLimit": {
      "offset": 43,
      "size": 1,
      "type": "uint8",
      "name": "Temperature Limit",
      "description": "Maximum ESC temperature before throttling",
      "unit": "°C",
      "cName": "limits.temperature",
      "raw": {
        "min": 70,
        "max": 141
      },
      "disabledValue": {
        "raw": 141,
        "display": "Disabled"
      }
    },

    "currentLimit": {
      "offset": 44,
      "size": 1,
      "type": "number",
      "name": "Current Limit",
      "description": "Maximum motor current",
      "unit": "A",
      "cName": "limits.current",
      "raw": {
        "min": 0,
        "max": 101
      },
      "display": {
        "min": 0,
        "max": 202,
        "factor": 2,
        "offset": 0,
        "decimals": 0
      },
      "disabledValue": {
        "raw": 101,
        "displayValue": 202,
        "display": "Disabled"
      }
    },

    "sineModePower": {
      "offset": 45,
      "size": 1,
      "type": "uint8",
      "name": "Sine Mode Power",
      "description": "Power level during sine mode startup",
      "cName": "sine_mode_power",
      "raw": {
        "min": 1,
        "max": 10
      }
    },

    "inputType": {
      "offset": 46,
      "size": 1,
      "type": "enum",
      "name": "Input Type",
      "description": "ESC input protocol",
      "cName": "input_type",
      "values": [
        { "raw": 0, "name": "Auto", "description": "Automatically detect input protocol" },
        { "raw": 1, "name": "DShot", "description": "DShot digital protocol" },
        { "raw": 2, "name": "Servo", "description": "Standard PWM servo signal" },
        { "raw": 3, "name": "Serial", "description": "Serial communication" },
        { "raw": 4, "name": "EDT ARM", "description": "EDT arming protocol" }
      ]
    },

    "autoTiming": {
      "offset": 47,
      "size": 1,
      "type": "bool",
      "name": "Auto Timing",
      "description": "Automatically adjust commutation timing",
      "minFirmwareVersion": "2.16",
      "cName": "auto_advance"
    },

    "startupMelody": {
      "offset": 48,
      "size": 128,
      "type": "rtttl",
      "name": "Startup Melody",
      "description": "RTTTL format startup tune",
      "cName": "tune"
    },

    "canNode": {
      "offset": 176,
      "size": 1,
      "type": "uint8",
      "name": "CAN Node ID",
      "description": "CAN bus node identifier",
      "minEepromVersion": 4,
      "cName": "can.can_node",
      "raw": {
        "min": 0,
        "max": 127
      }
    },

    "canEscIndex": {
      "offset": 177,
      "size": 1,
      "type": "uint8",
      "name": "CAN ESC Index",
      "description": "ESC index for CAN communication",
      "minEepromVersion": 4,
      "cName": "can.esc_index",
      "raw": {
        "min": 0,
        "max": 32
      }
    },

    "canRequireArming": {
      "offset": 178,
      "size": 1,
      "type": "bool",
      "name": "CAN Require Arming",
      "description": "Require arming command before motor start",
      "minEepromVersion": 4,
      "cName": "can.require_arming"
    },

    "canTelemRate": {
      "offset": 179,
      "size": 1,
      "type": "uint8",
      "name": "CAN Telemetry Rate",
      "description": "CAN telemetry transmission rate",
      "unit": "Hz",
      "minEepromVersion": 4,
      "cName": "can.telem_rate",
      "raw": {
        "min": 0,
        "max": 200
      }
    },

    "canRequireZeroThrottle": {
      "offset": 180,
      "size": 1,
      "type": "bool",
      "name": "CAN Require Zero Throttle",
      "description": "Require zero throttle before arming",
      "minEepromVersion": 4,
      "cName": "can.require_zero_throttle"
    },

    "canFilterHz": {
      "offset": 181,
      "size": 1,
      "type": "uint8",
      "name": "CAN Filter Hz",
      "description": "CAN input filter frequency",
      "unit": "Hz",
      "minEepromVersion": 4,
      "cName": "can.filter_hz",
      "raw": {
        "min": 0,
        "max": 100
      }
    },

    "canDebugRate": {
      "offset": 182,
      "size": 1,
      "type": "uint8",
      "name": "CAN Debug Rate",
      "description": "CAN debug message rate",
      "unit": "Hz",
      "minEepromVersion": 4,
      "cName": "can.debug_rate",
      "raw": {
        "min": 0,
        "max": 200
      }
    },

    "canTermEnable": {
      "offset": 183,
      "size": 1,
      "type": "bool",
      "name": "CAN Termination Enable",
      "description": "Enable CAN bus termination resistor",
      "minEepromVersion": 4,
      "cName": "can.term_enable"
    },

    "canReserved": {
      "offset": 184,
      "size": 8,
      "type": "uint8",
      "name": "CAN Reserved",
      "description": "Reserved bytes for future CAN settings",
      "minEepromVersion": 4,
      "cName": "can.reserved"
    }
  },

  "groups": {
    "info": {
      "name": "ESC Information",
      "fields": ["bootByte", "eepromVersion", "bootloaderVersion", "firmwareMajor", "firmwareMinor"],
      "description": "Read-only ESC identification and version information"
    },
    "motor": {
      "name": "Motor Settings",
      "fields": ["directionReversed", "bidirectionalMode", "motorKv", "motorPoles", "timingAdvance", "autoTiming", "startupPower", "pwmFrequency", "variablePwmFreq", "complementaryPwm", "stuckRotorProtection", "stallProtection", "hallSensors"],
      "description": "Motor configuration and commutation settings"
    },
    "extended": {
      "name": "Extended Settings",
      "fields": ["maxRampSpeed", "minDutyCycle", "disableStickCalibration"],
      "description": "Extended motor control settings (EEPROM v3+)",
      "minEepromVersion": 3
    },
    "limits": {
      "name": "Limits",
      "fields": ["temperatureLimit", "currentLimit", "lowVoltageCutoff", "lowVoltageThreshold", "absoluteVoltageCutoff"],
      "description": "Protection limits and cutoffs"
    },
    "currentControl": {
      "name": "Current Control",
      "fields": ["currentPidP", "currentPidI", "currentPidD"],
      "description": "Current control PID tuning (EEPROM v3+)",
      "minEepromVersion": 3
    },
    "sineStartup": {
      "name": "Sinusoidal Startup",
      "fields": ["sineStartup", "sineModeRange", "sineModePower"],
      "description": "Sinusoidal startup mode settings"
    },
    "brake": {
      "name": "Brake",
      "fields": ["brakeOnStop", "rcCarReversing", "dragBrakeStrength", "runningBrakeLevel", "activeBrakePower"],
      "description": "Braking behavior settings"
    },
    "servo": {
      "name": "Servo Settings",
      "fields": ["servoLowThreshold", "servoHighThreshold", "servoNeutral", "servoDeadband"],
      "description": "PWM servo input calibration"
    },
    "misc": {
      "name": "Miscellaneous",
      "fields": ["beepVolume", "telemetry30ms", "inputType", "startupMelody"],
      "description": "Other ESC settings"
    },
    "can": {
      "name": "CAN Bus",
      "fields": ["canNode", "canEscIndex", "canRequireArming", "canTelemRate", "canRequireZeroThrottle", "canFilterHz", "canDebugRate", "canTermEnable"],
      "description": "CAN bus communication settings (EEPROM v4+)",
      "minEepromVersion": 4
    }
  },

  "meta": {
    "maintainer": "AM32 Project",
    "repository": "https://github.com/am32-firmware/AM32",
    "license": "GPL-3.0",
    "lastUpdated": "2026-01-05",
    "consumers": [
      {
        "name": "AM32 Firmware",
        "language": "C",
        "usage": "Source of truth for EEPROM struct layout"
      },
      {
        "name": "AM32 Configurator",
        "language": "TypeScript/Vue",
        "usage": "Web-based ESC configuration tool"
      },
      {
        "name": "QGroundControl",
        "language": "C++/QML",
        "usage": "Ground control station ESC settings"
      }
    ]
  }
}