Battery Swapping - CSMS Developer Guide

function handleAuthorizeRequest(stationId, request):
    idToken = request.idToken

    // 1. Look up the token in the authorization database
    tokenRecord = database.findToken(idToken.idToken, idToken.type)

    // 2. Validate the token
    if tokenRecord is null:
        return { idTokenInfo: { status: "Invalid" } }

    if tokenRecord.isBlocked:
        return { idTokenInfo: { status: "Blocked" } }

    if tokenRecord.expiryDate < now():
        return { idTokenInfo: { status: "Expired" } }

    if not tokenRecord.hasValidSwapContract:
        return { idTokenInfo: { status: "Invalid" } }

    // 3. Check location-based restrictions
    if not tokenRecord.isAllowedAtStation(stationId):
        return { idTokenInfo: { status: "NotAtThisLocation" } }

    // 4. Grant authorization
    return {
        idTokenInfo: {
            status: "Accepted",
            cacheExpiryDateTime: "2025-12-31T23:59:59Z",
            language1: tokenRecord.preferredLanguage
        }
    }

{
  "idToken": {
    "idToken": "AABBCCDD11223344",
    "type": "ISO14443"
  },
  "requestId": 42
}

function initiateBatterySwapRemote(stationId, userId):
    // 1. Validate user authorization
    user = database.findUser(userId)
    if not user.hasValidSwapContract():
        return error("User not authorized for battery swapping")

    // 2. Generate unique requestId
    requestId = generateUniqueRequestId()

    // 3. Store the pending swap request for correlation
    database.storePendingSwapRequest({
        requestId: requestId,
        stationId: stationId,
        userId: userId,
        idToken: user.idToken,
        createdAt: now(),
        status: "Pending"
    })

    // 4. Send the request to BSS
    response = sendToBSS(stationId, "RequestBatterySwapRequest", {
        idToken: {
            idToken: user.idToken.value,
            type: user.idToken.type
        },
        requestId: requestId
    })

    // 5. Handle response
    if response.status == "Accepted":
        database.updatePendingSwapRequest(requestId, { status: "Accepted" })
        // Now wait for BatterySwapRequest messages (S03)
    else:
        database.updatePendingSwapRequest(requestId, {
            status: "Rejected",
            reason: response.statusInfo?.reasonCode
        })
        notifyUser(userId, "Swap rejected: " + response.statusInfo?.additionalInfo)

{
  "customData": {
    "vendorId": "org.openchargealliance.batteryswapresponse",
    "status": "Rejected",
    "statusInfo": {
      "reasonCode": "BatteryUnknown",
      "additionalInfo": "Not a battery of this CPO"
    }
  }
}

function handleNotifyEventRequest(stationId, request):
    for event in request.eventData:
        component = event.component
        variable = event.variable

        // Filter for battery slot state changes
        if component.name == "Connector" and variable.name == "AvailabilityState":
            slotId = component.evse.id
            newState = event.actualValue   // "Occupied" or "Available"

            database.updateSlotAvailability(stationId, slotId, newState)

    // Always return empty acknowledgement
    return {}

{
  "eventType": "Updated",
  "timestamp": "2025-12-03T14:45:00Z",
  "triggerReason": "MeterValuePeriodic",
  "seqNo": 3,
  "transactionInfo": {
    "transactionId": "tx-bss-slot3-20251203",
    "chargingState": "Charging"
  },
  "evse": { "id": 3 },
  "meterValue": [
    {
      "timestamp": "2025-12-03T14:45:00Z",
      "sampledValue": [
        {
          "value": 45.0,
          "measurand": "SoC"
        }
      ]
    }
  ]
}

{
  "eventType": "Ended",
  "timestamp": "2025-12-03T18:00:00Z",
  "triggerReason": "EVCommunicationLost",
  "seqNo": 20,
  "transactionInfo": {
    "transactionId": "tx-bss-slot3-20251203",
    "chargingState": "Idle",
    "stoppedReason": "EVDisconnected",
    "timeSpentCharging": 12540
  },
  "evse": { "id": 3 }
}

function handleTransactionEventRequest(stationId, request):
    txId = request.transactionInfo.transactionId
    evseId = request.evse?.id

    switch request.eventType:

        case "Started":
            isBatterySwapCharging = isBatterySwapStation(stationId)
                && (request.idToken?.type == "NoAuthorization"
                    || isBatterySwapIdToken(stationId, request.idToken))

            database.createTransaction({
                transactionId: txId,
                stationId: stationId,
                evseId: evseId,
                startTime: request.timestamp,
                isBatterySwapCharging: isBatterySwapCharging,
                chargingState: request.transactionInfo.chargingState
            })

            // Link to slot if this is a BSS
            if isBatterySwapCharging:
                database.updateSlot(stationId, evseId, {
                    chargingTransactionId: txId
                })

            return {}  // Empty response is valid

        case "Updated":
            tx = database.findTransaction(txId)
            tx.chargingState = request.transactionInfo.chargingState
            tx.lastUpdated = request.timestamp

            // Track SoC from meter values
            if request.meterValue:
                for mv in request.meterValue:
                    for sv in mv.sampledValue:
                        if sv.measurand == "SoC":
                            tx.currentSoC = sv.value
                            database.updateSlot(stationId, evseId, {
                                batterySoC: sv.value
                            })

            // Detect suspension at max SoC
            if request.triggerReason == "EnergyLimitReached":
                tx.chargingState = "SuspendedEVSE"
                database.updateSlot(stationId, evseId, {
                    swapEligible: true
                })

            database.saveTransaction(tx)
            return {}

        case "Ended":
            tx = database.findTransaction(txId)
            tx.endTime = request.timestamp
            tx.stoppedReason = request.transactionInfo.stoppedReason
            tx.timeSpentCharging = request.transactionInfo.timeSpentCharging
            tx.status = "Completed"

            // Clear slot charging transaction link
            database.updateSlot(stationId, evseId, {
                chargingTransactionId: null
            })

            database.saveTransaction(tx)
            return {}

{
  "type": "object",
  "required": ["eventType", "requestId", "idToken", "batteryData"],
  "properties": {
    "eventType": {
      "type": "string",
      "enum": ["BatteryIn", "BatteryOut", "BatteryOutTimeout"]
    },
    "requestId": {
      "type": "integer",
      "description": "Correlates BatteryIn/Out events and optional RequestBatterySwapRequest"
    },
    "idToken": {
      "type": "object",
      "required": ["idToken", "type"],
      "properties": {
        "idToken":        { "type": "string", "maxLength": 255 },
        "type":           { "type": "string", "maxLength": 20 },
        "additionalInfo": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["additionalIdToken", "type"],
            "properties": {
              "additionalIdToken": { "type": "string", "maxLength": 255 },
              "type":              { "type": "string", "maxLength": 50 }
            }
          }
        }
      }
    },
    "batteryData": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": ["evseId", "serialNumber", "soC", "soH"],
        "properties": {
          "evseId":         { "type": "integer", "minimum": 0 },
          "serialNumber":   { "type": "string", "maxLength": 50 },
          "soC":            { "type": "number", "minimum": 0.0, "maximum": 100.0 },
          "soH":            { "type": "number", "minimum": 0.0, "maximum": 100.0 },
          "productionDate": { "type": "string", "format": "date-time" },
          "vendorInfo":     { "type": "string", "maxLength": 500 }
        }
      }
    }
  }
}

{
  "type": "object",
  "description": "Empty acknowledgement. The request cannot be rejected via standard fields.",
  "properties": {
    "customData": {
      "type": "object",
      "required": ["vendorId"],
      "properties": {
        "vendorId": { "type": "string", "maxLength": 255 }
      }
    }
  }
}

{
  "type": "object",
  "required": ["requestId", "idToken"],
  "properties": {
    "requestId": {
      "type": "integer",
      "description": "Request ID to match with BatterySwapRequest"
    },
    "idToken": {
      "type": "object",
      "required": ["idToken", "type"],
      "properties": {
        "idToken":        { "type": "string", "maxLength": 255 },
        "type":           { "type": "string", "maxLength": 20 },
        "additionalInfo": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["additionalIdToken", "type"],
            "properties": {
              "additionalIdToken": { "type": "string", "maxLength": 255 },
              "type":              { "type": "string", "maxLength": 50 }
            }
          }
        }
      }
    }
  }
}

BatteryRecord {
    evseId:          integer
    serialNumber:    string
    soC:             number
    soH:             number
    productionDate:  datetime?
    vendorInfo:      string?
}

SlotStatus {
    stationId:              string
    evseId:                 integer
    availabilityState:      "Available" | "Occupied" | "Unavailable"
    batterySerialNumber:    string?
    batterySoC:             number?
    batterySoH:             number?
    swapEligible:           boolean     // SoC >= BatterySwapTargetSoc
    chargingTransactionId:  string?
    lastUpdated:            datetime
}