BetterFleet VDV 261 conformance profile¶

Version and authority

This page describes BetterFleet's interpretation of VDV Recommendation 261, Edition 2, issue 05/2023. The licensed VDV document is authoritative. VDV lists issue 07/2024 as the current publication; comparison with that issue is pending, so this page makes no claim of conformance with the current issue.

References on this page are to the 05/2023 issue.

Scope¶

VDV 261 defines the Vehicle to Infrastructure Communication Protocol (V2ICP). It carries operational values between a vehicle's Electric Vehicle Communication Controller (EVCC) and a backend through ISO 15118 Value Added Service 3 InternetAccess.

The EVCC initiates the HTTPS connection.
The Supply Equipment Communication Controller (SECC) acts as a gateway and does not inspect the V2ICP payload.
The backend receives vehicle values and returns operational directives.
The VAS remains available only while the ISO 15118 charging session is active.

The recommendation does not define BetterFleet's optimisation, persistence, schema-discovery, or diagnostic-ingestion APIs.

Connection profile¶

Area	05/2023 requirement
Network	IPv6 end to end; backend reached by fixed address or URL/FQDN. IPv4 is excluded.
Service	ISO 15118 VAS 3 `InternetAccess`, ParameterSetID 4.
Transport	HTTPS on VAS Internet port 443.
TLS	TLS 1.2 with `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256`.
Trust	The vehicle validates the backend certificate against the configured trust chain.
Authentication	HTTP Basic Authentication; VIN is the username. A blank configured password means no Basic Authentication.
Method	Vehicle sends JSON using HTTP `POST`.
User agent	`V2ICP-Client/2.0.0`.
Encoding	US-ASCII.

These requirements belong at the deployed vehicle/backend boundary. The current FastAPI facade validates JSON payloads and enforces VIN/EVCC-bound Basic Authentication. It does not establish VAS, require IPv6, or terminate TLS.

Configuration¶

Vehicle¶

The vehicle address type is 0 disabled, 1 fixed IP address, or 2 URL. The configured URL, path, and password are each at most 150 bytes. The assembled URL is at most 249 characters, a URL begins with an alphabetic character, and an IPv6 literal is enclosed in square brackets.

Backend¶

The backend address type is 1 fixed IP address or 2 URL. The backend stores a credential for each vehicle, with the VIN as username. BetterFleet additionally binds that credential to the vehicle's EVCC ID so the request cannot select another Core vehicle record. The preconditioning policy is:

Value	Meaning
`0`	The vehicle determines the type of preconditioning.
`1`	The backend specifies the type of preconditioning.

The recommended password policy is at least eight visible ASCII characters with an uppercase letter, lowercase letter, number, and an approved special character.

V2ICP wire contract¶

The request and response are each one flat JSON object. There is no parameters wrapper.

{
  "seq": 0,
  "vin": "WVWZZZ1JZXW000001",
  "evccid": "001122334455",
  "odo": 12345,
  "bat_eamount": 42,
  "prec_eamount": 8,
  "h2_stat": 0,
  "bat_stat": 0
}

seq is an unsigned 8-bit counter (0..255) and wraps to zero.
vin is exactly 17 ASCII bytes.
evccid is exactly 12 hexadecimal characters, with no separators.
Unknown elements are accepted and ignored.

Vehicle request rules¶

At seq = 0, the vehicle sends all available vehicle fields.
The normal send interval is ten seconds.
Later requests carry changed values, plus h2_stat and bat_stat on every request.
If no response arrives within 15 seconds, the vehicle retries up to three times before reconnect handling begins.

Requirement V2ICP-71 says h2_stat and bat_stat are present in every request. Some examples in the 05/2023 issue omit them from delta messages. BetterFleet follows the explicit numbered requirement; this ambiguity must be checked against issue 07/2024.

Backend response rules¶

A valid request receives HTTP 200 with the same seq and vin.
At seq = 0, the response contains every backend field. An unavailable value uses its specified SNA value.
Later responses carry changed backend fields.
The response body is at most 512 bytes.

{
  "seq": 0,
  "vin": "WVWZZZ1JZXW000001",
  "driveoff": 12,
  "prec_dsrd": 1,
  "prec_hvac": 1,
  "ambienttemp": 18,
  "target_dist": 120,
  "target_soc": 85
}

driveoff = 12 means 12 five-minute units, or 60 minutes until departure.

Vehicle fields¶

Field	Meaning
`odo`	Odometer value.
`bat_reqtime`	Time requested to charge the traction battery.
`bat_eamount`	Energy requested to charge the traction battery.
`prec_reqtime`	Time required for vehicle preconditioning.
`prec_eamount`	Energy required or estimated for vehicle preconditioning. It is not cumulative energy consumed.
`chrg_stat`	Charging state.
`h2_stat`	Hydrogen-system safety state.
`bat_stat`	Traction-battery safety state.

Safety status values use -1 for SNA. h2_stat uses 0 okay and 1 not okay. bat_stat uses 0 okay, 1 not okay, and 2 critical.

Backend fields¶

Field	Meaning
`driveoff`	Countdown in five-minute units: `0..288`; `-1` is SNA.
`prec_dsrd`	Whether preconditioning is requested.
`prec_hvac`	Requested climate function when backend policy selects the type.
`ambienttemp`	Expected ambient temperature at departure, supplied by the backend.
`target_dist`	Planned target distance.
`target_soc`	Planned target state of charge.

prec_hvac uses these 05/2023 values:

Value	Meaning
`-1`	SNA.
`0`	Hot water and ventilation.
`1`	Hot water and heating.
`2`	No hot water; cooling or ventilation only.
`3`	No climate preconditioning.

The source notes that a vehicle with automatic climate control may ignore this directive. Value 3 is not an instruction to select an automatic mode. The wording should be checked against issue 07/2024.

BetterFleet extensions¶

The following surfaces help integration and testing but are outside VDV 261:

GET /vdv261/schemas and GET /vdv261/schemas/{schema_name}
GET /vdv261/openapi.json
POST /vdv261/v2icp/diagnostics

The former bprec_eamount field is absent from the 05/2023 VDV tables and has been removed from the VDV wire model. A future BetterFleet-specific battery preconditioning value needs an explicitly versioned extension contract.

BetterFleet implementation status¶

Capability	Status
Flat JSON request and response validation	Implemented in the facade.
Core 05/2023 field ranges and enums	Implemented for published models.
Mandatory `h2_stat` and `bat_stat`	Enforced on every request.
Full `seq = 0` backend response	Implemented with current preconditioning directives and SNA for unavailable values.
Schema, OpenAPI, and diagnostic surfaces	Implemented as BetterFleet extensions.
VIN/EVCC-bound HTTP Basic authentication	The VIN remains the Basic username; the configured credential must also match the request EVCC ID.
Manage Core service authentication	OAuth client credentials are cached and refreshed before expiry.
VAS discovery, IPv6, TLS, and session lifecycle	Outside the current facade; integration work remains.
Preconditioning and departure directive mapping	Implemented through Manage Core for `driveoff`, `prec_dsrd`, and `prec_hvac`.
512-byte response enforcement and full protocol conformance tests	Pending.
Comparison with current VDV 261 issue 07/2024	Pending receipt of the licensed issue.