Commissioning API — Validate and Activate Chargers

Run and monitor the charge point commissioning workflow. Track check status, apply templates, retrieve diagnostics, and report issues.

The commissioning workflow validates that a newly installed charge point is correctly configured and communicating with Dynamo CSMS before it goes live for EV drivers. All commissioning endpoints are authenticated with an installer JWT (obtained from POST /api/v1/installer/login) and scoped to a specific charge_point_id.

A typical commissioning flow:

1. Start the session — triggers connectivity and configuration checks
2. Poll status — monitor test progress
3. Apply a template if standard checks fail
4. Review logs and diagnostics to diagnose failures
5. Report issues for hardware defects or site problems
6. Commission when all checks pass (see Charge Points)

---

Start commissioning

POST /api/v1/installer/commissioning/{charge_point_id}/start

Kicks off a commissioning session for the charge point. The system runs a sequence of automated checks: OCPP connectivity, heartbeat, configuration validation, and a test transaction.

charge_point_id · string · required

The unique identifier of the charge point to commission.

template_id · string

Optional commissioning template to apply before running checks. If omitted, the default template for the charge point model is used.

skip_test_transaction · boolean

Set to true to skip the test transaction step. Useful on sites where a vehicle is not available during commissioning. Defaults to false.

cURL

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/start \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "tpl_standard_ac_22kw",
    "skip_test_transaction": false
  }'

Response 202 Accepted

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "running",
  "started_at": "2024-03-10T14:30:00Z",
  "estimated_duration_seconds": 120,
  "steps": [
    {"name": "connectivity", "status": "pending"},
    {"name": "heartbeat", "status": "pending"},
    {"name": "configuration", "status": "pending"},
    {"name": "test_transaction", "status": "pending"}
  ]
}

session_id · string

Unique identifier for this commissioning session.

status · string

Initial status is running. Poll the status endpoint to track progress.

steps · array

Ordered list of commissioning steps with their individual statuses.

---

Get commissioning status

GET /api/v1/installer/commissioning/{charge_point_id}/status

Returns the current state of the active (or most recent) commissioning session for the charge point.

charge_point_id · string · required

The charge point’s unique identifier.

curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/status \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "completed",
  "result": "passed",
  "started_at": "2024-03-10T14:30:00Z",
  "completed_at": "2024-03-10T14:32:15Z",
  "steps": [
    {
      "name": "connectivity",
      "status": "passed",
      "duration_ms": 342,
      "detail": "WebSocket connected successfully"
    },
    {
      "name": "heartbeat",
      "status": "passed",
      "duration_ms": 1050,
      "detail": "Heartbeat received within 2s"
    },
    {
      "name": "configuration",
      "status": "passed",
      "duration_ms": 8200,
      "detail": "All 12 configuration keys applied"
    },
    {
      "name": "test_transaction",
      "status": "passed",
      "duration_ms": 25600,
      "detail": "Test transaction completed, 0.02 kWh delivered"
    }
  ]
}

status · string

One of: running, paused, completed, stopped, failed.

result · string | null

passed or failed once the session is complete. null while still running.

steps[].status · string

Individual step result: pending, running, passed, failed, skipped.

---

Stop commissioning

POST /api/v1/installer/commissioning/{charge_point_id}/stop

Stops the active commissioning session. Use this if you need to abort due to hardware or site issues.

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/stop \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "stopped",
  "stopped_at": "2024-03-10T14:31:00Z"
}

---

Pause commissioning

POST /api/v1/installer/commissioning/{charge_point_id}/pause

Pauses the running session at the current step. Useful when the charge point needs brief physical attention during commissioning.

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/pause \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "paused",
  "paused_at": "2024-03-10T14:31:00Z",
  "paused_at_step": "configuration"
}

---

Resume commissioning

POST /api/v1/installer/commissioning/{charge_point_id}/resume

Resumes a paused commissioning session from where it left off.

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/resume \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "status": "running",
  "resumed_at": "2024-03-10T14:35:00Z",
  "resuming_at_step": "configuration"
}

---

Restart commissioning

POST /api/v1/installer/commissioning/{charge_point_id}/restart

Starts a fresh commissioning session from the beginning, discarding the current session’s results.

template_id · string

Optionally switch to a different commissioning template for the new session.

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/restart \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Response 202 Accepted — same schema as the start response.

---

Get commissioning logs

GET /api/v1/installer/commissioning/{charge_point_id}/logs

Returns detailed event logs for the current or most recent commissioning session. Useful for debugging failures.

charge_point_id · string · required

The charge point’s unique identifier.

session_id · string

Retrieve logs for a specific historical session. Omit to get the most recent session’s logs.

level · string

Filter by log level: debug, info, warn, error. Defaults to all levels.

curl "https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/logs?level=error" \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "session_id": "comm_9f2c4a7b",
  "logs": [
    {
      "timestamp": "2024-03-10T14:30:01Z",
      "level": "info",
      "step": "connectivity",
      "message": "Attempting WebSocket connection to charge point"
    },
    {
      "timestamp": "2024-03-10T14:30:01.342Z",
      "level": "info",
      "step": "connectivity",
      "message": "WebSocket connected successfully"
    },
    {
      "timestamp": "2024-03-10T14:30:45Z",
      "level": "warn",
      "step": "configuration",
      "message": "Key 'ReserveConnectorZeroSupported' not supported by firmware — skipped"
    }
  ],
  "total": 47
}

---

Report an issue

POST /api/v1/installer/commissioning/{charge_point_id}/report-issue

Submits an issue report for a commissioning problem, flagging it for review by the Dynamo CSMS support team or the CPO.

charge_point_id · string · required

The charge point’s unique identifier.

category · string · required

Issue category. One of: hardware_defect, network_problem, configuration_error, site_issue, other.

description · string · required

Detailed description of the issue. Minimum 20 characters.

severity · string · required

One of: low, medium, high, critical.

step · string

The commissioning step where the issue occurred (e.g. "configuration", "test_transaction").

photo_urls · string[]

URLs of photos uploaded to document the issue (hardware damage, wiring, etc.).

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/report-issue \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "network_problem",
    "description": "Charge point connects briefly then drops WebSocket connection after ~5 seconds. Tested on both 4G and site WiFi. Issue persists across factory resets.",
    "severity": "high",
    "step": "connectivity",
    "photo_urls": [
      "https://storage.example.com/photos/cp_site42_001_lcd.jpg"
    ]
  }'

Response 201 Created

{
  "issue_id": "iss_4c8f2a1b",
  "charge_point_id": "CP-SITE42-001",
  "category": "network_problem",
  "severity": "high",
  "status": "open",
  "created_at": "2024-03-10T15:00:00Z",
  "reference_number": "DYN-2024-00847"
}

---

List issues

GET /api/v1/installer/commissioning/{charge_point_id}/issues

Returns all issue reports filed for this charge point.

curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/issues \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "issues": [
    {
      "issue_id": "iss_4c8f2a1b",
      "category": "network_problem",
      "severity": "high",
      "status": "open",
      "created_at": "2024-03-10T15:00:00Z",
      "reference_number": "DYN-2024-00847"
    }
  ],
  "total": 1
}

---

List commissioning templates

GET /api/v1/installer/commissioning/templates

Returns all available commissioning templates. Templates pre-configure OCPP parameters and commissioning steps for specific hardware models or deployment scenarios.

curl https://api.dynamo-csms.com/api/v1/installer/commissioning/templates \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "templates": [
    {
      "template_id": "tpl_standard_ac_22kw",
      "name": "Standard AC 22kW",
      "description": "Default commissioning for Type 2 AC chargers up to 22kW.",
      "compatible_models": ["ABB Terra AC W22-G5", "Schneider EVlink Pro AC"],
      "steps": ["connectivity", "heartbeat", "configuration", "test_transaction"],
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "template_id": "tpl_dc_rapid_50kw",
      "name": "DC Rapid 50kW",
      "description": "Commissioning template for DC rapid chargers with CHAdeMO and CCS connectors.",
      "compatible_models": ["ABB Terra 54 CJG", "Tritium PKM75"],
      "steps": ["connectivity", "heartbeat", "configuration", "connector_test", "test_transaction"],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "total": 2
}

---

Apply template

POST /api/v1/installer/commissioning/{charge_point_id}/apply-template

Applies a commissioning template to a charge point mid-session, pushing OCPP configuration keys defined in the template to the hardware.

charge_point_id · string · required

The charge point’s unique identifier.

template_id · string · required

The ID of the template to apply.

curl -X POST https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/apply-template \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "tpl_standard_ac_22kw"}'

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "template_id": "tpl_standard_ac_22kw",
  "applied_keys": 12,
  "rejected_keys": ["ReserveConnectorZeroSupported"],
  "applied_at": "2024-03-10T14:32:00Z"
}

applied_keys · integer

Number of configuration keys successfully applied.

rejected_keys · string[]

Keys that were not applied — usually because the firmware does not support them.

---

Get diagnostics

GET /api/v1/installer/commissioning/{charge_point_id}/diagnostics

Returns hardware and firmware diagnostic information reported by the charge point during commissioning. Useful for support escalations and firmware compatibility checks.

curl https://api.dynamo-csms.com/api/v1/installer/commissioning/CP-SITE42-001/diagnostics \
  -H "Authorization: Bearer INSTALLER_ACCESS_TOKEN"

Response 200 OK

{
  "charge_point_id": "CP-SITE42-001",
  "collected_at": "2024-03-10T14:30:05Z",
  "firmware": {
    "version": "3.8.2",
    "vendor": "ABB",
    "last_updated": "2023-11-01T00:00:00Z"
  },
  "ocpp": {
    "version": "1.6",
    "supported_features": [
      "Core", "FirmwareManagement", "LocalAuthListManagement",
      "Reservation", "SmartCharging", "RemoteTrigger"
    ]
  },
  "network": {
    "interface": "ethernet",
    "ip_address": "192.168.1.101",
    "signal_strength": null,
    "dns_resolution_ok": true,
    "ntp_synced": true
  },
  "hardware": {
    "connectors": 2,
    "meter_type": "MID certified",
    "rcd_present": true
  },
  "configuration_readonly_keys": [
    "ChargePointVendor",
    "ChargePointModel",
    "ChargePointSerialNumber"
  ]
}

---

Error responses

Status	Code	Meaning
400	validation_error	Missing or invalid request field
401	unauthorized	Missing or expired installer token
404	not_found	Charge point or template not found
409	session_already_running	A commissioning session is already active for this charge point
409	not_connected	Charge point is not currently connected via OCPP
422	already_commissioned	Charge point has already been commissioned