UpdateFirmware

FirmwareManagement CSMS->CS OCPP 2.0.1

Sent by the CSMS to instruct the Charging Station to download and install a firmware update from a given URL.

Quick Reference

Required Fields

requestId integer

Unique ID for this firmware update request

firmware FirmwareType

Object with the firmware location, retrieve date, and optional signature

firmware.location string(512)

URI pointing to the firmware file (HTTPS recommended)

firmware.retrieveDateTime string (date-time)

Earliest date/time to start downloading the firmware

Optional Fields

retries integer

Number of download retry attempts

retryInterval integer

Seconds to wait between retry attempts

firmware.installDateTime string (date-time)

Date/time to install the firmware (after download)

firmware.signingCertificate string(5500)

Certificate for verifying the firmware signature

firmware.signature string(800)

Base64 encoded firmware signature

Example Payload

{
  "requestId": 1,
  "firmware": {
    "location": "https://firmware.example.com/station/v2.1.0.bin",
    "retrieveDateTime": "2024-01-15T02:00:00Z",
    "installDateTime": "2024-01-15T03:00:00Z"
  },
  "retries": 3,
  "retryInterval": 60
}

Example Full Frame

[
  2,
  "msg-001",
  "UpdateFirmware",
  {
    "requestId": 1,
    "firmware": {
      "location": "https://firmware.example.com/station/v2.1.0.bin",
      "retrieveDateTime": "2024-01-15T02:00:00Z",
      "installDateTime": "2024-01-15T03:00:00Z"
    },
    "retries": 3,
    "retryInterval": 60
  }
]

Format: [MessageType, MessageId, Action, Payload]

Open in Builder Go to Validator

Overview

UpdateFirmware initiates an over-the-air firmware update on the Charging Station. The station downloads the firmware at the specified time and installs it, reporting progress via FirmwareStatusNotification.

When to Send

  • To deploy a security patch
  • To add new features or fix bugs
  • During scheduled maintenance windows

Expected Response

  • status: Accepted, Rejected, AcceptedCanceled, or InvalidCertificate

The full update progress is then reported via FirmwareStatusNotification with status values: Downloading, Downloaded, Installing, Installed, DownloadFailed, InstallationFailed, etc.

Key Differences from OCPP 1.6J

  • requestId is now required (was optional in 1.6J)
  • Firmware is wrapped in a FirmwareType object (not flat fields)
  • Signature verification fields added directly to FirmwareType
  • retrieveDateTime replaces retrieveDate

Best Practices

  1. Schedule downloads off-peak — Use retrieveDateTime at night to avoid interrupting sessions
  2. Use HTTPS — Always use HTTPS for the firmware location URL
  3. Include signature — Use signingCertificate + signature for secure firmware delivery
  4. Monitor via FirmwareStatusNotification — Track progress using the matching requestId

Testing Tips

  • Test successful download and install cycle
  • Test with an invalid URL to verify DownloadFailed status notification
  • Test the signature verification path with a valid certificate + signature pair

Common Errors

PropertyConstraintViolation

Cause: firmware.location exceeds 512 characters

Solution: Keep the firmware URL under 512 characters

TypeConstraintViolation

Cause: requestId missing

Solution: requestId is required in OCPP 2.0.1 to track the update via FirmwareStatusNotification

Related Actions

FirmwareStatusNotification Reset GetLog